Fonction SetupDiOpenDeviceInfoA (setupapi.h)

Article
08/26/2023

La fonction SetupDiOpenDeviceInfo ajoute un élément d’informations sur l’appareil pour un instance d’appareil à un jeu d’informations sur l’appareil, s’il n’en existe pas déjà un dans le jeu d’informations sur l’appareil, et récupère les informations qui identifient l’élément d’informations sur l’appareil pour l’appareil instance dans le jeu d’informations de l’appareil.

Syntaxe

WINSETUPAPI BOOL SetupDiOpenDeviceInfoA(
  [in]            HDEVINFO         DeviceInfoSet,
  [in]            PCSTR            DeviceInstanceId,
  [in, optional]  HWND             hwndParent,
  [in]            DWORD            OpenFlags,
  [out, optional] PSP_DEVINFO_DATA DeviceInfoData
);

Paramètres

[in] DeviceInfoSet

Handle au jeu d’informations sur l’appareil auquel SetupDiOpenDeviceInfo ajoute un élément d’informations sur l’appareil, s’il n’en existe pas déjà, pour l’appareil instance spécifié par DeviceInstanceId.

[in] DeviceInstanceId

Pointeur vers une chaîne terminée par null qui fournit l’identificateur de instance d’appareil d’un appareil (par exemple, « Root*PNP0500\0000 »). Si DeviceInstanceId a la valeur NULL ou fait référence à une chaîne de longueur nulle, SetupDiOpenDeviceInfo ajoute un élément d’informations sur l’appareil au jeu d’informations d’appareil fourni, s’il n’en existe pas déjà, pour l’appareil racine dans l’arborescence de l’appareil.

[in, optional] hwndParent

Handle de la fenêtre de niveau supérieur à utiliser pour toute interface utilisateur liée à l’installation de l’appareil.

[in] OpenFlags

Variable de type DWORD qui contrôle la façon dont l’élément d’informations sur l’appareil est ouvert. La valeur de ce paramètre peut être une ou plusieurs des valeurs suivantes :

DIOD_CANCEL_REMOVE

Si cet indicateur est spécifié et que l’appareil a été marqué pour la suppression en attente, le système d’exploitation annule la suppression en attente.

DIOD_INHERIT_CLASSDRVS

Si cet indicateur est spécifié, l’élément d’informations sur l’appareil résultant hérite de la liste des pilotes de classe, le cas échéant, associée au jeu d’informations sur l’appareil. En outre, s’il existe un pilote sélectionné pour le jeu d’informations sur l’appareil, ce même pilote est sélectionné pour le nouvel élément d’informations sur l’appareil.

Si l’élément d’informations sur l’appareil était déjà présent, sa liste de pilotes de classe, le cas échéant, est remplacée par la liste héritée.

[out, optional] DeviceInfoData

Pointeur vers une structure de SP_DEVINFO_DATA fournie par l’appelant qui reçoit des informations sur l’élément d’informations sur l’appareil pour l’appareil instance spécifié par DeviceInstanceId. L’appelant doit définir cbSize sur sizeof(SP_DEVINFO_DATA). Ce paramètre est facultatif et peut être NULL.

Valeur retournée

SetupDiOpenDeviceInfo retourne TRUE si elle réussit. Sinon, la fonction retourne FALSE et l’erreur journalisée peut être récupérée avec un appel à GetLastError.

Remarques

Si cette instance d’appareil est ajoutée à un ensemble qui a une classe associée, la classe d’appareil doit être identique ou l’appel échoue. Dans ce cas, un appel à GetLastError retourne ERROR_CLASS_MISMATCH.

Si le nouvel élément d’informations sur l’appareil est correctement ouvert, mais que la mémoire tampon DeviceInfoData fournie par l’appelant n’est pas valide, cette fonction retourne FALSE. Dans ce cas, un appel à GetLastError retourne ERROR_INVALID_USER_BUFFER. Toutefois, l’élément d’informations sur l’appareil est ajouté en tant que nouveau membre de l’ensemble.

Notes

L’en-tête setupapi.h définit SetupDiOpenDeviceInfo comme un 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.

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