SetupDiOpenDeviceInfoW, fonction (setupapi.h)
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 SetupDiOpenDeviceInfoW(
[in] HDEVINFO DeviceInfoSet,
[in] PCWSTR 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 |
| Ensemble d’API | ext-ms-win-setupapi-classinstallers-l1-1-1 (introduit dans Windows 8.1) |