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 demande d’E/S d’être mise en file d’attente. La méthode tente également d’annuler les demandes d’E/S qui ont quitté la file d’attente de la cible d’E/S et 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 qui a été 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 de type WDF_IO_TARGET_PURGE_IO_ACTION 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

None

Remarques

Un bogue case activée 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é à l’adresse 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é à IRQL <= DISPATCH_LEVEL. Sinon, WdfIoTargetPurge doit être appelé dans IRQL = PASSIVE_LEVEL.

Pour faire de 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 demande, telle qu’une demande de réinitialisation d’un canal USB (voir WdfUsbTargetPipeResetSynchronously), à un périphérique après que le pilote a appelé WdfIoTargetPurge.

Lorsqu’un pilote appelle WdfIoTargetPurge, l’infrastructure n’essaie pas d’annuler ou d’attendre les demandes d’E/S qui ont été précédemment envoyées à 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 a appelé l’une de ces fonctions, il ne doit appeler aucune de ces fonctions 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 la valeur ActionWdfIoTargetPurgeIoAndWait.

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 de 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;
}

Configuration requise

Voir aussi

WDF_IO_TARGET_PURGE_IO_ACTION

WdfIoTargetCreate

WdfIoTargetGetState

WdfIoTargetStart

WdfIoTargetStop