Funzione SetupDiCreateDevRegKeyA (setupapi.h)

Articolo
03/15/2023

La funzione SetupDiCreateDevRegKey crea una chiave del Registro di sistema per informazioni di configurazione specifiche del dispositivo e restituisce un handle alla chiave.

Sintassi

WINSETUPAPI HKEY SetupDiCreateDevRegKeyA(
  [in]           HDEVINFO         DeviceInfoSet,
  [in]           PSP_DEVINFO_DATA DeviceInfoData,
  [in]           DWORD            Scope,
  [in]           DWORD            HwProfile,
  [in]           DWORD            KeyType,
  [in, optional] HINF             InfHandle,
  [in, optional] PCSTR            InfSectionName
);

Parametri

[in] DeviceInfoSet

Handle a un set di informazioni sul dispositivo contenente un elemento informazioni dispositivo che rappresenta il dispositivo per cui creare una chiave del Registro di sistema.

[in] DeviceInfoData

Puntatore a una struttura SP_DEVINFO_DATA che specifica l'elemento informazioni sul dispositivo in DeviceInfoSet.

[in] Scope

Ambito della chiave del Registro di sistema da creare. L'ambito determina la posizione in cui vengono archiviate le informazioni. La chiave creata può essere globale o specifica del profilo hardware. I possibili valori sono i seguenti:

DICS_FLAG_GLOBAL

Creare una chiave per archiviare le informazioni di configurazione globali. Queste informazioni non sono specifiche di un determinato profilo hardware. Nei sistemi operativi basati su NT viene creata una chiave radicata in HKEY_LOCAL_MACHINE. La chiave esatta aperta dipende dal valore del parametro KeyType .

DICS_FLAG_CONFIGSPECIFIC

Creare una chiave per archiviare informazioni di configurazione specifiche del profilo hardware. Questa chiave è radicata in uno dei rami specifici del profilo hardware, anziché HKEY_LOCAL_MACHINE.

[in] HwProfile

Profilo hardware per cui creare una chiave se HwProfileFlags è impostato su SPDICS_FLAG_CONFIGSPECIFIC. Se HwProfile è 0, viene creata la chiave per il profilo hardware corrente. Se HwProfileFlags è SPDICS_FLAG_GLOBAL, HwProfile viene ignorato.

[in] KeyType

Tipo di chiave di archiviazione del Registro di sistema da creare. I possibili valori sono i seguenti:

DIREG_DEV

Creare una chiave hardware per il dispositivo.

DIREG_DRV

Creare una chiave software per il dispositivo.

[in, optional] InfHandle

Handle per un file INF aperto che contiene una sezione DDInstall INF da eseguire per la chiave appena creata. Questo parametro è facoltativo e può essere NULL. Se questo parametro è specificato, è necessario specificare anche InfSectionName .

[in, optional] InfSectionName

Nome di una sezione DDInstall INF nel file INF specificato da InfHandle. Questa sezione viene eseguita per la chiave appena creata. Questo parametro è facoltativo e può essere NULL. Se questo parametro è specificato, è necessario specificare anche InfHandle .

Valore restituito

Se SetupDiCreateDevRegKey ha esito positivo, la funzione restituisce un handle alla chiave del Registro di sistema specificata in cui è possibile archiviare e recuperare i dati di configurazione specifici del dispositivo. Se SetupDiCreateDevRegKey ha esito negativo, la funzione restituisce INVALID_HANDLE_VALUE. Chiamare GetLastError per ottenere informazioni sull'errore estese.

Commenti

Il chiamante di SetupDiCreateDevRegKey deve essere membro del gruppo Administrators.

Chiudere l'handle restituito da SetupDiCreateDevRegKey chiamando RegCloseKey.

Se la chiave specificata esiste già, SetupDiCreateDevRegKey restituisce un handle a tale chiave. In caso contrario, SetupDiCreateDevRegKey crea la chiave specificata e restituisce un handle alla nuova chiave. Per Windows Server 2003 e versioni successive di Windows, l'handle delle chiavi ha KEY_READ e KEY_WRITE solo l'accesso. Per le versioni precedenti di Windows, questo handle ha KEY_ALL_ACCESS accesso.

L'istanza del dispositivo specificata deve essere registrata prima di chiamare SetupDiCreateDevRegKey . Si noti tuttavia che il sistema operativo registra automaticamente le istanze del dispositivo PnP. Per informazioni su come registrare istanze di dispositivi non PnP, vedere SetupDiRegisterDeviceInfo.

Per le installazioni che usano i file di layout (specificati dalla voce LayoutFile in una sezione INF Version), il file di layout deve essere aperto da una chiamata a SetupOpenAppendInfFile (descritta nella documentazione di Microsoft Windows SDK) prima che SetupDiCreateDevRegKey venga chiamato.

Se il set di informazioni sul dispositivo fornito contiene elementi di informazioni sul dispositivo per un sistema remoto e InfHandle e InfSectionName vengono specificati anche, la richiesta di creazione avrà esito negativo e una chiamata successiva a GetLastError restituirà ERROR_REMOTE_REQUEST_UNSUPPORTED.

Nota

L'intestazione setupapi.h definisce SetupDiCreateDevRegKey come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante preprocessore UNICODE. La combinazione dell'utilizzo dell'alias di codifica neutrale con il codice che non è neutrale dalla codifica può causare errori di corrispondenza che causano errori di compilazione o runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzione.

Requisiti

Requisito	Valore
Client minimo supportato	Disponibile in Microsoft Windows 2000 e versioni successive di Windows.
Piattaforma di destinazione	Desktop
Intestazione	setupapi.h (includere Setupapi.h)
Libreria	Setupapi.lib