Compartir a través de

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

  • Artículo

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.

IRP Acerca de la implementación de la devolución de llamada
IRP_MJ_CLEANUP La rutina DispatchCleanup de un controlador debe denominarse XxxDispatchCleanup, donde Xxx es un prefijo específico del controlador. La rutina DriverEntry del controlador debe almacenar la dirección de la rutina DispatchCleanup en DriverObject-MajorFunction>[IRP_MJ_CLEANUP].
IRP_MJ_CLOSE La rutina DispatchClose de un controlador debe denominarse XxxDispatchClose, donde Xxx es un prefijo específico del controlador. La rutina DriverEntry del controlador debe almacenar la dirección de la rutina DispatchClose en DriverObject-MajorFunction>[IRP_MJ_CLOSE].
IRP_MJ_CREATE La rutina DispatchCreate de un controlador debe denominarse XxxDispatchCreate, donde Xxx es un prefijo específico del controlador. La rutina DriverEntry del controlador debe almacenar la dirección de la rutina DispatchCreate en DriverObject-MajorFunction>[IRP_MJ_CREATE].
IRP_MJ_CREATE o IRP_MJ_CLOSE Un controlador puede proporcionar una sola rutina DispatchCreateClose en lugar de rutinas DispatchCreate y DispatchClose independientes.

La rutina DispatchCreateClose de un controlador debe denominarse XxxDispatchCreateClose, donde Xxx es un prefijo específico del controlador. La rutina DriverEntry del controlador debe almacenar la dirección de la rutina DispatchCreateClose en DriverObject-MajorFunction>[IRP_MJ_CREATE] y enDriverObject-MajorFunction>[IRP_MJ_CLOSE].
IRP_MJ_DEVICE_CONTROL La rutina DispatchDeviceControl de un controlador debe denominarse XxxDispatchDeviceControl, donde Xxx es un prefijo específico del controlador. La rutina DriverEntry del controlador debe almacenar la dirección de la rutina DispatchDeviceControl en DriverObject-MajorFunction>[IRP_MJ_DEVICE_CONTROL].

El sistema usa las marcas FILE_XXX en el código de control de E/S para determinar si el remitente irP tiene los privilegios para enviar el IRP al objeto de dispositivo. Los controladores para Windows Server 2003 y versiones posteriores de Windows pueden usar la rutina IoValidateDeviceIoControlAccess para realizar comprobaciones de acceso más estrictas en DispatchDeviceControl.
IRP_MJ_FLUSH_BUFFERS La rutina DispatchFlushBuffers de un controlador debe denominarse XxxDispatchFlushBuffers, donde Xxx es un prefijo específico del controlador. La rutina DriverEntry del controlador debe almacenar la dirección de la rutina DispatchFlushBuffers en DriverObject-MajorFunction>[IRP_MJ_FLUSH_BUFFERS].
IRP_MJ_INTERNAL_DEVICE_CONTROL La rutina DispatchInternalDeviceControl de un controlador debe denominarse XxxDispatchInternalDeviceControl, donde Xxx es un prefijo específico del controlador. La rutina DriverEntry del controlador debe almacenar la dirección de la rutina DispatchInternalDeviceControl en DriverObject-MajorFunction>[IRP_MJ_INTERNAL_DEVICE_CONTROL].
IRP_MJ_PNP La rutina DispatchPnP de un controlador debe denominarse XxxDispatchPnP, donde Xxx es un prefijo específico del controlador. La rutina DriverEntry del controlador debe almacenar la dirección de la rutina DispatchPnP en DriverObject-MajorFunction>[IRP_MJ_PNP].
IRP_MJ_POWER La rutina DispatchPower de un controlador debe denominarse XxxDispatchPower, donde Xxx es un prefijo específico del controlador. La rutina DriverEntry del controlador debe almacenar la dirección de la rutina DispatchPower en DriverObject-MajorFunction>[IRP_MJ_POWER].
IRP_MJ_QUERY_INFORMATION La rutina DispatchQueryInformation de un controlador debe denominarse XxxDispatchQueryInformation, donde Xxx es un prefijo específico del controlador. La rutina DriverEntry del controlador debe almacenar la dirección de la rutina DispatchQueryInformation en DriverObject-MajorFunction>[IRP_MJ_QUERY_INFORMATION].
IRP_MJ_READ La rutina DispatchRead de un controlador debe denominarse XxxDispatchRead, donde Xxx es un prefijo específico del controlador. La rutina DriverEntry del controlador debe almacenar la dirección de la rutina DispatchRead en DriverObject-MajorFunction>[IRP_MJ_READ].
IRP_MJ_READ o IRP_MJ_WRITE Un controlador puede proporcionar una sola rutina DispatchReadWrite en lugar de rutinas de DispatchRead y DispatchWrite independientes.

La rutina DispatchReadWrite de un controlador debe denominarse XxxDispatchReadWrite, donde Xxx es un prefijo específico del controlador. La rutina DriverEntry del controlador debe almacenar la dirección de la rutina DispatchReadWrite en DriverObject-MajorFunction>[IRP_MJ_READ] y enDriverObject-MajorFunction>[IRP_MJ_WRITE].
IRP_MJ_SET_INFORMATION La rutina DispatchSetInformation de un controlador debe denominarse XxxDispatchSetInformation, donde Xxx es un prefijo específico del controlador. La rutina DriverEntry del controlador debe almacenar la dirección de la rutina DispatchSetInformation en DriverObject-MajorFunction>[IRP_MJ_SET_INFORMATION].
IRP_MJ_SHUTDOWN La rutina DispatchShutdown de un controlador debe denominarse XxxDispatchShutdown, donde Xxx es un prefijo específico del controlador. La rutina DriverEntry del controlador debe almacenar la dirección de la rutina DispatchShutdown en DriverObject-MajorFunction>[IRP_MJ_SHUTDOWN].

Además, para recibir solicitudes de IRP_MJ_SHUTDOWN , un controlador debe llamar a IoRegisterShutdownNotification o IoRegisterLastChanceShutdownNotification para registrar su rutina DispatchShutdown con el sistema.
IRP_MJ_SYSTEM_CONTROL La rutina DispatchSystemControl de un controlador debe denominarse XxxDispatchSystemControl, donde Xxx es un prefijo específico del controlador. La rutina DriverEntry del controlador debe almacenar la dirección de la rutina DispatchSystemControl en DriverObject-MajorFunction>[IRP_MJ_SYSTEM_CONTROL].
IRP_MJ_WRITE La rutina DispatchWrite de un controlador debe denominarse XxxDispatchWrite, donde Xxx es un prefijo específico del controlador. La rutina DriverEntry del controlador debe almacenar la dirección de la rutina DispatchWrite en DriverObject-MajorFunction>[IRP_MJ_WRITE].

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

Requisito Value
Plataforma de destino Escritorio
Encabezado wdm.h (incluya Wdm.h, Ntddk.h, Ntifs.h)
IRQL Se llama en PASSIVE_LEVEL (consulte la sección Comentarios).