msi.h (msi.h) 的 MsiEnumProductsExA 函数

  • 项目

MsiEnumProductsEx 函数枚举当前在指定上下文中播发或安装的产品的一个或所有实例。 此函数取代 MsiEnumProducts。

语法

UINT MsiEnumProductsExA(
  [in, optional]      LPCSTR            szProductCode,
  [in]                LPCSTR            szUserSid,
  [in]                DWORD             dwContext,
  [in]                DWORD             dwIndex,
  [out, optional]     CHAR [39]         szInstalledProductCode,
  [out, optional]     MSIINSTALLCONTEXT *pdwInstalledContext,
  [out, optional]     LPSTR             szSid,
  [in, out, optional] LPDWORD           pcchSid
);

参数

[in, optional] szProductCode

ProductCode 要枚举的产品的 GUID。 仅枚举 szUserSid 和 dwContext 参数指定的上下文范围内的产品的实例。 此参数可以设置为 NULL 以枚举指定上下文中的所有产品。

[in] szUserSid

以 Null 结尾的字符串，指定一个安全标识符 (SID) 来限制枚举的上下文。 特殊的 SID 字符串 s-1-1-0 (Everyone) 指定系统中所有用户的枚举。 s-1-1-0 以外的 SID 值被视为 user-SID，并将枚举限制为当前用户或系统中的任何用户。 此参数可以设置为 NULL ，以将枚举范围限制为当前用户。

SID 类型 含义
NULL
 指定当前登录的用户。
用户 SID
 指定系统中特定用户的枚举。 用户 SID 的示例是“S-1-3-64-2415071341-1358098788-3127455600-2561”。
s-1-1-0
 指定系统中所有用户的枚举。
 
注意 特殊 SID 字符串 s-1-5-18 (系统) 不能用于枚举按计算机安装的产品或修补程序。 如果 dwContext 设置为仅MSIINSTALLCONTEXT_MACHINE， 则 szUserSid 必须为 NULL。
 

[in] dwContext

将枚举限制为上下文。 此参数可以是下表中显示的值的任意一个或组合。

上下文 含义
MSIINSTALLCONTEXT_USERMANAGED
 枚举扩展为 szUserSid 指定的用户的所有每用户托管安装。 无效的 SID 不返回任何项。
MSIINSTALLCONTEXT_USERUNMANAGED
 枚举扩展到 szUserSid 指定的用户的所有每用户非托管安装。 无效的 SID 不返回任何项。
MSIINSTALLCONTEXT_MACHINE
 枚举已扩展到所有每台计算机安装。 当 dwInstallContext 设置为仅MSIINSTALLCONTEXT_MACHINE时， szUserSID 参数必须为 NULL。

[in] dwIndex

指定要检索的产品的索引。 首次调用 MsiEnumProductsEx 函数时，此参数必须为零，然后为后续调用递增。 仅当上一次调用返回ERROR_SUCCESS时，索引才应递增。 由于产品没有进行排序，因此任何新产品的索引是任意的。 这意味着该函数可以按任意顺序返回产品。

[out, optional] szInstalledProductCode

TCHAR 的以 Null 结尾的字符串，为枚举的产品实例提供 ProductCode GUID。 此参数可以为 NULL。

[out, optional] pdwInstalledContext

返回要枚举的产品实例的上下文。 输出值可以是MSIINSTALLCONTEXT_USERMANAGED、MSIINSTALLCONTEXT_USERUNMANAGED或MSIINSTALLCONTEXT_MACHINE。 此参数可以为 NULL。

[out, optional] szSid

接收此产品实例所在的帐户的字符串 SID 的输出缓冲区。 此缓冲区返回安装在每台计算机上下文中的实例的空字符串。

此缓冲区应足够大，以包含 SID。 如果缓冲区太小，该函数将返回ERROR_MORE_DATA并将 *pcchSid 设置为 SID 中的 TCHAR 数，不包括终止 NULL 字符。

如果 szSid 设置为 NULL 且 pcchSid 设置为有效指针，则该函数将返回ERROR_SUCCESS并将 *pcchSid 设置为值中的 TCHAR 数，不包括终止 NULL。 然后，可以再次调用 函数来检索值， szSid 缓冲区足够大，足以包含 *pcchSid + 1 个字符。

如果 szSid 和 pcchSid 都设置为 NULL，则如果值存在，则函数返回ERROR_SUCCESS，而不检索值。

[in, out, optional] pcchSid

调用 函数时，此参数应是指向变量的指针，该变量指定 szSid 缓冲区中的 TCHAR 数。 当函数返回时，无论函数是否将值复制到指定的缓冲区中，此参数都设置为所请求值的大小。 大小作为请求值中的 TCHAR 数返回，不包括终止 null 字符。

仅当 szSid 也为 NULL 时，此参数才能设置为 NULL，否则函数将返回ERROR_INVALID_PARAMETER。

返回值

MsiEnumProductsEx 函数返回以下值之一。

返回代码 说明
ERROR_ACCESS_DENIED
 如果范围包括当前用户以外的用户，则需要管理员权限。
ERROR_BAD_CONFIGURATION
 配置数据已损坏。
ERROR_INVALID_PARAMETER
 向该函数传递了无效参数。
ERROR_NO_MORE_ITEMS
 没有更多要枚举的产品。
ERROR_SUCCESS
 枚举产品。
ERROR_MORE_DATA
 szSid 参数太小，无法获取用户 SID。
ERROR_UNKNOWN_PRODUCT
 产品未安装在指定上下文中的计算机上。
ERROR_FUNCTION_FAILED
 意外的内部故障。

注解

若要枚举产品，应用程序必须首先调用 MsiEnumProductsEx 函数，并将 iIndex 参数设置为零。 然后，应用程序必须递增 iProductIndex 参数并调用 MsiEnumProductsEx ，直到它返回 ERROR_NO_MORE_ITEMS 并且没有更多要枚举的产品。

对 MsiEnumProductsEx 进行多次调用以枚举所有产品时，每个调用都必须从同一线程进行。

用户必须具有管理员权限才能枚举所有用户帐户或当前用户帐户以外的用户帐户的产品。 枚举跳过仅播发 (的产品，例如，在按用户非托管上下文中) 枚举所有用户或当前用户以外的用户时未安装的产品。

使用 MsiGetProductInfoEx 获取 MsiEnumProductsEx 枚举的每个产品实例的状态或其他信息。

注意

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

要求

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

另请参阅

MsiEnumProducts

在 Windows Installer 2.0 及更低版本中不受支持

ProductCode

移除修补程序