Funzione SetupDiSetClassPropertyExW (setupapi.h)

Articolo
03/15/2023

La funzione SetupDiSetClassPropertyEx imposta una proprietà del dispositivo per una classe di installazione del dispositivo o una classe di interfaccia del dispositivo in un computer locale o remoto.

Sintassi

WINSETUPAPI BOOL SetupDiSetClassPropertyExW(
  [in]           const GUID       *ClassGuid,
  [in]           const DEVPROPKEY *PropertyKey,
  [in]           DEVPROPTYPE      PropertyType,
  [in, optional] const PBYTE      PropertyBuffer,
  [in]           DWORD            PropertyBufferSize,
  [in]           DWORD            Flags,
  [in, optional] PCWSTR           MachineName,
                 PVOID            Reserved
);

Parametri

[in] ClassGuid

Puntatore a un GUID che identifica la classe di configurazione del dispositivo o la classe di interfaccia del dispositivo per cui impostare una proprietà del dispositivo. Per informazioni su come specificare il tipo di classe, vedere il parametro Flags .

[in] PropertyKey

Puntatore a una struttura DEVPROPKEY che rappresenta la chiave della proprietà della classe di dispositivo da impostare.

[in] PropertyType

Valore di tipo DEVPROPTYPE che rappresenta l'identificatore property-data-type per la proprietà di classe. Per altre informazioni sull'identificatore di tipo property-data, vedere la sezione Osservazioni più avanti in questo argomento.

[in, optional] PropertyBuffer

Puntatore a un buffer contenente il valore della proprietà della classe. Se la proprietà o il valore della proprietà viene eliminato, questo puntatore deve essere impostato su NULL e PropertyBufferSize deve essere impostato su zero. Per altre informazioni sui requisiti dei valori delle proprietà, vedere la sezione Osservazioni più avanti in questo argomento.

[in] PropertyBufferSize

Dimensioni, in byte, del buffer PropertyBuffer . Le dimensioni del buffer delle proprietà devono essere coerenti con l'identificatore property-data-type fornito da PropertyType. Se PropertyBuffer è impostato su NULL, PropertyBufferSize deve essere impostato su zero.

[in] Flags

Uno dei valori seguenti, che specifica se la classe è una classe di installazione del dispositivo o una classe di interfaccia del dispositivo:

DICLASSPROP_INSTALLER

ClassGuid specifica una classe di installazione del dispositivo. Questo flag non può essere usato con DICLASSPROP_INTERFACE.

DICLASSPROP_INTERFACE

ClassGuid specifica una classe di interfaccia del dispositivo. Questo flag non può essere usato con DICLASSPROP_INSTALLER.

[in, optional] MachineName

Puntatore a una stringa Unicode con terminazione NULL contenente il nome UNC, incluso il prefisso "\" di un computer. Questo puntatore può essere impostato su NULL. Se il puntatore è NULL, SetupDiSetClassPropertyEx imposta la proprietà classe per una classe installata nel computer locale.

Attenzione

L'uso di questa funzione per accedere ai computer remoti non è supportato a partire da Windows 8 e Windows Server 2012, perché questa funzionalità è stata rimossa.

Reserved

Questo parametro deve essere impostato su NULL.

Valore restituito

SetupDiSetClassPropertyEx restituisce TRUE se ha esito positivo. In caso contrario, restituisce FALSE e l'errore registrato può essere recuperato chiamando GetLastError.

La tabella seguente include alcuni dei codici di errore più comuni che questa funzione potrebbe registrare.

Codice restituito	Descrizione
ERROR_INVALID_FLAGS	Il valore di Flag non è valido.
ERROR_INVALID_CLASS	La classe di installazione del dispositivo specificata da ClassGuid non è valida. Questo errore può verificarsi solo se viene specificato il flag DICLASSPROP_INSTALLER.
ERROR_INVALID_REFERENCE_STRING	La stringa di riferimento dell'interfaccia del dispositivo non è valida. Questo errore può verificarsi solo se viene specificato il flag di DICLASSPROP_INTERFACE.
ERROR_INVALID_REG_PROPERTY	La chiave di proprietà fornita da PropertyKey non è valida.
ERROR_INVALID_DATA	Non è stato valido un valore dati interno non specificato. Questo errore potrebbe essere registrato se il valore ClassGuid non è un GUID valido o il valore della proprietà non corrisponde al tipo di proprietà specificato da PropertyType.
ERROR_INVALID_USER_BUFFER	Un buffer utente non è valido. Una possibilità è che PropertyBuffer è NULL e PropertyBufferSize non è zero.
ERROR_INVALID_MACHINENAME	Il nome del computer specificato da MachineName non è valido.
ERROR_NO_SUCH_INTERFACE_CLASS	La classe dell'interfaccia del dispositivo specificata da ClassGuid non esiste. Questo errore può verificarsi solo se viene specificato il flag di DICLASSPROP_INTERFACE.
ERROR_INSUFFICIENT_BUFFER	Un buffer dati interno passato a una chiamata di sistema è troppo piccolo.
ERROR_NOT_ENOUGH_MEMORY	Memoria di sistema insufficiente per completare l'operazione.
ERROR_NOT_FOUND	Non è stato trovato un elemento non specificato. Una possibilità è che la proprietà da eliminare non esiste.
ERROR_ACCESS_DENIED	Il chiamante non dispone dei privilegi di amministratore.

Commenti

SetupDiSetClassPropertyEx fa parte del modello di proprietà del dispositivo unificato.

SetupAPI supporta solo una versione Unicode di SetupDiSetClassPropertyEx.

Un chiamante di SetupDiSetClassPropertyEx deve essere membro del gruppo Administrators per impostare una proprietà dell'interfaccia del dispositivo.

SetupDiSetClassPropertyEx applica i requisiti per l'identificatore property-data-type e il valore della proprietà.

Per ottenere le chiavi delle proprietà del dispositivo che rappresentano le proprietà del dispositivo impostate per una classe di dispositivo in un computer remoto, chiamare SetupDiGetClassPropertyKeysEx.

Per recuperare una proprietà della classe di dispositivo in un computer locale, chiamare SetupDiGetClassPropertye recuperare una proprietà della classe di dispositivo in un computer remoto, chiamare SetupDiGetClassPropertyEx.

Per impostare una proprietà della classe di dispositivo in un computer locale, chiamare SetupDiSetClassProperty.

Requisiti

Requisito	Valore
Client minimo supportato	Disponibile in Windows Vista e versioni successive di Windows.
Piattaforma di destinazione	Desktop
Intestazione	setupapi.h (includere Setupapi.h)
Libreria	Setupapi.lib