SetupDiGetClassPropertyExW, fonction (setupapi.h)
La fonction SetupDiGetClassPropertyEx récupère une propriété de classe pour une classe d’installation d’appareil ou une classe d’interface d’appareil sur un ordinateur local ou distant.
Syntaxe
WINSETUPAPI BOOL SetupDiGetClassPropertyExW(
[in] const GUID *ClassGuid,
[in] const DEVPROPKEY *PropertyKey,
[out] DEVPROPTYPE *PropertyType,
[out, optional] PBYTE PropertyBuffer,
[in] DWORD PropertyBufferSize,
[out, optional] PDWORD RequiredSize,
[in] DWORD Flags,
[in, optional] PCWSTR MachineName,
PVOID Reserved
);
Paramètres
[in] ClassGuid
Pointeur vers un GUID qui identifie la classe d’installation d’appareil ou la classe d’interface d’appareil pour laquelle récupérer une propriété d’appareil pour la classe d’appareil. Pour plus d’informations sur la spécification du 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 demandée.
[out] PropertyType
Pointeur vers une variable de type DEVPROPTYPE qui reçoit l’identificateur property-data-type de la propriété de classe d’appareil demandée, où l’identificateur de type de données de propriété est le ou au niveau du bit entre un identificateur de type de données de base et, si le type de données de base est modifié, un modificateur property-data-type.
[out, optional] PropertyBuffer
Pointeur vers une mémoire tampon qui reçoit la propriété de classe d’appareil demandée. SetupDiGetClassPropertyEx récupère la valeur de propriété demandée uniquement si la mémoire tampon est suffisamment grande pour contenir toutes les données de valeur de propriété. Le pointeur peut être NULL. Si le pointeur est défini sur NULL et que RequiredSize est fourni, SetupDiGetClassPropertyEx retourne la taille de la propriété de classe d’appareil, en octets, dans *RequiredSize.
[in] PropertyBufferSize
Taille, en octets, de la mémoire tampon PropertyBuffer . Si PropertyBuffer a la valeur NULL, PropertyBufferSize doit avoir la valeur zéro.
[out, optional] RequiredSize
Pointeur vers une variable de type DWORD qui reçoit la taille, en octets, de la propriété de classe d’appareil si la propriété est récupérée ou la taille de mémoire tampon requise si la mémoire tampon n’est pas suffisamment grande. Ce pointeur peut être défini sur NULL.
[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 terminée par NULL qui contient le nom UNC, y compris le préfixe « \ », d’un ordinateur. Le pointeur peut être défini sur NULL. Si MachineName a la valeur NULL, SetupDiGetClassPropertyEx récupère la propriété de classe d’appareil demandée à partir de 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 être défini sur NULL.
Valeur retournée
SetupDiGetClassPropertyEx retourne TRUE si elle réussit. Sinon, elle 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 des indicateurs n’est pas égale à zéro. |
|
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é. |
|
Un paramètre non spécifié n’est pas valide. |
|
La clé de propriété fournie par PropertyKey n’est pas valide. |
|
La chaîne de référence de l’interface d’appareil n’est pas valide. Cette erreur peut être retournée si l’indicateur DICLASSPROP_INTERFACE est spécifié. |
|
Une valeur de données interne non spécifiée n’était pas valide. |
|
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. |
|
La mémoire système disponible était insuffisante pour terminer l’opération. |
|
La propriété d’appareil demandée n’existe pas. |
|
L’appelant n’a pas de privilèges d’administrateur. |
Remarques
SetupDiGetClassPropertyEx fait partie du modèle de propriété d’appareil unifié.
SetupAPI prend uniquement en charge une version Unicode de SetupDiGetClassPropertyEx.
Un appelant de SetupDiGetClassPropertyEx doit être membre du groupe Administrateurs pour définir une propriété d’interface d’appareil.
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 SetupDiGetClassProperty.
Pour définir une propriété de classe d’appareil sur un ordinateur local, appelez SetupDiSetClassPropertyet pour définir une propriété de classe d’appareil sur un ordinateur distant, appelez SetupDiSetClassPropertyEx.
Configuration requise
| Condition requise | Valeur |
|---|---|
| Client minimal pris en charge | Disponible dans Windows Vista et les versions plus récentes de Windows. |
| Plateforme cible | DesktopPour universel, appelez CM_Get_Class_Property_ExW |
| En-tête | setupapi.h (inclure Setupapi.h) |
| Bibliothèque | Setupapi.lib |