WdfControlDeviceInitAllocate-Funktion (wdfcontrol.h)

Artikel
02/29/2024

[Gilt nur für KMDF]

Die WdfControlDeviceInitAllocate-Methode weist eine WDFDEVICE_INIT Struktur zu, die ein Treiber beim Erstellen eines neuen Steuerelementgeräteobjekts verwendet.

Syntax

PWDFDEVICE_INIT WdfControlDeviceInitAllocate(
  [in] WDFDRIVER            Driver,
  [in] const UNICODE_STRING *SDDLString
);

Parameter

[in] Driver

Ein Handle für ein Frameworktreiberobjekt.

[in] SDDLString

Ein Zeiger auf eine UNICODE_STRING-Struktur , die eine Unicode-Zeichenfolge beschreibt. Diese Zeichenfolge ist eine SDDL-Darstellung (Security Descriptor Definition Language) eines Sicherheitsdeskriptors. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".

Rückgabewert

WdfControlDeviceInitAllocate gibt einen Zeiger auf eine vom Framework zugewiesene WDFDEVICE_INIT-Struktur zurück, wenn der Vorgang erfolgreich ist. Andernfalls gibt die Methode NULL zurück.

Hinweise

Wenn Der Treiber ein Steuerelementgeräteobjekt erstellen soll, muss der Treiber WdfControlDeviceInitAllocate aufrufen, um eine WDFDEVICE_INIT-Struktur abzurufen, die er an WdfDeviceCreate übergeben kann.

Ihr Treiber kann eine Sicherheitseinstellung mithilfe einer Teilmenge von SDDL angeben. Die Datei Wdmsec.h definiert einen Satz von SDDL_DEVOBJ_Xxx-formatierten Konstanten, die Sie verwenden können. Weitere Informationen zu Sicherheitsbeschreibungen und SDDL finden Sie unter Schützen von Geräteobjekten.

Die WdfDeviceInitAssignSDDLString-Methode überschreibt ggf. die Sicherheitseinstellung, die WdfControlDeviceInitAllocate angibt.

Weitere Informationen zum Aufrufen von WdfControlDeviceInitAllocate finden Sie unter Verwenden von Steuerelementgeräteobjekten.

Beispiele

Im folgenden Codebeispiel wird eine DEVICE_INIT-Struktur zugeordnet, ein Geräteobjektname zugewiesen, eine Rückruffunktion zum Herunterfahren von Benachrichtigungen registriert und ein Steuerelementgerätobjekt erstellt. Ein komplexeres Beispiel, das WdfControlDeviceInitAllocate verwendet, finden Sie im NONPNP-Beispieltreiber oder im NDISProt-Beispieltreiber .

PWDFDEVICE_INIT  deviceInit = NULL;
NTSTATUS  status;
WDF_OBJECT_ATTRIBUTES  objectAttribs;

deviceInit = WdfControlDeviceInitAllocate(
                                          hDriver,
                                          &SDDL_DEVOBJ_SYS_ALL_ADM_RWX_WORLD_RW_RES_R
                                          );
if (deviceInit == NULL) {
    status = STATUS_INSUFFICIENT_RESOURCES;
    goto Error;
}
status = WdfDeviceInitAssignName(
                                 deviceInit,
                                 &ntDeviceName
                                 );
if (!NT_SUCCESS(status)) {
    WdfDeviceInitFree(deviceInit);
    deviceInit = NULL;
    goto Error;
}
WdfControlDeviceInitSetShutdownNotification(
                                            deviceInit,
                                            EvtShutdownNotification,
                                            WdfDeviceShutdown
                                            );
WDF_OBJECT_ATTRIBUTES_INIT(&objectAttribs);

status = WdfDeviceCreate(
                         &deviceInit,
                         &objectAttribs,
                         &controlDevice
                         );
if (!NT_SUCCESS(status)) {
    WdfDeviceInitFree(deviceInit);
    deviceInit = NULL;
    goto Error;
}
WdfControlFinishInitializing(controlDevice);

Anforderungen

Anforderung	Wert
Zielplattform	Universell
KMDF-Mindestversion	1.0
Kopfzeile	wdfcontrol.h (einschließen von Wdf.h)
Bibliothek	Wdf01000.sys (siehe Versionsverwaltung der Frameworkbibliothek).)
IRQL	PASSIVE_LEVEL
DDI-Complianceregeln	ControlDeviceInitAPI(kmdf), CtlDeviceFinishInitDeviceAdd(kmdf), CtlDeviceFinishInitDrEntry(kmdf), DoubleDeviceInitFree(kmdf), DriverCreate(kmdf), InitFreeDeviceCallback(kmdf), InitFreeDeviceCreate(kmdf), InitFreeDeviceCreateType2(kmdf), InitFreeDeviceCreateType4(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)