SetupDiGetCustomDevicePropertyW, fonction (setupapi.h)

Article
11/20/2024

La fonction SetupDiGetCustomDeviceProperty récupère une propriété d’appareil personnalisée spécifiée à partir du Registre.

Syntaxe

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
);

Paramètres

[in] DeviceInfoSet

Handle vers le jeu d’informations d’appareil qui contient un élément d’informations sur l’appareil qui représente l’appareil pour lequel récupérer une propriété d’appareil personnalisée.

[in] DeviceInfoData

Pointeur vers une structure SP_DEVINFO_DATA qui spécifie l’élément d’informations d’appareil dans DeviceInfoSet.

[in] CustomPropertyName

Nom de valeur de Registre représentant une propriété personnalisée.

[in] Flags

Valeur d’indicateur qui indique comment les informations demandées doivent être retournées. L’indicateur peut être égal à zéro ou à l’un des éléments suivants :

DICUSTOMDEVPROP_MERGE_MULTISZ

Si elle est définie, la fonction récupère les valeurs de propriété propres à l’instance d’appareil et les valeurs de propriété spécifiques à l’ID matériel, concaténées sous forme de chaîne REG_MULTI_SZ typée. (Pour plus d’informations, consultez la section Remarques sur cette page de référence.)

[out, optional] PropertyRegDataType

Pointeur vers une variable de type DWORD qui reçoit le type de données de la propriété récupérée. Le type de données est spécifié comme l’une des constantes REG_ préfixées qui représente les types de données de Registre. Ce paramètre est facultatif et peut être NULL.

[out] PropertyBuffer

Pointeur vers une mémoire tampon qui reçoit les informations de propriété demandées.

[in] PropertyBufferSize

Taille, en octets, de la mémoire tampon PropertyBuffer .

[out, optional] RequiredSize

Pointeur vers une variable de type DWORD qui reçoit la taille de la mémoire tampon, en octets, requise pour recevoir les informations demandées. Ce paramètre est facultatif et peut être NULL. Si ce paramètre est spécifié, SetupDiGetCustomDeviceProperty retourne la taille requise, que la mémoire tampon PropertyBuffer soit suffisamment grande pour recevoir les informations demandées.

Valeur de retour

Si l’opération réussit, SetupDiGetCustomDeviceProperty retourne TRUE. Sinon, la fonction retourne FALSE et l’erreur journalisée peut être récupérée avec un appel à GetLastError. Si la mémoire tampon PropertyBuffer n’est pas assez grande pour recevoir les informations demandées, SetupDiGetCustomDeviceProperty retourne FALSE et un appel ultérieur à GetLastError retourne ERROR_INSUFFICIENT_BUFFER.

Remarques

SetupDiGetCustomDeviceProperty récupère les propriétés d’appareil associées à une seule instance d’appareil ou à tous les appareils correspondant à un id matériel spécifique. (Pour plus d’informations sur les ID matériels, consultez chaînes d’identification d’appareil).

Les fournisseurs peuvent définir des propriétés pour une instance d’appareil à l’aide directives AddReg INF dans sections INF DDInstall.HW et en spécifiant la racine de Registre HKR.

Seul le système peut définir des propriétés pour les ID matériels. Le système fournit une propriété « Icon » pour certains ID matériels.

La fonction vérifie d’abord si la propriété spécifiée existe pour l’instance d’appareil spécifiée. Dans ce cas, la valeur de la propriété est retournée. Si ce n’est pas le cas, la fonction vérifie si la propriété existe pour tous les appareils correspondant à l’ID matériel de l’instance d’appareil spécifiée. Dans ce cas, la valeur de la propriété est retournée. Si DICUSTOMDEVPROP_MERGE_MULTISZ est défini dans Indicateurs, la fonction retourne les valeurs de propriété associées à l’instance de l’appareil et à l’ID matériel, s’ils existent tous les deux.

Note

L’en-tête setupapi.h définit SetupDiGetCustomDeviceProperty comme alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. Le mélange de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.

Exigences

Exigence	Valeur
client minimum pris en charge	Disponible dans Windows XP et versions ultérieures de Windows.
plateforme cible	Bureau
d’en-tête	setupapi.h (include Setupapi.h)
bibliothèque	Setupapi.lib
DLL	Setupapi.dll