DRIVER_DISPATCH função de retorno de chamada (wdm.h)

  • Artigo

A rotina de retorno de chamada atende a vários IRPs. Para obter uma lista de códigos de função, consulte Comentários.

Sintaxe

DRIVER_DISPATCH DriverDispatch;

NTSTATUS DriverDispatch(
  [in, out] _DEVICE_OBJECT *DeviceObject,
  [in, out] _IRP *Irp
)
{...}

Parâmetros

[in, out] DeviceObject

Ponteiro fornecido pelo chamador para uma estrutura DEVICE_OBJECT . Esse é o objeto de dispositivo para o dispositivo de destino, criado anteriormente pela rotina AddDevice do driver.

[in, out] Irp

Ponteiro fornecido pelo chamador para uma estrutura IRP que descreve a operação de E/S solicitada.

Retornar valor

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.

Comentários

Os parâmetros de entrada para todas as rotinas de expedição são fornecidos na estrutura IRP apontada pelo Irp. Parâmetros adicionais são fornecidos no local de pilha de E/S associado do driver, que é descrito pela estrutura IO_STACK_LOCATION e pode ser obtido chamando IoGetCurrentIrpStackLocation.

Geralmente, todas as rotinas de expedição são executadas em um contexto de thread arbitrário em IRQL = PASSIVE_LEVEL, mas há exceções. Para obter mais informações, consulte Rotinas de expedição e IRQLs.

Para obter mais informações sobre rotinas de expedição, consulte Escrevendo rotinas de expedição. Para obter mais informações sobre IRPs, consulte Manipulando IRPs.

IRP Sobre a implementação do retorno de chamada
IRP_MJ_CLEANUP A rotina DispatchCleanup de um driver deve ser denominada XxxDispatchCleanup, em que Xxx é um prefixo específico do driver. A rotina DriverEntry do driver deve armazenar o endereço da rotina DispatchCleanup em DriverObject-MajorFunction>[IRP_MJ_CLEANUP].
IRP_MJ_CLOSE A rotina DispatchClose de um driver deve ser chamada xxxDispatchClose, em que Xxx é um prefixo específico do driver. A rotina DriverEntry do driver deve armazenar o endereço da rotina DispatchClose em DriverObject-MajorFunction>[IRP_MJ_CLOSE].
IRP_MJ_CREATE A rotina DispatchCreate de um driver deve ser denominada XxxDispatchCreate, em que Xxx é um prefixo específico do driver. A rotina DriverEntry do driver deve armazenar o endereço da rotina DispatchCreate em DriverObject-MajorFunction>[IRP_MJ_CREATE].
IRP_MJ_CREATE ou IRP_MJ_CLOSE Um driver pode fornecer uma única rotina DispatchCreateClose em vez de rotinas separadas DispatchCreate e DispatchClose .

A rotina DispatchCreateClose de um driver deve ser denominada XxxDispatchCreateClose, em que Xxx é um prefixo específico do driver. A rotina DriverEntry do driver deve armazenar o endereço da rotina DispatchCreateClose em DriverObject-MajorFunction>[IRP_MJ_CREATE] e emDriverObject-MajorFunction>[IRP_MJ_CLOSE].
IRP_MJ_DEVICE_CONTROL A rotina DispatchDeviceControl de um driver deve ser denominada XxxDispatchDeviceControl, em que Xxx é um prefixo específico do driver. A rotina DriverEntry do driver deve armazenar o endereço da rotina DispatchDeviceControl em DriverObject-MajorFunction>[IRP_MJ_DEVICE_CONTROL].

