SetupDiGetDeviceInterfaceDetailW, fonction (setupapi.h)

Article
08/26/2023

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

Syntaxe

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

Paramètres

[in] DeviceInfoSet

Pointeur vers le jeu d’informations sur 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 de 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 sizeof(SP_DEVICE_INTERFACE_DETAIL_DATA) avant d’appeler cette fonction. Le membre cbSize 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 valeur NULL pour terminer une chaîne de MULTI_SZ vide.

Ce paramètre doit être égal à zéro si DeviceInterfaceDetailData a la valeur 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 de l’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 sizeof(SP_DEVINFO_DATA). Ce paramètre est facultatif et peut être NULL.

Valeur retournée

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é 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 DeviceInterfaceDetailDataNULL, un DeviceInterfaceDetailDataSize de zéro et une variable RequiredSize valide. En réponse à un tel appel, cette fonction retourne la taille de mémoire tampon requise dans RequiredSize et échoue lorsque GetLastError retourne 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 passé à 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é entre les démarrages du système.

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

Notes

L’en-tête setupapi.h définit SetupDiGetDeviceInterfaceDetail en tant qu’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. La combinaison 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.

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
Ensemble d’API	ext-ms-win-setupapi-classinstallers-l1-1-2 (introduit dans Windows 10, version 10.0.14393)

Voir aussi

SetupDiEnumDeviceInterfaces

SetupDiGetClassDevs

Partager via