Méthode IPort ::NewRegistryKey (portcls.h)

La méthode NewRegistryKey ouvre une clé de Registre existante ou crée une clé dans le Registre. La méthode crée un objet de clé de Registre pour représenter la clé et génère une référence à cet objet à l’appelant. L’appelant accède ensuite à la clé via l’interface IRegistryKey de l’objet.

Syntaxe

NTSTATUS NewRegistryKey(
  PREGISTRYKEY       *OutRegistryKey,
  PUNKNOWN           OuterUnknown,
  ULONG              RegistryKeyType,
  ACCESS_MASK        DesiredAccess,
  POBJECT_ATTRIBUTES ObjectAttributes,
  ULONG              CreateOptions,
  PULONG             Disposition
);

Paramètres

OutRegistryKey

Pointeur vers une variable de pointeur allouée par l’appelant dans laquelle la méthode écrit la référence à l’objet IRegistryKey. Cet objet représente la clé de Registre en cours d’ouverture ou de création. L’appelant doit spécifier une valeur de pointeur non NULL valide pour ce paramètre.

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 comme NULL.

RegistryKeyType

Spécifie le type de clé de Registre auquel l’appelant demande l’accès. Pour plus d'informations, consultez la section Notes qui suit.

DesiredAccess

Masque de contrôle d’accès qui spécifie le type d’accès requis par l’appelant à la clé. Ce paramètre est de type ACCESS_MASK. Pour plus d'informations, consultez la section Notes qui suit.

ObjectAttributes

Pointeur vers les attributs d’objet de la clé en cours de création ou d’ouverture. Si RegistryKeyType a la valeur GeneralRegistryKey, ce paramètre doit pointer vers une structure système valide et initialisée de type OBJECT_ATTRIBUTES avec une chaîne ObjectName valide pour la clé ; sinon, la méthode n’utilise pas ce paramètre. Pour plus d'informations, consultez la section Notes qui suit.

CreateOptions

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

Disposition

Pointeur vers une variable ULONG allouée par l’appelant dans laquelle la méthode écrit une valeur status indiquant si une nouvelle 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’a pas besoin de la valeur status. La méthode utilise ce paramètre uniquement si RegistryKeyType a la valeur GeneralRegistryKey. La méthode n’utilise pas le paramètre pour les autres types de clés. Pour plus d'informations, consultez la section Notes qui suit.

Valeur retournée

Cette méthode retourne NTSTATUS qui contient STATUS_SUCCESS si l’appel a réussi. Sinon, la méthode retourne un code d’erreur approprié.

Remarques

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

Si le paramètre RegistryKeyType a la valeur GeneralRegistryKey, la méthode NewRegistryKey ouvre une clé de Registre existante ou crée une clé dans le Registre, comme indiqué par la valeur que la méthode génère via le paramètre Disposition. Si le type de clé est une valeur autre que GeneralRegistryKey, la méthode ouvre une clé déjà existante qui a été créée précédemment pendant Plug-and-Play énumération d’appareil.

L’appelant doit définir le paramètre RegistryKeyType sur l’une des valeurs d’énumération indiquées dans le tableau suivant.

Valeur RegistryKeyType	Signification
GeneralRegistryKey	Fournir un accès générique à n’importe quel type de clé. Ouvre la clé si elle existe ou crée la clé si ce n’est pas le cas.
DeviceRegistryKey	Ouvrez une clé existante contenant des informations spécifiques à l’appareil.
DriverRegistryKey	Ouvrez une clé existante contenant des informations spécifiques au pilote.
HwProfileRegistryKey	Ouvrez une clé existante relative au profil matériel actuel pour obtenir des informations sur le périphérique ou le pilote. Cela permet au pilote d’accéder aux informations de configuration spécifiques au profil matériel.
DeviceInterfaceRegistryKey	Ouvrez une clé de Registre existante contenant des informations sur un instance d’interface d’appareil particulier.

Pour une valeur RegistryKeyType de GeneralRegistryKey, l’appelant doit fournir une valeur de paramètre ObjectAttributes valide, et les paramètres CreateOptions et Disposition sont facultatifs. Pour toute autre valeur RegistryKeyType, l’appelant doit fournir une valeur de paramètre DeviceObject valide, et les paramètres CreateOptions et Disposition ne sont pas utilisés.

Le paramètre ObjectAttributes pointe vers une structure opaque de type OBJECT_ATTRIBUTES qui contient des attributs d’objet tels que le nom de clé et le descripteur de sécurité. Utilisez la macro InitializeObjectAttributes pour initialiser la structure. Dans le paramètre Attributes pour cette macro, définissez l’indicateur OBJ_KERNEL_HANDLE, sauf si vous avez l’intention d’autoriser les applications non sécurisées en mode utilisateur à disposer d’un accès en lecture/écriture à la clé de Registre.

Le paramètre DesiredAccess est un masque de contrôle d’accès. Il spécifie le type de contrôle d’accès que l’appelant doit avoir à la nouvelle clé de Registre lors de l’accès à celle-ci via l’objet OutRegistryKey. Ce masque ne doit pas être confondu avec l’ACL (liste de contrôle d’accès) qui contrôle l’accès des utilisateurs à la clé de Registre. Lors de l’appel de NewRegistryKey pour créer 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 l’ACL. Toutefois, si le type de clé est GeneralRegistryKey et que le pointeur de descripteur de sécurité dans la structure ObjectAttributes a la valeur NULL ou que le pointeur ACL dans le descripteur de sécurité est NULL, la nouvelle clé créée par l’appel héritera de la liste de contrôle d’accès de la clé parente par défaut.

Si la clé n’est pas de type GeneralRegistryKey, la clé conserve la liste de contrôle d’accès qui Plug-and-Play affectée à la clé lors de sa création lors de l’énumération de l’appareil.

La méthode NewRegistryKey est similaire à la fonction PcNewRegistryKey, sauf que l’objet d’appareil et l’objet de port doivent être spécifiés explicitement dans un appel PcNewRegistryKey, mais sont simplement impliqués dans un appel NewRegistryKey. PcNewRegistryKey est généralement appelé par les pilotes d’adaptateur. Les pilotes miniport appellent généralement NewRegistryKey à la place.

Une fois qu’une clé de Registre a été créée ou ouverte par un appel à NewRegistryKey ou PcNewRegistryKey, la méthode IRegistryKey ::NewSubKey peut être utilisée pour créer des sous-clés sous cette clé.

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

Configuration requise

Condition requise	Valeur
En-tête	portcls.h
IRQL	PASSIVE_LEVEL

Voir aussi

IPort