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

Статья
11/20/2024

Функция 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

Вызываемое значение, указывающее длину буфера в символах, на который указывает буфер. Вызовите 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 (include Cfgmgr32.h)
библиотеки	Cfgmgr32.lib
DLL	CfgMgr32.dll

См. также

CM_Get_Device_Interface_List_Size

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