PcNewRegistryKey-Funktion (portcls.h)

Artikel
08/07/2023

Die PcNewRegistryKey-Funktion wird geöffnet oder erstellt einen neuen Registrierungsschlüssel und ein IRegistryKey-Objekt zur Darstellung des Schlüssels. Der Aufrufer greift über dieses Objekt auf den Schlüssel zu.

Syntax

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
);

Parameter

[out] OutRegistryKey

Ausgabezeiger auf das Registrierungsschlüsselobjekt, das von dieser Funktion erstellt wurde. Dieser Parameter verweist auf eine vom Aufrufer zugeordnete Zeigervariable, in die die Funktion den Zeiger auf das IRegistryKey-Objekt ausgibt. Das -Objekt stellt den Registrierungsschlüssel dar, der geöffnet oder erstellt wird. Geben Sie einen gültigen Zeigerwert ohne NULL für diesen Parameter an.

[in, optional] OuterUnknown

Zeiger auf die IUnknown-Schnittstelle eines Objekts, das das OutRegistryKey-Objekt aggregieren muss. Legen Sie diesen Parameter auf NULL fest, sofern keine Aggregation erforderlich ist.

[in] RegistryKeyType

Gibt den Typ des Registrierungsschlüssels an, den der Aufrufer erstellen oder öffnen möchte. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".

[in] DesiredAccess

Gibt eine Zugriffssteuerungsmaske an. Dieser Parameter ist eine Struktur vom Typ ACCESS_MASK. Es gibt den Typ des Zugriffs an, den der Aufrufer auf den Registrierungsschlüssel anfordert, der geöffnet oder erstellt werden soll. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".

[in, optional] DeviceObject

Zeiger auf das Geräteobjekt des Adaptertreibers. Dieser Zeiger wird in den Typ PVOID umgewandelt. Wenn RegistryKeyType ein anderer Wert als GeneralRegistryKey ist, muss dieser Parameter auf eine gültige, initialisierte Systemstruktur vom Typ DEVICE_OBJECT verweisen. Wenn der Wert von RegistryKeyTypeGeneralRegistryKey ist, verwendet die PcNewRegistryKey-Funktion diesen Parameter nicht. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".

[in, optional] SubDevice

Gibt den Aspekt des Geräts an, das Clients angeboten werden soll. Adaptertreiber müssen diesem Parameter den Wert NULL zuweisen.

[in, optional] ObjectAttributes

Zeiger auf die Objektattribute des Schlüssels, der erstellt oder geöffnet wird. Wenn RegistryKeyType den Wert GeneralRegistryKey hat, muss dieser Parameter auf eine gültige, initialisierte Systemstruktur vom Typ OBJECT_ATTRIBUTES mit einer gültigen ObjectName-Zeichenfolge für den Schlüssel verweisen. Andernfalls verwendet die Funktion diesen Parameter nicht. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".

[in, optional] CreateOptions

Gibt die Erstellungsoptionen an. Kann null sein, wenn keines gewünscht ist. Wenn RegistryKeyType nicht GeneralRegistryKey ist, ignoriert die PcNewRegistryKey-Funktion diesen Parameter. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".

[out, optional] Disposition

Zeiger auf eine Variable, die einen Wert empfängt, der angibt, ob ein Schlüssel erstellt oder ein vorhandener Schlüssel geöffnet wurde. Dieser Parameter ist optional und kann als NULL angegeben werden. Wenn RegistryKeyType ein anderer Wert als GeneralRegistryKey ist, ignoriert die PcNewRegistryKey-Funktion diesen Parameter. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".

Rückgabewert

PcNewRegistryKey gibt STATUS_SUCCESS zurück, wenn der Aufruf erfolgreich war. Andernfalls wird ein geeigneter Fehlercode zurückgegeben.

Hinweise

Wenn der Wert des RegistryKeyType-ParametersGeneralRegistryKey lautet, öffnet die PcNewRegistryKey-Funktion entweder einen vorhandenen Schlüssel oder erstellt einen neuen Schlüssel in der Registrierung, wie durch den Wert angegeben, den die Funktion über den Parameter Disposition ausgibt. Wenn der Schlüssel einen anderen Typ als GeneralRegistryKey aufweist, öffnet die Funktion einen bereits vorhandenen Schlüssel, der zuvor während Plug & Play Geräteenumeration erstellt wurde.

Die Parameter DesiredAccess, ObjectAttributes, CreateOptions und Disposition übernehmen die Werte, die für die Parameter mit denselben Namen im ZwCreateKey-Aufruf definiert sind.

