Funzione IoSetCompletionRoutineEx (wdm.h)
La routine IoSetCompletionRoutineEx registra una routine IoCompletion, chiamata quando il driver di livello inferiore successivo ha completato l'operazione richiesta per l'IRP specificato.
Sintassi
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
);
Parametri
[in] DeviceObject
Puntatore all'oggetto dispositivo del driver.
[in] Irp
Puntatore alIRPche il driver sta elaborando.
[in] CompletionRoutine
Specifica il punto di ingresso per il driver fornito routine IoCompletion, che viene chiamato quando il driver inferiore successivo completa il pacchetto.
[in, optional] Context
Puntatore a un contesto determinato dal driver da passare alla routine IoCompletion. Le informazioni sul contesto devono essere archiviate in memoria non in pagine, perché la routine IoCompletion viene chiamata in IRQL <= DISPATCH_LEVEL.
[in] InvokeOnSuccess
Specifica se la routine di completamento viene chiamata se l'IRP viene completato con un valore di stato di esito positivo nella struttura di IO_STATUS_BLOCK di IRP, in base ai risultati della macro NT_SUCCESS (vedere Uso dei valori NTSTATUS).
[in] InvokeOnError
Specifica se la routine di completamento viene chiamata se l'IRP viene completato con un valore di stato non riuscito nella struttura di IO_STATUS_BLOCK di IRP.
[in] InvokeOnCancel
Specifica se la routine di completamento viene chiamata se un driver o il kernel ha chiamato IoCancelIrp per annullare l'IRP.
Valore restituito
Questa routine restituisce STATUS_SUCCESS in caso di esito positivo o STATUS_INSUFFICIENT_RESOURCES se è disponibile memoria insufficiente per l'operazione.
Osservazioni
A differenza di IoSetCompletionRoutine, la routine IoSetCompletionRoutineEx restituisce un valore NTSTATUS. Il driver deve controllare questo valore per determinare se la routine IoCompletion è stata registrata correttamente. Se la routine IoCompletion viene registrata correttamente, IoSetCompletionRoutineEx alloca memoria che rimane allocata fino a quando non viene eseguita la routine IoCompletion . I driver devono assicurarsi che la routine IoCompletion venga eseguita chiamando IoCallDriver; in caso contrario, il kernel perderà memoria.
La routine IoCompletion deve appartenere al driver proprietario dell'oggetto dispositivo a cui punta DeviceObject. Questo requisito impedisce che la routine IoCompletion venga scaricata prima che venga restituita.
Il comportamento di IoSetCompletionRoutineEx corrisponde alla routine IoSetCompletionRoutine, ad eccezione del fatto che:
IoSetCompletionRoutineEx garantisce che un driver non Plug and Play non venga scaricato prima dell'esecuzione della routine IoCompletion.
IoSetCompletionRoutineEx è una routine che restituisce un valore NTSTATUS.