Partager via

SetupDiOpenDeviceInterfaceA, fonction (setupapi.h)

  • Article

La fonction SetupDiOpenDeviceInterface récupère des informations sur une interface d’appareil et ajoute l’interface au jeu d’informations d’appareil spécifié pour un système local ou un système distant.

Syntaxe

WINSETUPAPI BOOL SetupDiOpenDeviceInterfaceA(
  [in]            HDEVINFO                  DeviceInfoSet,
  [in]            PCSTR                     DevicePath,
  [in]            DWORD                     OpenFlags,
  [out, optional] PSP_DEVICE_INTERFACE_DATA DeviceInterfaceData
);

Paramètres

[in] DeviceInfoSet

Pointeur vers un jeu d’informations d’appareil qui contient ou contiendra un élément d’informations sur l’appareil qui représente l’appareil qui prend en charge l’interface à ouvrir.

[in] DevicePath

Pointeur vers une chaîne terminée par NULL qui fournit le nom de l’interface d’appareil à ouvrir. Ce nom est un chemin d’accès d’appareil Win32 qui est généralement reçu dans une structure de notification PnP ou obtenu par un appel précédent à SetupDiEnumDeviceInterfaces et à ses fonctions associées .

[in] OpenFlags

Indicateurs qui déterminent la façon dont l’élément d’interface de l’appareil doit être ouvert. Le seul indicateur valide est le suivant :

DIODI_NO_ADD

Spécifie que l’élément d’informations sur l’appareil sous-jacent ne sera pas créé si cet élément n’est pas déjà présent dans le jeu d’informations sur l’appareil spécifié. Pour plus d’informations, consultez la section Notes suivante.

[out, optional] DeviceInterfaceData

Pointeur vers une structure de SP_DEVICE_INTERFACE_DATA initialisée par l’appelant qui reçoit les données d’interface demandées. Ce pointeur est facultatif et peut être NULL. Si une mémoire tampon est fournie, l’appelant doit définir le membre cbSize de la structure sur sizeof(SP_DEVICE_INTERFACE_DATA) avant d’appeler SetupDiOpenDeviceInterface. Pour plus d’informations, consultez la section Notes suivante.

Valeur retournée

SetupDiOpenDeviceInterface retourne TRUE si la fonction s’est terminée sans erreur. Si la fonction s’est terminée avec une erreur, elle retourne FALSE et le code d’erreur de l’échec peut être récupéré en appelant GetLastError.

Remarques

Si un élément d’interface d’appareil pour l’interface existe déjà dans DeviceInfoSet, SetupDiOpenDeviceInterface met à jour les indicateurs. Par conséquent, cette fonction peut être utilisée pour mettre à jour les indicateurs d’une interface d’appareil. Par exemple, une interface peut avoir été inactive lors de sa première ouverture, mais elle est devenue active par la suite. Si l’élément d’informations sur l’appareil sous-jacent n’est pas déjà présent dans DeviceInfoSet, cette fonction en crée un et l’ajoute à DeviceInfoSet.

Si la fonction ouvre correctement la nouvelle interface d’appareil, mais que l’appelant n’a pas fourni de structure valide dans le paramètre DeviceInterfaceData , la fonction retourne FALSE et un appel ultérieur à GetLastError retourne ERROR_INVALID_USER_BUFFER. Toutefois, dans ce cas, SetupDiOpenDeviceInterface ajoute l’interface demandée au jeu d’informations de l’appareil.

Si la nouvelle interface d’appareil est correctement ouverte, mais que la mémoire tampon DeviceInterfaceData fournie par l’appelant n’est pas valide, cette fonction retourne FALSE et GetLastError retourne ERROR_INVALID_USER_BUFFER. L’erreur de mémoire tampon de l’appelant n’empêche pas l’ouverture de l’interface.

Si l’indicateur DIODI_NO_ADD est spécifié pour le paramètre OpenFlags et qu’un élément d’informations sur l’appareil sous-jacent n’est pas déjà présent dans le jeu d’informations sur l’appareil spécifié, cette fonction renvoie FALSE et GetLastError renvoie ERROR_NO_SUCH_DEVICE_INTERFACE.

Lorsque l’application a fini d’utiliser les informations récupérées par SetupDiOpenDeviceInterface, l’application doit appeler SetupDiDeleteDeviceInterfaceData.

MF_DEVSOURCE_ATTRIBUTE_SOURCE_TYPE_VIDCAP_SYMBOLIC_LINK attribut peut être passé en tant que valeur de l’argument DevicePath de la fonction SetupDiOpenDeviceInterface .

Notes

L’en-tête setupapi.h définit SetupDiOpenDeviceInterface en tant qu’alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. La combinaison de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.

Configuration requise

Condition requise Valeur
Client minimal pris en charge Disponible dans Microsoft Windows 2000 et versions ultérieures de Windows.
Plateforme cible Desktop (Expérience utilisateur)
En-tête setupapi.h (inclure Setupapi.h)
Bibliothèque Setupapi.lib

Voir aussi

SetupDiDeleteDeviceInterfaceData

SetupDiEnumDeviceInterfaces