Fonction SetupDiSetClassPropertyExW (setupapi.h)
La fonction SetupDiSetClassPropertyEx définit une propriété d’appareil pour une classe d’installation d’appareil ou une classe d’interface d’appareil sur un ordinateur local ou distant.
Syntaxe
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
);
Paramètres
[in] ClassGuid
Pointeur vers un GUID qui identifie la classe d’installation de l’appareil ou la classe d’interface d’appareil pour laquelle définir une propriété d’appareil. Pour plus d’informations sur la façon de spécifier le type de classe, consultez le paramètre Flags .
[in] PropertyKey
Pointeur vers une structure DEVPROPKEY qui représente la clé de propriété d’appareil de la propriété de classe d’appareil à définir.
[in] PropertyType
Valeur de type DEVPROPTYPE qui représente l’identificateur de type de données de propriété pour la propriété de classe. Pour plus d’informations sur l’identificateur de type de données de propriété, consultez la section Remarques plus loin dans cette rubrique.
[in, optional] PropertyBuffer
Pointeur vers une mémoire tampon qui contient la valeur de la propriété de classe. Si la propriété ou la valeur de la propriété est supprimée, ce pointeur doit avoir la valeur NULL et PropertyBufferSize doit être défini sur zéro. Pour plus d’informations sur les exigences relatives à la valeur des propriétés, consultez la section Remarques plus loin dans cette rubrique.
[in] PropertyBufferSize
Taille, en octets, de la mémoire tampon PropertyBuffer . La taille de la mémoire tampon de propriété doit être cohérente avec l’identificateur de type de données de propriété fourni par PropertyType. Si PropertyBuffer a la valeur NULL, PropertyBufferSize doit avoir la valeur zéro.
[in] Flags
L’une des valeurs suivantes, qui spécifie si la classe est une classe d’installation d’appareil ou une classe d’interface d’appareil :
DICLASSPROP_INSTALLER
ClassGuid spécifie une classe d’installation d’appareil. Cet indicateur ne peut pas être utilisé avec DICLASSPROP_INTERFACE.
DICLASSPROP_INTERFACE
ClassGuid spécifie une classe d’interface d’appareil. Cet indicateur ne peut pas être utilisé avec DICLASSPROP_INSTALLER.
[in, optional] MachineName
Pointeur vers une chaîne Unicode terminée par null qui contient le nom UNC, y compris le préfixe « \ », d’un ordinateur. Ce pointeur peut être défini sur NULL. Si le pointeur a la valeur NULL, SetupDiSetClassPropertyEx définit la propriété de classe pour une classe installée sur l’ordinateur local.
Attention
L’utilisation de cette fonction pour accéder aux machines distantes n’est pas prise en charge à partir de Windows 8 et Windows Server 2012, car cette fonctionnalité a été supprimée.
Reserved
Ce paramètre doit avoir la valeur NULL.
Valeur retournée
SetupDiSetClassPropertyEx retourne TRUE s’il réussit. Sinon, il retourne FALSE, et l’erreur journalisée peut être récupérée en appelant GetLastError.
Le tableau suivant inclut certains des codes d’erreur les plus courants que cette fonction peut enregistrer.
| Code de retour | Description |
|---|---|
|
La valeur de Flags n’est pas valide. |
|
La classe d’installation de l’appareil spécifiée par ClassGuid n’est pas valide. Cette erreur ne peut se produire que si l’indicateur DICLASSPROP_INSTALLER est spécifié. |
|
La chaîne de référence de l’interface d’appareil n’est pas valide. Cette erreur ne peut se produire que si l’indicateur DICLASSPROP_INTERFACE est spécifié. |
|
La clé de propriété fournie par PropertyKey n’est pas valide. |
|
Une valeur de données interne non spécifiée n’était pas valide. Cette erreur peut être consignée si la valeur ClassGuid n’est pas un GUID valide ou si la valeur de propriété ne correspond pas au type de propriété spécifié par PropertyType. |
|
Une mémoire tampon utilisateur n’est pas valide. Une possibilité est que PropertyBuffer a la valeur NULL et PropertyBufferSize n’est pas zéro. |
|
Le nom de l’ordinateur spécifié par MachineName n’est pas valide. |
|
La classe d’interface d’appareil spécifiée par ClassGuid n’existe pas. Cette erreur ne peut se produire que si l’indicateur DICLASSPROP_INTERFACE est spécifié. |
|
Une mémoire tampon de données interne qui a été passée à un appel système était trop petite. |
|
Il n’y avait pas assez de mémoire système disponible pour terminer l’opération. |
|
Un élément non spécifié est introuvable. Il est possible que la propriété à supprimer n’existe pas. |
|
L’appelant ne dispose pas de privilèges d’administrateur. |
Remarques
SetupDiSetClassPropertyEx fait partie du modèle de propriété d’appareil unifié.
SetupAPI prend uniquement en charge une version Unicode de SetupDiSetClassPropertyEx.
Un appelant de SetupDiSetClassPropertyEx doit être membre du groupe Administrateurs pour définir une propriété d’interface d’appareil.
SetupDiSetClassPropertyEx applique des exigences sur l’identificateur de type de données de propriété et la valeur de la propriété.
Pour obtenir les clés de propriété d’appareil qui représentent les propriétés d’appareil définies pour une classe d’appareil sur un ordinateur distant, appelez SetupDiGetClassPropertyKeysEx.
Pour récupérer une propriété de classe d’appareil sur un ordinateur local, appelez SetupDiGetClassPropertyet pour récupérer une propriété de classe d’appareil sur un ordinateur distant, appelez SetupDiGetClassPropertyEx.
Pour définir une propriété de classe d’appareil sur un ordinateur local, appelez SetupDiSetClassProperty.
Configuration requise
| Condition requise | Valeur |
|---|---|
| Client minimal pris en charge | Disponible dans Windows Vista et les versions plus récentes de Windows. |
| Plateforme cible | Desktop (Expérience utilisateur) |
| En-tête | setupapi.h (inclure Setupapi.h) |
| Bibliothèque | Setupapi.lib |