RegOpenKeyExW, fonction (winreg.h)

Article
11/20/2024

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 transactionnelles sur une clé, appelez la fonction RegOpenKeyTransacted.

Syntaxe

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

Paramètres

[in] hKey

Handle vers 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_LOCAL_MACHINEHKEY_USERS

[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 est 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 à la clé ouverte.

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

[in] ulOptions

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

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

[in] samDesired

Masque qui spécifie les droits d’accès souhaités à l’ouverture de la clé. 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é des clés 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 de retour

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 de FORMAT_MESSAGE_FROM_SYSTEM pour obtenir une description générique de l’erreur.

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é lorsque le handle de la clé a été obtenu. 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é autorise. En revanche, la fonction RegSetValueEx nécessite 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 Registry Virtualization 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.

Note

L’en-tête winreg.h définit RegOpenKeyEx 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	Windows 2000 Professionnel [applications de bureau uniquement]
serveur minimum pris en charge	Windows 2000 Server [applications de bureau uniquement]
plateforme cible	Windows
d’en-tête	winreg.h (inclure Windows.h)
bibliothèque	Advapi32.lib
DLL	Advapi32.dll