Funzione WdfDeviceCreate (wdfdevice.h)

Articolo
02/29/2024

[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.

Dopo che il driver chiama WdfDeviceCreate, non può più accedere alla struttura WDFDEVICE_INIT.

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)