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

Статья
08/22/2023

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

Синтаксис

CMAPI CONFIGRET CM_Get_Device_Interface_ListW(
  [in]           LPGUID      InterfaceClassGuid,
  [in, optional] DEVINSTID_W pDeviceID,
  [out]          PZZWSTR     Buffer,
  [in]           ULONG       BufferLen,
  [in]           ULONG       ulFlags
);

Параметры

[in] InterfaceClassGuid

Предоставляет ИДЕНТИФИКАТОР GUID, идентифицирующий класс интерфейса устройства.

[in, optional] pDeviceID

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

[out] Buffer

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

[in] BufferLen

Предоставленное вызывающим объектом значение, указывающее длину (в символах) буфера, на который указывает buffer. Вызовите 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

Поделиться через