FONCTION ORCreateKey

Article
06/13/2023

Crée la clé de Registre spécifiée dans une ruche de Registre hors connexion. Si la clé existe déjà, la fonction l’ouvre.

Syntaxe

DWORD ORCreateKey(
  _In_      ORHKEY               Handle,
  _In_      PCWSTR               lpSubKey,
  _In_opt_  PWSTR                lpClass,
  _In_opt_  DWORD                dwOptions,
  _In_opt_  PSECURITY_DESCRIPTOR pSecurityDescriptor,
  _Out_     PORHKEY              phkResult,
  _Out_opt_ PDWORD               pdwDisposition
);

Paramètres

Gérer [in]

Handle d’une clé de Registre ouverte dans une ruche de Registre hors connexion.

lpSubKey [in]

Pointeur vers une chaîne Unicode qui contient le nom d’une sous-clé que cette fonction ouvre ou crée. Le paramètre lpSubKey doit spécifier une sous-clé de la clé identifiée par le paramètre Handle ; il peut se trouver jusqu’à 32 niveaux de profondeur dans l’arborescence du Registre. Pour plus d’informations sur les noms de clés, consultez Structure du Registre.

Ce paramètre ne peut pas avoir la valeur NULL.

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

lpClass [in, facultatif]

Classe (type d’objet) de cette clé. Ce paramètre peut être ignoré. Ce paramètre peut être NULL.

dwOptions [in, facultatif]

Ce paramètre peut être 0 ou l’une des valeurs suivantes.

Valeur	Signification
REG_OPTION_CREATE_LINK 0x00000002L	La clé est un lien symbolique. Le chemin d’accès cible est affecté à la valeur L " SymbolicLinkValue " de la clé. Le chemin d’accès cible doit être un chemin d’accès de Registre absolu. Si cette option est définie, REG_OPTION_NON_VOLATILE doit également être défini. Si le paramètre lpSubKey spécifie une clé existante, elle doit avoir été créée avec REG_OPTION_CREATE_LINK. Les liens symboliques du Registre ne doivent être utilisés que lorsque cela est absolument nécessaire pour la compatibilité de l’application.
REG_OPTION_NON_VOLATILE 0x000000000L	La clé n’est pas volatile; il s’agit de la valeur par défaut. Les informations sont stockées dans un fichier et sont conservées lors du redémarrage du système. La fonction ORSaveHive enregistre les clés qui ne sont pas volatiles.

Valeur

Signification

REG_OPTION_CREATE_LINK
0x00000002L

La clé est un lien symbolique. Le chemin d’accès cible est affecté à la valeur L " SymbolicLinkValue " de la clé. Le chemin d’accès cible doit être un chemin d’accès de Registre absolu. Si cette option est définie, REG_OPTION_NON_VOLATILE doit également être défini.
Si le paramètre lpSubKey spécifie une clé existante, elle doit avoir été créée avec REG_OPTION_CREATE_LINK.
Les liens symboliques du Registre ne doivent être utilisés que lorsque cela est absolument nécessaire pour la compatibilité de l’application.

REG_OPTION_NON_VOLATILE
0x000000000L

La clé n’est pas volatile; il s’agit de la valeur par défaut. Les informations sont stockées dans un fichier et sont conservées lors du redémarrage du système. La fonction ORSaveHive enregistre les clés qui ne sont pas volatiles.

pSecurityDescriptor [in, facultatif]

Pointeur vers une structure SECURITY_DESCRIPTOR qui contient un descripteur de sécurité pour la nouvelle clé. Si pSecurityDescriptor a la valeur NULL, la clé obtient un descripteur de sécurité par défaut. Les ACL d’un descripteur de sécurité par défaut pour une clé sont héritées de sa clé parente directe.

phkResult [out]

Pointeur vers une variable qui reçoit un handle vers la clé ouverte ou créée. Utilisez la fonction ORCloseKey pour fermer la clé une fois que vous avez terminé d’utiliser le handle.

pdwDisposition [out, facultatif]

Pointeur vers une variable qui reçoit l’une des valeurs de disposition suivantes.

Valeur	Signification
REG_CREATED_NEW_KEY 0x00000001L	La clé n’existait pas et a été créée.
REG_OPENED_EXISTING_KEY 0x00000002L	La clé existait et était simplement ouverte sans être modifiée.

Si pdwDisposition a la valeur NULL, aucune information de disposition n’est retournée.

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.

Si le paramètre dwOptions est défini avec REG_OPTION_CREATE_LINK mais que REG_OPTION_NON_VOLATILE est clair, ou si le handle à retourner est un handle à la clé racine de la ruche, la fonction retourne ERROR_INVALID_PARAMETER.

Notes

La clé créée par la fonction ORCreateKey n’a aucune valeur. Une application peut utiliser la fonction ORSetValue pour définir des valeurs de clé.

La fonction ORCreateKey ne peut pas être utilisée pour créer la clé racine dans une ruche de Registre hors connexion. Utilisez la fonction ORCreateHive pour créer la clé racine et obtenir un handle à la clé.

Le Registre hors connexion ne prend pas en charge l’enregistrement de clés individuelles. Utilisez la fonction ORSaveHive pour enregistrer une clé et ses sous-clés dans une ruche.

Spécifications

Condition requise	Valeur
Composant redistribuable	Bibliothèque du Registre hors connexion Windows version 1.0 ou ultérieure
En-tête	Offreg.h
DLL	Offreg.dll

Voir aussi

ORCloseKey
ORCreateHive
ORDeleteKey
ORSaveHive
SECURITY_DESCRIPTOR

Partager via