WdfIoTargetWdmGetTargetFileHandle, fonction (wdfiotarget.h)

  • Article

[S’applique à KMDF et UMDF]

La méthode WdfIoTargetWdmGetTargetFileHandle retourne un handle au fichier associé à une cible d’E/S distante spécifiée.

Syntaxe

HANDLE WdfIoTargetWdmGetTargetFileHandle(
  [in] WDFIOTARGET IoTarget
);

Paramètres

[in] IoTarget

Handle pour un objet cible d’E/S distant. Ce handle a été obtenu à partir d’un appel précédent à WdfIoTargetCreate.

Valeur retournée

Si le pilote a spécifié un nom d’objet lorsqu’il a appelé WdfIoTargetOpen, WdfIoTargetWdmGetTargetFileHandle retourne le handle de fichier associé à la cible d’E/S spécifiée. Sinon , WdfIoTargetWdmGetTargetFileHandle retourne null.

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

Remarques

Pour KMDF, le handle de fichier retourné est un handle en mode noyau valide dans un contexte de thread arbitraire. Pour plus d’informations sur la façon dont un pilote peut utiliser ce handle de fichier, consultez Utilisation d’un handle de fichier.

Le handle de fichier retourné par la méthode WdfIoTargetWdmGetTargetFileHandle est valide jusqu’à ce que le pilote appelle WdfIoTargetClose ou WdfIoTargetCloseForQueryRemove, ou jusqu’à ce que l’objet cible d’E/S distant soit supprimé. Si le pilote fournit une fonction EvtCleanupCallback pour l’objet cible d’E/S distant, et si l’objet est supprimé avant la fermeture de la cible d’E/S distante, le pointeur est valide jusqu’à ce que la fonction EvtCleanupCallback retourne.

Si le pilote tente d’accéder à l’objet de périphérique WDM après sa suppression, le pilote peut provoquer le blocage du système. L’exemple toastmon montre comment le pilote peut fournir une fonction de rappel EvtIoTargetQueryRemove afin qu’il soit averti si la cible d’E/S est supprimée.

Pour UMDF, WdfIoTargetWdmGetTargetFileHandle retourne un HANDLE Win32 valide uniquement dans le processus en cours. Un pilote UMDF hérité (version 1.x) appelle IWDFDevice ::RetrieveDeviceName pour obtenir le nom de l’appareil en mode noyau sous-jacent, puis ouvre un handle avec CreateFile. Le pilote peut ensuite envoyer des E/S directement aux appareils inférieurs à l’aide de DeviceIoControl. À compter d’UMDF 2.15, les pilotes UMDF v2 peuvent ouvrir la cible d’E/S locale par fichier (WDF_IO_TARGET_OPEN_PARAMS_INIT_OPEN_BY_FILE) et récupérer le handle de fichier à l’aide de WdfIoTargetWdmGetTargetFileHandle. L’infrastructure ouvre et ferme le handle de fichier lorsque la cible distante est fermée ou supprimée. Le handle de fichier reste valide dans le contrat de WdfIoTargetWdmGetTargetFileHandle décrit ci-dessus.

Avertissement

Si un pilote UMDF v2 appelle WdfIoTargetWdmGetTargetFileHandle pour obtenir le handle Win32 à partir d’une cible distante ouverte à l’aide de WDF_IO_TARGET_OPEN_PARAMS_INIT_OPEN_BY_FILE, n’envoyez pas d’E/S qui se chevauchent/asynchrones avec des API telles que DeviceIoControl. Cela peut bloquer le processus hébergeant le pilote. Si le pilote doit envoyer des E/S qui se chevauchent, il doit également définir le bit d’ordre inférieur du membre hEvent de la structure CHEVAUCHEMENT. Cela est dû au fait que l’infrastructure lie en interne le handle à un port d’achèvement d’E/S. Un handle d’événements valide dont le bit d’ordre faible est défini empêche la saisie semi-automatique d’être mise en file d’attente vers le port d’achèvement.

Pour plus d’informations sur WdfIoTargetWdmGetTargetFileHandle, consultez Obtention d’informations sur 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 obtient un handle pour le fichier associé à une cible d’E/S distante spécifiée.

HANDLE h;

h = WdfIoTargetWdmGetTargetFileHandle(IoTarget);

Un pilote UMDF hérité (version 1.x) appelle IWDFDevice ::RetrieveDeviceName pour obtenir le nom de l’appareil en mode noyau sous-jacent, puis lui ouvrir un handle avec CreateFile. Le pilote envoie ensuite les E/S directement à l’appareil à l’aide de DeviceIoControl.

À compter d’UMDF 2.15, le pilote ouvre la cible d’E/S locale par fichier et récupère son handle. L’infrastructure ouvre et ferme le handle de fichier. Le handle de fichier reste valide dans le contrat de WdfIoTargetWdmGetTargetFileHandle.

NTSTATUS status;

WDF_IO_TARGET_OPEN_PARAMS params;

WDFIOTARGET ioTarget = NULL;

HANDLE handle = NULL;

status = WdfIoTargetCreate(Device, &attr, &ioTarget);

if (!NT_SUCCESS(status)) {

    // error handling

}

WDF_IO_TARGET_OPEN_PARAMS_INIT_OPEN_BY_FILE(&params, NULL);

status = WdfIoTargetOpen(ioTarget, &params);

if (!NT_SUCCESS(status)) {

    // error handling

}

handle = WdfIoTargetWdmGetTargetFileHandle(ioTarget);

if (handle == NULL) {

    // error handling

}

if (ioTarget != NULL) {
    WdfIoTargetClose(ioTarget);
}
// You can now call DeviceIoControl(handle, ...) etc.
// NOTE: See Warning above on submitting overlapped or asynchronous I/O

Configuration requise

Condition requise Valeur
Plateforme cible Universal
Version KMDF minimale 1.0
Version UMDF minimale 2.15
En-tête wdfiotarget.h (inclure Wdf.h)
Bibliothèque Wdf01000.sys (consultez Gestion de version de la bibliothèque d’infrastructure.)
IRQL <=DISPATCH_LEVEL
Règles de conformité DDI DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Voir aussi

WdfIoTargetCreate

WdfIoTargetWdmGetTargetFileObject