PcNewRegistryKey-Funktion (portcls.h)
Die PcNewRegistryKey--Funktion wird geöffnet oder erstellt einen neuen Registrierungsschlüssel und erstellt ein IRegistryKey--Objekt, das den Schlüssel darstellt. 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 von dieser Funktion erstellte Registrierungsschlüsselobjekt. Dieser Parameter verweist auf eine vom Aufrufer zugewiesene 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, nichtNULL- Zeigerwert für diesen Parameter an.
[in, optional] OuterUnknown
Zeiger auf die IUnknown- Schnittstelle eines Objekts, das das OutRegistryKey-Objekt aggregieren muss. Wenn keine Aggregation erforderlich ist, legen Sie diesen Parameter auf NULL-fest.
[in] RegistryKeyType
Gibt den Registrierungsschlüsseltyp 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. Er gibt den Typ des Zugriffs an, den der Aufrufer an 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 gegossen. Wenn RegistryKeyType- ein anderer Wert als GeneralRegistryKey-ist, muss dieser Parameter auf eine gültige, initialisierte Systemstruktur vom Typ DEVICE_OBJECTverweisen. Wenn der Wert von RegistryKeyTypeGeneralRegistryKeyist, 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
Zeigen Sie auf die Objektattribute des zu erstellenden oder geöffneten Schlüssels. Wenn RegistryKeyType- den Wert GeneralRegistryKey-aufweist, muss dieser Parameter auf eine gültige, initialisierte Systemstruktur des Typs 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 wird. Wenn RegistryKeyType- nicht GeneralRegistryKey-ist, ignoriert die funktion PcNewRegistryKey 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 entsprechender Fehlercode zurückgegeben.
Bemerkungen
Wenn der Wert des RegistryKeyType- Parameters GeneralRegistryKeyist, ö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 der Plug- und Play-Geräteenumeration erstellt wurde.
Die parameter DesiredAccess, ObjectAttributes, CreateOptionsund Disposition Parameter übernehmen die Werte, die für die Parameter mit denselben Namen im ZwCreateKey Aufruf definiert sind.
Der RegistryKeyType Parameter sollte auf einen der Enumerationswerte festgelegt werden, die in der folgenden Tabelle angezeigt werden.
| RegistryKeyType-Wert | Bedeutung |
|---|---|
| GeneralRegistryKey- | Bieten Sie generischen Zugriff auf einen beliebigen Schlüsseltyp. Öffnen Sie den angegebenen Schlüssel, wenn er bereits vorhanden ist, oder erstellen Sie den Schlüssel, wenn er nicht vorhanden ist. |
| DeviceRegistryKey- | Öffnen Sie einen vorhandenen Schlüssel, der gerätespezifische Informationen enthält. Der Schlüssel befindet sich unter dem Schlüssel für die geräteinstanz, die durch DeviceObjectangegeben wird. |
| 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 Konfigurationsinformationen zugreifen, die hardwarespezifisch sind. |
| DeviceInterfaceRegistryKey- | Wird nicht mit PcNewRegistryKeyverwendet. Weitere Informationen finden Sie unter IPort::NewRegistryKey. |
Für einen RegistryKeyType- Wert von GeneralRegistryKeymuss der Aufrufer einen gültigen ObjectAttributes Parameterwert bereitstellen, und die CreateOptions und Disposition Parameter sind optional. Für alle anderen RegistryKeyType--Wert muss der Aufrufer einen gültigen DeviceObject Parameterwert bereitstellen, und die CreateOptions und Disposition Parameter werden nicht verwendet.
Der ObjectAttributes Parameter verweist auf eine undurchsichtige Struktur des Typs OBJECT_ATTRIBUTES, die Objektattribute wie Schlüsselname und Sicherheitsbeschreibung enthält. Verwenden Sie das InitializeObjectAttributes- Makro, um die Struktur zu initialisieren. Legen Sie im Attributes Parameter für dieses Makro das OBJ_KERNEL_HANDLE Flag fest, es sei denn, Sie beabsichtigen, nicht sichere Anwendungen im Benutzermodus Lese-/Schreibzugriff auf den Registrierungsschlüssel zu gewähren.
Der parameter DesiredAccess ist ein Zugriffssteuerungsformat. Er gibt den Typ der Zugriffssteuerung an, über den der Aufrufer beim Zugriff auf den neuen Registrierungsschlüssel über das OutRegistryKey-Objekt verfügen muss. Diese Maske sollte nicht mit der Zugriffssteuerungsliste (Access Control List, ACL) verwechselt werden, die den Zugriff von Benutzern auf den Registrierungsschlüssel steuert. Beim Aufrufen von PcNewRegistryKey zum Erstellen eines Registrierungsschlüssels vom Typ GeneralRegistryKeygibt 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 und entweder der Sicherheitsdeskriptorzeiger in der ObjectAttributes-Struktur NULL- ist 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 von einem anderen Typ als GeneralRegistryKeyist, behält der Schlüssel die ACL bei, die dem Schlüssel zugewiesen ist, 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- auf.
Die Parameter OutRegistryKey und OuterUnknown folgen den Referenzzählungskonventionen für COM-Objekte.
Anforderungen
| Anforderung | Wert |
|---|---|
| mindestens unterstützte Client- | Der PortCls-Systemtreiber implementiert die PcNewRegistryKey-Funktion in Microsoft Windows 98/Me und in Windows 2000 und höher. |
| Zielplattform- | Universal |
| Header- | portcls.h (include Portcls.h) |
| Library | Portcls.lib |
| IRQL- | PASSIVE_LEVEL |