SetupDiCreateDeviceInfoA, fonction (setupapi.h)
La fonction SetupDiCreateDeviceInfo crée un nouvel élément d’informations sur l’appareil et l’ajoute en tant que nouveau membre au jeu d’informations sur l’appareil spécifié.
Syntaxe
WINSETUPAPI BOOL SetupDiCreateDeviceInfoA(
[in] HDEVINFO DeviceInfoSet,
[in] PCSTR DeviceName,
[in] const GUID *ClassGuid,
[in, optional] PCSTR DeviceDescription,
[in, optional] HWND hwndParent,
[in] DWORD CreationFlags,
[out, optional] PSP_DEVINFO_DATA DeviceInfoData
);
Paramètres
[in] DeviceInfoSet
Handle pour les informations de périphérique définies pour l’ordinateur local.
[in] DeviceName
Pointeur vers une chaîne terminée par NULL qui fournit un ID de instance d’appareil complet (par exemple, « Root*PNP0500\0000 ») ou un ID d’appareil énuméré à la racine sans le préfixe d’énumérateur et le suffixe d’identificateur instance (par exemple, « *PNP0500 »). L’identificateur d’appareil énuméré par la racine ne peut être utilisé que si l’indicateur DICD_GENERATE_ID est spécifié dans le paramètre CreationFlags .
[in] ClassGuid
Pointeur vers le GUID de la classe de configuration de l’appareil. Si la classe d’installation de l’appareil n’est pas connue, définissez *ClassGuid sur une structure GUID_NULL.
[in, optional] DeviceDescription
Pointeur vers une chaîne terminée par NULL qui fournit la description textuelle de l’appareil. Ce pointeur est facultatif et peut être NULL.
[in, optional] hwndParent
Handle vers la fenêtre de niveau supérieur à utiliser pour toute interface utilisateur liée à l’installation de l’appareil. Ce handle est facultatif et peut être NULL.
[in] CreationFlags
Variable de type DWORD qui contrôle la façon dont l’élément d’informations sur l’appareil est créé. Il peut s’agir d’une combinaison des valeurs suivantes :
DICD_GENERATE_ID
Si cet indicateur est spécifié, DeviceName contient uniquement un ID d’appareil énuméré par la racine et le système utilise cet ID pour générer un ID de instance d’appareil complet pour le nouvel élément d’informations sur l’appareil.
Appelez SetupDiGetDeviceInstanceId pour récupérer l’ID de instance d’appareil qui a été généré pour cet élément d’informations sur l’appareil.
DICD_INHERIT_CLASSDRVS
Si cet indicateur est spécifié, l’élément d’informations sur le périphérique résultant hérite de la liste des pilotes de classe, le cas échéant, associée au jeu d’informations de périphérique. En outre, s’il existe un pilote sélectionné pour l’ensemble d’informations sur le périphérique, ce même pilote est sélectionné pour le nouvel élément d’informations sur le périphérique.
[out, optional] DeviceInfoData
Pointeur vers une structure de SP_DEVINFO_DATA qui reçoit le nouvel élément d’informations sur l’appareil. Ce pointeur est facultatif et peut être NULL. Si la structure est fournie, l’appelant doit définir le membre cbSize de cette structure sur sizeof(SP_DEVINFO_DATA) avant d’appeler la fonction. Pour plus d’informations, consultez la section Notes suivante.
Valeur retournée
La fonction retourne TRUE si elle réussit. Sinon, elle retourne FALSE et l’erreur journalisée peut être récupérée en effectuant un appel à GetLastError.
Remarques
L’appelant de cette fonction doit être membre du groupe Administrateurs.
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 instance d’appareil spécifié est identique à une clé de instance d’appareil existante dans le Registre, l’appel échoue. Dans ce cas, un appel à GetLastError retourne ERROR_DEVINST_ALREADY_EXISTS. Cela se produit uniquement si l’indicateur DICD_GENERATE_ID n’est pas défini.
Si le nouvel élément d’informations sur l’appareil a été créé avec succès, mais que la mémoire tampon DeviceInfoData fournie par l’appelant n’est pas valide, la fonction retourne FALSE. Dans ce cas, un appel à GetLastError retourne ERROR_INVALID_USER_BUFFER. Toutefois, l’élément d’informations sur l’appareil a déjà été ajouté en tant que nouveau membre de l’ensemble.
DeviceInfoSet doit contenir uniquement des éléments sur l’ordinateur local.
Notes
L’en-tête setupapi.h définit SetupDiCreateDeviceInfo comme 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
| Client minimal pris en charge | Disponible dans Microsoft Windows 2000 et versions ultérieures de Windows. |
| Plateforme cible | Bureau |
| En-tête | setupapi.h (inclure Setupapi.h) |
| Bibliothèque | Setupapi.lib |