O sistema usa os sinalizadores FILE_XXX no código de controle de E/S para determinar se o remetente IRP tem os privilégios para enviar o IRP para o objeto do dispositivo. Drivers para Windows Server 2003 e versões posteriores do Windows podem usar a rotina IoValidateDeviceIoControlAccess para executar verificações de acesso mais rigorosas no DispatchDeviceControl.
IRP_MJ_FLUSH_BUFFERS A rotina DispatchFlushBuffers de um driver deve ser denominada XxxDispatchFlushBuffers, em que Xxx é um prefixo específico do driver. A rotina DriverEntry do driver deve armazenar o endereço da rotina DispatchFlushBuffers em DriverObject-MajorFunction>[IRP_MJ_FLUSH_BUFFERS].
IRP_MJ_INTERNAL_DEVICE_CONTROL A rotina DispatchInternalDeviceControl de um driver deve ser denominada XxxDispatchInternalDeviceControl, em que Xxx é um prefixo específico do driver. A rotina DriverEntry do driver deve armazenar o endereço da rotina DispatchInternalDeviceControl em DriverObject-MajorFunction>[IRP_MJ_INTERNAL_DEVICE_CONTROL].
IRP_MJ_PNP A rotina DispatchPnP de um driver deve ser denominada XxxDispatchPnP, em que Xxx é um prefixo específico do driver. A rotina DriverEntry do driver deve armazenar o endereço da rotina DispatchPnP em DriverObject-MajorFunction>[IRP_MJ_PNP].
IRP_MJ_POWER A rotina DispatchPower de um driver deve ser chamada xxxDispatchPower, em que Xxx é um prefixo específico do driver. A rotina DriverEntry do driver deve armazenar o endereço da rotina DispatchPower em DriverObject-MajorFunction>[IRP_MJ_POWER].
IRP_MJ_QUERY_INFORMATION A rotina DispatchQueryInformation de um driver deve ser denominada XxxDispatchQueryInformation, em que Xxx é um prefixo específico do driver. A rotina DriverEntry do driver deve armazenar o endereço da rotina DispatchQueryInformation em DriverObject-MajorFunction>[IRP_MJ_QUERY_INFORMATION].
IRP_MJ_READ A rotina DispatchRead de um driver deve ser denominada XxxDispatchRead, em que Xxx é um prefixo específico do driver. A rotina DriverEntry do driver deve armazenar o endereço da rotina DispatchRead em DriverObject-MajorFunction>[IRP_MJ_READ].
IRP_MJ_READ ou IRP_MJ_WRITE Um driver pode fornecer uma única rotina DispatchReadWrite em vez de rotinas separadas de DispatchRead e DispatchWrite .

A rotina DispatchReadWrite de um driver deve ser chamada xxxDispatchReadWrite, em que Xxx é um prefixo específico do driver. A rotina DriverEntry do driver deve armazenar o endereço da rotina DispatchReadWrite em DriverObject-MajorFunction>[IRP_MJ_READ] e emDriverObject-MajorFunction>[IRP_MJ_WRITE].
IRP_MJ_SET_INFORMATION A rotina DispatchSetInformation de um driver deve ser chamada xxxDispatchSetInformation, em que Xxx é um prefixo específico do driver. A rotina DriverEntry do driver deve armazenar o endereço da rotina DispatchSetInformation em DriverObject-MajorFunction>[IRP_MJ_SET_INFORMATION].
IRP_MJ_SHUTDOWN A rotina DispatchShutdown de um driver deve ser denominada XxxDispatchShutdown, em que Xxx é um prefixo específico do driver. A rotina DriverEntry do driver deve armazenar o endereço da rotina DispatchShutdown em DriverObject-MajorFunction>[IRP_MJ_SHUTDOWN].

Além disso, para receber IRP_MJ_SHUTDOWN solicitações, um driver deve chamar IoRegisterShutdownNotification ou IoRegisterLastChanceShutdownNotification para registrar sua rotina DispatchShutdown com o sistema.
IRP_MJ_SYSTEM_CONTROL A rotina DispatchSystemControl de um driver deve ser chamada xxxDispatchSystemControl, em que Xxx é um prefixo específico do driver. A rotina DriverEntry do driver deve armazenar o endereço da rotina DispatchSystemControl em DriverObject-MajorFunction>[IRP_MJ_SYSTEM_CONTROL].
IRP_MJ_WRITE A rotina DispatchWrite de um driver deve ser denominada XxxDispatchWrite, em que Xxx é um prefixo específico do driver. A rotina DriverEntry do driver deve armazenar o endereço da rotina DispatchWrite em DriverObject-MajorFunction>[IRP_MJ_WRITE].

Exemplos

Para definir uma rotina de retorno de chamada, 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 a encontrar erros e é um requisito para gravar drivers para o sistema operacional Windows.

Por exemplo, para definir uma rotina de retorno de chamada DispatchCleanup chamada MyDispatchCleanup, use o tipo DRIVER_DISPATCH conforme mostrado neste exemplo de código:

DRIVER_DISPATCH MyDispatchCleanup;

Em seguida, implemente sua rotina de retorno de chamada da seguinte maneira:

_Use_decl_annotations_
NTSTATUS
  MyDispatchCleanup(
    struct _DEVICE_OBJECT  *DeviceObject,
    struct _IRP  *Irp
    )
  {
      // Function body
  }

O tipo de função DRIVER_DISPATCH é 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 the_Use_decl_annotations_annotation à definição de função. The_Use_decl_annotations_annotation garante que as anotações aplicadas ao tipo de função DRIVER_DISPATCH 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
Plataforma de Destino Área de Trabalho
Cabeçalho wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
IRQL Chamado em PASSIVE_LEVEL (consulte a seção Comentários).