CM_Get_Device_ID_ListA 函数 (cfgmgr32.h)

项目
02/26/2024

CM_Get_Device_ID_List 函数检索本地计算机设备实例的设备实例 ID 列表。

语法

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 必须指定设备实例标识符。函数返回指定设备实例的总线关系的设备实例 ID。

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) 。

该函数返回表示指定复合开发节点的传输关系的开发节点的设备实例标识符。

有关复合开发节点和传输关系的详细信息，请参阅以下 “备注” 部分。

CM_GETIDLIST_DONOTGENERATE

仅用于 CM_GETIDLIST_FILTER_SERVICE。如果已设置，并且设备树不包含指定服务的 devnode，则此标志将阻止函数为服务创建开发节点。

CM_GETIDLIST_FILTER_EJECTRELATIONS

如果设置了此标志， pszFilter 必须指定设备实例标识符。函数返回指定设备实例的弹出关系的设备实例 ID。

CM_GETIDLIST_FILTER_ENUMERATOR

如果设置了此标志， pszFilter 必须指定设备枚举器的名称，（可选）后跟设备 ID。字符串格式为 EnumeratorName\<DeviceID>，例如 ROOT 或 ROOT\*PNP0500。

如果 pszFilter 仅提供枚举器名称，则函数将返回与枚举器关联的每个设备的实例的设备实例 ID 。可以通过调用 CM_Enumerate_Enumerators 来获取枚举器名称。

如果 pszFilter 同时提供枚举器和设备 ID，则函数仅返回与枚举器关联的指定设备的实例的设备实例 ID 。

CM_GETIDLIST_FILTER_NONE

如果设置了此标志，将忽略 pszFilter ，并返回系统上所有设备的列表。

CM_GETIDLIST_FILTER_POWERRELATIONS

如果设置了此标志， pszFilter 必须指定设备实例标识符。函数返回指定设备实例的电源关系的设备实例 ID。

CM_GETIDLIST_FILTER_REMOVALRELATIONS

如果设置了此标志， pszFilter 必须指定设备实例标识符。函数返回指定设备实例的删除关系的设备实例 ID。

CM_GETIDLIST_FILTER_SERVICE

如果设置了此标志， pszFilter 必须指定 Microsoft Windows 服务的名称， (通常是驱动程序) 。函数返回由指定服务控制的设备实例的设备实例 ID。

请注意，如果设备树不包含指定服务的开发节点，则此函数默认创建一个。若要禁止此行为，还需设置 CM_GETIDLIST_DONOTGENERATE。

如果未指定搜索筛选器标志，则函数将返回所有设备实例的所有设备实例 ID。

返回值

如果操作成功，函数将返回CR_SUCCESS。否则，它将返回 Cfgmgr32.h 中定义的CR_前缀错误代码之一。

注解

从 Windows 7 开始，支持基于数据包的数据的多个传输路径的设备称为复合设备，由复合开发节点表示。复合开发节点在逻辑上将复合设备表示为单个设备的用户和应用程序，即使复合开发节点可以有多个物理设备的路径。

物理设备的每个活动传输路径都由一个传输开发节点表示，称为复合设备的 传输关系 。

复合开发节点 (但不是相关的传输开发节点，) 向应用程序和系统公开设备接口。当应用程序使用这些公共设备接口时，复合设备会将基于数据包的数据路由到其中一个或多个传输开发节点，然后将数据传输到物理设备。

例如，如果物理手机同时连接到 USB 和蓝牙总线上的计算机，则每个总线将枚举该总线上的子传输开发节点，以表示设备的物理连接。

在这种情况下，如果在 ulFlags 中设置CM_GETIDLIST_FILTER_TRANSPORTRELATIONS标志，并在 pszFilter 中指定手机的复合开发节点的设备实例 ID，则该函数将在 Buffer 参数中返回两个传输开发节点的设备实例 ID。

有关设备实例 ID 的详细信息，请参阅设备标识字符串。

注意

cfgmgr32.h 标头将 CM_Get_Device_ID_List 定义为别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。将非特定编码别名的使用与非非特定编码的代码混合使用可能会导致不匹配，从而导致编译或运行时错误。有关详细信息，请参阅函数原型的约定。

要求

要求	值
最低受支持的客户端	在 Microsoft Windows 2000 及更高版本的 Windows 中可用。
目标平台	通用
标头	cfgmgr32.h (包括 Cfgmgr32.h)
Library	Cfgmgr32.lib
DLL	CfgMgr32.dll

另请参阅

CM_Get_Device_ID_List_Size