msiprocessMessage 函数 (msiquery.h)

  • 项目

MsiProcessMessage 函数将错误记录发送到安装程序进行处理。

语法

int MsiProcessMessage(
  [in] MSIHANDLE      hInstall,
  [in] INSTALLMESSAGE eMessageType,
  [in] MSIHANDLE      hRecord
);

参数

[in] hInstall

提供给 DLL 自定义操作或通过 MsiOpenPackage、MsiOpenPackageEx 或 MsiOpenProduct 获取的安装的句柄。

[in] eMessageType

eMessage 参数必须是指定以下消息类型之一的值。 若要显示带有按钮或图标的消息框，请使用 OR 运算符向 MessageBox 和 MessageBoxEx 函数使用的标准消息框样式添加INSTALLMESSAGE_ERROR、INSTALLMESSAGE_WARNING或INSTALLMESSAGE_USER。 有关详细信息，请参阅下面的“备注”。

值 含义
INSTALLMESSAGE_FATALEXIT
 过早终止，可能是致命的内存不足问题所致。
INSTALLMESSAGE_ERROR
 格式化的错误消息，
 
[1] 是 错误表中的消息编号。
INSTALLMESSAGE_WARNING
 格式化的警告消息，
 
[1] 是错误表中的消息编号。
INSTALLMESSAGE_USER
 用户请求消息，
 
[1] 是错误表中的消息编号。
INSTALLMESSAGE_INFO
 日志信息性消息，
 
不显示。
INSTALLMESSAGE_FILESINUSE
 当前正在使用的文件列表，在被替换之前必须关闭。
INSTALLMESSAGE_RESOLVESOURCE
 请求确定有效的源位置。
INSTALLMESSAGE_RMFILESINUSE
 当前正在使用的文件列表，在被替换之前必须关闭。 从 Windows Installer 版本 4.0 开始提供。 有关此消息的详细信息，请参阅将重新启动管理器与外部 UI 配合使用。
INSTALLMESSAGE_OUTOFDISKSPACE
 磁盘空间不足的消息。
INSTALLMESSAGE_ACTIONSTART
 进度：开始操作，
 
[1] 操作名称，
 
[2] description，
 
[3] ACTIONDATA 消息的模板。
INSTALLMESSAGE_ACTIONDATA
 操作数据。 记录对应于 ACTIONSTART 消息模板的字段。
INSTALLMESSAGE_PROGRESS
 进度栏信息。 请参阅下面的记录字段的说明。
INSTALLMESSAGE_COMMONDATA
 若要启用“取消”按钮，请将 [1] 设置为 2，将 [2] 设置为 1。

若要禁用“取消”按钮，请将 [1] 设置为 2，将 [2] 设置为 0

[in] hRecord

包含消息格式和数据的记录的句柄。

返回值

此函数返回 int。

注解

MsiProcessMessage 函数执行任何已启用的日志记录操作并延迟执行。 你可以有选择地为各种消息类型启用日志记录。

对于INSTALLMESSAGE_FATALEXIT、INSTALLMESSAGE_ERROR、INSTALLMESSAGE_WARNING和INSTALLMESSAGE_USER消息，如果未设置字段 0，则必须将字段 1 设置为与 Error 表中的错误消息对应的错误代码。 然后，使用错误表中的模板设置消息的格式，然后再将其传递给用户界面处理程序进行显示。

进度栏消息的记录字段

下面介绍 eMessageType 设置为 INSTALLMESSAGE_PROGRESS 时的记录字段。 字段 1 指定进度消息的类型。 其他字段的含义取决于此字段中的值。 可以设置为字段 1 的可能值如下所示。
字段 1 值 字段 1 说明
0 重置进度栏并设置进度栏中的预期刻度线总数。
1 提供与当前操作要发送的进度消息相关的信息。
2 递增进度栏。
3 启用某个操作（如 CustomAction），以将刻度线添加到进度栏的预期总进度数。
 

字段 2 的含义取决于字段 1 中的值，如下所示。

字段 1 值 字段 2 说明
0 进度栏中的预期刻度线总数。
1 进度栏针对当前操作发送的每个 ActionData 消息移动的计时周期数。 如果字段 3 为 0，则忽略此字段。
2 进度栏已移动的刻度线数。
3 要添加到预期总进度的刻度线数。
 

字段 3 的含义取决于字段 1 中的值，如下所示。

字段 1 值 字段 3 值 字段 3 说明
0 0 向前进度栏（从左到右）
  1 向后进度条（从右到左）
1 0 当前操作将发送显式 ProgressReport 消息。
  1 每次当前操作发送 ActionData 消息时，按字段 2 中指定的时钟周期数递增进度栏。
2 未使用  
3 未使用  
 

字段 4 的含义取决于字段 1 中的值，如下所示。

字段 1 值 字段 4 值 字段 4 说明
0 0 正在执行。 在这种情况下，UI 可以计算并显示剩余时间。
  1 创建执行脚本。 在这种情况下，UI 可能会显示一条消息，用于指示安装程序正在完成准备安装的操作，请稍候。
1 未使用  
2 未使用  
3 未使用  
 

有关详细信息和代码示例，请参阅 将自定义操作添加到 ProgressBar。

消息框的显示

若要显示带有按钮或图标的消息框，请使用 OR 运算符添加INSTALLMESSAGE_ERROR、INSTALLMESSAGE_WARNING或INSTALLMESSAGE_USER MessageBox 和 MessageBoxEx 使用的消息框选项。 可用的按钮选项包括MB_OK、MB_OKCANCEL、MB_ABORTRETRYIGNORE、MB_YESNOCANCEL、MB_YESNO和MB_RETRYCANCEL。 可用的默认按钮选项包括MB_DEFBUTTON1、MB_DEFBUTTON2和MB_DEFBUTTON3。 可用的图标选项包括MB_ICONERROR、MB_ICONQUESTION、MB_ICONWARNING和MB_ICONINFORMATION。 如果未指定图标选项，Windows Installer 将根据消息类型选择默认图标样式。

例如，以下对 MsiProcessMessage 的 调用会发送带有MB_ICONWARNING图标和MB_ABORTRETRYCANCEL按钮的INSTALLMESSAGE_ERROR消息。

PMSIHANDLE hInstall;
PMSIHANDLE hRec;
MsiProcessMessage(hInstall, 
                  INSTALLMESSAGE(INSTALLMESSAGE_ERROR|MB_ABORTRETRYIGNORE|MB_ICONWARNING),
                  hRec);

如果自定义操作调用 MsiProcessMessage，则自定义操作应该能够处理用户的取消，并且应返回ERROR_INSTALL_USEREXIT。

有关使用 MsiProcessMessage 发送消息的详细信息，请参阅 使用 MsiProcessMessage 向 Windows 安装程序发送消息。

要求

要求 值
最低受支持的客户端 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
目标平台 Windows
标头 msiquery.h
Library Msi.lib
DLL Msi.dll

另请参阅

安装程序操作函数

使用 MsiProcessMessage 向 Windows Installer 发送消息