Funzione SetupDiCreateDevRegKeyA (setupapi.h)

Articolo
11/20/2024

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 per un set di informazioni sul dispositivo che contiene un elemento di informazioni sul dispositivo che rappresenta il dispositivo per cui creare una chiave del Registro di sistema.

[in] DeviceInfoData

Puntatore a una struttura di 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. Può essere uno dei valori seguenti:

DICS_FLAG_GLOBAL

Creare una chiave per archiviare le informazioni di configurazione globali. Queste informazioni non sono specifiche di un particolare 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 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. Può essere uno dei valori 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 contenente una sezione INF DDInstall da eseguire per la chiave appena creata. Questo parametro è facoltativo e può essere NULL. Se si specifica questo parametro, è 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 si specifica questo parametro, è 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.

Osservazioni

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.

È necessario registrare l'istanza del dispositivo specificata prima di chiamare SetupDiCreateDevRegKey. Si noti, tuttavia, che il sistema operativo registra automaticamente le istanze del dispositivo PnP. Per informazioni su come registrare istanze del dispositivo non PnP, vedere SetupDiRegisterDeviceInfo.

Per le installazioni che usano file di layout (specificati dalla voce LayoutFile in una sezione VERSIONE INF), il file di layout deve essere aperto da una chiamata a SetupOpenAppendInfFile (descritto 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 successiva chiamata 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 non indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere convenzioni di per i prototipi di funzioni.

Fabbisogno

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