Funzione SetupDiCreateDeviceInfoA (setupapi.h)

Articolo
08/26/2023

La funzione SetupDiCreateDeviceInfo crea un nuovo elemento informazioni sul dispositivo e lo aggiunge come nuovo membro al set di informazioni sul dispositivo specificato.

Sintassi

WINSETUPAPI BOOL SetupDiCreateDeviceInfoA(
  [in]            HDEVINFO         DeviceInfoSet,
  [in]            PCSTR            DeviceName,
  [in]            const GUID       *ClassGuid,
  [in, optional]  PCSTR            DeviceDescription,
  [in, optional]  HWND             hwndParent,
  [in]            DWORD            CreationFlags,
  [out, optional] PSP_DEVINFO_DATA DeviceInfoData
);

Parametri

[in] DeviceInfoSet

Handle per il set di informazioni sul dispositivo per il computer locale.

[in] DeviceName

Puntatore a una stringa con terminazione NULL che fornisce un ID istanza del dispositivo completo (ad esempio, "Root*PNP0500\0000") o un ID dispositivo con enumerazione radice senza il prefisso enumeratore e il suffisso dell'identificatore di istanza (ad esempio, "*PNP0500"). L'identificatore del dispositivo enumerato radice può essere usato solo se il flag DICD_GENERATE_ID è specificato nel parametro CreationFlags .

[in] ClassGuid

Puntatore al GUID della classe di installazione del dispositivo per il dispositivo. Se la classe di installazione del dispositivo del dispositivo non è nota, impostare *ClassGuid su una struttura GUID_NULL.

[in, optional] DeviceDescription

Puntatore a una stringa con terminazione NULL che fornisce la descrizione del testo del dispositivo. Questo puntatore è facoltativo e può essere NULL.

[in, optional] hwndParent

Handle per la finestra di primo livello da usare per qualsiasi interfaccia utente correlata all'installazione del dispositivo. Questo handle è facoltativo e può essere NULL.

[in] CreationFlags

Variabile di tipo DWORD che controlla la modalità di creazione dell'elemento informazioni sul dispositivo. Può essere una combinazione dei valori seguenti:

DICD_GENERATE_ID

Se questo flag viene specificato, DeviceName contiene solo un ID dispositivo enumerato root e il sistema usa tale ID per generare un ID istanza del dispositivo completo per il nuovo elemento informazioni dispositivo.

Chiamare SetupDiGetDeviceInstanceId per recuperare l'ID istanza del dispositivo generato per questo elemento informazioni sul dispositivo.

DICD_INHERIT_CLASSDRVS

Se questo flag viene specificato, l'elemento informazioni sul dispositivo risultante eredita l'elenco di driver di classe, se presente, associato al set di informazioni sul dispositivo. Inoltre, se è presente un driver selezionato per il set di informazioni sul dispositivo, lo stesso driver viene selezionato per il nuovo elemento informazioni sul dispositivo.

[out, optional] DeviceInfoData

Puntatore a una struttura di SP_DEVINFO_DATA che riceve il nuovo elemento informazioni sul dispositivo. Questo puntatore è facoltativo e può essere NULL. Se la struttura viene fornita, il chiamante deve impostare il membro cbSize di questa struttura su sizeof(SP_DEVINFO_DATA) prima di chiamare la funzione. Per altre informazioni, vedere la sezione Osservazioni seguente.

Valore restituito

Se la funzione ha esito positivo, la funzione restituisce TRUE . In caso contrario, restituisce FALSE e l'errore registrato può essere recuperato effettuando una chiamata a GetLastError.

Commenti

Il chiamante di questa funzione deve essere membro del gruppo Administrators.

Se questa istanza del dispositivo viene aggiunta a un set con una classe associata, la classe del dispositivo deve essere la stessa o la chiamata ha esito negativo. In questo caso, una chiamata a GetLastError restituisce ERROR_CLASS_MISMATCH.

Se l'istanza del dispositivo specificata corrisponde a una chiave di istanza del dispositivo esistente nel Registro di sistema, la chiamata non riesce. In questo caso, una chiamata a GetLastError restituisce ERROR_DEVINST_ALREADY_EXISTS. Ciò si verifica solo se il flag di DICD_GENERATE_ID non è impostato.

Se il nuovo elemento informazioni sul dispositivo è stato creato correttamente ma il buffer DeviceInfoData fornito dal chiamante non è valido, la funzione restituisce FALSE. In questo caso, una chiamata a GetLastError restituisce ERROR_INVALID_USER_BUFFER. Tuttavia, l'elemento informazioni sul dispositivo sarà stato aggiunto come nuovo membro del set già.

DeviceInfoSet deve contenere solo elementi nel computer locale.

Nota

L'intestazione setupapi.h definisce SetupDiCreateDeviceInfo 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


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