SetupDiCreateDeviceInfoA, fonction (setupapi.h)

Article
08/26/2023

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