SetupDiGetDeviceInterfaceDetailA, fonction (setupapi.h)

Article
11/20/2024

La fonction SetupDiGetDeviceInterfaceDetail retourne des détails sur une interface d’appareil.

Syntaxe

WINSETUPAPI BOOL SetupDiGetDeviceInterfaceDetailA(
  [in]            HDEVINFO                           DeviceInfoSet,
  [in]            PSP_DEVICE_INTERFACE_DATA          DeviceInterfaceData,
  [out, optional] PSP_DEVICE_INTERFACE_DETAIL_DATA_A DeviceInterfaceDetailData,
  [in]            DWORD                              DeviceInterfaceDetailDataSize,
  [out, optional] PDWORD                             RequiredSize,
  [out, optional] PSP_DEVINFO_DATA                   DeviceInfoData
);

Paramètres

[in] DeviceInfoSet

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

[in] DeviceInterfaceData

Pointeur vers une structure SP_DEVICE_INTERFACE_DATA qui spécifie l’interface dans DeviceInfoSet pour laquelle récupérer les détails. Un pointeur de ce type est généralement retourné par SetupDiEnumDeviceInterfaces.

[out, optional] DeviceInterfaceDetailData

Pointeur vers une structure SP_DEVICE_INTERFACE_DETAIL_DATA pour recevoir des informations sur l’interface spécifiée. Ce paramètre est facultatif et peut être NULL. Ce paramètre doit être NULL si DeviceInterfaceDetailSize est égal à zéro. Si ce paramètre est spécifié, l’appelant doit définir DeviceInterfaceDetailData.cbSize sur taille de(SP_DEVICE_INTERFACE_DETAIL_DATA) avant d’appeler cette fonction. Le cbSize membre contient toujours la taille de la partie fixe de la structure de données, et non une taille reflétant la chaîne de longueur variable à la fin.

[in] DeviceInterfaceDetailDataSize

Taille de la mémoire tampon DeviceInterfaceDetailData. La mémoire tampon doit être au moins (offsetof(SP_DEVICE_INTERFACE_DETAIL_DATA, DevicePath) + sizeof(TCHAR)) octets, pour contenir la partie fixe de la structure et une seule NULL pour mettre fin à une chaîne de MULTI_SZ vide.

Ce paramètre doit être égal à zéro si DeviceInterfaceDetailData est NULL.

[out, optional] RequiredSize

Pointeur vers une variable de type DWORD qui reçoit la taille requise de la mémoire tampon DeviceInterfaceDetailData. Cette taille inclut la taille de la partie fixe de la structure, ainsi que le nombre d’octets requis pour la chaîne de chemin d’accès d’appareil de longueur variable. Ce paramètre est facultatif et peut être NULL.

[out, optional] DeviceInfoData

Pointeur vers une mémoire tampon qui reçoit des informations sur l’appareil qui prend en charge l’interface demandée. L’appelant doit définir DeviceInfoData.cbSize sur taille de(SP_DEVINFO_DATA). Ce paramètre est facultatif et peut être NULL.

Valeur de retour

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

Remarques

L’utilisation de cette fonction pour obtenir des détails sur une interface est généralement un processus en deux étapes :

Obtenez la taille de mémoire tampon requise. Appelez setupDiGetDeviceInterfaceDetail avec un pointeur DeviceInterfaceDetailData, un pointeur DeviceInterfaceDetailDataSize de zéro et une variable obligatoire RequiredSize valide. En réponse à un tel appel, cette fonction retourne la taille de mémoire tampon requise à RequiredSize et échoue avec GetLastError retourner ERROR_INSUFFICIENT_BUFFER.
Allouez une mémoire tampon de taille appropriée et appelez à nouveau la fonction pour obtenir les détails de l’interface.

Le détail de l’interface retourné par cette fonction se compose d’un chemin d’accès d’appareil qui peut être transmis à des fonctions Win32 telles que CreateFile. N’essayez pas d’analyser le nom symbolique du chemin d’accès de l’appareil. Le chemin d’accès de l’appareil peut être réutilisé au démarrage du système.

setupDiGetDeviceInterfaceDetail peut être utilisé pour obtenir uniquement le DeviceInfoData. Si l’interface existe mais que DeviceInterfaceDetailData est NULL, cette fonction échoue, GetLastError retourne ERROR_INSUFFICIENT_BUFFER, et la structure DeviceInfoData est remplie d’informations sur l’appareil qui expose l’interface.

Note

L’en-tête setupapi.h définit SetupDiGetDeviceInterfaceDetail 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 Microsoft Windows 2000 et versions ultérieures de Windows.
plateforme cible	Bureau
d’en-tête	setupapi.h (include Setupapi.h)
bibliothèque	Setupapi.lib

Voir aussi

SetupDiEnumDeviceInterfaces

SetupDiGetClassDevs

Partager via