IPort::NewRegistryKey-Methode (portcls.h)

Die NewRegistryKey-Methode öffnet entweder einen vorhandenen Registrierungsschlüssel oder erstellt einen neuen Schlüssel in der Registrierung. Die -Methode erstellt ein Registrierungsschlüsselobjekt, um den Schlüssel darzustellen, und gibt einen Verweis auf dieses Objekt an den Aufrufer aus. Der Aufrufer greift dann über die IRegistryKey-Schnittstelle des Objekts auf den Schlüssel zu.

Syntax

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

Parameter

OutRegistryKey

Zeiger auf eine vom Aufrufer zugewiesene Zeigervariable, in die die -Methode den Verweis auf das IRegistryKey-Objekt schreibt. Dieses Objekt stellt den Registrierungsschlüssel dar, der geöffnet oder erstellt wird. Der Aufrufer muss einen gültigen Zeigerwert ohne NULL für diesen Parameter angeben.

OuterUnknown

Zeiger auf die IUnknown-Schnittstelle eines Objekts, das das Registrierungsschlüsselobjekt aggregieren muss. Dieser Parameter ist optional. Wenn die Aggregation nicht erforderlich ist, geben Sie diesen Parameter als NULL an.

RegistryKeyType

Gibt den Typ des Registrierungsschlüssels an, auf den der Aufrufer Zugriff anfordert. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".

DesiredAccess

Eine Zugriffssteuerungsmaske, die den Typ des Zugriffs angibt, den der Aufrufer für den Schlüssel benötigt. Dieser Parameter ist vom Typ ACCESS_MASK. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".

ObjectAttributes

Zeiger auf die Objektattribute des zu erstellenden oder geöffneten Schlüssels. Wenn RegistryKeyType über den Wert GeneralRegistryKey verfügt, 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 -Methode diesen Parameter nicht. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".

CreateOptions

Flags, die die Erstellungsoptionen angeben. Kann null sein, wenn keines gewünscht ist. Dieser Parameter ist erforderlich, wenn RegistryKeyType den Wert GeneralRegistryKey hat. Andernfalls verwendet die -Methode diesen Parameter nicht. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".

Disposition

Zeiger auf eine vom Aufrufer zugewiesene ULONG-Variable, in die die Methode einen status Wert schreibt, der angibt, ob ein neuer Schlüssel erstellt oder ein vorhandener Schlüssel geöffnet wurde. Dieser Parameter ist optional und kann als NULL angegeben werden, wenn der Aufrufer den status Wert nicht benötigt. Die -Methode verwendet diesen Parameter nur, wenn RegistryKeyType über den Wert GeneralRegistryKey verfügt. Die -Methode verwendet den -Parameter für keinen der anderen Schlüsseltypen. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".

Rückgabewert

Diese Methode gibt NTSTATUS zurück, die STATUS_SUCCESS enthält, wenn der Aufruf erfolgreich war. Andernfalls gibt die Methode einen entsprechenden Fehlercode zurück.

Hinweise

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

Wenn der RegistryKeyType-Parameter über den Wert GeneralRegistryKey verfügt, öffnet die NewRegistryKey-Methode entweder einen vorhandenen Registrierungsschlüssel oder erstellt einen neuen Schlüssel in der Registrierung, wie durch den Wert angegeben wird, den die Methode über den Disposition-Parameter ausgibt. Wenn der Schlüsseltyp ein anderer Wert als GeneralRegistryKey ist, öffnet die -Methode einen bereits vorhandenen Schlüssel, der zuvor während Plug & Play Geräteaufzählung erstellt wurde.

Der Aufrufer sollte den RegistryKeyType-Parameter auf einen der In der folgenden Tabelle aufgeführten Enumerationswerte festlegen.

RegistryKeyType-Wert	Bedeutung
GeneralRegistryKey	Stellen Sie generischen Zugriff auf einen beliebigen Schlüsseltyp bereit. Öffnet den Schlüssel, wenn er vorhanden ist, oder erstellt den Schlüssel, falls nicht.
DeviceRegistryKey	Öffnen Sie einen vorhandenen Schlüssel, der gerätespezifische Informationen enthält.
DriverRegistryKey	Öffnen Sie einen vorhandenen Schlüssel, der treiberspezifische Informationen enthält.
HwProfileRegistryKey	Öffnen Sie einen vorhandenen Schlüssel relativ zum aktuellen Hardwareprofil für Geräte- oder Treiberinformationen. Dadurch kann der Treiber auf Konfigurationsinformationen zugreifen, die hardwareprofilspezifisch sind.
DeviceInterfaceRegistryKey	Öffnen Sie einen vorhandenen Registrierungsschlüssel, der Informationen zu einer bestimmten Geräteschnittstelle instance enthält.

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 bereitstellen, und die Parameter CreateOptions und Disposition werden nicht verwendet.

Der ObjectAttributes-Parameter 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 Den Lese-/Schreibzugriff auf den Registrierungsschlüssel erlauben.

Der DesiredAccess-Parameter ist eine Zugriffssteuerungsmaske. Es gibt den Typ der Zugriffssteuerung an, die der Aufrufer auf den neuen Registrierungsschlüssel haben muss, wenn er über das OutRegistryKey-Objekt darauf zugreift. Diese Maske sollte nicht mit der ACL (Zugriffssteuerungsliste) verwechselt werden, die den Zugriff von Benutzern auf den Registrierungsschlüssel steuert. Beim Aufrufen von NewRegistryKey zum Erstellen eines Registrierungsschlüssels vom Typ GeneralRegistryKey gibt der ObjectAttributes-Parameter die Attribute des Schlüssels an, einschließlich einer Sicherheitsbeschreibung, die die ACL enthält. Wenn der Schlüsseltyp jedoch GeneralRegistryKey ist und entweder der Sicherheitsdeskriptorzeiger in der ObjectAttributes-Struktur NULL oder der ACL-Zeiger im Sicherheitsdeskriptor NULL ist, erbt der neue Schlüssel, der durch den Aufruf erstellt wurde, standardmäßig die ACL des übergeordneten Schlüssels.

Wenn der Schlüssel nicht vom Typ GeneralRegistryKey ist, behält der Schlüssel die ACL bei, die dem Schlüssel zugewiesen Plug & Play, als er während der Geräteaufzählung erstellt wurde.

Die NewRegistryKey-Methode ähnelt der PcNewRegistryKey-Funktion, 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 in der Regel von Adaptertreibern aufgerufen. Miniporttreiber rufen stattdessen normalerweise NewRegistryKey auf.

Nachdem ein Registrierungsschlüssel durch einen Aufruf von NewRegistryKey oder PcNewRegistryKey erstellt oder geöffnet wurde, kann die IRegistryKey::NewSubKey-Methode verwendet werden, um Unterschlüssel unter diesem Schlüssel zu erstellen.

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

Anforderungen

Anforderung	Wert
Header	portcls.h
IRQL	PASSIVE_LEVEL

Weitere Informationen

Iport