Función IoSetCompletionRoutineEx (wdm.h)
La rutina IoSetCompletionRoutineEx registra una rutina de IoCompletion , a la que se llama cuando el controlador de nivel inferior siguiente ha completado la operación solicitada para el IRP determinado.
Sintaxis
NTSTATUS IoSetCompletionRoutineEx(
[in] PDEVICE_OBJECT DeviceObject,
[in] PIRP Irp,
[in] PIO_COMPLETION_ROUTINE CompletionRoutine,
[in, optional] PVOID Context,
[in] BOOLEAN InvokeOnSuccess,
[in] BOOLEAN InvokeOnError,
[in] BOOLEAN InvokeOnCancel
);
Parámetros
[in] DeviceObject
Puntero al objeto de dispositivo del controlador.
[in] Irp
Puntero al IRP que el controlador está procesando.
[in] CompletionRoutine
Especifica el punto de entrada de la rutina ioCompletion proporcionada por el controlador, al 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 ioCompletion . La información de contexto debe almacenarse en memoria no paginada, porque 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 del IRP, en función de los resultados de la macro de NT_SUCCESS (consulte Uso de valores NTSTATUS).
[in] InvokeOnError
Especifica si se llama a la rutina de finalización si el IRP se completa con un valor de estado no válido en la estructura de IO_STATUS_BLOCK de IRP.
[in] InvokeOnCancel
Especifica si se llama a la rutina de finalización si un controlador o el kernel ha llamado a IoCancelIrp para cancelar el IRP.
Valor devuelto
Esta rutina devuelve STATUS_SUCCESS si se realiza correctamente o STATUS_INSUFFICIENT_RESOURCES si no hay suficiente memoria disponible para la operación.
Comentarios
A diferencia de IoSetCompletionRoutine, la rutina IoSetCompletionRoutineEx devuelve un valor NTSTATUS. El controlador debe comprobar este valor para determinar si la rutina ioCompletion se registró correctamente. Si la rutina ioCompletion se registra correctamente, IoSetCompletionRoutineEx asigna memoria que permanece asignada hasta que se ejecuta la rutina de IoCompletion . Los controladores deben asegurarse de que su rutina de IoCompletion se ejecuta llamando a IoCallDriver; de lo contrario, el kernel perderá memoria.
La rutina IoCompletion debe pertenecer al controlador que posee el objeto de dispositivo al que apunta DeviceObject. Este requisito impide que la rutina ioCompletion se descargue antes de que se devuelva.
El comportamiento de IoSetCompletionRoutineEx es el mismo que la rutina IoSetCompletionRoutine , excepto que:
IoSetCompletionRoutineEx garantiza que un controlador que no sea Plug and Play no se descargue antes de que se ejecute la rutina ioCompletion.
IoSetCompletionRoutineEx es una rutina que devuelve un valor NTSTATUS.