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

Функция CM_Get_Device_ID_List извлекает список идентификаторов экземпляров устройств для экземпляров устройств локального компьютера.

Синтаксис

CMAPI CONFIGRET CM_Get_Device_ID_ListA(
  [in, optional] PCSTR  pszFilter,
  [out]          PZZSTR Buffer,
  [in]           ULONG  BufferLen,
  [in]           ULONG  ulFlags
);

Параметры

[in, optional] pszFilter

Поставляемый вызывающим элементом указатель на символьную строку, которая имеет либо подмножество идентификаторов экземпляров (ID) устройства компьютера, либо значение NULL. См. следующее описание ulFlags.

[out] Buffer

Адрес буфера для получения набора строк идентификаторов экземпляра устройства с завершением NULL. Конец набора завершается дополнительным значением NULL. Требуемый размер буфера следует получить путем вызова CM_Get_Device_ID_List_Size.

[in] BufferLen

Длина буфера, указанного в буфере, заданном параметром Buffer, в символах вызывающего объекта.

[in] ulFlags

Один из следующих битовых флагов, предоставляемых вызывающим абонентом, который указывает фильтры поиска:

CM_GETIDLIST_FILTER_BUSRELATIONS

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

CM_GETIDLIST_FILTER_CLASS (Windows 7 и более поздние версии Windows)

Если этот флаг установлен, pszFilter содержит строку, указывающую GUID класса установки устройства . Возвращенный список содержит экземпляры устройств, для которых свойство (на которое ссылается константой CM_DRP_CLASSGUID) соответствует указанному GUID класса настройки устройства.

Константа CM_DRP_CLASSGUID определена в Cfgmgr32.h.

CM_GETIDLIST_FILTER_PRESENT (Windows 7 и более поздние версии Windows)

Если этот флаг установлен, возвращенный список содержит только экземпляры устройств, которые в настоящее время присутствуют в системе. Это значение можно объединить с другими значениями ulFlags , такими как CM_GETIDLIST_FILTER_CLASS.

CM_GETIDLIST_FILTER_TRANSPORTRELATIONS (Windows 7 и более поздние версии Windows)

Если этот флаг установлен, pszFilter должен указать идентификатор экземпляра устройства составного узла устройства (devnode).

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

Дополнительные сведения о составных devnodes и транспортных отношениях см. в следующем разделе Примечаний .

CM_GETIDLIST_DONOTGENERATE

Используется только с CM_GETIDLIST_FILTER_SERVICE. Если задано и если дерево устройств не содержит devnode для указанной службы, этот флаг не позволяет функции создать devnode для службы.

CM_GETIDLIST_FILTER_EJECTRELATIONS

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

CM_GETIDLIST_FILTER_ENUMERATOR

Если этот флаг установлен, pszFilter должен указать имя перечислителя устройств, за которым при необходимости следует идентификатор устройства. Формат строки— EnumeratorName\<DeviceID>, например ROOT или ROOT\*PNP0500.

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

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

CM_GETIDLIST_FILTER_NONE

Если этот флаг установлен, pszFilter игнорируется и возвращается список всех устройств в системе.

CM_GETIDLIST_FILTER_POWERRELATIONS

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

CM_GETIDLIST_FILTER_REMOVALRELATIONS

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

CM_GETIDLIST_FILTER_SERVICE

Если этот флаг установлен, pszFilter должен указать имя службы Microsoft Windows (как правило, драйвера). Функция возвращает идентификаторы экземпляров устройств для экземпляров устройств, управляемых указанной службой.

Обратите внимание, что если дерево устройств не содержит devnode для указанной службы, эта функция создает его по умолчанию. Чтобы запретить такое поведение, также задайте CM_GETIDLIST_DONOTGENERATE.

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

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

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

Комментарии

Начиная с Windows 7 устройство, поддерживающее несколько путей транспорта для данных на основе пакетов, называется составным устройством и представлено составным devnode. Составной devnode логически представляет составное устройство для пользователя и приложений как единое устройство, даже если составной devnode может иметь несколько путей к физическому устройству.

Каждый активный транспортный путь к физическому устройству представлен транспортным devnode и называется транспортным отношением для составного устройства.

Составной devnode (но не связанные транспортные devnodes) предоставляет интерфейсы устройств приложениям и системе. Когда приложение использует эти интерфейсы общедоступных устройств, составное устройство направляет данные на основе пакетов в один или несколько таких транспортных devnodes, которые затем передают данные на физическое устройство.

Например, если физический мобильный телефон одновременно подключен к компьютеру на USB-накопителе и к шинам Bluetooth, каждая шина перечисляет дочерний транспортный узел на этой шине, чтобы представить физическое подключение устройства.

В этом случае, если задать флаги CM_GETIDLIST_FILTER_TRANSPORTRELATIONS в ulFlags и указать идентификатор экземпляра устройства составного devnode мобильного телефона в pszFilter, функция возвращает идентификаторы экземпляров устройства для двух транспортных devnodes в параметре Buffer .

Дополнительные сведения об идентификаторах экземпляров устройств см. в разделе Строки идентификации устройств.

Примечание

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

Требования

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

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

CM_Get_Device_ID_List_Size