CM_Get_Device_Interface_ListW, 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_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 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.

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;
    }

Configuration requise

Voir aussi

CM_Get_Device_Interface_List_Size