WdfDeviceOpenRegistryKey-Funktion (wdfdevice.h)
[Gilt für KMDF und UMDF]
Die WdfDeviceOpenRegistryKey-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 WdfDeviceOpenRegistryKey(
[in] WDFDEVICE Device,
[in] ULONG DeviceInstanceKeyType,
[in] ACCESS_MASK DesiredAccess,
[in, optional] PWDF_OBJECT_ATTRIBUTES KeyAttributes,
[out] WDFKEY *Key
);
Parameter
[in] Device
Ein Handle für ein Framework-Geräteobjekt.
[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
WdfDeviceOpenRegistryKey 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 |
|---|---|
|
WdfDeviceOpenRegistryKey wurde unter IRQL = PASSIVE_LEVEL nicht aufgerufen. |
|
Ein ungültiger Parameter wurde angegeben. Für UMDF kann dieser Rückgabewert auf unzureichende Zugriffsrechte hinweisen. |
|
Ein Registrierungsschlüsselobjekt konnte nicht zugeordnet werden. |
|
Der angegebene Registrierungsschlüssel ist nicht vorhanden. |
Eine Liste mit anderen Rückgabewerten, die von der WdfDeviceOpenRegistryKey-Methode möglicherweise zurückgegeben werden, finden Sie unter Fehler beim Erstellen von Frameworkobjekten.
Die -Methode gibt möglicherweise andere NTSTATUS-Werte zurück.
Eine Fehlerüberprüfung tritt auf, wenn der Treiber ein ungültiges Objekthandle bereitstellt.
Hinweise
Wenn Ihr Treiber einen Hardware- oder Softwareschlüssel öffnen muss, bevor er WdfDeviceCreate aufgerufen hat, muss er WdfFdoInitOpenRegistryKey anstelle von WdfDeviceOpenRegistryKey aufrufen.
Wenn der Treiber den Registrierungsschlüssel verwendet hat, den er mit WdfDeviceOpenRegistryKey geöffnet hat, muss der Treiber WdfRegistryClose aufrufen.
Weitere Informationen zur Registrierung, zu Hardware- und Softwareschlüsseln sowie zu Registrierungsobjekten finden Sie unter Verwenden der Registrierung in Framework-Based Treibern.
Beispiele
Codebeispiele, die WdfDeviceOpenRegistryKey verwenden, finden Sie unter WdfRegistryCreateKey, WdfRegistryOpenKey und WdfRegistryQueryValue.
Anforderungen
| Anforderung | Wert |
|---|---|
| Zielplattform | Universell |
| KMDF-Mindestversion | 1.0 |
| UMDF-Mindestversion | 2.0 |
| Kopfzeile | wdfdevice.h (einschließen von Wdf.h) |
| Bibliothek | Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF) |
| IRQL | PASSIVE_LEVEL |
| DDI-Complianceregeln | AccessHardwareKey(kmdf), DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf) |