Função WdfDeviceCreate (wdfdevice.h)

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

Valor retornado

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

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 objeto de dispositivo físico (PDO). O tipo de objeto de dispositivo que a função cria depende de como o driver obteve a estrutura WDFDEVICE_INIT:

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 driver da 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 da 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 framework.

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

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

Confira também

WDFDEVICE_INIT

WDF_OBJECT_ATTRIBUTES

WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE

WDF_PNPPOWER_EVENT_CALLBACKS_INIT

WdfDeviceInitFree

WdfDeviceInitSetIoType

WdfDeviceInitSetPnpPowerEventCallbacks

WdfDeviceMiniportCreate