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 anteriormente por la rutina AddDevice del controlador.
[in, out] Irp
Puntero proporcionado por el autor de la llamada a una estructura IRP . Irp es igual al valor del miembro CurrentIrp 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, FreeMapRegisters y MapTransfer.
En el caso de ControllerControl, esto 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 los dispositivos bus-master devuelven DeallocateObject o DeallocateObjectKeepRegisters; los controladores que usan el sistema DMA devuelven KeepObject.
Comentarios
Para registrar una rutina 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 para proporcionar la dirección de la rutina AdapterControl . Cuando el adaptador es gratuito, el sistema llama a la rutina AdapterControl .
Si AdapterControl se ha registrado mediante una rutina StartIo , se garantiza que el parámetro Irp 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 AdapterControl , vea Escribir rutinas AdapterControl.
La rutina ControllerControl de un controlador se ejecuta en un contexto de subproceso arbitrario en IRQL = DISPATCH_LEVEL.
Para registrar una rutina 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 para proporcionar la dirección de la rutina ControllerControl . Cuando el controlador está libre, el sistema llama a la rutina ControllerControl .
Para obtener información detallada sobre cómo implementar una rutina ControllerControl , vea Escribir 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 más precisión los errores al ejecutar las herramientas de análisis de código, asegúrese de agregar la anotación a la _Use_decl_annotations_ definición de la función. La _Use_decl_annotations_ anotación 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 roles de función para controladores WDM. Para obtener información sobre _Use_decl_annotations_, consulte 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 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 AdapterControl denominada MyAdapterControl, use el tipo DRIVER_CONTROL 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 | Value |
|---|---|
| Plataforma de destino | Escritorio |
| Encabezado | wdm.h (incluya Wdm.h, Ntddk.h, Ntifs.h) |
| IRQL | Se llama en DISPATCH_LEVEL. |