Funzione WdfFdoInitOpenRegistryKey (wdffdo.h)

Articolo
08/08/2023

[Si applica a KMDF e UMDF]

Il metodo WdfFdoInitOpenRegistryKey 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 framework che rappresenta la chiave del Registro di sistema.

Sintassi

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

Parametri

[in] DeviceInit

Puntatore a una struttura WDFDEVICE_INIT ottenuta dal driver dalla funzione EvtDriverDeviceAdd callback.

[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

WdfFdoInitOpenRegistryKey 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	WdfFdoInitOpenRegistryKey non è stato chiamato in IRQL = PASSIVE_LEVEL.
STATUS_INVALID_PARAMETER	È stato specificato un parametro non valido oppure il driver non ha ottenuto la struttura WDFDEVICE_INIT dalla relativa funzione EvtDriverDeviceAdd callback. 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 WdfFdoInitOpenRegistryKey potrebbe restituire, vedere Errori di creazione di oggetti Framework.

Il metodo potrebbe restituire anche altri valori NTSTATUS.

Commenti

Il driver deve chiamare WdfFdoInitOpenRegistryKey prima di chiamare WdfDeviceCreate. Per altre informazioni sulla chiamata a WdfDeviceCreate, vedere Creazione di un oggetto dispositivo Framework.

Per altre informazioni sul metodo WdfFdoInitOpenRegistryKey , vedere Creazione di oggetti dispositivo in un driver di funzione.

o 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

L'esempio di codice seguente apre la chiave hardware di un dispositivo, con accesso in lettura.

WDFKEY key;
NTSTATUS status;

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

Requisiti

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

Vedi anche

WdfDeviceOpenRegistryKey

WdfDriverOpenParametersRegistryKey

Condividi tramite