Funzione SetupDiCreateDevRegKeyW (setupapi.h)

Articolo
08/26/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 SetupDiCreateDevRegKeyW(
  [in]           HDEVINFO         DeviceInfoSet,
  [in]           PSP_DEVINFO_DATA DeviceInfoData,
  [in]           DWORD            Scope,
  [in]           DWORD            HwProfile,
  [in]           DWORD            KeyType,
  [in, optional] HINF             InfHandle,
  [in, optional] PCWSTR           InfSectionName
);

Parametri

[in] DeviceInfoSet

Handle per un set di informazioni sul dispositivo che contiene un elemento informazioni sul 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 dove vengono archiviate le informazioni. La chiave creata può essere specifica del profilo hardware o globale. I possibili valori sono i seguenti:

DICS_FLAG_GLOBAL

Creare una chiave per archiviare le informazioni di configurazione globale. Queste informazioni non sono specifiche di un profilo hardware specifico. 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 il quale 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 di un file INF aperto che contiene una sezione INF DDInstall da eseguire per la chiave appena creata. Questo parametro è facoltativo e può essere NULL. Se questo parametro viene specificato, è necessario specificare anche InfSectionName .

[in, optional] InfSectionName

Nome di una sezione INF DDInstall 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 viene 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 estese sull'errore.

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 della chiave ha solo accesso KEY_READ e KEY_WRITE. Per le versioni precedenti di Windows, questo handle ha accesso KEY_ALL_ACCESS.

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 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 di chiamare SetupDiCreateDevRegKey.

Se il set di informazioni sul dispositivo fornito contiene elementi di informazioni sul dispositivo per un sistema remoto e vengono specificati anche InfHandle e InfSectionName , 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 del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice che non è indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzioni.

Requisiti

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