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

Artigo
03/08/2023

A rotina de retorno de chamada executa ações, depois que um InterruptService retorna, de um DPC encadeado,

A rotina CustomDpc conclui a manutenção de uma operação de E/S, após o retorno de uma rotina InterruptService .

A rotina CustomThreadedDpc executa a ação de um DPC encadeado. O sistema executa essa rotina quando o DPC encadeado é executado.

A rotina CustomTimerDpc é executada depois que o intervalo de tempo de um objeto de temporizador expira.

Sintaxe

KDEFERRED_ROUTINE KdeferredRoutine;

void KdeferredRoutine(
  [in]           _KDPC *Dpc,
  [in, optional] PVOID DeferredContext,
  [in, optional] PVOID SystemArgument1,
  [in, optional] PVOID SystemArgument2
)
{...}

Parâmetros

[in] Dpc

Ponteiro fornecido pelo chamador para uma estrutura KDPC , que representa o objeto DPC associado a essa rotina de retorno de chamada.

[in, optional] DeferredContext

Para CustomDpc, um ponteiro fornecido pelo chamador para informações de contexto definidas pelo driver que foi especificado em uma chamada anterior para KeInitializeDpc.

Para CustomThreadedDpc, especifica informações de contexto definidas pelo driver. Quando inicializou o objeto DPC, o driver forneceu esse valor como o parâmetro DeferredContext para KeInitializeThreadedDpc.

Ponteiro fornecido pelo chamador para uma estrutura KDPC , que representa o objeto DPC associado a essa rotina CustomTimerDpc .

[in, optional] SystemArgument1

Ponteiro fornecido pelo chamador para informações fornecidas pelo driver que foram especificadas em uma chamada anterior para KeInsertQueueDpc. Quando adicionou o DPC à fila DPC, o driver forneceu esse valor como o parâmetro SystemArgument1 para KeInsertQueueDpc.

Para CustomTimerDpc, esse valor não é usado.

[in, optional] SystemArgument2

Especifica informações de contexto definidas pelo driver. Quando adicionou o DPC à fila DPC, o driver forneceu esse valor como o parâmetro SystemArgument2 para KeInsertQueueDpc.

Para CustomTimerDpc, esse valor não é usado.

Retornar valor

Nenhum

Comentários

Para criar um objeto DPC e registrar uma rotina CustomDpc para esse objeto, um driver deve chamar KeInitializeDpc. (Se você precisar apenas de uma rotina DPC, poderá usar uma rotina DpcForIsr e o objeto DPC alocado pelo sistema.)

Para enfileirar uma rotina CustomDpc para execução, a rotina InterruptService de um driver deve chamar KeInsertQueueDpc.

Uma ou mais rotinas CustomDpc podem ser usadas em vez de, ou em conjunto com, uma rotina DpcForIsr . Um driver que mantém várias filas internas do IRP normalmente fornece uma rotina CustomDpc para cada fila. Cada rotina CustomDpc normalmente é responsável por pelo menos as seguintes tarefas:

Concluindo a operação de E/S descrita pelo IRP atual.
Desempacotando o próximo IRP de uma das filas IRP do driver. (Drivers que usam a fila IRP fornecida pelo sistema junto com uma chamada de rotina StartIo IoStartNextPacket.)
Definir o bloco de E/S status no IRP atual e chamar IoCompleteRequest para a solicitação concluída.

Uma rotina CustomDpc também pode repetir uma operação com falha ou configurar a próxima transferência para uma solicitação de E/S grande que foi dividida em partes menores.

Para obter mais informações sobre rotinas CustomDpc , consulte DPC Objects and DPCs.

Um driver registra um CustomThreadedDpc para um objeto DPC chamando KeInitializeThreadedDpc. Para realmente adicionar o DPC à fila DPC para que a rotina CustomThreadedDpc seja executada, chame KeInsertQueueDpc.

Para obter mais informações sobre como usar rotinas CustomThreadedDpc , consulte Introdução aos DPCs encadeados.

Uma rotina CustomThreadedDpc pode ser executada em IRQL = DISPATCH_LEVEL ou pode ser executada em IRQL = PASSIVE_LEVEL em um thread em tempo real.

Para criar um objeto DPC e registrar uma rotina CustomTimerDpc para esse objeto, um driver deve chamar KeInitializeDpc.

Para enfileirar uma rotina CustomTimerDpc para execução, uma rotina de driver deve chamar KeSetTimer ou KeSetTimerEx, fornecendo um ponteiro de objeto DPC retornado por KeInitializeDpc. O sistema chama a rotina CustomTimerDpc quando o intervalo do temporizador expira.

Para obter mais informações sobre rotinas CustomTimerDpc , consulte Objetos do Temporizador e DPCs.

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 CustomDpc chamada MyCustomDpc, use o tipo KDEFERRED_ROUTINE conforme mostrado neste exemplo de código:

KDEFERRED_ROUTINE MyCustomDpc;

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

_Use_decl_annotations_
VOID
  MyCustomDpc(
    struct _KDPC  *Dpc,
    PVOID  DeferredContext,
    PVOID  SystemArgument1,
    PVOID  SystemArgument2
    )
  {
      // Function body
  }