msi.h) (MsiEnumPatchesExA 函数

  • 项目

MsiEnumPatchesEx 函数枚举特定上下文中或跨所有上下文的所有修补程序。 枚举已应用于产品的修补程序。 还会枚举已注册但尚未应用于产品的修补程序。

语法

UINT MsiEnumPatchesExA(
  [in, optional]      LPCSTR            szProductCode,
  [in, optional]      LPCSTR            szUserSid,
  [in]                DWORD             dwContext,
  [in]                DWORD             dwFilter,
  [in]                DWORD             dwIndex,
  [out, optional]     CHAR [39]         szPatchCode,
  [out, optional]     CHAR [39]         szTargetProductCode,
  [out, optional]     MSIINSTALLCONTEXT *pdwTargetProductContext,
  [out, optional]     LPSTR             szTargetUserSid,
  [in, out, optional] LPDWORD           pcchTargetUserSid
);

参数

[in, optional] szProductCode

以 null 结尾的字符串，指定枚举其修补程序的产品的 ProductCode GUID。 如果不是 NULL，则修补程序枚举仅限于 szUserSid 和 dwContext 指定的用户和上下文下的此产品的实例。 如果 为 NULL，则枚举指定上下文下所有产品的修补程序。

[in, optional] szUserSid

以 null 结尾的字符串，指定限制枚举上下文 (SID) 的安全标识符。 特殊 SID 字符串“S-1-1-0” (Everyone) 指定系统中所有用户的枚举。 “S-1-1-0”以外的 SID 值被视为用户 SID，并将枚举限制为该用户。 为当前用户以外的用户枚举时，不会枚举使用低于 Windows Installer 版本 3.0 的版本在每用户非托管上下文中应用的任何修补程序。 此参数可以设置为 NULL 以指定当前用户。

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

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

上下文 含义
MSIINSTALLCONTEXT_USERMANAGED
 为 szUserSid 指定的用户扩展到按用户管理的安装的所有枚举。 无效的 SID 不返回任何项。
MSIINSTALLCONTEXT_USERUNMANAGED
 在此上下文中，仅为不是当前用户的用户枚举随 Windows Installer 版本 3.0 安装的修补程序。 对于当前用户， 函数枚举所有已安装的修补程序和新修补程序。 szUserSid 的 SID 无效不返回任何项。
MSIINSTALLCONTEXT_MACHINE
 扩展到所有每台计算机安装的枚举。 当 dwContext 设置为仅 MSIINSTALLCONTEXT_MACHINE 时， szUserSid 参数必须为 NULL。

[in] dwFilter

枚举的筛选器。 此参数可以是下列参数的一个或组合。

筛选器 含义
MSIPATCHSTATE_APPLIED
1
 枚举包括已应用的修补程序。 枚举不包括被取代或已过时的修补程序。
MSIPATCHSTATE_SUPERSEDED
2
 枚举包括标记为被取代的修补程序。
MSIPATCHSTATE_OBSOLETED
4
 枚举包括标记为已过时的修补程序。
MSIPATCHSTATE_REGISTERED
8
 枚举包括已注册但尚未应用的修补程序。 MsiSourceListAddSourceEx 函数可以注册新修补程序。
注意 不会枚举为当前用户以外的用户注册并在每用户非托管上下文中应用的修补程序。
 
MSIPATCHSTATE_ALL
15
 枚举包括所有已应用、已过时、被取代和已注册的修补程序。

[in] dwIndex

要检索的修补程序的索引。 对于第一次调用 MsiEnumPatchesEx 函数，此参数必须为零，然后为后续调用递增。 仅当上一次调用返回ERROR_SUCCESS时，才应递增 dwIndex 参数。

[out, optional] szPatchCode

一个输出缓冲区，用于包含要枚举的修补程序的 GUID。 缓冲区应足够大，可以保存 GUID。 此参数可以为 NULL。

[out, optional] szTargetProductCode

一个输出缓冲区，用于包含接收此修补程序的产品的 ProductCode GUID。 缓冲区应足够大，可以保存 GUID。 此参数可以为 NULL。

[out, optional] pdwTargetProductContext

返回要枚举的修补程序的上下文。 输出值可以是 MSIINSTALLCONTEXT_USERMANAGED、 MSIINSTALLCONTEXT_USERUNMANAGED或 MSIINSTALLCONTEXT_MACHINE。 此参数可以为 NULL。

[out, optional] szTargetUserSid

接收此修补程序实例所在的帐户的字符串 SID 的输出缓冲区。 此缓冲区返回每台计算机上下文的空字符串。

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

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

如果 szTargetUserSid 和 pcchTargetUserSid 都设置为 NULL，则该函数返回 ERROR_SUCCESS 值（如果存在），而不检索该值。

[in, out, optional] pcchTargetUserSid

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

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

返回值

MsiEnumPatchesEx 函数返回以下值之一。

返回代码 说明
ERROR_ACCESS_DENIED
 函数尝试访问权限不足的资源失败。
ERROR_BAD_CONFIGURATION
 配置数据已损坏。
ERROR_INVALID_PARAMETER
 将无效参数传递给函数。
ERROR_NO_MORE_ITEMS
 没有更多要枚举的修补程序。
ERROR_SUCCESS
 已成功枚举修补程序。
ERROR_UNKNOWN_PRODUCT
 szProduct 指定的产品未安装在指定上下文中的计算机上。
ERROR_MORE_DATA
 当 pcchTargetUserSid 指向的缓冲区大小小于复制 SID 所需的大小时，将返回此值。 在这种情况下，用户可以修复缓冲区，并再次调用 MsiEnumPatchesEx 以获取相同的索引值。

注解

非管理员只能在其可见性范围内枚举修补程序。 管理员可以枚举其他用户上下文的修补程序。

注意

msi.h 标头将 MsiEnumPatchesEx 定义为别名，该别名根据 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 Installer 版本所需的最低 Windows Service Pack 的信息，请参阅 Windows Installer 运行时要求。
目标平台 Windows
标头 msi.h
Library Msi.lib
DLL Msi.dll

另请参阅

安装上下文

MsiSourceListAddSourceEx

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

ProductCode