KDEFERRED_ROUTINE función de devolución de llamada (wdm.h)

Artículo
03/08/2023

La rutina de devolución de llamada realiza acciones, después de que un InterruptService devuelva, de un DPC subproceso,

La rutina CustomDpc finaliza el mantenimiento de una operación de E/S, después de que se devuelva una rutina InterruptService .

La rutina CustomThreadedDpc realiza la acción de un DPC subproceso. El sistema ejecuta esta rutina cuando se ejecuta el DPC subproceso.

La rutina CustomTimerDpc se ejecuta después de que expire el intervalo de tiempo de un objeto de temporizador.

Sintaxis

KDEFERRED_ROUTINE KdeferredRoutine;

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

Parámetros

[in] Dpc

Puntero proporcionado por el autor de la llamada a una estructura KDPC , que representa el objeto DPC asociado a esta rutina de devolución de llamada.

[in, optional] DeferredContext

Para CustomDpc, un puntero proporcionado por el autor de la llamada a la información de contexto definida por el controlador que se especificó en una llamada anterior a KeInitializeDpc.

En CustomThreadedDpc, especifica información de contexto definida por el controlador. Cuando inicializó el objeto DPC, el controlador proporcionó este valor como parámetro DeferredContext a KeInitializeThreadedDpc.

Puntero proporcionado por el autor de la llamada a una estructura KDPC , que representa el objeto DPC asociado a esta rutina CustomTimerDpc .

[in, optional] SystemArgument1

Puntero proporcionado por el autor de la llamada a la información proporcionada por el controlador que se especificó en una llamada anterior a KeInsertQueueDpc. Cuando agregó el DPC a la cola DPC, el controlador proporcionó este valor como el parámetro SystemArgument1 a KeInsertQueueDpc.

Para CustomTimerDpc, este valor no se usa.

[in, optional] SystemArgument2

Especifica información de contexto definida por el controlador. Cuando agregó el DPC a la cola DPC, el controlador proporcionó este valor como el parámetro SystemArgument2 a KeInsertQueueDpc.

Para CustomTimerDpc, este valor no se usa.

Valor devuelto

None

Observaciones

Para crear un objeto DPC y registrar una rutina CustomDpc para ese objeto, un controlador debe llamar a KeInitializeDpc. (Si solo necesita una rutina DPC, puede usar una rutina DpcForIsr y el objeto DPC asignado por el sistema).

Para poner en cola una rutina CustomDpc para su ejecución, la rutina InterruptService de un controlador debe llamar a KeInsertQueueDpc.

Se pueden usar una o varias rutinas customDpc en lugar de, o junto con, una rutina DpcForIsr . Un controlador que mantiene varias colas IRP internas normalmente proporciona una rutina CustomDpc para cada cola. Cada rutina customDpc suele ser responsable de al menos las siguientes tareas:

Completar la operación de E/S descrita por el IRP actual.
Poner en cola el siguiente IRP de una de las colas irP del controlador. (Los controladores que usan la cola irP proporcionada por el sistema junto con una rutina StartIo llaman a IoStartNextPacket).
Establecer el bloque de estado de E/S en el IRP actual y llamar a IoCompleteRequest para la solicitud completada.

Una rutina CustomDpc también podría reintentar una operación con errores o configurar la siguiente transferencia para una solicitud de E/S grande que se ha dividido en partes más pequeñas.

Para obtener más información sobre las rutinas customDpc , vea Objetos DPC y DPC.

Un controlador registra un CustomThreadedDpc para un objeto DPC llamando a KeInitializeThreadedDpc. Para agregar realmente el DPC a la cola DPC para que se ejecute la rutina CustomThreadedDpc , llame a KeInsertQueueDpc.

Para obtener más información sobre el uso de rutinas CustomThreadedDpc , vea Introduction to Threaded DPCs.

Una rutina CustomThreadedDpc se puede ejecutar en IRQL = DISPATCH_LEVEL, o bien puede ejecutarse en IRQL = PASSIVE_LEVEL en un subproceso en tiempo real.

Para crear un objeto DPC y registrar una rutina CustomTimerDpc para ese objeto, un controlador debe llamar a KeInitializeDpc.

Para poner en cola una rutina CustomTimerDpc para su ejecución, una rutina de controlador debe llamar a KeSetTimer o KeSetTimerEx, proporcionando un puntero de objeto DPC devuelto por KeInitializeDpc. El sistema llama a la rutina CustomTimerDpc cuando expira el intervalo del temporizador.

Para obtener más información sobre las rutinas customTimerDpc , vea Objetos de temporizador y DPC.

Ejemplos

Para definir una rutina de devolución de llamada, primero debe proporcionar una declaración de función que identifique el tipo de rutina de devolución de llamada que está definiendo. Windows proporciona un conjunto de tipos de función de devolución de llamada para controladores. Declarar una función mediante los tipos de función de devolución de llamada ayuda a Code Analysis for Drivers, Static Driver Verifier (SDV) y otras herramientas de comprobación encuentran errores y es un requisito para escribir controladores para el sistema operativo Windows.

Por ejemplo, para definir una rutina de devolución de llamada customDpc denominada MyCustomDpc, use el tipo KDEFERRED_ROUTINE como se muestra en este ejemplo de código:

KDEFERRED_ROUTINE MyCustomDpc;

A continuación, implemente la rutina de devolución de llamada de la siguiente manera:

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