Función IoSetCompletionRoutine (wdm.h)
La rutina IoSetCompletionRoutine registra una rutina ioCompletion, a la que se llamará cuando el controlador de nivel inferior haya completado la operación solicitada para el IRP especificado.
Sintaxis
void IoSetCompletionRoutine(
[in] PIRP Irp,
[in, optional] PIO_COMPLETION_ROUTINE CompletionRoutine,
[in, optional] __drv_aliasesMem PVOID Context,
[in] BOOLEAN InvokeOnSuccess,
[in] BOOLEAN InvokeOnError,
[in] BOOLEAN InvokeOnCancel
);
Parámetros
[in] Irp
Puntero al IRP de que el controlador está procesando.
[in, optional] CompletionRoutine
Especifica el punto de entrada para la rutina de IoCompletion proporcionada por el controlador, que se llama cuando el controlador siguiente inferior completa el paquete.
[in, optional] Context
Puntero a un contexto determinado por el controlador para pasar a la rutina de IoCompletion. La información de contexto debe almacenarse en memoria no paginada, ya que se llama a la rutina IoCompletion en IRQL <= DISPATCH_LEVEL.
[in] InvokeOnSuccess
Especifica si se llama a la rutina de finalización si el IRP se completa con un valor de estado correcto en la estructura de IO_STATUS_BLOCK de IRP, en función de los resultados de la macro de NT_SUCCESS (vea Using NTSTATUS values).
[in] InvokeOnError
Especifica si se llama a la rutina de finalización si el IRP se completa con un valor de estado no solicitado en la estructura IO_STATUS_BLOCK de IRP.
[in] InvokeOnCancel
Especifica si se llama a la rutina de finalización si se llama a un controlador o al kernel ioCancelIrp para cancelar el IRP.
Valor devuelto
Ninguno
Observaciones
Solo un controlador que pueda garantizar que no se descargará antes de que finalice su rutina de finalización puede usar IoSetCompletionRoutine. De lo contrario, el controlador debe usar IoSetCompletionRoutineEx, lo que impide que el controlador se descargue hasta que se ejecute su rutina de finalización.
Esta rutina establece la dirección de transferencia de la de IoCompletion en el IRP especificado. El controlador de nivel más bajo de una cadena de controladores en capas no puede llamar a esta rutina.
IoSetCompletionRoutine registra la rutina especificada a la que se llamará cuando el controlador de nivel inferior haya completado la operación solicitada de cualquiera o todas las maneras siguientes:
Con un valor de estado correcto
Con un valor de estado nonsuccess
Cancelando el IRP
Normalmente, el controlador de dispositivo subyacente establece el bloque de estado de E/S. Es leído pero no modificado por las rutinas de IoCompletion de los controladores de nivel superior.
Los controladores de nivel superior que asignan irP con IoAllocateIrp o IoBuildAsynchronousFsdRequest deben llamar a esta rutina con todos los parámetros InvokeOnXxx establecidos en TRUE antes de pasar el IRP asignado por el controlador a IoCallDriver. Cuando se llama a la rutina IoCompletion con un IRP de este tipo, debe liberar el IRP asignado por el controlador y cualquier otro recurso que configure el controlador para la solicitud, como MDL con IoBuildPartialMdl. Este controlador debe devolver STATUS_MORE_PROCESSING_REQUIRED cuando llama a IoFreeIrp para evitar el procesamiento de finalización del administrador de E/S para el IRP asignado por el controlador.
Los controladores que no son PnP que se pueden descargar antes de que se ejecuten sus rutinas de ioCompletion IoSetCompletionRoutineEx en su lugar.