Funzione IoSetCompletionRoutine (wdm.h)
La routine IoSetCompletionRoutine registra una routine IoCompletion , che verrà chiamata quando il driver di livello inferiore successivo ha completato l'operazione richiesta per l'IRP specificato.
Sintassi
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
);
Parametri
[in] Irp
Puntatore all'IRP che il driver sta elaborando.
[in, optional] CompletionRoutine
Specifica il punto di ingresso per la routine IoCompletion fornita dal driver, che viene chiamata 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 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
nessuno
Osservazioni
Solo un driver che può garantire che non verrà scaricato prima che la routine di completamento venga completata può usare IoSetCompletionRoutine. In caso contrario, il driver deve usare IoSetCompletionRoutineEx, che impedisce lo scaricamento del driver fino all'esecuzione della routine di completamento.
Questa routine imposta l'indirizzo di trasferimento della routine IoCompletion nell'IRP specificato. Il driver di livello più basso in una catena di driver a più livelli non può chiamare questa routine.
IoSetCompletionRoutine registra la routine specificata da chiamare quando il driver di livello inferiore successivo ha completato l'operazione richiesta in uno o in tutti i modi seguenti:
Con un valore di stato di esito positivo
Con un valore di stato non riuscito
Annullando l'IRP
In genere, il blocco di stato di I/O viene impostato dal driver di dispositivo sottostante. Viene letto ma non modificato dalle routine IoCompletion dei driver di livello superiore.
I driver di livello superiore che allocano IRP con IoAllocateIrp o IoBuildAsynchronousFsdRequest devono chiamare questa routine con tutti i parametri InvokeOnXxx impostati su TRUE prima di passare l'IRP allocato dal driver a IoCallDriver. Quando la routine IoCompletion viene chiamata con un IRP di questo tipo, deve liberare l'IRP allocato dal driver e qualsiasi altra risorsa configurata dal driver per la richiesta, ad esempio gli elenchi di certificati con IoBuildPartialMdl. Un driver di questo tipo deve restituire STATUS_MORE_PROCESSING_REQUIRED quando chiama IoFreeIrp per prevenire l'elaborazione del completamento del gestore di I/O per l'IRP allocata dal driver.
I driver non PnP che potrebbero essere scaricati prima dell'esecuzione delle routine IoCompletion devono usare invece IoSetCompletionRoutineEx .