Méthode IRegistryKey ::NewSubKey (portcls.h)

Article
03/01/2024

La NewSubKey méthode crée une sous-clé de Registre ou ouvre une sous-clé existante sous la clé représentée par l’objet IRegistryKey .

Syntaxe

NTSTATUS NewSubKey(
  [out]           IRegistryKey    **RegistrySubKey,
  [in]            PUNKNOWN        OuterUnknown,
  [in]            ACCESS_MASK     DesiredAccess,
  [in]            PUNICODE_STRING SubKeyName,
  [in]            ULONG           CreateOptions,
  [out, optional] PULONG          Disposition
);

Paramètres

[out] RegistrySubKey

Pointeur de sortie pour la nouvelle sous-clé. Ce paramètre pointe vers une variable de pointeur allouée par l’appelant dans laquelle la méthode écrit le pointeur vers le nouvel objet IRegistryKey . Cet objet représente la sous-clé en cours d’ouverture ou de création. Spécifiez une valeur de pointeur non NULL valide pour ce paramètre.

[in] OuterUnknown

Pointeur vers l’interface IUnknown d’un objet qui doit agréger l’objet de clé de Registre. Ce paramètre est facultatif. Si l’agrégation n’est pas requise, spécifiez ce paramètre sur NULL.

[in] DesiredAccess

Spécifie le type d’accès requis par l’appelant à la sous-clé en cours d’ouverture ou de création. Ce paramètre est de type ACCESS_MASK. Pour plus d'informations, consultez la section Notes qui suit.

[in] SubKeyName

Pointeur vers le nom à affecter à la sous-clé. Ce paramètre doit être un pointeur non NULL valide vers une structure initialisée de type UNICODE_STRING.

[in] CreateOptions

Indicateurs indiquant les options de création. Peut être égal à zéro si aucun n’est souhaité. Ce paramètre est requis si la valeur de RegistryKeyType est GeneralRegistryKey ; sinon, la méthode n’utilise pas ce paramètre. Pour plus d'informations, consultez la section Notes qui suit.

[out, optional] Disposition

Pointeur de sortie pour la valeur de destruction. Ce paramètre pointe vers une variable ULONG allouée par l’appelant dans laquelle la méthode écrit une valeur status indiquant si une clé a été créée ou si une clé existante a été ouverte. Ce paramètre est facultatif et peut être spécifié comme NULL si l’appelant n’en a pas besoin. Pour plus d'informations, consultez la section Notes qui suit.

Valeur retournée

NewSubKey retourne STATUS_SUCCESS si l’appel a réussi à sortir un pointeur IRegistryKey valide via le paramètre RegistrySubKey . Sinon, la méthode retourne un code d’erreur approprié.

Remarques

La NewSubKey méthode ouvre la clé de Registre spécifiée si elle existe déjà, ou crée une clé dans le Registre si elle n’existe pas. La méthode génère un pointeur vers l’interface IRegistryKey de la nouvelle clé via le paramètre RegistrySubKey . La méthode génère également une valeur status via le paramètre facultatif Disposition pour indiquer si la clé a été ouverte ou créée.

Les paramètres DesiredAccess, CreateOptions et Disposition prennent les valeurs définies pour les paramètres portant les mêmes noms dans l’appel PcNewRegistryKey .

Le paramètre DesiredAccess est un masque de contrôle d’accès qui spécifie le type de contrôle d’accès que l’appelant doit avoir à la sous-clé lors de l’accès à celle-ci via l’objet RegistrySubKey . Ce masque ne doit pas être confondu avec la liste de contrôle d’accès (ACL) qui contrôle l’accès des utilisateurs à la sous-clé de Registre. Lorsque la fonction PcNewRegistryKey ou la méthode IPort ::NewRegistryKey crée une clé de Registre de type GeneralRegistryKey, le paramètre ObjectAttributes spécifie les attributs de la clé, y compris un descripteur de sécurité qui contient la liste de contrôle d’accès. Toutefois, lorsque la NewSubKey méthode crée une sous-clé de Registre, cette sous-clé hérite simplement de la liste de contrôle d’accès de sa clé parente. La NewSubKey méthode ne fournit aucun moyen de spécifier une liste de contrôle d’accès qui diffère de celle de la clé parente.

Les paramètres RegistrySubKey et OuterUnknown suivent les conventions de comptage des références pour les objets COM.