Funzione IoSetCompletionRoutine (wdm.h)

Articolo
02/29/2024

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 .

Requisiti

Requisito	Valore
Piattaforma di destinazione	Desktop
Intestazione	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
IRQL	IRQL <= DISPATCH_LEVEL
Regole di conformità DDI	CompleteRequest(wdm), CompleteRequestStatusCheck(wdm), CompletionRoutineRegistered(wdm), IoAllocateForward(wdm), IoAllocateIrpSignalEventInCompletion(wdm), IoAllocateIrpSignalEventInCompletion2(wdm), IoAllocateIrpSignalEventInCompletion3(wdm), IoAllocateIrpSignalEventInCompletionTimeout(wdm), IoBuildFsdForward(wdm), IoBuildFsdIrpSignalEventInCompletion(wdm), IoBuildFsdIrpSignalEventInCompletion2(wdm), IoBuildFsdIrpSignalEventInCompletion3(wdm), IoBuildFsdIrpSignalEventInCompletionTimeout(wdm), IoFreeIrp(storport), IoSetCompletionRoutineNonPnpDriver(wdm), LowerDriverReturn(wdm), MarkPower(wdm), MarkPowerDown(wdm), MarkQueryRelations(wdm), MarkStartDevice(wdm), PendedCompletedRequest(wdm), SetCompletionRoutineFromDispatch(kmdf), SignalEventInCompletion(wdm), SignalEventInCompletion2(wdm), SignalEventInCompletion3(wdm), StartDeviceWait(wdm), StartDeviceWait3(wdm)