使用 MsiProcessMessage 向 Windows Installer 发送消息

  • 项目

使用 MsiProcessMessage 发送的消息与调用 MsiSetExternalUI 时 INSTALLUI_HANDLER 回调函数接收的消息相同。 否则，Windows Installer 会处理消息。 有关详细信息，请参阅分析 Windows Installer 消息。

例如，若要发送包含 MB_ICONWARNING 图标和 MB_ABORTRETRYCANCEL 按钮的 INSTALLMESSAGE_ERROR 消息：

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

其中，hInstall 是安装的句柄，提供给自定义操作或来自 MsiOpenProduct 或 MsiOpenPackage 的 hProduct 句柄，hRec 是包含要设置格式的错误信息的记录。 有关如何执行格式设置的信息，请参阅 MsiFormatRecord。

默认情况下，如果发送未指定按钮类型或图标类型的 INSTALLMESSAGE_ERROR 或 INSTALLMESSAGE_FATALEXIT 消息，则使用 MB_OK、无图标和 MB_DEFBUTTON1。

Windows Installer 在显示包含 MB_ABORTRETRYIGNORE 按钮规范的 MessageBox 时，不会使用“中止”字符串标记“中止”按钮，而是使用“取消”字符串进行标记。 所有错误消息都会避免使用“中止”一词，而改用“取消”。

MsiProcessMessage 函数的 hRecord 参数取决于发送给 MsiProcessMessage 的消息类型。 下表详细列出了与消息类型相关的记录要求：

INSTALLMESSAGE_FATALEXIT

 

INSTALLMESSAGE_INFO

 

INSTALLMESSAGE_OUTOFDISKSPACE

字段 说明
0 用于设置结果字符串格式的模板。 有关详细信息，请参阅 MsiFormatRecord。 引用的记录字段使用 [1] 表示字段 1，使用 [2] 表示字段 2，以此类推。
1 到 n 所有后续字段都与字段 0 中的模板引用的字段直接相关。

 

如果字段 0 为 Null，则 UI 处理程序接收的字符串的格式为：1: [字段 1 的数据] 2: [字段 2 的数据]，换句话说，对于记录的每个字段，其字符串包含字段编号，后跟存储在字段中的数据。

当 MsiEnableLog、“/l”命令行选项或日志记录策略指定“I”或 INSTALLLOGMODE_INFO 时，系统将记录来自 MsiProcessMessage 的信息消息。

INSTALLMESSAGE_ERROR

 

INSTALLMESSAGE_WARNING

 

INSTALLMESSAGE_USER

使用 Error 表中的消息。

字段 说明
0 必须为 Null。
1 Error 表中的消息编号。
2 到 n 与 Error 表中的指定消息相关。

 

例如，

字段 类型 数据
0 string Null
1 int 1304
2 string Myfile.txt

 

从 UI 处理程序接收的结果消息为：

错误 1304。 写入 Myfile.txt 文件时出错。 请验证是否有权访问该目录。

如果字段 0 不为 Null，则系统会覆盖错误表中的消息， 改由字段 0 的模板来确定消息格式。

消息中还可以指定按钮，包括默认按钮，以及与上述消息一起使用的图标。 INSTALLUI_HANDLER 中列出了按钮和图标类型。

INSTALLMESSAGE_COMMONDATA

发送此消息可启用或禁用进度对话框中的“取消”按钮。

字段 说明
0 未使用。
1 2 代表“取消”按钮。
2 值为 1 表示“取消”按钮应可见。 值为 0 表示“取消”按钮应不可见。

 

例如，若要禁用或隐藏“取消”按钮，记录将如下所示。

字段 类型 数据
0 string Null
1 int 2
2 int 0

 

INSTALLMESSAGE_ACTIONSTART

 

INSTALLMESSAGE_ACTIONDATA

INSTALLMESSAGE_ACTIONSTART 记录可确定 ActionData 记录的格式。

字段 说明
0 Null
1 操作名称， 此字段中的名称必须为非 Null。
2 操作说明。
3 操作模板， 用于根据此模板设置消息格式的 ActionData。

 

请勿在操作模板消息中引用字段 0。

INSTALLMESSAGE_ACTIONDATA 记录的格式如下所示。

字段 说明
0 Null
1 到 n 依赖于 ActionText 表中指定的相应 INSTALLMESSAGE_ACTIONSTART 消息或模板的字段 3。

 

例如 INSTALLMESSAGE_ACTIONSTART 记录。

字段 类型 数据
0 string Null
1 字符串 MyAction
2 string 这是对“MyAction”的说明
3 string MyAction 模板：字段 1 数据为 [1]。 字段 2 数据为 [2]。

 

INSTALLMESSAGE_ACTIONSTART 的模板（字段 3）引用字段 1 和 2，INSTALLMESSAGE_ACTIONDATA 记录应具有 2 个包含保证数据的字段。 这些字段可以是字符串类型，也可以是整数类型。

INSTALLMESSAGE_ACTIONDATA 记录。

字段 类型 数据
0 string Null
1 int 2
2 string MyAction 的 ActionData

 

INSTALLMESSAGE_FILESINUSE

FILESINUSE 是长度可变的记录。

字段 说明
0 此字段可以为 Null。 对于使用基本 UI 的安装，此字段可以指定显示在 FilesInUse 对话框的 ListBox 控件中的静态文本。 对于使用完整 UI 的安装，此字段不起作用，因为文本在创作自定义 FilesInUse 对话框时指定。
1 正在使用的文件的名称。
2 此字段标识正在使用的文件所在的进程。Windows Installer 版本 4.0：进程的进程 ID (PID) 或进程的窗口标题。
Windows Installer 3.1 及更低版本：此字段必须是进程的进程 ID (PID)。

 

例如，为发送 FilesInUse 消息以显示两个正在使用的文件 red.exe 和 blue.exe，记录包含四个字段和 0 字段。 记录的格式如下表所示。 此示例需要使用 Windows Installer 4.0 版本。

Windows Installer 3.1 及更低版本：下例中的字段 2 和 4 必须包含正在使用的 red.exe 和 blue.exe 所在的进程的 PID。

字段 说明
0 Null
1 Red.exe
2 Red 窗口标题
3 Blue.exe
4 Blue 窗口标题

 

注意

在 Windows Installer 4.0 版本上，如果从服务传递的 PID 没有窗口标题（例如系统托盘应用程序），则不会显示该文件，且详细日志会包含以下消息。

 

File In Use: -<FileName>- Window could not be found. Process ID: <PID>
No window with title could be found for FilesInUse

INSTALLMESSAGE_RESOLVESOURCE

INSTALLMESSAGE_RESOLVESOURCE 记录包含七个字段。 为使 INSTALLMESSAGE_RESOLVESOURCE 正常工作，外部 UI 处理程序可能不会处理 INSTALLMESSAGE_RESOLVESOURCE 消息。 Windows Installer 必须处理 INSTALLMESSAGE_RESOLVESOURCE 消息。 也就是说，外部 UI 处理程序筛选 INSTALLMESSAGE_RESOLVESOURCE 消息时会返回 0，以指示“未执行任何操作”。 最佳做法是避免发送 RESOLVESOURCE 消息。

字段 说明
0 Null
1 null
2 包名称。
3 产品代码。
4 相对路径（如果已知）可以为 Null。
5 0
6 是否验证包代码。 值为“1”表示应验证包代码。 值为“0”表示不应验证包代码。
7 媒体表中的必需磁盘。 值为“0”表示任何磁盘均可。