IRegistryKey::NewSubKey-Methode (portcls.h)

Artikel
02/29/2024

Die NewSubKey Methode erstellt entweder einen neuen Registrierungsunterschlüssel oder öffnet einen vorhandenen Unterschlüssel unter dem Schlüssel, der durch das IRegistryKey-Objekt dargestellt wird.

Syntax

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

Parameter

[out] RegistrySubKey

Ausgabezeiger für den neuen Unterschlüssel. Dieser Parameter verweist auf eine vom Aufrufer zugewiesene Zeigervariable, in die die -Methode den Zeiger auf das neue IRegistryKey-Objekt schreibt. Dieses Objekt stellt den zu öffnenden oder erstellten Unterschlüssel dar. Geben Sie einen gültigen Zeigerwert ohne NULL für diesen Parameter an.

[in] 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.

[in] DesiredAccess

Gibt den Typ des Zugriffs an, den der Aufrufer für den geöffneten oder erstellten Unterschlüssel benötigt. Dieser Parameter ist vom Typ ACCESS_MASK. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".

[in] SubKeyName

Zeiger auf den Namen, der dem Unterschlüssel zugewiesen werden soll. Dieser Parameter muss ein gültiger Nicht-NULL-Zeiger auf eine initialisierte Struktur vom Typ UNICODE_STRING sein.

[in] CreateOptions

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

[out, optional] Disposition

Ausgabezeiger für den Dispositionswert. Dieser Parameter verweist 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 ihn nicht benötigt. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".

Rückgabewert

NewSubKey gibt STATUS_SUCCESS zurück, wenn der Aufruf erfolgreich einen gültigen IRegistryKey-Zeiger über den RegistrySubKey-Parameter ausgegeben hat. Andernfalls gibt die Methode einen entsprechenden Fehlercode zurück.

Hinweise

Die NewSubKey Methode öffnet entweder den angegebenen Registrierungsschlüssel, wenn er bereits vorhanden ist, oder erstellt einen neuen Schlüssel in der Registrierung, falls er nicht vorhanden ist. Die -Methode gibt einen Zeiger auf die IRegistryKey-Schnittstelle des neuen Schlüssels über den RegistrySubKey-Parameter aus. Die Methode gibt auch einen status-Wert über den optionalen Disposition-Parameter aus, um anzugeben, ob der Schlüssel geöffnet oder erstellt wurde.

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

Der DesiredAccess-Parameter ist eine Zugriffssteuerungsmaske, die den Typ der Zugriffssteuerung angibt, die der Aufrufer beim Zugriff über das RegistrySubKey-Objekt auf den Unterschlüssel haben muss. Diese Maske sollte nicht mit der ACL (Zugriffssteuerungsliste) verwechselt werden, die den Zugriff von Benutzern auf den Registrierungsunterschlüssel steuert. Wenn die PcNewRegistryKey-Funktion oder die IPort::NewRegistryKey-Methode einen Registrierungsschlüssel vom Typ GeneralRegistryKey erstellt, gibt der ObjectAttributes-Parameter die Attribute des Schlüssels an, einschließlich eines Sicherheitsdeskriptors, der die ACL enthält. Wenn die NewSubKey Methode jedoch einen neuen Registrierungsunterschlüssel erstellt, erbt dieser Unterschlüssel einfach die ACL vom übergeordneten Schlüssel. Die NewSubKey -Methode bietet keine Möglichkeit, eine ACL anzugeben, die sich von der des übergeordneten Schlüssels unterscheidet.

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