Fonction RegOpenKeyExA (winreg.h)

Article
08/27/2023

Ouvre la clé de Registre spécifiée. Notez que les noms de clés ne respectent pas la casse.

Pour effectuer des opérations de Registre traitées sur une clé, appelez la fonction RegOpenKeyTransacted .

Syntaxe

LSTATUS RegOpenKeyExA(
  [in]           HKEY   hKey,
  [in, optional] LPCSTR lpSubKey,
  [in]           DWORD  ulOptions,
  [in]           REGSAM samDesired,
  [out]          PHKEY  phkResult
);

Paramètres

[in] hKey

Handle d’une clé de Registre ouverte. Ce handle est retourné par la fonction RegCreateKeyEx ou RegOpenKeyEx , ou il peut s’agir de l’une des clés prédéfinies suivantes :

HKEY_CLASSES_ROOTHKEY_CURRENT_CONFIGHKEY_CURRENT_USERHKEY_USERS HKEY_LOCAL_MACHINE

[in, optional] lpSubKey

Nom de la sous-clé de Registre à ouvrir.

Les noms de clés ne respectent pas la casse.

Si le paramètre lpSubKey a la valeur NULL ou un pointeur vers une chaîne vide, et si hKey est une clé prédéfinie, le système actualise la clé prédéfinie et phkResult reçoit le même handle hKey passé dans la fonction. Sinon, phkResult reçoit un nouveau handle pour la clé ouverte.

Pour plus d’informations, consultez Limites de taille des éléments du Registre.

[in] ulOptions

Spécifie l’option à appliquer lors de l’ouverture de la clé. Définissez ce paramètre sur zéro ou sur ce qui suit :

Valeur	Signification
REG_OPTION_OPEN_LINK	La clé est un lien symbolique. Les liens symboliques du Registre ne doivent être utilisés que lorsque cela est absolument nécessaire.

[in] samDesired

Masque qui spécifie les droits d’accès souhaités à la clé à ouvrir. La fonction échoue si le descripteur de sécurité de la clé n’autorise pas l’accès demandé pour le processus appelant. Pour plus d’informations, consultez Sécurité de la clé de Registre et droits d’accès.

[out] phkResult

Pointeur vers une variable qui reçoit un handle vers la clé ouverte. Si la clé n’est pas l’une des clés de Registre prédéfinies, appelez la fonction RegCloseKey une fois que vous avez terminé d’utiliser le handle.

Valeur retournée

Si la fonction réussit, la valeur de retour est ERROR_SUCCESS.

Si la fonction échoue, la valeur de retour est un code d’erreur différent de zéro défini dans Winerror.h. Vous pouvez utiliser la fonction FormatMessage avec l’indicateur FORMAT_MESSAGE_FROM_SYSTEM pour obtenir une description générique de l’erreur.

Notes

Sur les versions héritées de Windows, cette API est également exposée par kernel32.dll.

Remarques

Contrairement à la fonction RegCreateKeyEx , la fonction RegOpenKeyEx ne crée pas la clé spécifiée si la clé n’existe pas dans le Registre.

Certaines opérations de Registre effectuent des vérifications d’accès sur le descripteur de sécurité de la clé, et non sur le masque d’accès spécifié lors de l’obtention du handle de la clé. Par exemple, même si une clé est ouverte avec un samDesired de KEY_READ, elle peut être utilisée pour créer des clés de Registre si le descripteur de sécurité de la clé le permet. En revanche, la fonction RegSetValueEx exige spécifiquement que la clé soit ouverte avec le droit d’accès KEY_SET_VALUE.

Si votre service ou votre application emprunte l’identité de différents utilisateurs, n’utilisez pas cette fonction avec HKEY_CURRENT_USER. Au lieu de cela, appelez la fonction RegOpenCurrentUser .

Notez que les opérations qui accèdent à certaines clés de Registre sont redirigées. Pour plus d’informations, consultez Virtualisation du Registre et Données d’application 32 bits et 64 bits dans le Registre.

Exemples

lResult = RegOpenKeyEx (hKeyRoot, lpSubKey, 0, KEY_READ, &hKey);

if (lResult != ERROR_SUCCESS) 
{
    if (lResult == ERROR_FILE_NOT_FOUND) {
        printf("Key not found.\n");
        return TRUE;
    } 
    else {
        printf("Error opening key.\n");
        return FALSE;
    }
}

Pour voir cet exemple dans le contexte, consultez Suppression d’une clé avec des sous-clés.

Notes

L’en-tête winreg.h définit RegOpenKeyEx comme un 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.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 2000 Professionnel [applications de bureau uniquement]
Serveur minimal pris en charge	Windows 2000 Server [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	winreg.h (inclure Windows.h)
Bibliothèque	Advapi32.lib
DLL	Advapi32.dll