Funzione SetupDiGetCustomDevicePropertyW (setupapi.h)

Articolo
11/20/2024

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

Sintassi

WINSETUPAPI BOOL SetupDiGetCustomDevicePropertyW(
  [in]            HDEVINFO         DeviceInfoSet,
  [in]            PSP_DEVINFO_DATA DeviceInfoData,
  [in]            PCWSTR           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 cui recuperare una proprietà del dispositivo personalizzata.

[in] DeviceInfoData

Puntatore a una struttura di 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 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 delle proprietà specifiche dell'istanza del dispositivo che i valori delle proprietà specifiche dell'ID hardware, concatenati come stringa REG_MULTI_SZ tipizzata. 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 informazioni sulle proprietà richieste.

[in] PropertyBufferSize

Dimensioni, 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 si specifica questo parametro, SetupDiGetCustomDeviceProperty restituisce le dimensioni necessarie, indipendentemente dal fatto che il buffer PropertyBuffer sia sufficientemente grande da 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 da ricevere le informazioni richieste, SetupDiGetCustomDeviceProperty restituisce FALSE e una chiamata successiva a GetLastError restituirà ERROR_INSUFFICIENT_BUFFER.

Osservazioni

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 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 controlla prima di tutto 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 corrispondenti all'ID hardware dell'istanza del dispositivo specificata. In tal caso, viene restituito il valore della proprietà. Se DICUSTOMDEVPROP_MERGE_MULTISZ è impostato in Flag, la funzione restituisce i valori delle proprietà associati sia all'istanza del dispositivo che 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 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 Windows XP e versioni successive di Windows.
piattaforma di destinazione	Desktop
intestazione	setupapi.h (include Setupapi.h)
libreria	Setupapi.lib
dll	Setupapi.dll