Função WdfDriverCreate (wdfdriver.h)

Artigo
08/08/2023

[Aplica-se a KMDF e UMDF]

O método WdfDriverCreate cria um objeto de driver de estrutura para o driver de chamada.

Sintaxe

NTSTATUS WdfDriverCreate(
  [in]            PDRIVER_OBJECT         DriverObject,
  [in]            PCUNICODE_STRING       RegistryPath,
  [in, optional]  PWDF_OBJECT_ATTRIBUTES DriverAttributes,
  [in]            PWDF_DRIVER_CONFIG     DriverConfig,
  [out, optional] WDFDRIVER              *Driver
);

Parâmetros

[in] DriverObject

Um ponteiro para uma estrutura DRIVER_OBJECT que representa um objeto de driver WDM (Modelo de Driver do Windows). O driver recebe esse ponteiro como entrada para sua rotina driverEntry .

[in] RegistryPath

Um ponteiro para uma estrutura UNICODE_STRING que contém a cadeia de caracteres de caminho do Registro que o driver recebeu como entrada para sua rotina driverEntry .

[in, optional] DriverAttributes

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

[in] DriverConfig

Um ponteiro para uma estrutura de WDF_DRIVER_CONFIG alocada pelo chamador.

[out, optional] Driver

Um ponteiro para um local que recebe um identificador para o novo objeto de driver de estrutura. Esse parâmetro é opcional e pode ser WDF_NO_HANDLE.

Retornar valor

WdfDriverCreate retornará STATUS_SUCCESS se a operação for bem-sucedida. Caso contrário, esse método poderá retornar um dos seguintes valores:

Código de retorno	Descrição
STATUS_DRIVER_INTERNAL_ERROR	O driver chamado WdfDriverCriar mais de uma vez.
STATUS_INVALID_PARAMETER	Um driver PnP (não Plug and Play) especificou uma função de retorno de chamada EvtDriverDeviceAdd.

Para obter mais informações sobre valores retornados, consulte Erros de criação de objeto da estrutura.

Esse método também pode retornar outros valores NTSTATUS.

Um bug do sistema marcar ocorrerá se o parâmetro DriverObject, RegistryPath ou DriverConfig for NULL.

Comentários

Um driver que usa Kernel-Mode Driver Framework deve chamar WdfDriverCreate de dentro de sua rotina driverEntry , antes de chamar qualquer outra rotina de estrutura. Para obter mais informações sobre DriverEntry, consulte DriverEntry for Framework-based Drivers.

Antes que o driver chame WdfDriverCreate, o driver deve chamar WDF_DRIVER_CONFIG_INIT para inicializar sua estrutura de WDF_DRIVER_CONFIG .

O objeto de driver de estrutura é a parte superior da árvore de objetos de estrutura do driver e, portanto, não tem um objeto pai.

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

Exemplos

O exemplo de código a seguir é uma rotina DriverEntry que inicializa uma estrutura WDF_DRIVER_CONFIG e cria um objeto de driver de estrutura.

NTSTATUS
DriverEntry(
    IN PDRIVER_OBJECT  DriverObject,
    IN PUNICODE_STRING  RegistryPath
    )
{
    WDF_DRIVER_CONFIG  config;
    NTSTATUS  status = STATUS_SUCCESS;

    WDF_DRIVER_CONFIG_INIT(
                           &config,
                           MyEvtDeviceAdd
                           );
    config.EvtDriverUnload = MyEvtDriverUnload;
    status = WdfDriverCreate(
                             DriverObject,
                             RegistryPath,
                             WDF_NO_OBJECT_ATTRIBUTES,
                              &config,
                             WDF_NO_HANDLE
                             );
    if (!NT_SUCCESS(status)) {
        TraceEvents(
                    TRACE_LEVEL_ERROR,
                    DBG_PNP,
                    "WdfDriverCreate failed with status %!STATUS!",
                    status
                    );
    }
    return status;
}

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	wdfdriver.h (inclua Wdf.h)
Biblioteca	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
Regras de conformidade de DDI	ChangeQueueState(kmdf), DriverAttributeChanged(kmdf), DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), MiniportOnlyWdmDevice(kmdf)