Der Parameter RegistryKeyType sollte auf einen der in der folgenden Tabelle aufgeführten Enumerationswerte festgelegt werden.

RegistryKeyType-Wert	Bedeutung
GeneralRegistryKey	Stellen Sie generischen Zugriff auf jeden Schlüsseltyp bereit. Öffnen Sie den angegebenen Schlüssel, falls er bereits vorhanden ist, oder erstellen Sie den Schlüssel, falls dies nicht der Fall ist.
DeviceRegistryKey	Öffnen Sie einen vorhandenen Schlüssel, der gerätespezifische Informationen enthält. Der Schlüssel befindet sich unter dem Von DeviceObject angegebenen Schlüssel für das Gerät instance.
DriverRegistryKey	Öffnen Sie einen vorhandenen Schlüssel, der treiberspezifische Informationen enthält.
HwProfileRegistryKey	Öffnen Sie einen vorhandenen Schlüssel relativ zum aktuellen Hardwareprofil, das Geräte- oder Treiberinformationen enthält. Dadurch kann der Treiber auf hardwareprofilspezifische Konfigurationsinformationen zugreifen.
DeviceInterfaceRegistryKey	Wird nicht mit PcNewRegistryKey verwendet. Weitere Informationen finden Sie unter IPort::NewRegistryKey .

Für einen RegistryKeyType-Wert von GeneralRegistryKey muss der Aufrufer einen gültigen ObjectAttributes-Parameterwert angeben, und die Parameter CreateOptions und Disposition sind optional. Für jeden anderen RegistryKeyType-Wert muss der Aufrufer einen gültigen DeviceObject-Parameterwert angeben, und die Parameter CreateOptions und Disposition werden nicht verwendet.

Der Parameter ObjectAttributes verweist auf eine undurchsichtige Struktur vom Typ OBJECT_ATTRIBUTES, die Objektattribute wie Schlüsselname und Sicherheitsdeskriptor enthält. Verwenden Sie das Makro InitializeObjectAttributes , um die -Struktur zu initialisieren. Legen Sie im Parameter Attributes für dieses Makro das flag OBJ_KERNEL_HANDLE fest, es sei denn, Sie möchten nicht sicheren Anwendungen im Benutzermodus Lese-/Schreibzugriff auf den Registrierungsschlüssel gewähren.

Der DesiredAccess-Parameter ist eine Zugriffssteuerungsmaske. Es gibt den Typ der Zugriffssteuerung an, die der Aufrufer für den neuen Registrierungsschlüssel haben muss, wenn er über das OutRegistryKey-Objekt darauf zugreift. Diese Maske sollte nicht mit der Zugriffssteuerungsliste (Access Control List, ACL) verwechselt werden, die den Zugriff der Benutzer auf den Registrierungsschlüssel steuert. Wenn Sie PcNewRegistryKey aufrufen, um einen Registrierungsschlüssel vom Typ GeneralRegistryKey zu erstellen, gibt der Parameter ObjectAttributes die Attribute des Schlüssels an, einschließlich eines Sicherheitsdeskriptors, der die ACL enthält. Wenn der neue Schlüssel jedoch vom Typ GeneralRegistryKey ist und entweder der Sicherheitsdeskriptorzeiger in der ObjectAttributes-Struktur NULL oder der ACL-Zeiger im Sicherheitsdeskriptor NULL ist, erbt der neue Schlüssel standardmäßig die ACL des übergeordneten Schlüssels.

Wenn der Schlüssel einen anderen Typ als GeneralRegistryKey aufweist, behält der Schlüssel die ACL bei, die dem Schlüssel zugewiesen Plug & Play, als er während der Geräteenumeration erstellt wurde.

Die PcNewRegistryKey-Funktion ähnelt der IPort::NewRegistryKey-Methode , mit der Ausnahme, dass das Geräteobjekt und das Portobjekt explizit in einem PcNewRegistryKey-Aufruf angegeben werden müssen, aber einfach in einem NewRegistryKey-Aufruf impliziert werden. PcNewRegistryKey wird hauptsächlich von Adaptertreibern verwendet. Miniporttreiber rufen in der Regel NewRegistryKey stattdessen auf.

Die Parameter OutRegistryKey und OuterUnknown folgen den Referenzzählungskonventionen für COM-Objekte.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Der PortCls-Systemtreiber implementiert die PcNewRegistryKey-Funktion in Microsoft Windows 98/Me und windows 2000 und höher.
Zielplattform	Universell
Header	portcls.h (portcls.h einschließen)
Bibliothek	Portcls.lib
IRQL	PASSIVE_LEVEL