WdfIoTargetPurge, fonction (wdfiotarget.h)

[S’applique à KMDF et UMDF]

La méthode WdfIoTargetPurge annule toutes les demandes d’E/S mises en file d’attente vers une cible d’E/S locale, distante ou spécialisée et empêche toute nouvelle requête d’E/S d’être mise en file d’attente. La méthode tente également d’annuler les requêtes d’E/S qui ont quitté la file d’attente de la cible d’E/S et qui ont entré des pilotes inférieurs.

Syntaxe

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

Paramètres

[in] IoTarget

Handle vers un objet cible d’E/S local ou distant obtenu à partir d’un appel précédent à WdfDeviceGetIoTarget ou WdfIoTargetCreate, ou à partir d’une méthode fournie par une cible d’E/S spécialisée, telle que WdfUsbTargetPipeGetIoTarget.

[in] Action

Valeur WDF_IO_TARGET_PURGE_IO_ACTION-typée qui indique si l’infrastructure doit attendre le retour de WdfIoTargetPurge jusqu’à ce que toutes les demandes remises soient terminées ou annulées.

Valeur de retour

Aucun

Remarques

Une vérification de bogue se produit si le pilote fournit un handle d’objet non valide.

Si le pilote a précédemment appelé WdfUsbTargetPipeConfigContinuousReader, WdfIoTargetPurge doit être appelé à IRQL = PASSIVE_LEVEL. Si le pilote n’a pas appelé WdfUsbTargetPipeConfigContinuousReader et si le paramètre Action de WdfIoTargetPurge est WdfIoTargetPurgeIo, WdfIoTargetPurge peut être appelé au <IRQL = DISPATCH_LEVEL. Sinon, WdfIoTargetPurge doit être appelée à IRQL = PASSIVE_LEVEL.

Pour effectuer WdfIoTargetPurge un appel synchrone, le pilote peut définir la valeur WdfIoTargetPurgeIoAndWait du paramètre Action. Dans ce cas, WdfIoTargetPurge attend de retourner jusqu’à ce que toutes les demandes remises soient terminées ou annulées.

Une fois qu’un pilote a appelé WdfIoTargetPurge, il peut toujours envoyer une requête à la cible en définissant l’indicateur WDF_REQUEST_SEND_OPTION_IGNORE_TARGET_STATE dans la structure WDF_REQUEST_SEND_OPTIONS de la requête. Par exemple, un pilote peut envoyer une requête, telle qu’une demande de réinitialisation d’un canal USB (voir WdfUsbTargetPipeResetSynchronously), à un appareil une fois que le pilote a appelé WdfIoTargetPurge.

Lorsqu’un pilote appelle WdfIoTargetPurge, l’infrastructure ne tente pas d’annuler ou d’attendre les demandes d’E/S qui ont été envoyées précédemment à la cible à l’aide de l’indicateur WDF_REQUEST_SEND_OPTION_IGNORE_TARGET_STATE ou de l’indicateur WDF_REQUEST_SEND_OPTION_SEND_AND_FORGET dans la structure WDF_REQUEST_SEND_OPTIONS de la requête.

Une fois qu’un pilote a vidé une file d’attente d’E/S, il peut redémarrer la file d’attente en appelant WdfIoTargetStart.

Votre pilote doit appeler WdfIoTargetStart, WdfIoTargetStop et WdfIoTargetPurge de manière synchrone. Une fois que le pilote appelle l’une de ces fonctions, il ne doit appeler aucune des autres tant que l’appel précédent n’est pas retourné.

Votre pilote peut appeler WdfIoTargetPurge plusieurs fois sans appeler WdfIoTargetStart. Par exemple, votre pilote peut effectuer les opérations suivantes :

1. Appelez WdfIoTargetPurge et spécifiez une valeur Action de WdfIoTargetPurgeIo.
2. Déterminez si la cible doit reprendre le traitement des demandes d’E/S.
3. Si la cible doit reprendre, appelez WdfIoTargetStart. Sinon, appelez à nouveau WdfIoTargetPurge avec une valeur de Action de WdfIoTargetPurgeIoAndWait.

Pour plus d’informations sur les états cibles d’E/S, consultez Contrôle de l’état d’une cible d’E/S générale.

Pour plus d’informations sur les cibles d’E/S, consultez Utilisation des cibles d’E/S.

Exemples

L’exemple de code suivant montre comment une fonction de rappel EvtDeviceD0Exit peut appeler WdfIoTargetPurge, si le pilote utilise un lecteur continu pour un canal 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;
}

Spécifications

Voir aussi

WDF_IO_TARGET_PURGE_IO_ACTION

WdfIoTargetCreate

WdfIoTargetGetState

WdfIoTargetStart

WdfIoTargetStop