Funzione IoOpenDeviceRegistryKey (wdm.h)

Articolo
08/08/2023

La routine IoOpenDeviceRegistryKey restituisce un handle a un percorso di stato del Registro di sistema per una determinata istanza del dispositivo.

Sintassi

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

Parametri

[in] DeviceObject

Puntatore all'oggetto dispositivo fisico (PDO) dell'istanza del dispositivo per cui deve essere aperto il percorso 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, un percorso di stato del Registro di sistema specifico 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 archiviare 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 rispetto 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. Per una descrizione di ogni diritto di accesso KEY_XXX, vedere la routine ZwCreateKey.

[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 valori restituiti di errore possibili includono quanto segue:

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

Commenti

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 sono non volatile.

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

Per precompilare lo stato in questi percorsi di stato del Registro di sistema al momento dell'installazione del pacchetto driver, usare le 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.

Requisiti

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)