Funzione IoOpenDeviceRegistryKey (wdm.h)

Articolo
02/07/2025

La routine IoOpenDeviceRegistryKey restituisce un handle in una posizione dello stato del Registro di sistema per una particolare istanza del dispositivo.

Sintassi

NTSTATUS IoOpenDeviceRegistryKey(
  [in]  PDEVICE_OBJECT DeviceObject,
  [in]  ULONG          DevInstKeyType,
  [in]  ACCESS_MASK    DesiredAccess,
  [out] PHANDLE        DeviceRegKey
);

Parametri

[in] DeviceObject

Puntatore al oggetto dispositivo fisico (PDO) dell'istanza del dispositivo per cui deve essere aperta la posizione dello stato del Registro di sistema.

[in] DevInstKeyType

Specifica i flag che indicano se aprire una chiave hardware specifica del dispositivo o una chiave software specifica del driver. I flag indicano anche se la chiave è relativa al profilo hardware corrente. Per altre informazioni sulle chiavi hardware e software, vedere Introduzione alle chiavi del Registro di sistema per i driver.

I flag sono definiti come segue:

PLUGPLAY_REGKEY_DEVICE

Aprire la chiave hardware del dispositivo, una posizione dello stato del Registro di sistema specifica del dispositivo che contiene informazioni sul dispositivo. Questo flag non può essere specificato con PLUGPLAY_REGKEY_DRIVER.

PLUGPLAY_REGKEY_DRIVER

Aprire la chiave software del dispositivo, un percorso di stato del Registro di sistema specifico del dispositivo per l'archiviazione di informazioni specifiche del driver. Questo flag non può essere specificato con PLUGPLAY_REGKEY_DEVICE.

PLUGPLAY_REGKEY_CURRENT_HWPROFILE

I profili hardware sono deprecati e lo stato non deve essere archiviato in relazione a un profilo hardware.

Aprire una chiave relativa al profilo hardware corrente per informazioni sul dispositivo o sul driver. In questo modo il driver può accedere alle informazioni di configurazione specifiche del profilo hardware. Il chiamante deve specificare PLUGPLAY_REGKEY_DEVICE o PLUGPLAY_REGKEY_DRIVER con questo flag.

[in] DesiredAccess

Specifica il valore ACCESS_MASK che rappresenta l'accesso necessario al chiamante per la chiave. Vedere la routine ZwCreateKey per una descrizione di ogni KEY_XXX diritto di accesso.

[out] DeviceRegKey

Puntatore a un buffer allocato dal chiamante che, in caso di esito positivo, contiene un handle per il percorso dello stato del Registro di sistema richiesto.

Valore restituito

IoOpenDeviceRegistryKey restituisce STATUS_SUCCESS se la chiamata ha avuto esito positivo. I possibili valori restituiti dall'errore includono quanto segue:

Codice restituito	Descrizione
STATUS_INVALID_PARAMETER	Possibilmente indica che il chiamante ha specificato un set non valido di flag DevInstKeyType o ha fornito un DeviceObject che non è un PDO valido.

Osservazioni

Il driver deve chiamare ZwClose per chiudere l'handle restituito da questa routine quando l'accesso non è più necessario.

Le chiavi del Registro di sistema aperte da questa routine non sonovolatile.

Le applicazioni di installazione in modalità utente possono accedere a queste chiavi del Registro di sistema usando CM_Open_DevNode_Key o funzioni relative alle informazioni sul dispositivo, ad esempio SetupDiOpenDevRegKey o SetupDiCreateDevRegKey.

Per precompilare lo stato in questi percorsi di stato del Registro di sistema in fase di installazione del pacchetto driver, usare direttive INF AddReg in un file INF.

I chiamanti di IoOpenDeviceRegistryKey devono essere in esecuzione in IRQL = PASSIVE_LEVEL nel contesto di un thread di sistema.

Fabbisogno

Requisito	Valore
piattaforma di destinazione	Universale
intestazione	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
libreria	NtosKrnl.lib
dll	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (vedere la sezione Osservazioni)
regole di conformità DDI	HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm)