CM_Get_Device_Interface_ListA, fonction (cfgmgr32.h)

Article
08/22/2023

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
CR_BUFFER_SMALL	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

Voir aussi

CM_Get_Device_Interface_List_Size

Share via