SetupDiGetDevicePropertyW, fonction (setupapi.h)

Article
08/26/2023

La fonction SetupDiGetDeviceProperty récupère une propriété de instance d’appareil.

Syntaxe

WINSETUPAPI BOOL SetupDiGetDevicePropertyW(
  [in]            HDEVINFO         DeviceInfoSet,
  [in]            PSP_DEVINFO_DATA DeviceInfoData,
  [in]            const DEVPROPKEY *PropertyKey,
  [out]           DEVPROPTYPE      *PropertyType,
  [out, optional] PBYTE            PropertyBuffer,
  [in]            DWORD            PropertyBufferSize,
  [out, optional] PDWORD           RequiredSize,
  [in]            DWORD            Flags
);

Paramètres

[in] DeviceInfoSet

Handle d’un jeu d’informations d’appareil qui contient un instance d’appareil pour lequel récupérer une propriété instance d’appareil.

[in] DeviceInfoData

Pointeur vers la structure SP_DEVINFO_DATA qui représente l’appareil instance pour lequel récupérer une propriété de instance d’appareil.

[in] PropertyKey

Pointeur vers une structure DEVPROPKEY qui représente la clé de propriété de l’appareil demandé instance propriété.

[out] PropertyType

Pointeur vers une variable de type DEVPROPTYPE qui reçoit l’identificateur de type de données de propriété de la propriété de l’appareil demandé instance propriété, où l’identificateur de type de données de propriété est l’identificateur au niveau du bit OU entre un identificateur de type de données de base et, si le type de données de base est modifié, un modificateur de type de données de propriété.

[out, optional] PropertyBuffer

Pointeur vers une mémoire tampon qui reçoit la propriété de instance d’appareil demandée. SetupDiGetDeviceProperty récupère la 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 avoir la valeur NULL. Si le pointeur a la valeur NULL et que RequiredSize est fourni, SetupDiGetDeviceProperty retourne la taille de la propriété, 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é device instance 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 assez grande. Ce pointeur peut être défini sur NULL.

[in] Flags

Ce paramètre doit être défini sur zéro.

Valeur retournée

SetupDiGetDeviceProperty retourne TRUE si elle 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
ERROR_INVALID_FLAGS	La valeur de Flags n’est pas égale à zéro.
ERROR_INVALID_HANDLE	Le jeu d’informations sur l’appareil spécifié par DevInfoSet n’est pas valide.
ERROR_INVALID_PARAMETER	Un paramètre fourni n’est pas valide. Il est possible que l’élément d’informations sur l’appareil ne soit pas valide.
ERROR_INVALID_REG_PROPERTY	La clé de propriété fournie par PropertyKey n’est pas valide.
ERROR_INVALID_DATA	Une valeur de données interne non spécifiée n’était pas valide.
ERROR_INVALID_USER_BUFFER	Une mémoire tampon utilisateur n’est pas valide. Une possibilité est que PropertyBuffer a la valeur NULL et que PropertBufferSize n’est pas zéro.
ERROR_NO_SUCH_DEVINST	Le instance d’appareil spécifié par DevInfoData n’existe pas.
ERROR_INSUFFICIENT_BUFFER	La mémoire tampon PropertyBuffer est trop petite pour contenir la valeur de propriété demandée, ou une mémoire tampon de données interne qui a été passée à un appel système était trop petite.
ERROR_NOT_ENOUGH_MEMORY	Il n’y avait pas assez de mémoire système disponible pour terminer l’opération.
ERROR_NOT_FOUND	La propriété d’appareil demandée n’existe pas.
ERROR_ACCESS_DENIED	L’appelant ne dispose pas de privilèges d’administrateur.

Remarques

SetupDiGetDeviceProperty fait partie du modèle de propriété d’appareil unifié.

SetupAPI prend uniquement en charge une version Unicode de SetupDiGetDeviceProperty.

Pour obtenir les clés de propriété de l’appareil qui représentent les propriétés de l’appareil définies pour un instance d’appareil, appelez SetupDiGetDevicePropertyKeys.

Pour définir une propriété de instance d’appareil, appelez SetupDiSetDeviceProperty.

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_DevNode_Property
En-tête	setupapi.h (inclure SetupAPI.h)
Bibliothèque	SetupAPI.lib
DLL	SetupAPI.dll
Ensemble d’API	ext-ms-win-setupapi-classinstallers-l1-1-0 (introduit dans Windows 8)

Voir aussi

SetupDiGetDevicePropertyKeys

SetupDiSetDeviceProperty