Funzione WdfIoTargetPurge (wdfiotarget.h)

Articolo
02/27/2024

[Si applica a KMDF e UMDF]

Il metodo WdfIoTargetPurge annulla tutte le richieste di I/O accodate a una destinazione di I/O locale, remota o specializzata e impedisce la coda di eventuali nuove richieste di I/O. Il metodo tenta anche di annullare le richieste di I/O che hanno lasciato la coda della destinazione di I/O e immessi driver inferiori.

Sintassi

void WdfIoTargetPurge(
  [in] WDFIOTARGET                   IoTarget,
  [in] WDF_IO_TARGET_PURGE_IO_ACTION Action
);

Parametri

[in] IoTarget

Handle per un oggetto di destinazione I/O locale o remoto ottenuto da una chiamata precedente a WdfDeviceGetIoTarget o WdfIoTargetCreate o da un metodo fornito da una destinazione di I/O specializzata, ad esempio WdfUsbTargetPipeGetIoTarget.

[in] Action

Valore tipizzato WDF_IO_TARGET_PURGE_IO_ACTION che indica se il framework deve attendere la restituzione da WdfIoTargetPurge fino al completamento o all'annullamento di tutte le richieste recapitate.

Valore restituito

nessuno

Osservazioni

Se il driver fornisce un handle di oggetto non valido, si verifica un controllo di bug.

Se il driver ha precedentemente chiamato WdfUsbTargetPipeConfigContinuousReader, WdfIoTargetPurge deve essere chiamato in IRQL = PASSIVE_LEVEL. Se il driver non ha chiamato WdfUsbTargetPipeConfigContinuousReader e se il parametro Action di WdfIoTargetPurge è WdfIoTargetPurgeIo, WdfIoTargetPurge può essere chiamato in IRQL <= DISPATCH_LEVEL. In caso contrario, WdfIoTargetPurge deve essere chiamato in IRQL = PASSIVE_LEVEL.

Per eseguire una chiamata sincrona a WdfIoTargetPurge , il driver può impostare il valore WdfIoTargetPurgeIoAndWait del parametro Action . In questo caso, WdfIoTargetPurge attende la restituzione fino al completamento o all'annullamento di tutte le richieste recapitate.

Dopo che un driver ha chiamato WdfIoTargetPurge, può comunque inviare una richiesta alla destinazione impostando il flag WDF_REQUEST_SEND_OPTION_IGNORE_TARGET_STATE nella struttura WDF_REQUEST_SEND_OPTIONS della richiesta. Ad esempio, un driver potrebbe inviare una richiesta, ad esempio una richiesta per reimpostare una pipe USB (vedere WdfUsbTargetPipeResetSynchronously), a un dispositivo dopo che il driver ha chiamato WdfIoTargetPurge.

Quando un driver chiama WdfIoTargetPurge, il framework non tenta di annullare o attendere le richieste di I/O inviate in precedenza alla destinazione usando il flag WDF_REQUEST_SEND_OPTION_IGNORE_TARGET_STATE o il flag WDF_REQUEST_SEND_OPTION_SEND_AND_FORGET nella struttura di WDF_REQUEST_SEND_OPTIONS della richiesta.

Dopo che un driver ha eliminato una coda di I/O, può riavviare la coda chiamando WdfIoTargetStart.

Il driver deve chiamare WdfIoTargetStart, WdfIoTargetStop e WdfIoTargetPurge in modo sincrono. Dopo che il driver chiama una di queste funzioni, non deve chiamare nessuna delle altre finché non viene restituita la chiamata precedente.

Il driver può chiamare WdfIoTargetPurge più volte senza chiamare WdfIoTargetStart. Ad esempio, il driver potrebbe eseguire le operazioni seguenti:

Chiamare WdfIoTargetPurge e specificare il valore action di WdfIoTargetPurgeIo.
Determinare se la destinazione deve riprendere l'elaborazione delle richieste di I/O.
Se la destinazione deve riprendere, chiamare WdfIoTargetStart. In caso contrario, chiamare di nuovo WdfIoTargetPurge con un valore Action di WdfIoTargetPurgeIoAndWait.

Per altre informazioni sugli stati di destinazione di I/O, vedere Controllo dello stato di una destinazione di I/O generale.

Per altre informazioni sulle destinazioni di I/O, vedere Uso delle destinazioni di I/O.

Esempio

L'esempio di codice seguente mostra come una funzione di callback EvtDeviceD0Exit può chiamare WdfIoTargetPurge, se il driver usa un lettore continuo per una pipe USB.

NTSTATUS
MyEvtDeviceD0Exit(
    IN  WDFDEVICE Device,
    IN  WDF_POWER_DEVICE_STATE TargetState
)
{
    PDEVICE_CONTEXT  pDeviceContext;
    pDeviceContext = GetMyDeviceContext(Device);

    WdfIoTargetPurge(
                    WdfUsbTargetPipeGetIoTarget(pDeviceContext->InterruptPipe),
                    WdfIoTargetPurgeIoAndWait
                    );

    return STATUS_SUCCESS;
}

Requisiti

Requisito	Valore
Piattaforma di destinazione	Universale
Versione KMDF minima	1.11
Versione UMDF minima	2,0
Intestazione	wdfiotarget.h (include Wdf.h)
Libreria	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	Vedere la sezione Osservazioni.
Regole di conformità DDI	DriverCreate(kmdf)