MsiEnumComponentsExW 函数 (msi.h)

MsiEnumComponentsEx 函数枚举已安装的组件。 每次调用函数时,函数都会检索一个组件的组件代码。 组件代码是组件、版本和语言唯一的字符串 GUID。

Windows Installer 4.5 或更早版本不支持。 此函数从 Windows Installer 5.0 开始可用。

语法

UINT MsiEnumComponentsExW(
  [in, optional]  LPCWSTR           szUserSid,
  [in]            DWORD             dwContext,
  [in]            DWORD             dwIndex,
  [out, optional] WCHAR [39]        szInstalledComponentCode,
  [out, optional] MSIINSTALLCONTEXT *pdwInstalledContext,
  [out, optional] LPWSTR            szSid,
  [in, out]       LPDWORD           pcchSid
);

参数

[in, optional] szUserSid

一个以 null 结尾的字符串,其中包含 SID (安全标识符。) 已安装组件的枚举将扩展到此 SID 标识的用户。 特殊的 SID 字符串 s-1-1-0 (Everyone) 指定系统中所有用户的所有产品中所有已安装组件的枚举。 s-1-1-0 以外的 SID 值指定特定用户的用户 SID,并将枚举限制为指定用户安装的应用程序实例。

SID 类型 含义
NULL
指定当前登录的用户。
用户 SID
系统中特定用户的枚举。 用户 SID 的示例为“S-1-3-64-2415071341-1358098788-3127455600-2561”。
s-1-1-0
指定系统中的所有用户。
 
注意  

特殊的 SID 字符串 s-1-5-18 (系统) 不能用于枚举在每台计算机安装上下文中安装的应用程序。 将 SID 值设置为 s-1-5-18 将返回ERROR_INVALID_PARAMETER。 如果 dwContext 设置为仅MSIINSTALLCONTEXT_MACHINE, 则 szUserSid 必须为 NULL

 

[in] dwContext

一个标志,用于将已安装组件的枚举限制为在指定安装上下文中安装的产品实例。 枚举仅包括 由 szUserSid 指定的用户安装的产品实例。

标志 含义
MSIINSTALLCONTEXT_USERMANAGED
1
包括每用户托管安装上下文中存在的产品。
MSIINSTALLCONTEXT_USERUNMANAGED
2
包括每用户非托管安装上下文中存在的产品。
MSIINSTALLCONTEXT_MACHINE
4
包括每台计算机安装上下文中存在的产品。 当 dwInstallContext 设置为仅MSIINSTALLCONTEXT_MACHINE时, szUserSID 参数必须为 NULL

[in] dwIndex

指定要检索的组件的索引。 首次调用 MsiEnumComponentsEx 函数时,此参数必须为零 (0) 。 对于每个后续调用,索引必须递增 1。 仅当对函数的上一次调用返回ERROR_SUCCESS时,索引才应递增。 组件不进行排序,函数可以按任何顺序返回。

[out, optional] szInstalledComponentCode

接收已安装组件的组件代码 GUID 的输出缓冲区。 缓冲区的长度应足够大,以容纳包含组件代码的以 null 结尾的字符串值。 前 38 个 TCHAR 字符接收组件的 GUID,第 39 个字符接收终止 NULL 字符。

[out, optional] pdwInstalledContext

一个标志,为安装上下文提供安装组件的应用程序。

标志 含义
MSIINSTALLCONTEXT_USERMANAGED
1
应用程序安装在每用户管理的安装上下文中。
MSIINSTALLCONTEXT_USERUNMANAGED
2
应用程序安装在每用户非托管安装上下文中。
MSIINSTALLCONTEXT_MACHINE
4
应用程序安装在每台计算机安装安装上下文中。

[out, optional] szSid

接收安全标识符 (SID) ,该标识符标识安装了拥有组件的应用程序的用户。 如果应用程序的此实例安装在每台计算机安装上下文中,则位置会收到一个空字符串。

此位置的缓冲区长度应足够大,以容纳包含 SID 的以 null 结尾的字符串值。 如果缓冲区太小,函数将返回 ERROR_MORE_DATA 并且 pcchSid 指向的位置接收 SID 中的 TCHAR 数,不包括终止 NULL 字符。

如果 szSid 设置为 NULL而 pcchSid 是指向内存中某个位置的有效指针,则该函数将返回 ERROR_SUCCESS 并且位置接收 SID 中的 TCHAR 数,不包括终止 null 字符。 然后,可以再次调用 该函数来检索值, szSid 缓冲区的大小调整到足以包含 *pcchSid + 1 个字符的大小。

SID 类型 含义
空字符串
应用程序安装在每台计算机安装上下文中。
用户 SID
安装应用程序的系统中用户的 SID。

[in, out] pcchSid

接收 SID 中的 TCHAR 数,不包括终止 null 字符。 当函数返回时,无论函数能否成功复制 SID 并将 null 字符终止到 szSid 指向的缓冲区位置,此变量都设置为所请求的 SID 的大小。 大小作为请求值中的 TCHAR 数返回,不包括终止 null 字符。

仅当 szSid 也为 NULL 时,此参数才能设置为 NULL,否则函数将返回ERROR_INVALID_PARAMETER。 如果 szSidpcchSid 都设置为 NULL,则该函数返回 ERROR_SUCCESS (如果 SID 存在),而不检索 SID 值。

返回值

MsiEnumProductsEx 函数返回以下值之一。

返回代码 说明
ERROR_ACCESS_DENIED
需要管理员权限才能枚举由当前用户以外的用户安装的应用程序组件。
ERROR_BAD_CONFIGURATION
配置数据已损坏。
ERROR_INVALID_PARAMETER
将无效参数传递给函数。
ERROR_NO_MORE_ITEMS
没有更多要枚举的组件。
ERROR_SUCCESS
函数成功。
ERROR_MORE_DATA
提供的缓冲区太小,无法容纳整个值。
ERROR_FUNCTION_FAILED
函数失败。

注解

注意

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

要求

要求
最低受支持的客户端 Windows Server 2012、Windows 8、Windows Server 2008 R2 或 Windows 7 上的 Windows Installer 5.0。 若要了解 Windows Installer 版本所需的最低 Windows Service Pack,请参阅 Windows Installer 运行时要求。
目标平台 Windows
标头 msi.h
Library Msi.lib
DLL Msi.dll