Funzione WdfDeviceOpenRegistryKey (wdfdevice.h)

Articolo
02/29/2024

[Si applica a KMDF e UMDF]

Il metodo WdfDeviceOpenRegistryKey apre la chiave hardware di un dispositivo o la chiave software di un driver nel Registro di sistema e crea un oggetto chiave del Registro di sistema del framework che rappresenta la chiave del Registro di sistema.

Sintassi

NTSTATUS WdfDeviceOpenRegistryKey(
  [in]           WDFDEVICE              Device,
  [in]           ULONG                  DeviceInstanceKeyType,
  [in]           ACCESS_MASK            DesiredAccess,
  [in, optional] PWDF_OBJECT_ATTRIBUTES KeyAttributes,
  [out]          WDFKEY                 *Key
);

Parametri

[in] Device

Handle per un oggetto dispositivo framework.

[in] DeviceInstanceKeyType

Specifica la chiave o la sottochiave da aprire.

Nota

UMDF non supporta la creazione di sottochiave.

Si tratta di un OR bit per bit dei flag seguenti (definiti in Wdm.h).

Flag DeviceInstanceKeyType	Significato	Framework
PLUGPLAY_REGKEY_DEVICE	Apre la chiave hardware del dispositivo.	KMDF/UMDF
PLUGPLAY_REGKEY_DRIVER	Apre la chiave software del driver. Un driver UMDF che imposta questo flag deve anche impostare DesiredAccess su KEY_READ. In caso contrario, questo metodo restituisce STATUS_ACCESS_DENIED.	KMDF/UMDF
PLUGPLAY_REGKEY_CURRENT_HWPROFILE	Un driver KMDF usa questo flag per aprire la copia della chiave hardware o software presente nel profilo hardware corrente.	KMDF
PLUGPLAY_REGKEY_DRIVER \| WDF_REGKEY_DRIVER_SUBKEY	Un driver UMDF usa questi flag insieme per aprire la sottochiave ServiceName della chiave software del driver per l'accesso in lettura/scrittura.	UMDF
PLUGPLAY_REGKEY_DEVICE \| WDF_REGKEY_DEVICE_SUBKEY	Analogamente, un driver UMDF usa questi flag per aprire la sottochiave ServiceName della chiave hardware del dispositivo per l'accesso in lettura/scrittura.	UMDF

[in] DesiredAccess

Valore ACCESS_MASK tipizzato che specifica i diritti di accesso richiesti dal driver per la chiave del Registro di sistema specificata.

Un driver KMDF richiede in genere KEY_READ, KEY_WRITE o KEY_READ | KEY_WRITE.

Se si scrive un driver UMDF, usare la tabella seguente.

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

Come procedura consigliata, chiedere solo i tipi di accesso necessari al driver.

[in, optional] KeyAttributes

Puntatore a una struttura WDF_OBJECT_ATTRIBUTES che contiene attributi forniti dal driver per il nuovo oggetto chiave del Registro di sistema. Questo parametro è facoltativo e può essere WDF_NO_OBJECT_ATTRIBUTES.

[out] Key

Puntatore a una posizione che riceve un handle per il nuovo oggetto chiave del Registro di sistema.

Valore restituito

WdfDeviceOpenRegistryKey restituisce STATUS_SUCCESS se l'operazione ha esito positivo. In caso contrario, il metodo potrebbe restituire uno dei valori seguenti:

Codice restituito	Descrizione
STATUS_INVALID_DEVICE_REQUEST	WdfDeviceOpenRegistryKey non è stato chiamato in IRQL = PASSIVE_LEVEL.
STATUS_INVALID_PARAMETER	È stato specificato un parametro non valido. Per UMDF, questo valore restituito può indicare diritti di accesso insufficienti.
STATUS_INSUFFICIENT_RESOURCES	Impossibile allocare un oggetto chiave del Registro di sistema.
STATUS_OBJECT_NAME_NOT_FOUND	La chiave del Registro di sistema specificata non esiste.

Per un elenco di altri valori restituiti che il metodo WdfDeviceOpenRegistryKey potrebbe restituire, vedere Errori di creazione dell'oggetto Framework.

Il metodo potrebbe restituire altri valori NTSTATUS.

Un controllo di bug si verifica se il driver fornisce un handle di oggetti non valido.

Commenti

Se il driver deve aprire una chiave hardware o software prima di aver chiamato WdfDeviceCreate, deve chiamare WdfFdoInitOpenRegistryKey anziché WdfDeviceOpenRegistryKey.

Al termine dell'uso della chiave del Registro di sistema aperta con WdfDeviceOpenRegistryKey, il driver deve chiamare WdfRegistryClose.

Per altre informazioni sugli oggetti del Registro di sistema, hardware e software e del Registro di sistema, vedere Uso del Registro di sistema in Framework-Based Driver.

Esempio

Per esempi di codice che usano WdfDeviceOpenRegistryKey, vedere WdfRegistryCreateKey, WdfRegistryOpenKey e WdfRegistryQueryValue.

Requisiti

Requisito	Valore
Piattaforma di destinazione	Universale
Versione KMDF minima	1,0
Versione UMDF minima	2,0
Intestazione	wdfdevice.h (includere Wdf.h)
Libreria	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
Regole di conformità DDI	AccessHardwareKey(kmdf), DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Vedi anche

WdfFdoInitOpenRegistryKey

Condividi tramite