Funzione WdfRegistryOpenKey (wdfregistry.h)

Articolo
08/08/2023

[Si applica a KMDF e UMDF]

Il metodo WdfRegistryOpenKey apre una chiave del Registro di sistema specificata e crea un oggetto del Registro di sistema framework che rappresenta la chiave del Registro di sistema.

Sintassi

NTSTATUS WdfRegistryOpenKey(
  [in, optional] WDFKEY                 ParentKey,
  [in]           PCUNICODE_STRING       KeyName,
  [in]           ACCESS_MASK            DesiredAccess,
  [in, optional] PWDF_OBJECT_ATTRIBUTES KeyAttributes,
  [out]          WDFKEY                 *Key
);

Parametri

[in, optional] ParentKey

Handle per un oggetto del Registro di sistema del framework. Questo oggetto rappresenta una chiave del Registro di sistema padre aperta dal driver. Questo parametro è facoltativo e può essere NULL. Se il parametro non è NULL, la chiave specificata da KeyName deve risiedere in questa chiave padre nel Registro di sistema. Per altre informazioni su questa chiave padre, vedere la sezione Osservazioni.

[in] KeyName

Puntatore a una struttura UNICODE_STRING contenente il nome della chiave da aprire. Il nome della chiave può includere informazioni sul percorso. Se ParentKey è NULL, KeyName deve specificare un percorso completo di una chiave del Registro di sistema. Per esempi, vedere la sezione Osservazioni.

[in] DesiredAccess

Valore ACCESS_MASK tipizzato che specifica i diritti di accesso richiesti dal driver per la chiave del Registro di sistema specificata. Per un elenco dei diritti di accesso che i driver usano in genere per le chiavi del Registro di sistema, vedere Apertura di un handle a un oggetto Registry-Key. Il driver deve richiedere solo i tipi di accesso necessari. Ad esempio, il driver non deve richiedere KEY_ALL_ACCESS se leggerà solo la chiave del Registro di sistema.

[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

WdfRegistryOpenKey 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	WdfRegistryOpenKey non è stato chiamato in IRQL = PASSIVE_LEVEL.
STATUS_INVALID_PARAMETER	È stato specificato un parametro non valido.
STATUS_INSUFFICIENT_RESOURCES	Impossibile allocare un oggetto chiave del Registro di sistema.
STATUS_ACCESS_DENIED	Il sistema ha negato i diritti di accesso specificati.
STATUS_OBJECT_NAME_NOT_FOUND	La chiave del Registro di sistema specificata non esiste.

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

Questo metodo potrebbe restituire anche altri valori NTSTATUS.

Commenti

Per ottenere un handle a un oggetto chiave del Registro di sistema che rappresenta una chiave padre, il driver può chiamare WdfDriverOpenParametersRegistryKey, WdfDeviceOpenRegistryKey o WdfFdoInitOpenRegistryKey.

Il formato stringa specificato nel parametro KeyName dipende dal fatto che il chiamante sia un driver KMDF o un driver UMDF. Ad esempio, per aprire il percorso seguente:

HKLM\System\CurrentControlSet\Control

Il driver potrebbe usare questa logica condizionale:

#ifdef _KERNEL_MODE
#define CONTROL_KEY_FULL_PATH L"\\Registry\\Machine\\System\\CurrentControlSet\\Control "
#else
#define CONTROL_KEY_FULL_PATH L"System\\CurrentControlSet\\Control\\" 
#endif

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

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

Esempio

L'esempio di codice seguente apre la chiave software di un driver e quindi apre la chiave del Registro di sistema MySubKey , che si trova sotto la chiave software del driver.

WDFKEY  hKey, subkey;
NTSTATUS  status;
UNICODE_STRING myKeyStr;

status = WdfDeviceOpenRegistryKey(
                                  device,
                                  PLUGPLAY_REGKEY_DRIVER,
                                  KEY_READ,
                                  WDF_NO_OBJECT_ATTRIBUTES,
                                  &hKey
                                  );
if (NT_SUCCESS(status)){
    RtlInitUnicodeString(
                         &myKeyStr,
                         L"MySubKey"
                         );
    status = WdfRegistryOpenKey(
                                hKey,
                                &myKeyStr,
                                KEY_READ,
                                WDF_NO_OBJECT_ATTRIBUTES,
                                &subkey
                                );
}

Requisiti

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