SetupDiCreateDeviceInfoW, fonction (setupapi.h)
La fonction SetupDiCreateDeviceInfo crée un élément d’informations sur l’appareil et l’ajoute en tant que nouveau membre au jeu d’informations d’appareil spécifié.
Syntaxe
WINSETUPAPI BOOL SetupDiCreateDeviceInfoW(
[in] HDEVINFO DeviceInfoSet,
[in] PCWSTR DeviceName,
[in] const GUID *ClassGuid,
[in, optional] PCWSTR DeviceDescription,
[in, optional] HWND hwndParent,
[in] DWORD CreationFlags,
[out, optional] PSP_DEVINFO_DATA DeviceInfoData
);
Paramètres
[in] DeviceInfoSet
Handle vers l’ensemble d’informations de l’appareil pour l’ordinateur local.
[in] DeviceName
Pointeur vers une chaîne terminée par NULL qui fournit un ID d’instance d’appareil complet (par exemple, « Root*PNP0500\0000 ») ou un ID d’appareil énuméré racine sans préfixe d’énumérateur et suffixe d’identificateur d’instance (par exemple, « *PNP0500 »). L’identificateur d’appareil énuméré racine ne peut être utilisé que si l’indicateur DICD_GENERATE_ID est spécifié dans le paramètre CreationFlags.
[in] ClassGuid
Pointeur vers la classe de configuration de l’appareil GUID pour l’appareil. Si la classe d’installation de l’appareil n’est pas connue, définissez *ClassGuid sur une structure de 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 d’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é racine et le système utilise cet ID pour générer un ID d’instance d’appareil complet pour le nouvel élément d’informations sur l’appareil.
Appelez SetupDiGetDeviceInstanceId pour récupérer l’ID d’instance d’appareil 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 l’appareil résultant hérite de la liste des pilotes de classe, le cas échéant, associé 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.
[out, optional] DeviceInfoData
Pointeur vers une structure 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 cbSize membre de cette structure sur sizeof(SP_DEVINFO_DATA) avant d’appeler la fonction. Pour plus d’informations, consultez la section suivante Remarques.
Valeur de retour
La fonction retourne TRUE si elle réussit. Sinon, elle retourne FAUX 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 jeu 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 l’instance d’appareil spécifiée est identique à une clé d’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 l’appelant a fourni mémoire tampon DeviceInfoData 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 été ajouté en tant que nouveau membre de l’ensemble déjà.
Le DeviceInfoSet doit contenir uniquement des éléments sur l’ordinateur local.
Note
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. 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 |