SetupDiOpenDeviceInterfaceA, fonction (setupapi.h)
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 d’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 de l’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 d’appareil pour l’appareil sous-jacent ne sera pas créé si cet élément n’est pas déjà présent dans le jeu d’informations d’appareil spécifié. Pour plus d’informations, consultez la section suivante Remarques.
[out, optional] DeviceInterfaceData
Pointeur vers une structure d'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 suivante Remarques.
Valeur de retour
SetupDiOpenDeviceInterface retourne TRUE si la fonction s’est terminée sans erreur. Si la fonction s’est terminée avec une erreur, elle retourne faux 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 a peut-être été inactive lorsqu’elle a été ouverte pour la première fois, 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 une 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 l’appelant DeviceInterfaceData tampon 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’interface d’être ouverte.
Si l’indicateur DIODI_NO_ADD est spécifié pour le paramètre OpenFlags
Une fois l’application terminée à l’aide des informations qui SetupDiOpenDeviceInterface récupérées, l’application doit appeler SetupDiDeleteDeviceInterfaceData.
Note
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. Le mélange 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.
Exigences
| Exigence | Valeur |
|---|---|
| client minimum pris en charge | Disponible dans Microsoft Windows 2000 et versions ultérieures de Windows. |
| plateforme cible | Bureau |
| d’en-tête | setupapi.h (include Setupapi.h) |
| bibliothèque | Setupapi.lib |