SetupDiCreateDeviceInfoA, 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 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 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.

Exigences

Voir aussi

SP_DEVINFO_DATA

SetupDiDeleteDeviceInfo

SetupDiEnumDeviceInfo

SetupDiOpenDeviceInfo