CM_Get_Device_Interface_ListA, fonction (cfgmgr32.h)
La fonction CM_Get_Device_Interface_List récupère une liste d’instances d’interface d’appareil qui appartiennent à une classe d’interface d’appareil spécifiée.
Syntaxe
CMAPI CONFIGRET CM_Get_Device_Interface_ListA(
[in] LPGUID InterfaceClassGuid,
[in, optional] DEVINSTID_A pDeviceID,
[out] PZZSTR Buffer,
[in] ULONG BufferLen,
[in] ULONG ulFlags
);
Paramètres
[in] InterfaceClassGuid
Fournit un GUID qui identifie une classe d’interface d’appareil.
[in, optional] pDeviceID
Pointeur fourni par l’appelant vers une chaîne terminée par NULL qui représente un ID de instance d’appareil. Si elle est spécifiée, la fonction récupère les interfaces d’appareil prises en charge par l’appareil pour la classe spécifiée. Si cette valeur est NULL ou si elle pointe vers une chaîne de longueur nulle, la fonction récupère toutes les interfaces qui appartiennent à la classe spécifiée.
[out] Buffer
Pointeur fourni par l’appelant vers une mémoire tampon qui reçoit plusieurs chaînes Unicode terminées par NULL, chacune représentant le nom de lien symbolique d’une interface instance.
[in] BufferLen
Valeur fournie par l’appelant qui spécifie la longueur, en caractères, de la mémoire tampon pointée par Buffer. Appelez CM_Get_Device_Interface_List_Size pour déterminer la taille de mémoire tampon requise.
[in] ulFlags
Contient l’un des indicateurs suivants fournis par l’appelant :
CM_GET_DEVICE_INTERFACE_LIST_ALL_DEVICES
La fonction fournit une liste contenant les interfaces d’appareil associées à tous les appareils qui correspondent au GUID et à l’ID de instance d’appareil spécifiés, le cas échéant.
CM_GET_DEVICE_INTERFACE_LIST_PRESENT
La fonction fournit une liste contenant les interfaces d’appareil associées aux appareils actuellement actifs et qui correspondent au GUID et à l’ID de instance d’appareil spécifiés, le cas échéant.
Valeur retournée
Si l’opération réussit, la fonction retourne CR_SUCCESS. Sinon, elle retourne l’un des codes d’erreur avec le préfixe CR_ tel que défini dans Cfgmgr32.h.
Le tableau suivant inclut certains des codes d’erreur les plus courants que cette fonction peut retourner.
Code de retour | Description |
---|---|
|
La mémoire tampon est trop petite pour contenir la liste demandée des interfaces d’appareil. |
Remarques
Entre l’appel de CM_Get_Device_Interface_List_Size pour obtenir la taille de la liste et l’appel de CM_Get_Device_Interface_List pour obtenir la liste, une nouvelle interface d’appareil peut être ajoutée au système, ce qui entraîne la non-validité de la taille retournée. Les appelants doivent être robustes à cette condition et réessayer d’obtenir la taille et la liste si CM_Get_Device_Interface_List retourne CR_BUFFER_SMALL.
Exemples
Cet extrait de code illustre la nouvelle tentative d’obtention de la taille et de la liste, comme décrit dans la section Remarques.
CONFIGRET cr = CR_SUCCESS;
PWSTR DeviceInterfaceList = NULL;
ULONG DeviceInterfaceListLength = 0;
do {
cr = CM_Get_Device_Interface_List_Size(&DeviceInterfaceListLength,
(LPGUID)&GUID_DEVINTERFACE_VOLUME,
NULL,
CM_GET_DEVICE_INTERFACE_LIST_ALL_DEVICES);
if (cr != CR_SUCCESS)
{
break;
}
if (DeviceInterfaceList != NULL) {
HeapFree(GetProcessHeap(),
0,
DeviceInterfaceList);
}
DeviceInterfaceList = (PWSTR)HeapAlloc(GetProcessHeap(),
HEAP_ZERO_MEMORY,
DeviceInterfaceListLength * sizeof(WCHAR));
if (DeviceInterfaceList == NULL)
{
cr = CR_OUT_OF_MEMORY;
break;
}
cr = CM_Get_Device_Interface_List((LPGUID)&GUID_DEVINTERFACE_VOLUME,
NULL,
DeviceInterfaceList,
DeviceInterfaceListLength,
CM_GET_DEVICE_INTERFACE_LIST_ALL_DEVICES);
} while (cr == CR_BUFFER_SMALL);
if (cr != CR_SUCCESS)
{
goto Exit;
}
Notes
L’en-tête cfgmgr32.h définit CM_Get_Device_Interface_List 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 | Universal |
En-tête | cfgmgr32.h (inclure Cfgmgr32.h) |
Bibliothèque | Cfgmgr32.lib |
DLL | CfgMgr32.dll |