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

Artículo
02/07/2025

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 DEVICE_OBJECT. Este es el objeto de dispositivo para el dispositivo de destino, creado previamente por la rutina de addDevice del controlador.

[in, out] Irp

Puntero proporcionado por el autor de la llamada a una estructura irP de 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.

Observaciones

Los parámetros de entrada para todas las rutinas de Dispatch se proporcionan en la estructura irP de apuntada por Irp. Se proporcionan parámetros adicionales en la ubicación de pila de E/S asociada del controlador, que se describe mediante la estructura IO_STACK_LOCATION y se puede obtener llamando a IoGetCurrentIrpStackLocation.

Por lo general, todas las rutinas de Dispatch 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 IRQLs.

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

IRP	Acerca de la implementación de la devolución de llamada
IRP_MJ_CLEANUP	La rutina de DispatchCleanup de un controlador debe denominarse XxxDispatchClean up, donde Xxx es un prefijo específico del controlador. La rutina del controlador DriverEntry 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 de 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 del controlador DriverEntry 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 única rutina de DispatchCreateClose en lugar de rutinas DispatchCreate y DispatchClose. La rutina DispatchCreateClose de un controlador debe denominarse XxxDispatchCreateClose, donde Xxx es un prefijo específico del controlador. La rutina del controlador DriverEntry debe almacenar la dirección de la rutina DispatchCreateClose en DriverObject->MajorFunction[IRP_MJ_CREATE] y en DriverObject->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 del controlador DriverEntry debe almacenar la dirección de la rutina DispatchDeviceControl en DriverObject->MajorFunction[IRP_MJ_DEVICE_CONTROL]. El sistema usa las marcas deXXX FILE_ 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 de 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 del controlador DriverEntry debe almacenar la dirección de la rutina DispatchFlushBuffers en DriverObject->MajorFunction[IRP_MJ_FLUSH_BUFFERS].
IRP_MJ_INTERNAL_DEVICE_CONTROL	La rutina de DispatchInternalDeviceControl de un controlador debe denominarse XxxDispatchInternalDeviceControl, donde Xxx es un prefijo específico del controlador. La rutina de 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 de DispatchPnP de un controlador debe denominarse XxxDispatchPnP, donde Xxx es un prefijo específico del controlador. La rutina del controlador DriverEntry debe almacenar la dirección de la rutina DispatchPnP en DriverObject>MajorFunction[IRP_MJ_PNP].
IRP_MJ_POWER	La rutina de DispatchPower de un controlador debe denominarse XxxDispatchPower, donde Xxx es un prefijo específico del controlador. La rutina del controlador DriverEntry debe almacenar la dirección de DispatchPower en DriverObject>MajorFunction[IRP_MJ_POWER].
IRP_MJ_QUERY_INFORMATION	La rutina de DispatchQueryInformation de un controlador debe denominarse XxxDispatchQueryInformation, donde Xxx es un prefijo específico del controlador. La rutina del controlador DriverEntry debe almacenar la dirección de la rutina DispatchQueryInformation en DriverObject>MajorFunction[IRP_MJ_QUERY_INFORMATION].
IRP_MJ_READ	La rutina de dispatchRead de un controlador debe denominarse XxxDispatchRead, donde Xxx es un prefijo específico del controlador. La rutina del controlador DriverEntry 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 única rutina de DispatchReadWrite en lugar de rutinas de DispatchRead y DispatchWrite. La rutina de DispatchReadWrite de un controlador debe denominarse XxxDispatchReadWrite, donde Xxx es un prefijo específico del controlador. La rutina de driverEntry del controlador debe almacenar la dirección de la rutina DispatchReadWrite en DriverObject->MajorFunction[IRP_MJ_READ] y en DriverObject>MajorFunction[IRP_MJ_WRITE].
IRP_MJ_SET_INFORMATION	La rutina de DispatchSetInformation de un controlador debe denominarse XxxDispatchSetInformation, donde Xxx es un prefijo específico del controlador. La rutina del controlador DriverEntry 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 del controlador DriverEntry 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 de DispatchShutdown con el sistema.
IRP_MJ_SYSTEM_CONTROL	La rutina de DispatchSystemControl de un controlador debe denominarse XxxDispatchSystemControl, donde Xxx es un prefijo específico del controlador. La rutina del controlador DriverEntry debe almacenar la dirección de la rutina DispatchSystemControl en DriverObject>MajorFunction[IRP_MJ_SYSTEM_CONTROL].
IRP_MJ_WRITE	La rutina de dispatchWrite de un controlador debe denominarse XxxDispatchWrite, donde Xxx es un prefijo específico del controlador. La rutina del controlador DriverEntry 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 va a definir. 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 Análisis de código para controladores, comprobador de controladores estáticos (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 tal 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 mayor 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 rol de función para controladores WDM. Para obtener información sobre Use_decl_annotations, vea Anotación del comportamiento de la función.

Requisitos

Requisito	Valor
de la plataforma de destino de	Escritorio
encabezado de	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
irQL	Se llama en PASSIVE_LEVEL (consulte la sección Comentarios).

Compartir a través de