Funzione WdfDeviceOpenRegistryKey (wdfdevice.h)

  • Articolo

[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