DRIVER_CONTROL función de devolución de llamada (wdm.h)
Esta rutina inicia una transferencia de datos DMA o una operación de transferencia de datos.
Sintaxis
DRIVER_CONTROL DriverControl;
IO_ALLOCATION_ACTION DriverControl(
[in] _DEVICE_OBJECT *DeviceObject,
[in, out] _IRP *Irp,
[in] PVOID MapRegisterBase,
[in] PVOID Context
)
{...}
Parámetros
[in] 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 previamente por la rutina de addDevice del controlador.
[in, out] Irp
Puntero proporcionado por el autor de la llamada a una estructura irP de. irp es igual al valor del miembro CurrentIrp de de DeviceObject cuando se registró la rutina de devolución de llamada.
[in] MapRegisterBase
En el caso de AdapterControl, se trata de un valor opaco proporcionado por el autor de la llamada que representa los registros de mapa que el sistema ha asignado para esta operación de transferencia. El controlador pasa este valor a FlushAdapterBuffers, FreeMapRegistersy MapTransfer.
En el caso de ControllerControl, no se usa .
[in] Context
Puntero proporcionado por el autor de la llamada a la información de contexto definida por el controlador, especificada en una llamada anterior a AllocateAdapterChannel.
Valor devuelto
La rutina debe devolver uno de los valores definidos por la enumeración IO_ALLOCATION_ACTION. Los controladores de dispositivos bus-master devuelven DeallocateObject o DeallocateObjectKeepRegisters; controladores que usan la devolución de DMA del sistema KeepObject.
Observaciones
Para registrar una rutina de AdapterControl para un objeto de dispositivo específico, un controlador debe llamar a ioGetDmaAdapter para obtener un objeto de adaptador y, a continuación, llamar a AllocateAdapterChannel para solicitar el uso del adaptador y proporcionar la dirección del AdapterControl rutina. Cuando el adaptador está libre, el sistema llama a la rutina AdapterControl.
Si AdapterControl se ha registrado mediante una rutina StartIo, se garantiza que el parámetro irp de apunte al IRP que está procesando actualmente la rutina StartIo. De lo contrario, los controladores deben establecer el miembro CurrentIrp de la estructura de objetos de dispositivo antes de llamar a AllocateAdapterChannel.
Para obtener información detallada sobre cómo implementar una rutina de AdapterControl de, consulte Escritura de rutinas adapterControl.
La rutina controllerControl de un controlador se ejecuta en un contexto arbitrario de subprocesos en IRQL = DISPATCH_LEVEL.
Para registrar una rutina de ControllerControl para un objeto de dispositivo específico, un controlador debe llamar a IoCreateController para obtener un objeto de controlador y, a continuación, llamar a IoAllocateController para solicitar el uso del controlador y proporcionar la dirección de ControllerControl rutina. Cuando el controlador está libre, el sistema llama a la rutina ControllerControl.
Para obtener información detallada sobre cómo implementar una rutina de ControllerControl, consulte Escritura de rutinas controllerControl. Consulte también objetos de controlador.
El tipo de función DRIVER_CONTROL 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 la anotación _Use_decl_annotations_ a la definición de función. La anotación _Use_decl_annotations_ garantiza que se usen las anotaciones que se aplican al tipo de función DRIVER_CONTROL 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.
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 de AdapterControl denominada MyAdapterControl, use el tipo DRIVER_CONTROL tal como se muestra en este ejemplo de código:
DRIVER_CONTROL MyAdapterControl;
A continuación, implemente la rutina de devolución de llamada de la siguiente manera:
_Use_decl_annotations_
IO_ALLOCATION_ACTION
MyAdapterControl(
struct _DEVICE_OBJECT *DeviceObject,
struct _IRP *Irp,
PVOID MapRegisterBase,
PVOID Context
)
{
// Function body
}
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 DISPATCH_LEVEL. |