WdfDeviceCreate-Funktion (wdfdevice.h)
[Gilt für KMDF und UMDF]
Die WdfDeviceCreate-Methode erstellt ein Framework-Geräteobjekt.
NTSTATUS WdfDeviceCreate(
[in, out] PWDFDEVICE_INIT *DeviceInit,
[in, optional] PWDF_OBJECT_ATTRIBUTES DeviceAttributes,
[out] WDFDEVICE *Device
);
[in, out] DeviceInit
Die Adresse eines Zeigers auf eine WDFDEVICE_INIT Struktur. Wenn WdfDeviceCreate keine Fehler auftritt, wird der Zeiger auf NULL-festgelegt.
[in, optional] DeviceAttributes
Ein Zeiger auf eine vom Aufrufer zugewiesene WDF_OBJECT_ATTRIBUTES Struktur, die Attribute für das neue Objekt enthält. (Das ParentObject-Element der Struktur muss NULL-sein.) Dieser Parameter ist optional und kann WDF_NO_OBJECT_ATTRIBUTES werden.
[out] Device
Ein Zeiger auf eine Position, die ein Handle für das neue Framework-Geräteobjekt empfängt.
Wenn die WdfDeviceCreate Methode keine Fehler auftritt, wird STATUS_SUCCESS zurückgegeben. Weitere Rückgabewerte sind:
Rückgabecode | Beschreibung |
---|---|
STATUS_INVALID_PARAMETER | Es wird ein ungültiger Device oder DeviceInit Handle bereitgestellt. |
STATUS_INVALID_DEVICE_STATE | Der Treiber hat bereits ein Geräteobjekt für das Gerät erstellt. |
STATUS_INVALID_SECURITY_DESCR | Der Treiber WdfDeviceInitAssignSDDLString oder WdfDeviceInitSetDeviceClass, aber keinen Namen für das Geräteobjekt bereitgestellt hat. |
STATUS_INSUFFICIENT_RESOURCES | Ein Geräteobjekt konnte nicht zugewiesen werden. |
STATUS_OBJECT_NAME_COLLISION | Der Gerätename, der durch einen Aufruf von WdfDeviceInitAssignName angegeben wurde, ist bereits vorhanden. Der Treiber kann WdfDeviceInitAssignName- erneut aufrufen, um einen neuen Namen zuzuweisen. |
Eine Liste mit anderen Rückgabewerten, die WdfDeviceCreate zurückgeben können, finden Sie unter Framework Object Creation Errors.
Die Methode gibt möglicherweise andere NTSTATUS-Wertezurück.
Vor dem Aufrufen WdfDeviceCreatemuss der Treiber vom Framework bereitgestellte Funktionen aufrufen, die die WDFDEVICE_INIT-Struktur initialisieren. Weitere Informationen zum Initialisieren dieser Struktur finden Sie unter WDFDEVICE_INIT. Wenn der Treiber fehler beim Aufrufen der Initialisierungsfunktionen auftritt, darf er nicht WdfDeviceCreateaufrufen. In diesem Fall muss der Treiber möglicherweise WdfDeviceInitFree-aufrufen. Informationen zum Aufrufen WdfDeviceInitFree-finden Sie unter WdfDeviceInitFree.
Ein Aufruf von WdfDeviceCreate erstellt ein Framework-Geräteobjekt, das entweder ein funktionales Geräteobjekt (FDO) oder ein physisches Geräteobjekt (PDO) darstellt. Der Typ des von der Funktion erstellten Geräteobjekts hängt davon ab, wie der Treiber die WDFDEVICE_INIT Struktur abgerufen hat:
- Wenn der Treiber die WDFDEVICE_INIT Struktur von einem EvtDriverDeviceAdd Rückruf empfangen hat, erstellt WdfDeviceCreate einen FDO.
- Wenn der Treiber die WDFDEVICE_INIT Struktur von einem EvtChildListCreateDevice Callback oder von einem Aufruf an WdfPdoInitAllocateerhalten hat, erstellt WdfDeviceCreate einen PDO.
Miniporttreiber, die das Framework verwenden, müssen WdfDeviceMiniportCreate anstelle von WdfDeviceCreateaufrufen.
Das übergeordnete Element jedes Framework-Geräteobjekts ist das Framework-Treiberobjekt des Treibers. Der Treiber kann dieses übergeordnete Element nicht ändern, und das ParentObject Member der WDF_OBJECT_ATTRIBUTES Struktur muss NULL-sein. Das Framework löscht jedes Framework-Geräteobjekt (mit Ausnahme einiger Steuerelementgeräteobjekte), wenn der Plug and Play (PnP)-Manager feststellt, dass das Gerät entfernt wurde.
Wenn Ihr Treiber EvtCleanupCallback oder EvtDestroyCallback- Rückruffunktionen für das Framework-Geräteobjekt bereitstellt, beachten Sie, dass das Framework diese Rückruffunktionen bei IRQL = PASSIVE_LEVEL aufruft.
Weitere Informationen zum Erstellen von Geräteobjekten finden Sie unter Creating a Framework Device Object.
Das folgende Codebeispiel zeigt, wie eine EvtDriverDeviceAdd Rückruffunktion ein Geräteobjekt initialisieren und erstellen kann.
NTSTATUS
MyEvtDeviceAdd(
IN WDFDRIVER Driver,
IN PWDFDEVICE_INIT DeviceInit
)
{
WDF_PNPPOWER_EVENT_CALLBACKS pnpPowerCallbacks;
WDF_OBJECT_ATTRIBUTES attributes;
NTSTATUS status;
WDFDEVICE device;
//
// Initialize the WDF_PNPPOWER_EVENT_CALLBACKS structure.
//
WDF_PNPPOWER_EVENT_CALLBACKS_INIT(&pnpPowerCallbacks);
pnpPowerCallbacks.EvtDevicePrepareHardware = MyEvtDevicePrepareHardware;
pnpPowerCallbacks.EvtDeviceD0Entry = MyEvtDeviceD0Entry;
pnpPowerCallbacks.EvtDeviceD0Exit = MyEvtDeviceD0Exit;
WdfDeviceInitSetPnpPowerEventCallbacks(
DeviceInit,
&pnpPowerCallbacks
);
//
// This driver uses buffered I/O.
//
WdfDeviceInitSetIoType(
DeviceInit,
WdfDeviceIoBuffered
);
//
// Specify the device object's context space by
// using a driver-defined DEVICE_CONTEXT structure.
//
WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(
&attributes,
DEVICE_CONTEXT
);
//
// Create the device object.
//
status = WdfDeviceCreate(
&DeviceInit,
&attributes,
&device
);
if (!NT_SUCCESS(status)) {
return status;
}
return STATUS_SUCCESS;
}
Anforderung | Wert |
---|---|
Zielplattform- | Universal |
Minimale KMDF-Version | 1.0 |
Mindest-UMDF-Version | 2.0 |
Header- | wdfdevice.h (einschließen Wdf.h) |
Library | Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF) |
IRQL- | PASSIVE_LEVEL |
DDI-Complianceregeln | AccessHardwareKey(kmdf), AddPdoToStaticChildList(kmdf), ChangeQueueState(kmdf), ChildDeviceInitAPI() kmdf), ChildListConfiguration(kmdf), ControlDeviceDeleted(kmdf), ControlDeviceInitAllocate(kmdf), ControlDeviceInitAPI(kmdf), CtlDeviceFinishInitDeviceAdd(kmdf), CtlDeviceFinishInitDr, DeviceCreateFail(kmdf), DeviceInitAllocate(kmdf), DeviceInitAPI(kmdf), DriverCreate(kmdf), InitFreeDeviceCreate(kmdf), InitFreeDeviceCreateType2(kmdf), InitFreeDeviceCreateType4(kmdf), InitFreeNull(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), PdoDeviceInitAPI(kmdf), PdoInitFreeDeviceCre, PdoInitFreeDeviceCreateType2(kmdf), PdoInitFreeDeviceCreateType4(kmdf) |
WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE
WDF_PNPPOWER_EVENT_CALLBACKS_INIT