Funzione WdfRegistryCreateKey (wdfregistry.h)

Articolo
08/08/2023

[Si applica a KMDF e UMDF]

Il metodo WdfRegistryCreateKey crea e apre una chiave del Registro di sistema specificata oppure apre semplicemente la chiave se esiste già e crea un oggetto chiave del Registro di sistema del framework che rappresenta la chiave del Registro di sistema.

Sintassi

NTSTATUS WdfRegistryCreateKey(
  [in, optional]  WDFKEY                 ParentKey,
  [in]            PCUNICODE_STRING       KeyName,
  [in]            ACCESS_MASK            DesiredAccess,
  [in]            ULONG                  CreateOptions,
  [out, optional] PULONG                 CreateDisposition,
  [in, optional]  PWDF_OBJECT_ATTRIBUTES KeyAttributes,
  [out]           WDFKEY                 *Key
);

Parametri

[in, optional] ParentKey

Handle per un oggetto chiave 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.

[in] DesiredAccess

Valore tipizzato ACCESS_MASK che specifica i diritti di accesso richiesti dal driver per la chiave del Registro di sistema specificata. Per un elenco dei diritti di accesso usati in genere dai driver 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] CreateOptions

Uno o più flag. Per informazioni su questi flag, vedere il parametro CreateOptions o ZwCreateKey.

[out, optional] CreateDisposition

Puntatore a una posizione che riceve REG_CREATED_NEW_KEY se viene creata una nuova chiave o REG_OPENED_EXISTING_KEY se viene aperta una chiave esistente. Questi valori sono definiti in Wdm.h. Questo puntatore è facoltativo e può essere NULL.

[in, optional] KeyAttributes

Puntatore a una struttura WDF_OBJECT_ATTRIBUTES che contiene gli 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

WdfRegistryCreateKey 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	WdfRegistryCreateKey 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 WdfRegistryCreateKey potrebbe restituire, vedere Errori di creazione di oggetti framework.

Questo metodo potrebbe anche restituire altri valori NTSTATUS.

Commenti

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

Per impostazione predefinita, l'elemento padre del nuovo oggetto chiave del Registro di sistema è l'oggetto driver del framework creato dal metodo WdfDriverCreate . È possibile utilizzare il membro ParentObject della struttura WDF_OBJECT_ATTRIBUTES per specificare un elemento padre diverso. Il framework elimina l'oggetto chiave del Registro di sistema quando elimina l'oggetto padre. Se il driver non modifica l'elemento padre predefinito, il driver deve eliminare l'oggetto chiave del Registro di sistema al termine dell'utilizzo dell'oggetto ; in caso contrario, l'oggetto chiave del Registro di sistema rimarrà finché il gestore di I/O non scarica il driver.

Se il driver non modifica l'elemento padre predefinito, il driver deve chiamare WdfRegistryClose al termine dell'utilizzo dell'oggetto; in caso contrario, l'oggetto chiave del Registro di sistema rimarrà finché il gestore di I/O non scarica il driver. In alternativa, il driver può chiamare WdfObjectDelete per eliminare l'oggetto chiave del Registro di sistema.

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

Esempio

L'esempio di codice seguente apre la chiave software di un driver e quindi crea e apre la chiave del Registro di sistema myKeyStr , 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"myKeyStr"
                         );
    status = WdfRegistryCreateKey(
                                  hKey,
                                  &myKeyStr,
                                  KEY_READ,
                                  REG_OPTION_NON_VOLATILE,
                                  NULL,
                                  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 (include Wdf.h)
Libreria	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
Regole di conformità DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)