msi.h) (MsiEnumComponentsExA 函数

  • 项目

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

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

语法

UINT MsiEnumComponentsExA(
  [in, optional]  LPCSTR            szUserSid,
  [in]            DWORD             dwContext,
  [in]            DWORD             dwIndex,
  [out, optional] CHAR [39]         szInstalledComponentCode,
  [out, optional] MSIINSTALLCONTEXT *pdwInstalledContext,
  [out, optional] LPSTR             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 (System) 不能用于枚举安装在每台计算机安装上下文中的应用程序。 将 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 的大小，无论该函数能否成功将 SID 和终止 null 字符复制到 szSid 指向的缓冲区位置。 大小作为请求值中的 TCHAR 数返回，不包括终止 null 字符。

仅当 szSid 也为 NULL 时，此参数才能设置为 NULL，否则函数返回ERROR_INVALID_PARAMETER。 如果 szSid 和 pcchSid 都设置为 NULL，则如果 SID 存在，则函数将返回ERROR_SUCCESS，而不检索 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