WdfIoTargetStop, fonction (wdfiotarget.h)

Article
02/29/2024

[S’applique à KMDF et UMDF]

La méthode WdfIoTargetStop cesse d’envoyer des requêtes en file d’attente à une cible d’E/S locale ou distante.

Syntaxe

void WdfIoTargetStop(
  [in] WDFIOTARGET                  IoTarget,
  [in] WDF_IO_TARGET_SENT_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 qu’une cible d’E/S spécialisée fournit.

[in] Action

Valeur de type WDF_IO_TARGET_SENT_IO_ACTION qui spécifie comment l’infrastructure doit gérer les demandes d’E/S que le pilote a envoyées à la cible d’E/S, si la cible n’a pas terminé les demandes.

Valeur de retour

None

Remarques

Un bogue case activée se produit si le pilote fournit un handle d’objet non valide.

Si votre pilote peut détecter les erreurs d’appareil récupérables, vous pouvez appeler WdfIoTargetStop pour arrêter temporairement l’envoi de demandes, puis appeler ultérieurement WdfIoTargetStart pour reprendre l’envoi des demandes.

Lors de l’arrêt, une cible d’E/S continue d’accepter de nouvelles demandes, mais ne remet pas les requêtes en file d’attente au pilote approprié.

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

Si un pilote appelle WdfUsbTargetPipeConfigContinuousReader pour configurer un lecteur continu pour un canal USB, la fonction de rappel EvtDeviceD0Exit du pilote doit appeler WdfIoTargetStop pour arrêter le lecteur.

Si un pilote a appelé WdfIoTargetStop, il peut toujours envoyer une requête à la cible en définissant l’indicateur WDF_REQUEST_OPTION_IGNORE_TARGET_STATE dans la structure WDF_REQUEST_SEND_OPTIONS de la requête. Si un pilote définit cet indicateur, il 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é WdfIoTargetStop.

Lorsqu’un pilote appelle WdfIoTargetStop, le framework 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.

Votre pilote doit appeler WdfIoTargetStart et WdfIoTargetStop de manière synchrone. Une fois que le pilote a appelé l’une de ces fonctions, il ne doit pas appeler l’une ou l’autre des fonctions avant le retour du premier appel.

Votre pilote peut appeler WdfIoTargetStop plusieurs fois à partir d’un seul thread sans appeler WdfIoTargetStart. Par exemple, votre pilote peut effectuer les opérations suivantes :

Appelez WdfIoTargetStop et spécifiez une valeur Action de WdfIoTargetLeaveSentIoPending.
Déterminez si la cible doit reprendre le traitement des demandes d’E/S.
Si la cible doit reprendre, appelez WdfIoTargetStart. Sinon, appelez à nouveau WdfIoTargetStop avec la valeur ActionWdfIoTargetCancelSentIo.

RemarqueWdfIoTargetStop n’est pas thread safe. Il n’est pas sûr d’appeler WdfIoTargetStop simultanément à partir de différents threads.

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

Si le pilote a appelé WdfUsbTargetPipeConfigContinuousReader pour le canal, WdfIoTargetStop doit être appelé à l’adresse IRQL = PASSIVE_LEVEL.

Si le pilote n’a pas appelé WdfUsbTargetPipeConfigContinuousReader et si le paramètre Action de WdfIoTargetStop est WdfIoTargetLeaveSentIoPending, WdfIoTargetStop peut être appelé à l’adresse IRQL <= DISPATCH_LEVEL. Sinon, WdfIoTargetStop est appelé dans IRQL = PASSIVE_LEVEL.

Exemples

L’exemple de code suivant montre comment une fonction de rappel EvtDeviceD0Exit peut appeler WdfIoTargetStop, 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);

    WdfIoTargetStop(
                    WdfUsbTargetPipeGetIoTarget(pDeviceContext->InterruptPipe),
                    WdfIoTargetCancelSentIo
                    );

    return STATUS_SUCCESS;
}

Configuration requise

Condition requise	Valeur
Plateforme cible	Universal
Version KMDF minimale	1.0
Version UMDF minimale	2.0
En-tête	wdfiotarget.h (inclure Wdf.h)
Bibliothèque	Wdf01000.sys (KMDF) ; WUDFx02000.dll (UMDF)
IRQL	Consultez la section Notes.
Règles de conformité DDI	DriverCreate(kmdf), FailD0EntryIoTargetState(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)