Funzione SetupDiGetCustomDevicePropertyA (setupapi.h)

Articolo
03/05/2024

La funzione SetupDiGetCustomDeviceProperty recupera una proprietà del dispositivo personalizzata specificata dal Registro di sistema.

Sintassi

WINSETUPAPI BOOL SetupDiGetCustomDevicePropertyA(
  [in]            HDEVINFO         DeviceInfoSet,
  [in]            PSP_DEVINFO_DATA DeviceInfoData,
  [in]            PCSTR            CustomPropertyName,
  [in]            DWORD            Flags,
  [out, optional] PDWORD           PropertyRegDataType,
  [out]           PBYTE            PropertyBuffer,
  [in]            DWORD            PropertyBufferSize,
  [out, optional] PDWORD           RequiredSize
);

Parametri

[in] DeviceInfoSet

Handle per il set di informazioni sul dispositivo che contiene un elemento informazioni sul dispositivo che rappresenta il dispositivo per il quale recuperare una proprietà del dispositivo personalizzata.

[in] DeviceInfoData

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

[in] CustomPropertyName

Nome del valore del Registro di sistema che rappresenta una proprietà personalizzata.

[in] Flags

Valore del flag che indica come devono essere restituite le informazioni richieste. Il flag può essere zero o uno dei seguenti:

DICUSTOMDEVPROP_MERGE_MULTISZ

Se impostata, la funzione recupera sia i valori di proprietà specifici dell'istanza del dispositivo che i valori delle proprietà specifiche dell'ID hardware, concatenati come stringa tipizzata REG_MULTI_SZ. Per altre informazioni, vedere la sezione Osservazioni in questa pagina di riferimento.

[out, optional] PropertyRegDataType

Puntatore a una variabile di tipo DWORD che riceve il tipo di dati della proprietà recuperata. Il tipo di dati viene specificato come una delle costanti con prefisso REG_ che rappresenta i tipi di dati del Registro di sistema. Questo parametro è facoltativo e può essere NULL.

[out] PropertyBuffer

Puntatore a un buffer che riceve le informazioni sulle proprietà richieste.

[in] PropertyBufferSize

Dimensione, in byte, del buffer PropertyBuffer .

[out, optional] RequiredSize

Puntatore a una variabile di tipo DWORD che riceve le dimensioni del buffer, in byte, necessarie per ricevere le informazioni richieste. Questo parametro è facoltativo e può essere NULL. Se questo parametro viene specificato, SetupDiGetCustomDeviceProperty restituisce le dimensioni necessarie, indipendentemente dal fatto che il buffer PropertyBuffer sia sufficientemente grande per ricevere le informazioni richieste.

Valore restituito

Se l'operazione ha esito positivo, SetupDiGetCustomDeviceProperty restituisce TRUE. In caso contrario, la funzione restituisce FALSE e l'errore registrato può essere recuperato con una chiamata a GetLastError. Se il buffer PropertyBuffer non è sufficientemente grande per ricevere le informazioni richieste, SetupDiGetCustomDeviceProperty restituisce FALSE e una chiamata successiva a GetLastError restituirà ERROR_INSUFFICIENT_BUFFER.

Commenti

SetupDiGetCustomDeviceProperty recupera le proprietà del dispositivo associate a una singola istanza del dispositivo o a tutti i dispositivi corrispondenti a un determinato ID hardware. Per informazioni sugli ID hardware, vedere Stringhe di identificazione del dispositivo.

I fornitori possono impostare le proprietà per un'istanza del dispositivo usando le direttive INF AddReg nelle sezioni INF DDInstall.HW e specificando la radice del Registro di sistema HKR .

Solo il sistema può impostare le proprietà per gli ID hardware. Il sistema fornisce una proprietà "Icon" per alcuni ID hardware.

La funzione verifica innanzitutto se la proprietà specificata esiste per l'istanza del dispositivo specificata. In tal caso, viene restituito il valore della proprietà. In caso contrario, la funzione verifica se la proprietà esiste per tutti i dispositivi che corrispondono all'ID hardware dell'istanza del dispositivo specificata. In tal caso, viene restituito il valore della proprietà. Se DICUSTOMDEVPROP_MERGE_MULTISZ è impostato in Flags, la funzione restituisce i valori delle proprietà associati all'istanza del dispositivo e all'ID hardware, se presenti entrambi.

Nota

L'intestazione setupapi.h definisce SetupDiGetCustomDeviceProperty 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 Windows XP e versioni successive di Windows.
Piattaforma di destinazione	Desktop
Intestazione	setupapi.h (include Setupapi.h)
Libreria	Setupapi.lib
DLL	Setupapi.dll