IRegistryKey::NewSubKey-Methode (portcls.h)

Artikel
02/07/2025

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 in das neue IRegistryKey-Objekt schreibt. Dieses Objekt stellt den Unterschlüssel dar, der geöffnet oder erstellt wird. Geben Sie einen gültigen, nichtNULL- Zeigerwert 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 keine Aggregation erforderlich ist, geben Sie diesen Parameter als NULL-an.

[in] DesiredAccess

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

[in] SubKeyName

Zeigen Sie auf den Namen, der dem Unterschlüssel zugewiesen werden soll. Dieser Parameter muss ein gültiger, nichtNULL- Zeiger auf eine initialisierte Struktur vom Typ UNICODE_STRINGsein.

[in] CreateOptions

Flags, die die Erstellungsoptionen angeben. Kann null sein, wenn keines gewünscht wird. Dieser Parameter ist erforderlich, wenn der Wert von RegistryKeyTypeGeneralRegistryKeyist; 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 Statuswert 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 war, einen gültigen IRegistryKey- Zeiger über den RegistrySubKey Parameter auszugeben. Andernfalls gibt die Methode einen geeigneten Fehlercode zurück.

Bemerkungen

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

Die parameter DesiredAccess, CreateOptionsund Disposition Parameter übernehmen die Werte, die für die Parameter mit denselben Namen im PcNewRegistryKey Aufruf definiert sind.

Der parameter DesiredAccess ist ein Zugriffssteuerungsformat, das den Typ der Zugriffssteuerung angibt, die der Aufrufer für den Unterschlüssel benötigen muss, wenn er über das RegistrySubKey-Objekt darauf zugreifen kann. 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 IPort::NewRegistryKey-Methode einen Registrierungsschlüssel vom Typ GeneralRegistryKeyerstellt, 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 von seinem ü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 Konventionen für die Referenzzählung von COM-Objekten.