Funzione WdfDeviceCreate (wdfdevice.h)
[Si applica a KMDF e UMDF]
Il metodo WdfDeviceCreate crea un oggetto dispositivo framework.
Sintassi
NTSTATUS WdfDeviceCreate(
[in, out] PWDFDEVICE_INIT *DeviceInit,
[in, optional] PWDF_OBJECT_ATTRIBUTES DeviceAttributes,
[out] WDFDEVICE *Device
);
Parametri
[in, out] DeviceInit
Indirizzo di un puntatore a una struttura WDFDEVICE_INIT . Se WdfDeviceCreate non rileva errori, imposta il puntatore su NULL.
[in, optional] DeviceAttributes
Puntatore a una struttura WDF_OBJECT_ATTRIBUTES allocata dal chiamante che contiene attributi per il nuovo oggetto. Il membro ParentObject della struttura deve essere NULL. Questo parametro è facoltativo e può essere WDF_NO_OBJECT_ATTRIBUTES.
[out] Device
Puntatore a una posizione che riceve un handle per il nuovo oggetto dispositivo framework.
Valore restituito
Se il metodo WdfDeviceCreate non rileva errori, restituisce STATUS_SUCCESS. I valori restituiti aggiuntivi includono:
|Codice restituito|Descrizione| |--- |--- | |STATUS_INVALID_PARAMETER|Viene fornito un handle Device o DeviceInit non valido.| |STATUS_INVALID_DEVICE_STATE|Il driver ha già creato un oggetto dispositivo per il dispositivo.| |STATUS_INVALID_SECURITY_DESCR|il driver denominato WdfDeviceInitAssignSDDLString o WdfDeviceInitSetDeviceClass ma non ha fornito un nome per l'oggetto dispositivo.| |STATUS_INSUFFICIENT_RESOURCES|Impossibile allocare un oggetto dispositivo.| |STATUS_OBJECT_NAME_COLLISION|Il nome del dispositivo specificato da una chiamata a WdfDeviceInitAssignName esiste già. Il driver può chiamare di nuovo WdfDeviceInitAssignName per assegnare un nuovo nome.| Per un elenco di altri valori restituiti che WdfDeviceCreate può restituire, vedere Errori di creazione di oggetti framework.
Il metodo potrebbe restituire altri valori NTSTATUS.
Commenti
Prima di chiamare WdfDeviceCreate, il driver deve chiamare funzioni fornite dal framework che inizializzano la struttura WDFDEVICE_INIT. Per altre informazioni sull'inizializzazione di questa struttura, vedere WDFDEVICE_INIT. Se il driver rileva errori durante la chiamata delle funzioni di inizializzazione, non deve chiamare WdfDeviceCreate. In questo caso, il driver potrebbe dover chiamare WdfDeviceInitFree. Per informazioni su quando chiamare WdfDeviceInitFree, vedere WdfDeviceInitFree.
Una chiamata a WdfDeviceCreate crea un oggetto dispositivo framework che rappresenta un oggetto dispositivo funzionale (FDO) o un oggetto dispositivo fisico (PDO). Il tipo di oggetto dispositivo creato dalla funzione dipende dal modo in cui il driver ha ottenuto la struttura WDFDEVICE_INIT:
- Se il driver ha ricevuto la struttura WDFDEVICE_INIT da un callback EvtDriverDeviceAdd , WdfDeviceCreate crea un fdO.
- Se il driver ha ricevuto la struttura WDFDEVICE_INIT da un callback EvtChildListCreateDevice o da una chiamata a WdfPdoInitAllocate, WdfDeviceCreate crea un PDO.
I driver miniport che usano il framework devono chiamare WdfDeviceMiniportCreate anziché WdfDeviceCreate.
L'elemento padre di ogni oggetto dispositivo framework è l'oggetto driver framework del driver. Il driver non può modificare questo elemento padre e il membro ParentObject della struttura WDF_OBJECT_ATTRIBUTES deve essere NULL. Il framework elimina ogni oggetto dispositivo framework (ad eccezione di alcuni oggetti dispositivo di controllo) quando il gestore Plug and Play (PnP) determina che il dispositivo è stato rimosso.
Se il driver fornisce funzioni di callback EvtCleanupCallback o EvtDestroyCallback per l'oggetto dispositivo framework, si noti che il framework chiama queste funzioni di callback in IRQL = PASSIVE_LEVEL.
Per altre informazioni sulla creazione di oggetti dispositivo, vedere Creazione di un oggetto dispositivo framework.
Esempio
L'esempio di codice seguente mostra come una funzione di callback EvtDriverDeviceAdd potrebbe inizializzare e creare un oggetto dispositivo.
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;
}
Requisiti
| Requisito | Valore |
|---|---|
| Piattaforma di destinazione | Universale |
| Versione KMDF minima | 1.0 |
| Versione UMDF minima | 2,0 |
| Intestazione | wdfdevice.h (include Wdf.h) |
| Libreria | Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF) |
| IRQL | PASSIVE_LEVEL |
| Regole di conformità DDI | AccessHardwareKey(kmdf), AddPdoToStaticChildList(kmdf), ChangeQueueState(kmdf), ChildDeviceInitAPI(kmdf), ChildListConfiguration(kmdf), ControlDeviceDeleted(kmdf), ControlDeviceInitAllocate(kmdf), ControlDeviceInitAPI(kmdf), CtlDeviceFinishInitDeviceAdd(kmdf), CtlDeviceFinishInitDrEntry(kmdf), DeviceCreateFail(kmdf), DeviceInitAllocate(kmdf), DeviceInitAPI(kmdf), DriverCreate(kmdf), InitFreeDeviceCreate(kmdf), InitFreeDeviceCreateType2(kmdf), InitFreeDeviceCreateType4(kmdf), InitFreeNull(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), PdoDeviceInitAPI(kmdf), PdoInitFreeDeviceCreate(kmdf), PdoInitFreeDeviceCreateType2(kmdf), PdoInitFreeDeviceCreateType4(kmdf) |
Vedi anche
WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE
WDF_PNPPOWER_EVENT_CALLBACKS_INIT