fonction CM_Get_Device_Interface_ListW (cfgmgr32.h)

Article
11/20/2024

La fonction CM_Get_Device_Interface_List récupère une liste d’instances d’interface d’appareil appartenant à une classe d’interface d’appareil spécifiée.

Syntaxe

CMAPI CONFIGRET CM_Get_Device_Interface_ListW(
  [in]           LPGUID      InterfaceClassGuid,
  [in, optional] DEVINSTID_W pDeviceID,
  [out]          PZZWSTR     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 d’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 appartenant à 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 instance d’interface.

[in] BufferLen

Valeur fournie par l’appelant qui spécifie la longueur, en caractères, de la mémoire tampon pointée par tampon. Appelez CM_Get_Device_Interface_List_Size pour déterminer la taille de mémoire tampon requise.

[in] ulFlags

Contient l’un des indicateurs fournis par l’appelant suivant :

CM_GET_DEVICE_INTERFACE_LIST_ALL_DEVICES

La fonction fournit une liste contenant des interfaces d’appareil associées à tous les appareils qui correspondent au GUID spécifié et à l’ID d’instance d’appareil, le cas échéant.

CM_GET_DEVICE_INTERFACE_LIST_PRESENT

La fonction fournit une liste contenant des interfaces d’appareil associées aux appareils actuellement actifs et qui correspondent au GUID et à l’ID d’instance d’appareil spécifiés, le cas échéant.

Valeur de retour

Si l’opération réussit, la fonction retourne CR_SUCCESS. Sinon, il 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.

Retourner le code	Description
CR_BUFFER_SMALL	La mémoire tampon 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 l’absence de 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 une 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;
    }

Note

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. 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	Universel
d’en-tête	cfgmgr32.h (include Cfgmgr32.h)
bibliothèque	Cfgmgr32.lib
DLL	CfgMgr32.dll

Voir aussi

CM_Get_Device_Interface_List_Size

Partager via