функция CM_Get_Device_Interface_ListA (cfgmgr32.h)

Функция CM_Get_Device_Interface_List извлекает список экземпляров интерфейса устройства, принадлежащих указанному классу интерфейса устройства.

Синтаксис

CMAPI CONFIGRET CM_Get_Device_Interface_ListA(
  [in]           LPGUID      InterfaceClassGuid,
  [in, optional] DEVINSTID_A pDeviceID,
  [out]          PZZSTR      Buffer,
  [in]           ULONG       BufferLen,
  [in]           ULONG       ulFlags
);

Параметры

[in] InterfaceClassGuid

Предоставляет GUID, идентифицирующий класс интерфейса устройства.

[in, optional] pDeviceID

Предоставленный вызывающим элементом указатель на строку с завершением NULL, представляющую идентификатор экземпляра устройства. Если этот параметр указан, функция извлекает интерфейсы устройства, поддерживаемые устройством для указанного класса. Если это значение равно NULL или указывает на строку нулевой длины, функция извлекает все интерфейсы, принадлежащие указанному классу.

[out] Buffer

Предоставленный вызывающим объектом указатель на буфер, который получает несколько строк Юникода с завершением NULL, каждая из которых представляет символьное имя ссылки экземпляра интерфейса.

[in] BufferLen

Значение, предоставленное вызывающим объектом, указывающее длину буфера, на который указывает буфер (в символах). Вызовите CM_Get_Device_Interface_List_Size, чтобы определить требуемый размер буфера.

[in] ulFlags

Содержит один из следующих флагов, предоставленных вызывающей стороны:

CM_GET_DEVICE_INTERFACE_LIST_ALL_DEVICES

Функция предоставляет список, содержащий интерфейсы устройств, связанные со всеми устройствами, которые соответствуют указанному GUID и идентификатору экземпляра устройства, если таковые есть.

CM_GET_DEVICE_INTERFACE_LIST_PRESENT

Функция предоставляет список, содержащий интерфейсы устройств, связанные с активными устройствами, которые соответствуют указанному GUID и идентификатору экземпляра устройства, если таковые имеются.

Возвращаемое значение

Если операция выполнена успешно, функция возвращает CR_SUCCESS. В противном случае возвращается один из кодов ошибок с префиксом CR_, как определено в Cfgmgr32.h.

В следующей таблице приведены некоторые из наиболее распространенных кодов ошибок, которые может возвращать эта функция.

Код возврата	Описание
CR_BUFFER_SMALL	Буфер буфера слишком мал, чтобы вместить запрошенный список интерфейсов устройств.

Комментарии

Между вызовом CM_Get_Device_Interface_List_Size для получения размера списка и вызовом CM_Get_Device_Interface_List для получения списка в систему можно добавить новый интерфейс устройства, в результате чего возвращаемый размер больше не будет допустимым.  Вызывающие абоненты должны быть надежными в этом условии и повторить попытку получения размера и списка, если CM_Get_Device_Interface_List возвращает CR_BUFFER_SMALL.

Примеры

Этот фрагмент кода демонстрирует повторную попытку получения размера и списка, как описано в разделе Примечания.

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

Примечание

Заголовок cfgmgr32.h определяет CM_Get_Device_Interface_List как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОД. Сочетание использования псевдонима, не зависящий от кодировки, с кодом, не зависящим от кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования

Требование	Значение
Минимальная версия клиента	Доступно в Microsoft Windows 2000 и более поздних версиях Windows.
Целевая платформа	Универсальное
Верхняя часть	cfgmgr32.h (включая Cfgmgr32.h)
Библиотека	Cfgmgr32.lib
DLL	CfgMgr32.dll

См. также раздел

CM_Get_Device_Interface_List_Size