WdfFdoInitOpenRegistryKey-Funktion (wdffdo.h)

Artikel
03/01/2024

[Gilt für KMDF und UMDF]

Die WdfFdoInitOpenRegistryKey-Methode öffnet den Hardwareschlüssel eines Geräts oder den Softwareschlüssel eines Treibers in der Registrierung und erstellt ein Framework-Registrierungsschlüsselobjekt, das den Registrierungsschlüssel darstellt.

Syntax

NTSTATUS WdfFdoInitOpenRegistryKey(
  [in]           PWDFDEVICE_INIT        DeviceInit,
  [in]           ULONG                  DeviceInstanceKeyType,
  [in]           ACCESS_MASK            DesiredAccess,
  [in, optional] PWDF_OBJECT_ATTRIBUTES KeyAttributes,
  [out]          WDFKEY                 *Key
);

Parameter

[in] DeviceInit

Ein Zeiger auf eine WDFDEVICE_INIT Struktur, die der Treiber aus seiner Rückruffunktion EvtDriverDeviceAdd abgerufen hat.

[in] DeviceInstanceKeyType

Gibt an, welcher Schlüssel oder Unterschlüssel geöffnet werden soll.

Hinweis

UMDF unterstützt das Erstellen von Unterschlüsseln nicht.

Dies ist ein bitweiser OR der folgenden Flags (die in Wdm.h definiert sind).

DeviceInstanceKeyType-Flag	Bedeutung	Framework
PLUGPLAY_REGKEY_DEVICE	Öffnet den Hardwareschlüssel des Geräts.	KMDF/UMDF
PLUGPLAY_REGKEY_DRIVER	Öffnet den Softwareschlüssel des Treibers. Ein UMDF-Treiber, der dieses Flag festlegt, muss auch DesiredAccess auf KEY_READ festlegen. Andernfalls gibt diese Methode STATUS_ACCESS_DENIED zurück.	KMDF/UMDF
PLUGPLAY_REGKEY_CURRENT_HWPROFILE	Ein KMDF-Treiber verwendet dieses Flag, um die Kopie des Hardware- oder Softwareschlüssels im aktuellen Hardwareprofil zu öffnen.	KMDF
PLUGPLAY_REGKEY_DRIVER \| WDF_REGKEY_DRIVER_SUBKEY	Ein UMDF-Treiber verwendet diese Flags zusammen, um den Unterschlüssel ServiceName des Treibersoftwareschlüssels für Lese-/Schreibzugriff zu öffnen.	UMDF
PLUGPLAY_REGKEY_DEVICE \| WDF_REGKEY_DEVICE_SUBKEY	Ebenso verwendet ein UMDF-Treiber diese Flags, um den Unterschlüssel ServiceName des Hardwareschlüssels des Geräts für Lese-/Schreibzugriff zu öffnen.	UMDF

[in] DesiredAccess

Ein ACCESS_MASK typisierter Wert, der Zugriffsrechte angibt, die der Treiber für den angegebenen Registrierungsschlüssel anfordert.

Ein KMDF-Treiber fordert in der Regel KEY_READ, KEY_WRITE oder KEY_READ | KEY_WRITE.

Wenn Sie einen UMDF-Treiber schreiben, verwenden Sie die folgende Tabelle.

DeviceInstanceKeyType	DesiredAccess
PLUGPLAY_REGKEY_DEVICE	KEY_READ
PLUGPLAY_REGKEY_DEVICE \| WDF_REGKEY_DEVICE_SUBKEY	KEY_READ oder KEY_READ \| KEY_SET_VALUE
PLUGPLAY_REGKEY_DRIVER	KEY_READ
PLUGPLAY_REGKEY_DRIVER \| WDF_REGKEY_DRIVER_SUBKEY	KEY_READ oder KEY_READ \| KEY_SET_VALUE

Fragen Sie als bewährte Methode nur nach den Zugriffstypen, die Ihr Treiber benötigt.

[in, optional] KeyAttributes

Ein Zeiger auf eine WDF_OBJECT_ATTRIBUTES-Struktur , die vom Treiber bereitgestellte Attribute für das neue Registrierungsschlüsselobjekt enthält. Dieser Parameter ist optional und kann WDF_NO_OBJECT_ATTRIBUTES werden.

[out] Key

Ein Zeiger auf einen Speicherort, der ein Handle auf das neue Registrierungsschlüsselobjekt empfängt.

Rückgabewert

WdfFdoInitOpenRegistryKey gibt STATUS_SUCCESS zurück, wenn der Vorgang erfolgreich ist. Andernfalls gibt die Methode möglicherweise einen der folgenden Werte zurück:

Rückgabecode	Beschreibung
STATUS_INVALID_DEVICE_REQUEST	WdfFdoInitOpenRegistryKey wurde unter IRQL = PASSIVE_LEVEL nicht aufgerufen.
STATUS_INVALID_PARAMETER	Ein ungültiger Parameter wurde angegeben, oder der Treiber hat die WDFDEVICE_INIT-Struktur nicht aus seiner Rückruffunktion EvtDriverDeviceAdd abgerufen. Für UMDF kann dieser Rückgabewert auf unzureichende Zugriffsrechte hinweisen.
STATUS_INSUFFICIENT_RESOURCES	Ein Registrierungsschlüsselobjekt konnte nicht zugeordnet werden.
STATUS_OBJECT_NAME_NOT_FOUND	Der angegebene Registrierungsschlüssel ist nicht vorhanden.

Eine Liste anderer Rückgabewerte, die von der WdfFdoInitOpenRegistryKey-Methode möglicherweise zurückgegeben werden, finden Sie unter Fehler beim Erstellen von Frameworkobjekten.

Die Methode kann auch andere NTSTATUS-Werte zurückgeben.

Hinweise

Der Treiber muss WdfFdoInitOpenRegistryKey aufrufen, bevor er WdfDeviceCreate aufruft. Weitere Informationen zum Aufrufen von WdfDeviceCreate finden Sie unter Erstellen eines Framework-Geräteobjekts.

Weitere Informationen zur WdfFdoInitOpenRegistryKey-Methode finden Sie unter Erstellen von Geräteobjekten in einem Funktionstreiber.

oder weitere Informationen zur Registrierung, Hardware- und Softwareschlüsseln sowie Registrierungsobjekten finden Sie unter Verwenden der Registrierung in Framework-Based Drivers.

Beispiele

Im folgenden Codebeispiel wird der Hardwareschlüssel eines Geräts mit Lesezugriff geöffnet.

WDFKEY key;
NTSTATUS status;

status = WdfFdoInitOpenRegistryKey(
                                   DeviceInit,
                                   PLUGPLAY_REGKEY_DEVICE,
                                   GENERIC_READ,
                                   WDF_NO_OBJECT_ATTRIBUTES,
                                   &key
                                   );
if (!NT_SUCCESS(status)) {
    return status;
}

Anforderungen

Anforderung	Wert
Zielplattform	Universell
KMDF-Mindestversion	1.0
UMDF-Mindestversion	2.0
Kopfzeile	wdffdo.h (einschließen von Wdf.h)
Bibliothek	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
DDI-Complianceregeln	DeviceInitAPI(kmdf), DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Weitere Informationen

WdfDeviceOpenRegistryKey

WdfDriverOpenParametersRegistryKey

Freigeben über