Funzione SetupDiCreateDeviceInfoW (setupapi.h)

Articolo
11/20/2024

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

Sintassi

WINSETUPAPI BOOL SetupDiCreateDeviceInfoW(
  [in]            HDEVINFO         DeviceInfoSet,
  [in]            PCWSTR           DeviceName,
  [in]            const GUID       *ClassGuid,
  [in, optional]  PCWSTR           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 radice senza il prefisso dell'enumeratore e il suffisso dell'identificatore dell'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 alla classe di configurazione del dispositivo GUID 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 si specifica questo flag, DeviceName contiene solo un ID dispositivo enumerato radice e il sistema usa tale ID per generare un ID istanza del dispositivo completo per il nuovo elemento informazioni sul dispositivo.

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

DICD_INHERIT_CLASSDRVS

Se questo flag viene specificato, l'elemento di informazioni sul dispositivo risultante eredita l'elenco dei 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 dispositivo.

[out, optional] DeviceInfoData

Puntatore a una struttura SP_DEVINFO_DATA che riceve il nuovo elemento informazioni dispositivo. Questo puntatore è facoltativo e può essere NULL. Se viene fornita la struttura, 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 ha esito positivo, la funzione restituisce TRUE. In caso contrario, restituisce FALSE e l'errore registrato può essere recuperato effettuando una chiamata a GetLastError.

Osservazioni

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 non riesce. 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 DICD_GENERATE_ID non è impostato.

Se il nuovo elemento informazioni dispositivo è stato creato correttamente, ma il chiamante fornito DeviceInfoData buffer 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à.

Il 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 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