DRIVER_INITIALIZE função de retorno de chamada (wdm.h)
DRIVER_INITIALIZE é a definição de tipo do ponto de entrada de inicialização do driver, que é denominado convencionalmente DriverEntry. Essa é a primeira rotina chamada depois que um driver é carregado.
Sintaxe
DRIVER_INITIALIZE DriverInitialize;
NTSTATUS DriverInitialize(
[in] _DRIVER_OBJECT *DriverObject,
[in] PUNICODE_STRING RegistryPath
)
{...}
Parâmetros
[in] DriverObject
Um ponteiro para a estrutura de DRIVER_OBJECT do driver.
[in] RegistryPath
Um ponteiro para uma cadeia de caracteres Unicode contada especificando o caminho para a chave do Registro do driver.
Valor de retorno
Se a rotina for bem-sucedida, ela deverá retornar STATUS_SUCCESS. Caso contrário, ele deverá retornar um dos valores de status de erro definidos em Ntstatus.h.
Observações
O parâmetro DriverObject fornece a rotina DriverEntry com um ponteiro para o objeto de driver do driver, que é alocado pelo gerente de E/S. A rotina DriverEntry deve preencher o objeto driver com pontos de entrada para as rotinas padrão do driver.
O ponteiro DriverObject fornece ao driver acesso ao DriverObject->HardwareDatabase, que aponta para uma cadeia de caracteres Unicode contada que especifica um caminho para a árvore de \Registry\Machine\Hardware do registro.
A cadeia de caracteres de caminho do Registro apontada pelo RegistryPath é do formulário \Registry\Machine\System\CurrentControlSet\Services\DriverName. Um driver pode usar esse caminho para armazenar informações específicas do driver; consulte Chaves do Registro para Drivers. A rotina DriverEntry deve salvar uma cópia da cadeia de caracteres Unicode, não o ponteiro, já que o gerenciador de E/S libera o buffer de RegistryPath após driverEntry retorna.
Para obter mais informações sobre como implementar uma rotina de do DriverEntry, consulte Escrevendo umde Rotina de DriverEntry.
Embora seja possível nomear essa rotina como algo diferente de driverEntry, não é recomendável fazer isso. As ferramentas de build fornecidas pelo DDK informam automaticamente ao vinculador que o ponto de entrada do driver é chamado DriverEntry, portanto, dar à rotina outro nome exige que você modifique as ferramentas de build. Para obter mais informações sobre ferramentas de build, consulte Criando um driver.
Exemplos
Para definir uma rotina de retorno de chamada DriverEntry, primeiro você deve fornecer uma declaração de função que identifique o tipo de rotina de retorno de chamada que você está definindo. O Windows fornece um conjunto de tipos de função de retorno de chamada para drivers. Declarar uma função usando os tipos de função de retorno de chamada ajuda a Análise de Código para Drivers, SDV (Verificador de Driver Estático) e outras ferramentas de verificação encontram erros.
Para definir uma rotina de retorno de chamada DriverEntry, use o tipo DRIVER_INITIALIZE, conforme mostrado neste exemplo de código:
DRIVER_INITIALIZE DriverEntry;
Em seguida, implemente sua rotina de retorno de chamada da seguinte maneira:
_Use_decl_annotations_
NTSTATUS
DriverEntry(
struct _DRIVER_OBJECT *DriverObject,
PUNICODE_STRING RegistryPath
)
{
// Function body
}
O tipo de função DRIVER_INITIALIZE é definido no arquivo de cabeçalho Wdm.h. Para identificar erros com mais precisão ao executar as ferramentas de análise de código, adicione a anotação _Use_decl_annotations_
à sua definição de função. A anotação _Use_decl_annotations_
garante que as anotações aplicadas ao tipo de função DRIVER_INITIALIZE no arquivo de cabeçalho sejam usadas. Para obter mais informações sobre os requisitos para declarações de função, consulte Declarando funções usando tipos de função de função para drivers WDM. Para obter informações sobre _Use_decl_annotations_
, consulte Anotando o comportamento da função.
Requisitos
Requisito | Valor |
---|---|
da Plataforma de Destino | Área de trabalho |
cabeçalho | wdm.h (incluem Mcd.h, Ntddk.h, Ntifs.h, Wudfwdm.h) |
IRQL | Chamado no PASSIVE_LEVEL. |