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 类型 | 含义 |
---|---|
|
指定当前登录的用户。 |
|
指定系统中特定用户的枚举。 用户 SID 的示例是“S-1-3-64-2415071341-1358098788-3127455600-2561”。 |
|
指定系统中所有用户的枚举。 |
[in] dwContext
将枚举限制为上下文。 此参数可以是下表中显示的值的任意一个或组合。
[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 函数返回以下值之一。
返回代码 | 说明 |
---|---|
|
如果范围包括当前用户以外的用户,则需要管理员权限。 |
|
配置数据已损坏。 |
|
向该函数传递了无效参数。 |
|
没有更多要枚举的产品。 |
|
枚举产品。 |
|
szSid 参数太小,无法获取用户 SID。 |
|
产品未安装在指定上下文中的计算机上。 |
|
意外的内部故障。 |
注解
若要枚举产品,应用程序必须首先调用 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 |