WdfIoTargetOpen, fonction (wdfiotarget.h)

Article
08/08/2023

[S’applique à KMDF et UMDF]

La méthode WdfIoTargetOpen ouvre une cible d’E/S distante afin que le pilote puisse lui envoyer des demandes d’E/S.

Syntaxe

NTSTATUS WdfIoTargetOpen(
  [in] WDFIOTARGET                IoTarget,
  [in] PWDF_IO_TARGET_OPEN_PARAMS OpenParams
);

Paramètres

[in] IoTarget

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

[in] OpenParams

Pointeur vers une structure de WDF_IO_TARGET_OPEN_PARAMS allouée par l’appelant.

Valeur retournée

WdfIoTargetOpen retourne STATUS_SUCCESS si l’opération réussit. Sinon, cette méthode peut retourner l’une des valeurs suivantes :

Code de retour	Description
STATUS_INVALID_DEVICE_STATE	La cible d’E/S spécifiée est déjà ouverte.
STATUS_INSUFFICIENT_RESOURCES	Les ressources système disponibles étaient insuffisantes pour terminer l’opération.
STATUS_INFO_LENGTH_MISMATCH	La taille de la structure WDF_IO_TARGET_OPEN_PARAMS spécifiée par OpenParams était incorrecte.
STATUS_NO_SUCH_DEVICE	Le membre TargetFileObject de la structure WDF_IO_TARGET_OPEN_PARAMS de l’appelant a spécifié un objet file non valide.
STATUS_INVALID_PARAMETER	Un paramètre non valide a été détecté.
STATUS_NOT_FOUND	Le nom de l’appareil identifié dans le paramètre OpenParams est introuvable.

Cette méthode peut également retourner d’autres valeurs NTSTATUS.

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

Remarques

Les pilotes peuvent ouvrir des cibles d’E/S distantes en fournissant une chaîne Unicode qui représente un nom d’objet ou en fournissant un pointeur vers une structure de DEVICE_OBJECT modèle de pilote Windows (WDM). (Les pilotes basés sur l’infrastructure n’ont généralement pas de pointeurs vers les structures DEVICE_OBJECT d’autres pilotes.)

Pour obtenir un nom d’interface de périphérique avant d’appeler WdfIoTargetOpen, un pilote UMDF doit appeler CM_Register_Notification pour s’inscrire aux notifications d’arrivée et de suppression de l’interface. Il peut ensuite ouvrir la cible distante à l’aide du nom symbolique de l’interface qu’elle reçoit dans la routine de rappel de notification d’interface. Le pilote doit continuer à écouter la notification de suppression pendant que le handle est ouvert. Si le pilote cible échoue, le pilote UMDF doit fermer le handle.

Si l’interface existe déjà, un pilote UMDF doit appeler CM_Get_Device_Interface_List, éventuellement en appelant d’abord CM_Get_Device_Interface_List_Size pour déterminer la taille de mémoire tampon requise.

Si vous souhaitez que votre pilote utilise sa cible d’E/S locale, le pilote doit appeler WdfDeviceGetIoTarget au lieu de WdfIoTargetOpen.

Si un appel à WdfIoTargetOpen échoue, le pilote doit appeler WdfObjectDelete pour supprimer l’objet cible d’E/S.

Pour plus d’informations sur WdfIoTargetOpen, consultez Initialisation 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 suivant crée un objet cible d’E/S, initialise une structure WDF_IO_TARGET_OPEN_PARAMS et ouvre une cible d’E/S distante en spécifiant le nom du lien symbolique d’un appareil.

WDF_OBJECT_ATTRIBUTES  ioTargetAttrib;
WDFIOTARGET  ioTarget;
WDF_IO_TARGET_OPEN_PARAMS  openParams;

WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(
                                        &ioTargetAttrib,
                                        TARGET_DEVICE_INFO
                                        );
status = WdfIoTargetCreate(
                           device,
                           &ioTargetAttrib,
                           &ioTarget
                           );
if (!NT_SUCCESS(status)) {
    return status;
}
WDF_IO_TARGET_OPEN_PARAMS_INIT_OPEN_BY_NAME(
                                            &openParams,
                                            SymbolicLink,
                                            STANDARD_RIGHTS_ALL
                                            );
status = WdfIoTargetOpen(
                         ioTarget,
                         &openParams
                         );
if (!NT_SUCCESS(status)) {
    WdfObjectDelete(ioTarget);
    return status;
}

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	PASSIVE_LEVEL
Règles de conformité DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)