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 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 WdfDeviceInitAssignSDLString 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.
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) |
Confira também
WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE
WDF_PNPPOWER_EVENT_CALLBACKS_INIT