Fonction PcNewRegistryKey (portcls.h)

Article
08/07/2023

La fonction PcNewRegistryKey ouvre ou crée une clé de Registre et un objet IRegistryKey pour représenter la clé. L’appelant accède à la clé via cet objet.

Syntaxe

PORTCLASSAPI NTSTATUS PcNewRegistryKey(
  [out]           PREGISTRYKEY       *OutRegistryKey,
  [in, optional]  PUNKNOWN           OuterUnknown,
  [in]            ULONG              RegistryKeyType,
  [in]            ACCESS_MASK        DesiredAccess,
  [in, optional]  PVOID              DeviceObject,
  [in, optional]  PVOID              SubDevice,
  [in, optional]  POBJECT_ATTRIBUTES ObjectAttributes,
  [in, optional]  ULONG              CreateOptions,
  [out, optional] PULONG             Disposition
);

Paramètres

[out] OutRegistryKey

Pointeur de sortie vers l’objet de clé de Registre créé par cette fonction. Ce paramètre pointe vers une variable pointeur allouée par l’appelant dans laquelle la fonction génère le pointeur vers l’objet IRegistryKey . L’objet représente la clé de Registre en cours d’ouverture ou de création. Spécifiez une valeur de pointeur non NULL valide pour ce paramètre.

[in, optional] OuterUnknown

Pointeur vers l’interface IUnknown d’un objet qui doit agréger l’objet OutRegistryKey . Sauf si l’agrégation est requise, définissez ce paramètre sur NULL.

[in] RegistryKeyType

Spécifie le type de clé de Registre que l’appelant souhaite créer ou ouvrir. Pour plus d'informations, consultez la section Notes qui suit.

[in] DesiredAccess

Spécifie un masque de contrôle d’accès. Ce paramètre est une structure de type ACCESS_MASK. Elle indique le type d’accès que l’appelant demande à la clé de Registre qui doit être ouverte ou créée. Pour plus d'informations, consultez la section Notes qui suit.

[in, optional] DeviceObject

Pointeur vers l’objet de périphérique du pilote de l’adaptateur. Ce pointeur est converti en type PVOID. Si RegistryKeyType est une valeur autre que GeneralRegistryKey, ce paramètre doit pointer vers une structure système initialisée valide de type DEVICE_OBJECT. Si la valeur de RegistryKeyType est GeneralRegistryKey, la fonction PcNewRegistryKey n’utilise pas ce paramètre. Pour plus d'informations, consultez la section Notes qui suit.

[in, optional] SubDevice

Spécifie l’aspect de l’appareil qui doit être offert aux clients. Les pilotes d’adaptateur doivent affecter la valeur NULL à ce paramètre.

[in, optional] ObjectAttributes

Pointeur vers les attributs de l’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 initialisée valide de type OBJECT_ATTRIBUTES avec une chaîne ObjectName valide pour la clé ; sinon, la fonction n’utilise pas ce paramètre. Pour plus d'informations, consultez la section Notes qui suit.

[in, optional] CreateOptions

Spécifie les options de création. Peut être égal à zéro si aucun n’est souhaité. Si RegistryKeyType n’est pas GeneralRegistryKey, la fonction PcNewRegistryKey ignore ce paramètre. Pour plus d'informations, consultez la section Notes qui suit.

[out, optional] Disposition

Pointeur vers une variable qui reçoit une valeur 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 RegistryKeyType est une valeur autre que GeneralRegistryKey, la fonction PcNewRegistryKey ignore ce paramètre. Pour plus d'informations, consultez la section Notes qui suit.

Valeur retournée

PcNewRegistryKey retourne STATUS_SUCCESS si l’appel a réussi. Sinon, elle retourne un code d’erreur approprié.

Remarques

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

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

Le paramètre RegistryKeyType doit être défini 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é. Ouvrez la clé spécifiée si elle existe déjà ou créez la clé si ce n’est pas le cas.
DeviceRegistryKey	Ouvrez une clé existante contenant des informations spécifiques à l’appareil. La clé se trouve sous la clé de l’appareil instance spécifiée par DeviceObject.
DriverRegistryKey	Ouvrez une clé existante contenant des informations spécifiques au pilote.
HwProfileRegistryKey	Ouvrez une clé existante relative au profil matériel actuel contenant 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	Non utilisé avec PcNewRegistryKey. Pour plus d’informations, consultez IPort ::NewRegistryKey .

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 Attributs de cette macro, définissez l’indicateur OBJ_KERNEL_HANDLE, sauf si vous envisagez d’autoriser les applications non sécurisées en mode utilisateur à avoir 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 sur la nouvelle clé de Registre lors de l’accès à celle-ci via l’objet OutRegistryKey . 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 clé de Registre. Lorsque vous appelez PcNewRegistryKey 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 la liste de contrôle d’accès. Toutefois, si la nouvelle clé est de type GeneralRegistryKey et que le pointeur de descripteur de sécurité dans la structure ObjectAttributes est NULL ou que le pointeur ACL dans le descripteur de sécurité est NULL, la nouvelle clé hérite de la liste de contrôle d’accès de la clé parente par défaut.

Si la clé est d’un type autre que GeneralRegistryKey, la clé conserve la liste de contrôle d’accès qui Plug-and-Play affectée à la clé lorsqu’elle a été créée lors de l’énumération de l’appareil.

La fonction PcNewRegistryKey est similaire à la méthode IPort ::NewRegistryKey , 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 principalement utilisé par les pilotes d’adaptateur. Les pilotes miniport appellent généralement NewRegistryKey à la place.

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

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Le pilote système PortCls implémente la fonction PcNewRegistryKey dans Microsoft Windows 98/Me et dans les systèmes d’exploitation Windows 2000 et ultérieur.
Plateforme cible	Universal
En-tête	portcls.h (include Portcls.h)
Bibliothèque	Portcls.lib
IRQL	PASSIVE_LEVEL