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

Essa rotina inicia uma transferência de dados de DMA ou uma operação de transferência de dados.

Sintaxe

DRIVER_CONTROL DriverControl;

IO_ALLOCATION_ACTION DriverControl(
  [in]      _DEVICE_OBJECT *DeviceObject,
  [in, out] _IRP *Irp,
  [in]      PVOID MapRegisterBase,
  [in]      PVOID Context
)
{...}

Parâmetros

[in] 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 . Irp é igual ao valor do membro CurrentIrp de DeviceObject quando a rotina de retorno de chamada foi registrada.

[in] MapRegisterBase

No caso de AdapterControl, esse é um valor opaco fornecido pelo chamador que representa os registros de mapa atribuídos pelo sistema para essa operação de transferência. O driver passa esse valor para FlushAdapterBuffers, FreeMapRegisters e MapTransfer.

No caso de ControllerControl, isso não é usado.

[in] Context

Ponteiro fornecido pelo chamador para informações de contexto definidas pelo driver, especificado em uma chamada anterior para AllocateAdapterChannel.

Retornar valor

A rotina deve retornar um dos valores definidos pela enumeração IO_ALLOCATION_ACTION . Os drivers de dispositivos master de ônibus retornam DeallocateObject ou DeallocateObjectKeepRegisters; os drivers que usam o DMA do sistema retornam KeepObject.

Comentários

Para registrar uma rotina AdapterControl para um objeto de dispositivo específico, um driver deve chamar IoGetDmaAdapter para obter um objeto adaptador e, em seguida, chamar AllocateAdapterChannel para solicitar o uso do adaptador e fornecer o endereço da rotina AdapterControl . Quando o adaptador é gratuito, o sistema chama a rotina AdapterControl .

Se AdapterControl tiver sido registrado por uma rotina StartIo , será garantido que o parâmetro Irp aponte para o IRP atualmente sendo processado pela rotina StartIo . Caso contrário, os drivers devem definir o membro CurrentIrp da estrutura do objeto do dispositivo antes de chamar AllocateAdapterChannel.

Para obter informações detalhadas sobre como implementar uma rotina AdapterControl , consulte Escrevendo rotinas adapterControl.

A rotina ControllerControl de um driver é executada em um contexto de thread arbitrário em IRQL = DISPATCH_LEVEL.

Para registrar uma rotina ControllerControl para um objeto de dispositivo específico, um driver deve chamar IoCreateController para obter um objeto controlador e, em seguida, chamar IoAllocateController para solicitar o uso do controlador e fornecer o endereço da rotina ControllerControl . Quando o controlador é gratuito, o sistema chama a rotina ControllerControl .

Para obter informações detalhadas sobre como implementar uma rotina ControllerControl , consulte Escrevendo rotinas controllercontrol. Consulte também Objetos do Controlador.

O tipo de função DRIVER_CONTROL é 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 _Use_decl_annotations_ anotação à sua definição de função. A _Use_decl_annotations_ anotação garante que as anotações aplicadas ao tipo de função DRIVER_CONTROL 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.

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 AdapterControl chamada MyAdapterControl, use o tipo DRIVER_CONTROL conforme mostrado neste exemplo de código:

DRIVER_CONTROL MyAdapterControl;

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

_Use_decl_annotations_
IO_ALLOCATION_ACTION
 MyAdapterControl(
    struct _DEVICE_OBJECT  *DeviceObject,
    struct _IRP  *Irp,
    PVOID  MapRegisterBase,
    PVOID  Context
    )
  {
      // Function body
  }

Requisitos

Requisito	Valor
Plataforma de Destino	Área de Trabalho
Cabeçalho	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
IRQL	Chamado em DISPATCH_LEVEL.

Confira também

AllocateAdapterChannel