msi.h) msi.h (MsiEnumClientsExA 函数

  • 项目

MsiEnumClientsEx 函数枚举使用指定组件的已安装应用程序。 函数在每次调用应用程序时检索应用程序的 产品代码 。

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

语法

UINT MsiEnumClientsExA(
  [in]                LPCSTR            szComponent,
  [in, optional]      LPCSTR            szUserSid,
  [in]                DWORD             dwContext,
  [in]                DWORD             dwProductIndex,
  [out, optional]     CHAR [39]         szProductBuf,
  [out, optional]     MSIINSTALLCONTEXT *pdwInstalledContext,
  [out, optional]     LPSTR             szSid,
  [in, out, optional] LPDWORD           pcchSid
);

parameters

[in] szComponent

标识组件的组件代码 GUID。 函数枚举使用此组件的应用程序。

[in, optional] szUserSid

包含安全标识符 (SID.) 以 null 结尾的字符串值 应用程序枚举将扩展到此 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] dwProductIndex

指定要检索的应用程序的索引。 首次调用函数时，此参数的值必须为零 (0) 。 对于每个后续调用，索引必须递增 1。 仅当对函数的上一次调用返回 ERROR_SUCCESS时，索引才应递增。

[out, optional] szProductBuf

一个字符串值，用于接收应用程序的产品代码。 此位置的缓冲区长度应足够大，以容纳包含产品代码的以 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, optional] pcchSid

指向内存中某个位置的指针，该位置包含一个变量，该变量指定 SID 中的 TCHAR 数，不包括终止 null 字符。 当函数返回时，无论函数能否成功复制 SID 并将 null 字符终止到 szSid 指向的缓冲区位置，此变量都设置为所请求的 SID 的大小。 大小作为请求值中的 TCHAR 数返回，不包括终止 null 字符。

仅当 szSid 也为 NULL 时，此参数才能设置为 NULL，否则函数将返回ERROR_INVALID_PARAMETER。 如果 szSid 和 pcchSid 都设置为 NULL，则该函数返回 ERROR_SUCCESS （如果 SID 存在），而不检索 SID 值。

返回值

MsiEnumClientsEx 函数返回以下值之一。

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

注解

注意

msi.h 标头将 MsiEnumClientsEx 定义为别名，该别名根据 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