SetupDiCreateDevRegKeyA, fonction (setupapi.h)
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 vers un jeu d’informations d’appareil qui contient un élément d’informations d’appareil qui représente l’appareil pour lequel créer une clé de Registre.
[in] DeviceInfoData
Pointeur vers une structure SP_DEVINFO_DATA qui spécifie l’élément d’informations d’appareil dans DeviceInfoSet.
[in] Scope
Étendue de la clé de Registre à créer. L’étendue détermine l’emplacement où les informations sont stockées. La clé créée peut être spécifique au profil global ou matériel. Il peut s’agir de l’une des valeurs suivantes :
DICS_FLAG_GLOBAL
Créez une clé pour stocker les informations de configuration globales. Ces informations ne sont pas spécifiques à un profil matériel particulier. Sur les systèmes d’exploitation basés sur NT, cela crée une clé racine à 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 les informations de configuration spécifiques au profil matériel. Cette clé est enracinée dans l’une des branches spécifiques au 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 est 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. Il peut s’agir de 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 vers un fichier INF ouvert qui contient une section d'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 doivent également être spécifiés.
Valeur de retour
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 antérieures de Windows, ce handle a KEY_ALL_ACCESS accès.
L’instance d’appareil spécifiée doit être inscrite avant setupDiCreateDevRegKey est appelée. 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’appareils non PnP, consultez SetupDiRegisterDeviceInfo.
Pour les installations qui utilisent des fichiers de disposition (spécifiées 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 du Kit de développement logiciel (SDK) Microsoft Windows) avant SetupDiCreateDevRegKey est appelé.
Si le jeu d’informations d’appareil fourni contient des éléments d’informations sur l’appareil pour un système distant, et 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.
Note
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. 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 |