Funzione IoSetCompletionRoutineEx (wdm.h)

Articolo
03/08/2023

La routine IoSetCompletionRoutineEx registra una routine IoCompletion , che viene 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 all'IRP che il driver sta elaborando.

[in] 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

Questa routine restituisce STATUS_SUCCESS in caso di esito positivo o STATUS_INSUFFICIENT_RESOURCES se è disponibile memoria insufficiente per l'operazione.

Commenti

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 all'esecuzione della 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 di quanto segue:

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.

Requisiti

Requisito	Valore
Piattaforma di destinazione	Universale
Intestazione	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Libreria	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= DISPATCH_LEVEL
Regole di conformità DDI	CompleteRequest(wdm), CompleteRequestStatusCheck(wdm), CompletionRoutineRegistered(wdm), HwStorPortProhibitedDDDIs(storport), IoAllocateForward(wdm), IoAllocateIrpSignalEventInCompletion(wdm), IoAllocateIrpSignalEventInCompletion2(wdm), IoAllocateIrpSignalEventInCompletion3(wdm), IoAllocateIrpSignalEventInCompletionTimeout(wdm), IoBuildFsdForward(wdm), IoBuildFsdIrpSignalEventInCompletion(wdm), IoBuildFsdIrpSignalEventInCompletion2(wdm), IoBuildFsdIrpSignalEventInCompletion3(wdm), IoBuildFsdIrpSignalEventInCompletionTimeout(wdm), IoSetCompletionExCompleteIrp(wdm), IoSetCompletionRoutineExCheck(wdm), IoSetCompletionRoutineExCheckDeviceObject(wdm), LowerDriverReturn(wdm), MarkPower(wdm), MarkPowerDown(wdm) , MarkQueryRelations(wdm), MarkStartDevice(wdm), PendedCompletedRequestEx(wdm), SetCompletionRoutineFromDispatch(kmdf), SignalEventInCompletion(wdm), SignalEventInCompletion2(wdm), SignalEventInCompletion3(wdm), StartDeviceWait2(wdm), StartDeviceWait4(wdm)