SetupDiCreateDevRegKeyA, fonction (setupapi.h)

Article
08/26/2023

La fonction SetupDiCreateDevRegKey crée une clé de Registre pour les informations de configuration spécifiques à l’appareil et retourne un handle à la clé.

Syntaxe

WINSETUPAPI HKEY SetupDiCreateDevRegKeyA(
  [in]           HDEVINFO         DeviceInfoSet,
  [in]           PSP_DEVINFO_DATA DeviceInfoData,
  [in]           DWORD            Scope,
  [in]           DWORD            HwProfile,
  [in]           DWORD            KeyType,
  [in, optional] HINF             InfHandle,
  [in, optional] PCSTR            InfSectionName
);

Paramètres

[in] DeviceInfoSet

Handle d’un jeu d’informations d’appareil qui contient un élément d’informations sur l’appareil qui représente l’appareil pour lequel créer une clé de Registre.

[in] DeviceInfoData

Pointeur vers une structure de SP_DEVINFO_DATA qui spécifie l’élément d’informations sur l’appareil dans DeviceInfoSet.

[in] Scope

Étendue de la clé de Registre à créer. L’étendue détermine l’emplacement de stockage des informations. La clé créée peut être globale ou spécifique au profil matériel. Peut avoir l’une des valeurs suivantes :

DICS_FLAG_GLOBAL

Créez une clé pour stocker les informations de configuration globale. Ces informations ne sont pas spécifiques à un profil matériel particulier. Sur les systèmes d’exploitation NT, cela crée une clé enracinée à HKEY_LOCAL_MACHINE. La clé exacte ouverte dépend de la valeur du paramètre KeyType .

DICS_FLAG_CONFIGSPECIFIC

Créez une clé pour stocker des informations de configuration spécifiques au profil matériel. Cette clé est enracinée dans l’une des branches spécifiques du profil matériel, au lieu de HKEY_LOCAL_MACHINE.

[in] HwProfile

Profil matériel pour lequel créer une clé si HwProfileFlags est défini sur SPDICS_FLAG_CONFIGSPECIFIC. Si HwProfile a la valeur 0, la clé du profil matériel actuel est créée. Si HwProfileFlags est SPDICS_FLAG_GLOBAL, HwProfile est ignoré.

[in] KeyType

Type de clé de stockage de Registre à créer. Peut avoir l’une des valeurs suivantes :

DIREG_DEV

Créez une clé matérielle pour l’appareil.

DIREG_DRV

Créez une clé logicielle pour l’appareil.

[in, optional] InfHandle

Handle d’un fichier INF ouvert qui contient une section INF DDInstall à exécuter pour la clé nouvellement créée. Ce paramètre est facultatif et peut être NULL. Si ce paramètre est spécifié, InfSectionName doit également être spécifié.

[in, optional] InfSectionName

Nom d’une section INF DDInstall dans le fichier INF spécifié par InfHandle. Cette section est exécutée pour la clé nouvellement créée. Ce paramètre est facultatif et peut être NULL. Si ce paramètre est spécifié, InfHandle doit également être spécifié.

Valeur retournée

Si SetupDiCreateDevRegKey réussit, la fonction retourne un handle à la clé de Registre spécifiée dans laquelle les données de configuration spécifiques à l’appareil peuvent être stockées et récupérées. Si SetupDiCreateDevRegKey échoue, la fonction retourne INVALID_HANDLE_VALUE. Appelez GetLastError pour obtenir des informations d’erreur étendues.

Remarques

L’appelant de SetupDiCreateDevRegKey doit être membre du groupe Administrateurs.

Fermez le handle retourné par SetupDiCreateDevRegKey en appelant RegCloseKey.

Si la clé spécifiée existe déjà, SetupDiCreateDevRegKey retourne un handle à cette clé. Sinon, SetupDiCreateDevRegKey crée la clé spécifiée et retourne un handle à la nouvelle clé. Pour Windows Server 2003 et versions ultérieures de Windows, le handle de clé a KEY_READ et KEY_WRITE accès uniquement. Pour les versions précédentes de Windows, ce handle dispose d’un accès KEY_ALL_ACCESS.

Le instance d’appareil spécifié doit être inscrit avant l’appel de SetupDiCreateDevRegKey. Notez toutefois que le système d’exploitation inscrit automatiquement les instances d’appareil PnP. Pour plus d’informations sur l’inscription d’instances d’appareil non PnP, consultez SetupDiRegisterDeviceInfo.

Pour les installations qui utilisent des fichiers de disposition (spécifiés par l’entrée LayoutFile dans une section Version INF), le fichier de disposition doit être ouvert par un appel à SetupOpenAppendInfFile (décrit dans la documentation Microsoft Windows SDK) avant l’appel de SetupDiCreateDevRegKey.

Si le jeu d’informations sur l’appareil fourni contient des éléments d’informations sur l’appareil pour un système distant, et si InfHandle et InfSectionName sont également spécifiés, la demande de création échoue et un appel ultérieur à GetLastError retourne ERROR_REMOTE_REQUEST_UNSUPPORTED.

Notes

L’en-tête setupapi.h définit SetupDiCreateDevRegKey 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

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