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

La rutina de devolución de llamada ofrece varios IRP. Para obtener una lista de códigos de función, vea Comentarios.

Sintaxis

DRIVER_DISPATCH DriverDispatch;

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

Parámetros

[in, out] DeviceObject

Puntero proporcionado por el autor de la llamada a una estructura de DEVICE_OBJECT . Este es el objeto de dispositivo para el dispositivo de destino, creado anteriormente por la rutina AddDevice del controlador.

[in, out] Irp

Puntero proporcionado por el autor de la llamada a una estructura IRP que describe la operación de E/S solicitada.

Valor devuelto

Si la rutina se realiza correctamente, debe devolver STATUS_SUCCESS. De lo contrario, debe devolver uno de los valores de estado de error definidos en Ntstatus.h.

Comentarios

Los parámetros de entrada para todas las rutinas dispatch se proporcionan en la estructura IRP a la que apunta Irp. Los parámetros adicionales se proporcionan en la ubicación de pila de E/S asociada del controlador, que se describe en la estructura de IO_STACK_LOCATION y se puede obtener mediante una llamada a IoGetCurrentIrpStackLocation.

Por lo general, todas las rutinas de distribución se ejecutan en un contexto de subproceso arbitrario en IRQL = PASSIVE_LEVEL, pero hay excepciones. Para obtener más información, vea Rutinas de distribución e IRQL.

Para obtener más información sobre las rutinas de envío, vea Escribir rutinas de distribución. Para obtener más información sobre los IRP, consulte Control de IRP.

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 DispatchCleanup denominada MyDispatchCleanup, use el tipo DRIVER_DISPATCH como se muestra en este ejemplo de código:

DRIVER_DISPATCH MyDispatchCleanup;

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

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

El tipo de función DRIVER_DISPATCH se define en el archivo de encabezado Wdm.h. Para identificar con más precisión los errores al ejecutar las herramientas de análisis de código, asegúrese de agregar the_Use_decl_annotations_annotation a la definición de función. The_Use_decl_annotations_annotation garantiza que se usen las anotaciones que se aplican al tipo de función DRIVER_DISPATCH en el archivo de encabezado. Para obtener más información sobre los requisitos de las declaraciones de función, vea Declarar funciones mediante tipos de roles de función para controladores WDM. Para obtener información sobre Use_decl_annotations, consulte Anotación del comportamiento de la función.

Requisitos