SetupDiGetDeviceInterfaceAlias, fonction (setupapi.h)

Article
08/26/2023

La fonction SetupDiGetDeviceInterfaceAlias retourne un alias d’une interface d’appareil spécifiée.

Syntaxe

WINSETUPAPI BOOL SetupDiGetDeviceInterfaceAlias(
  [in]  HDEVINFO                  DeviceInfoSet,
  [in]  PSP_DEVICE_INTERFACE_DATA DeviceInterfaceData,
  [in]  const GUID                *AliasInterfaceClassGuid,
  [out] PSP_DEVICE_INTERFACE_DATA AliasDeviceInterfaceData
);

Paramètres

[in] DeviceInfoSet

Pointeur vers le jeu d’informations sur l’appareil qui contient l’interface de l’appareil pour laquelle récupérer un alias. Ce handle est généralement retourné par SetupDiGetClassDevs.

[in] DeviceInterfaceData

Pointeur vers une structure de SP_DEVICE_INTERFACE_DATA qui spécifie l’interface d’appareil dans DeviceInfoSet pour laquelle récupérer un alias. Ce pointeur est généralement retourné par SetupDiEnumDeviceInterfaces.

[in] AliasInterfaceClassGuid

Pointeur vers un GUID qui spécifie la classe d’interface de l’alias à récupérer.

[out] AliasDeviceInterfaceData

Pointeur vers une mémoire tampon allouée à l’appelant qui contient, en cas de retour réussi, une structure de SP_DEVICE_INTERFACE_DATA terminée qui identifie l’alias demandé. L’appelant doit définir AliasDeviceInterfaceData.cbSize sur sizeof(SP_DEVICE_INTERFACE_DATA) avant d’appeler cette fonction.

Valeur retournée

SetupDiGetDeviceInterfaceAlias retourne TRUE si la fonction s’est terminée sans erreur. Si la fonction s’est terminée avec une erreur, FALSE est retourné et le code d’erreur de l’échec peut être récupéré en appelant GetLastError.

Les erreurs possibles retournées par GetLastError sont répertoriées dans le tableau suivant.

Code de retour	Description
ERROR_INVALID_PARAMETER	Paramètre DeviceInfoSet ou DeviceInterfaceData non valide.
ERROR_NO_SUCH_INTERFACE_DEVICE	Il n’existe aucun alias de classe AliasInterfaceClassGuid pour l’interface d’appareil spécifiée.
ERROR_INVALID_USER_BUFFER	Mémoire tampon AliasDeviceInterfaceData non valide.

Remarques

Les interfaces d’appareil sont considérées comme des alias si elles sont de classes d’interface différentes, mais sont prises en charge par le même appareil et ont des chaînes de référence identiques.

SetupDiGetDeviceInterfaceAlias peut être utilisé pour localiser un appareil qui expose plusieurs interfaces. Par exemple, considérez un disque qui peut faire partie d’un volume à tolérance de panne et qui peut contenir des données chiffrées. Le pilote de fonction pour le périphérique de disque peut inscrire une interface de volume à tolérance de panne et une interface de volume chiffré. Ces interfaces sont des alias d’interface de périphérique si le pilote de fonction les inscrit avec des chaînes de référence identiques et qu’elles font référence au même appareil. (Les chaînes de référence seront probablement NULL et sont donc égales.)

Pour localiser un tel appareil multi-interface, recherchez d’abord tous les appareils disponibles qui exposent l’une des interfaces, comme l’interface de volume à tolérance de panne, à l’aide de SetupDiGetClassDevs et SetupDiEnumDeviceInterfaces. Ensuite, passez un appareil avec la première interface (volume à tolérance de panne) à SetupDiGetDeviceInterfaceAlias et demandez un alias de l’autre classe d’interface (encrypted-volume).

Si l’alias demandé existe mais que la mémoire tampon AliasDeviceInterfaceData fournie par l’appelant n’est pas valide, cette fonction ajoute correctement l’élément d’interface de périphérique à DevInfoSet , mais retourne FALSE pour la valeur de retour. Dans ce cas, GetLastError retourne ERROR_INVALID_USER_BUFFER.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Disponible dans Microsoft Windows 2000 et versions ultérieures de Windows.
Plateforme cible	Desktop (Expérience utilisateur)
En-tête	setupapi.h (inclure Setupapi.h)
Bibliothèque	Setupapi.lib
DLL	Setupapi.dll

Voir aussi

SetupDiEnumDeviceInterfaces

SetupDiGetClassDevs