Função WdfDeviceCreate (wdfdevice.h)

Artigo
08/08/2023

[Aplica-se a KMDF e UMDF]

O método WdfDeviceCreate cria um objeto de dispositivo de estrutura.

Sintaxe

NTSTATUS WdfDeviceCreate(
  [in, out]      PWDFDEVICE_INIT        *DeviceInit,
  [in, optional] PWDF_OBJECT_ATTRIBUTES DeviceAttributes,
  [out]          WDFDEVICE              *Device
);

Parâmetros

[in, out] DeviceInit

O endereço de um ponteiro para uma estrutura WDFDEVICE_INIT . Se WdfDeviceCreate não encontrar erros, ele definirá o ponteiro como NULL.

[in, optional] DeviceAttributes

Um ponteiro para uma estrutura de WDF_OBJECT_ATTRIBUTES alocada pelo chamador que contém atributos para o novo objeto. (O membro ParentObject da estrutura deve ser NULL.) Esse parâmetro é opcional e pode ser WDF_NO_OBJECT_ATTRIBUTES.

[out] Device

Um ponteiro para um local que recebe um identificador para o novo objeto de dispositivo de estrutura.

Retornar valor

Se o método WdfDeviceCreate não encontrar erros, ele retornará STATUS_SUCCESS. Os valores de retorno adicionais incluem:

Código de retorno	Descrição
STATUS_INVALID_PARAMETER	Um identificador Device ou DeviceInit inválido é fornecido.
STATUS_INVALID_DEVICE_STATE	O driver já criou um objeto de dispositivo para o dispositivo.
STATUS_INVALID_SECURITY_DESCR	o driver chamado WdfDeviceInitAssignSDDLString ou WdfDeviceInitSetDeviceClass , mas não forneceu um nome para o objeto do dispositivo.
STATUS_INSUFFICIENT_RESOURCES	Não foi possível alocar um objeto de dispositivo.
STATUS_OBJECT_NAME_COLLISION	O nome do dispositivo especificado por uma chamada para WdfDeviceInitAssignName já existe. O driver pode chamar WdfDeviceInitAssignName novamente para atribuir um novo nome.

Para obter uma lista de outros valores retornados que WdfDeviceCreate pode retornar, consulte Erros de criação de objeto de estrutura.

O método pode retornar outros valores NTSTATUS.

Comentários

Antes de chamar WdfDeviceCreate, o driver deve chamar funções fornecidas pela estrutura que inicializam a estrutura WDFDEVICE_INIT. Para obter mais informações sobre como inicializar essa estrutura, consulte WDFDEVICE_INIT. Se o driver encontrar erros ao chamar as funções de inicialização, ele não deverá chamar WdfDeviceCreate. Nesse caso, o driver pode ter que chamar WdfDeviceInitFree. Para obter informações sobre quando chamar WdfDeviceInitFree, consulte WdfDeviceInitFree.

Uma chamada para WdfDeviceCreate cria um objeto de dispositivo de estrutura que representa um FDO (objeto de dispositivo funcional) ou um PDO (objeto de dispositivo físico). O tipo de objeto de dispositivo que a função cria depende de como o driver obteve a estrutura WDFDEVICE_INIT:

Se o driver recebeu a estrutura WDFDEVICE_INIT de um retorno de chamada EvtDriverDeviceAdd , WdfDeviceCreate criará um FDO.
Se o driver recebeu a estrutura WDFDEVICE_INIT de um retorno de chamada EvtChildListCreateDevice ou de uma chamada para WdfPdoInitAllocate, WdfDeviceCreate criará um PDO.

Depois que o driver chama WdfDeviceCreate, ele não pode mais acessar a estrutura WDFDEVICE_INIT.

Os drivers de miniport que usam a estrutura devem chamar WdfDeviceMiniportCreate em vez de WdfDeviceCreate.

O pai de cada objeto de dispositivo de estrutura é o objeto de driver de estrutura do driver. O driver não pode alterar esse pai e o membro ParentObject da estrutura WDF_OBJECT_ATTRIBUTES deve ser NULL. A estrutura exclui cada objeto de dispositivo de estrutura (exceto alguns objetos de dispositivo de controle) quando o gerenciador de Plug and Play (PnP) determina que o dispositivo foi removido.

Se o driver fornecer funções de retorno de chamada EvtCleanupCallback ou EvtDestroyCallback para o objeto de dispositivo de estrutura, observe que a estrutura chama essas funções de retorno de chamada em IRQL = PASSIVE_LEVEL.

Para obter mais informações sobre como criar objetos de dispositivo, consulte Criando um objeto de dispositivo de estrutura.

Exemplos

O exemplo de código a seguir mostra como uma função de retorno de chamada EvtDriverDeviceAdd pode inicializar e criar um objeto de 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;
}

Requisitos

Requisito	Valor
Plataforma de Destino	Universal
Versão mínima do KMDF	1.0
Versão mínima do UMDF	2,0
Cabeçalho	wdfdevice.h (inclua Wdf.h)
Biblioteca	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
Regras de conformidade da 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)