InstallShield内部库函数之22 杂项函数

InstallShield内部库函数之22  杂项函数
    下列函数提供不同的功能，如低层硬件接口，组件创建和操作和用户输出。
Do
执行当前定义的EXIT 和 HELP处理程序。
DoInstall
运行另一个InstallShield安装程序。
Handler
指定一个对退出和帮助事件响应时转移到的标号。
ISCompareServicePack
比较安装在目标OS上的服务程序包数和指定的服务程序包数。
MessageBeep
产生一个标准警告蜂鸣。
SendMessage
发送一个消息到另一个窗口或应用程序。
Sprintf
返回一个格式化的包含一个或多个字符，数字或字符串值的字符串。
System
退出到DOS，重启Windows或重启计算机。
VarRestore
恢复上一次调用VarSave时保存的系统变量SRCDIR和 TARGETDIR 的值。
VarSave
保存系统变量SRCDIR 和 TARGETDIR的当前值。
22.1  Do
语法：Do (nOperation);
说明：退出和帮助处理程序只支持向后兼容。在一个基于事件的脚本中，你必须使用OnCanceling 和 OnHelp事件处理程序来代替。
Do函数执行当前定义的EXIT和 HELP处理程序，给你对这些处理程序更大的控制，它们通常仅当用户按下F1键(HELP), F3 键(EXIT), 或 Cancel button (EXIT)时执行。使用Do函数，你可以执行EXIT 或 HELP来响应自定义对话框事件或从内部对话框来的任何用户输入。你也可以在脚本开发多成中使用Do函数来测试你的EXIT和 HELP 处理程序。
　　使用Do函数来注册排队的自注册文件。文件使用针对安装自注册文件的"批处理方法"来排队等候注册。当你调用Do(SELFREGISTRATIONPROCESS)时，InstallShield进行所有排队文件的自注册，即使它们中一个失败。
　　如果Do因任何原因失败，它会返回-1。自注册失败的文件的名称保存InstallShield系统变量ERRORFILENAME中，用分号分隔。
参数：
nOperation
指定要执行的操作类型。在该参数位置传递下列预定义常量之一：
EXIT：启动Exit操作。如果没有定义EXIT处理程序，则显示缺省的Exit对话框。
HELP：启动Help操作。如果没有定义HELP处理程序，函数没有任何动作。
SELFREGISTRATIONPROCESS：注册所有已经排队等候注册的自注册文件。
返回值：
0：Do函数成功启动指定操作。
< 0：Do函数未能启动指定操作。
注解：
·Do函数允许在用户没有按下F1或F3键时当前定义的HELP和EXIT处理程序执行。Do函数也比goto语句（它可以被使用来调用HELP和EXIT处理程序标号）提供更大的通用性。Goto语句不能使用在所有的环境中，但Do函数任何时间都可以被虚拟调用。有关缺省和自定义HELP和EXIT处理程序的更多信息，参阅Handle函数。
22.2  DoInstall
语法：DoInstall (szInsFile, szCmdLine, lWait);
说明：DoInstall函数运行另一个InstallShield安装程序。这个函数被调用时，第二个安装程序立即被执行。参数lWait指定调用脚本在继续执行之前是否要等待运行的安装程序完成。
　　由DoInstall调用的安装必须和运行它的安装有相同的主版本号和次版本号的InstallShield创建。如果试图用DoInstall来运行一个由任何其它InstallShield版本创建的安装程序，则都不可能成功。
　　如果第二个安装程序运行另一个可执行应用程序，第一个安装程序对运行的应用程序不能控制，也没有办法监控运行应用程序的状态。
参数：
szInsFile
指定要运行的已编译脚本文件（.inx）的全限定名（包含一个驱动器指示符和完整路径）。
szCmdLine
指定一个InstallShield命令行。这儿你可以指定任何有效的启动InstallShield命令行，然而，注意，在这个环境（上下文）中不适当的-f 和-l选项，不能被使用。
lWait
指定调用脚本在继续执行之前是否要等待运行的安装程序完成。在该参数位置传递下列预定义常量之一：
NOWAIT：调用安装程序在运行第二个安装程序后立即继续。
WAIT：调用安装程序在继续前要等待被运行的安装程序终止。
返回值：
1：由DoInstall调用（以WAIT为第三个参数）的安装程序成功终止。控制程序继续原安装程序中DoInstall函数下的语句。
2：由DoInstall调用（以NOWAIT为第三个参数）的安装程序成功终止。控制程序继续原安装程序中DoInstall函数下的语句。
-1：由DoInstall调用的安装程序不能被初始化。该错误的通常原因是丢失一个所需的安装文件，任何运行第二个安装程序时发生的一般错误都会产生该返回值。
-2：由DoInstall调用（以WAIT为第三个参数）的安装程序不能找到由szInsFile指定的.inx脚本文件。
-3：由DoInstall调用（以WAIT为第三个参数）的安装程序被用户取消。
任何其它负值：发生一个未确定错误。
注解：
·第二个安装程序总是运行在由系统变量SELECTED_LANGUAGE当前值指定的语言中。即使第二个安装程序的命令行中使用-l参数，也是如此。
·注意被运行的安装程序和运行它的安装程序中只有一个共享文件，就是IKernel.ex_。因此，正常运行时，第二个安装程序所需的所有其它安装文件必须和Setup.inx文件位于相同文件夹中。如果不存在这些文件，安装程序不会被正确运行。
因此，建议你将由媒体向导创建的所有文件拷贝到你从中运行第二个安装程序的文件夹中。如果你从第一个安装
4000
程序的安装支持文件夹（SUPPORTDIR）中运行第二个安装程序，则建议你把这些文件放置在第一个安装程序的安装文件窗格中的适当的语言和操作系统文件夹中，因而安装初始化时，它们会被自动解压缩在第一个安装程序的支持文件夹中。
22.3  Handler
语法：Handler (nObject, Label);
说明：退出和帮助处理程序只支持向后兼容。在一个基于事件的脚本中，你必须使用OnCanceling 和 OnHelp事件处理程序来代替。
    Handler函数创建事件的自定义处理程序，如Help的加速键（F1），Cancel的加速键和Exit的加速键（F3）。如果用户按下F1键，则当前定义的HELP处理程序被执行。如果用户按下F3键，则当前定义的EXIT处理程序被执行。如果你没有用Handler函数定义自定义的HELP和EXIT处理程序，则缺省的处理程序将被执行。缺省的EXIT处理程序显示一个Exit对话框。缺省的HELP处理程序不作任何处理。
    为执行用Handler定义的自定义处理程序，当nObject事件发生时，InstallShield调用参数Label指定的唯一标号。当InstallShield达到处理程序代码中的返回语句（在标号的下一句语句）时，控制程序返回到该语句（如果处理程序标号没有被调用，该语句已经接着执行）。
　　使用Handler，你可以指定EXIT或 HELP的自定义处理程序。你可以在Exit处理程序中显示MessageBox, SprintfBox, 和 AskYesNo对话框；然而，你不能显示Sd对话框。
参数：
nObject
指定转移（陷阱）事件。在该参数位置传递下列预定义常量之一：
EXIT：指定当Cancel按钮或F3加速键被按下时的自定义处理程序。如果你不定义一个处理程序，当Cancel按钮或F3加速键被按下时将显示一个缺省Exit对话框。
HELP：指定按下F1加速键时的自定义处理程序。如果你不定义一个处理程序，按下F1加速键时不作任何处理。
Label
指定当按下指定的按钮或加速键时程序必须跳转到的标号名。不要定义该标号为一个数值型值或一个字符串值。为取消一个当前定义的处理程序和重新安装缺省处理程序，给该参数传递-1。该方法在一些脚本中有用，那些脚本中安装的一个自定义处理程序只提供给特定进程，然后就转到缺省处理程序。
返回值：
0：Handler成功创建处理程序。
< 0：Handler未能创建处理程序。
注解：
·不要定义标号名为一个数值型值或一个字符串值。
·有效的加速键是F1键（Help）和F3(Exit)（它和脚本对话框中的Cancel按钮的效果一样）。
Help(F1)允许你运行Help引擎或提供其它合适的Help。当用户按下F1键，InstalShield调用当前定义的Help处理程序。你可以在Help处理程序中提供任何类型的Help函数功能。·如果你想要提供上下文有关Help，你必须跟踪你脚本中的上下文。
例如，你可以有一个包含当前上下文字符串的字符串值。然后你可以在Help处理程序的一个switch-case语句中使用该字符串值，根据该上下文字符串的值来指定适当的Help事件。你也可以测试你的Help处理例程中的全局变量nSdDialog。nSdDialog被设置为当前执行的Sd对话框的对话框ID（在InstallShield Include文件夹中的Sdrc.h中描述）。（当没有Sd 对话框执行时，nSdDialog不被定义。）因此当一个Sd对话框执行时，你可以让用户访问Sd对话框特定的Help。
·正如Help处理程序，你也可以定义并执行自定义和Sd对话框特定的EXIT处理程序。
·在脚本中，EXIT和HELP处理程序标号和它们的相关代码必须放置在结束程序语句之前。
22.4  ISCompareServicePack
语法：ISCompareServicePack (szServicePack);
说明：ISCompareServicePack函数仅和用InstallShield以前的版本创建的脚本兼容。我们建议你通过检测SYSINFO.WINNT.nServicePack 的值来确定Windows NT Service Pack数。
    ISCompareServicePack函数比较安装在Windows NT系统上的服务程序包数和由szServicePack指定的服务程序包数。
参数：
szServicePack
指定要和目标计算机上的服务程序包数比较的服务程序包数。该字符串的格式必须是"Service Pack n"，n是服务程序包数。比较区分大小写。
返回值：
LESS_THAN (1)：目标系统上没有安装服务程序包或其数目小于参数szServicePack传递的值。
EQUALS (2)：服务程序包数匹配。
GREATER_THAN (0)：目标系统上的服务程序包数大于参数szServicePack传递的值。
-1 ：ISCompareServicePack未能比较服务程序包数。
注解：
该函数仅工作于WinNT4.0。
22.4  MessageBeep
语法：MessageBeep (nReserved);
说明：MessageBeep函数播放缺省的系统声音。
参数：
nReserved
给该参数传递0。不允许其它值。
返回值：
该函数无返回值。
注解：
·你有可以通过调用PlayMMedia播放一个音频文件来提供音频信号。
22.5  SendMessage
语法：SendMessage (nHwnd, nMsg, nwParam, nlParam);
说明：SendMessage函数发送一个消息到一个或多个窗口。SendMessage直到消息已经被处理才返回到安装脚本的控制程序。SendMessage函数是直接传递Windows API SendMessage。详细信息请咨询Windows编程文档。
参数：
nHwnd
指定标识接收消息的窗口的句柄。
nMsg
指定发送给窗口的消息。
nwParam
指定附加消息的信息。
nlParam
指定附加消息的信息。
返回值：
InstallShield SendMessage函数返回它以相同名调用Windows API返回的值。返回值依赖于由Windows API SendMessage接受的消息。有关Windows API SendMessage的返回消息的详细信息请咨询Windows编程文档。
注解：
·为用参数nMsg发送一个消息或处理返回值，你必须在脚本中定义和Windows.h中定义的常量等值的常量。你不能在你的脚本中使用#include来包含Windows.h。
22.7  Sprintf
语法：Sprintf (svResult, szFormat [,arg] [,...]);
说明：Sprintf函数从可变数据中使用格式说明符和匹配变量来创建一个字符串。Sprintf函数和Microsoft Windows API wsprintf一样工作。
参数：
svResult
从传递到第三个参数和随后参数的变量中创建一个字符串，根据第二个参数szFormat的说明进行格式化并返回该字符串。
szFormat
指定一个字符串，它可以包含文字文本并且必须包含针对每个嵌入到svResult返回的字符串中的变量的相应的格式说明符。
arg
你可以指定多达9个可被包含在消息中的变量。消息中的每个格式说明符都必须有相应的变量；每个变量的类型必须和它各自的格式说明符相匹配。
Sprintf will generate a compiler error or fail at run time under the following conditions:
Sprintf在下列情况下产生一个编译错误或运行时失败：
指定了多于9个格式说明符和变量：编译错误。
变量的数目和格式说明符的数目不匹配。当一个说明符没有一个相应的变量时，结果字符串在该说明符的位置将包含不可预测的字符。当变量多于说明符时，多余的变量将不会被插入到结果字符串中。
一个变量和它相应的格式说明符不匹配。结果字符串将在该说明符的位置将包含不可预测的字符。
返回值：
如果Sprintf函数成功，返回值是保存在变量svResult中的字符串的长度，不包括终结空字符。
22.8  System
语法：System (nOp);
说明：使用System函数来重启Windows或重启系统。System函数不执行一个异常中止的安装（即，它不已经删除安装的文件）。然而，InstallShield删除它放置在系统中的任何临时目录和临时文件来进行安装。
    System函数具有与InstallShield的更早版本的兼容性。使用InstallShield的当前版本时，用来重启Windows 或系统的最好的函数是RebootDialog 和 SdFinishReboot。这两个函数中，SdFinishReboot函数功能性最好。参阅各自的函数说明来看哪个最适合你的需要。
参数：
nOp
指定在终止安装后执行什么。在该参数位置传递下列预定义常量之一：
SYS_BOOTMACHINE：重启系统。
注解：
·该函数调用Microsoft Windows API ExitWindows。由于当今系统中BIOS类型的千变万化，该函数高度依赖于BIOS和系统的交互作用。
·一些系统当该函数被调用时不会重启或可能挂起。许多安装例程（包括系统软件如MS-DOS的安装）在它们重启系统前给用户显示一个警告消息。该警告消息指示发生了什么并指导用户在命令失败时手动重启系统。
22.9  VarRestore
语法：VarRestore (nType);
说明：VarRestore函数给系统变量SRCDIR 和 TARGETDIR重新赋值为先前调用VarSave而保存的值。无论何时你要临时修改SRCDIR 和 TARGETDIR的值（例如在调用XcopyFile前设置源目录和目标目录），你都要调用VarSave。后面再调用VarRestore来把这些变量的值设置为它们原先的值。
参数：
nType
指定常量SRCTARGETDIR来表明你要恢复先前保存的系统变量SRCDIR 和 TARGETDIR的值。
返回值：
0：表明恢复了先前保存的系统变量SRCDIR 和 TARGETDIR的值。
< 0：表明没有可以恢复的保存值。当你没有首先调用VarSave而调用VarRestore时，或你调用VarStore的次数多于你调用VarSave的次数时，发生该错误。
注解：
·每次你调用VarSave时，InstallShield把SRCDIR 和 TARGETDIR的当前值推进一个内部栈中（即一个FILO(Fisrt In Last Out)的存储区域）。这种方法允许你在内存中堆积一系列的SRCDIR 和 TARGETDIR的值。然后你可以调用VarRestore从堆栈中以与存放它们的次序相反的次序来检索这些值。
例如，如果你调用VarSave三次（在这些调用中没有调用VarRestore），则在堆栈中有三组SRCDIR 和 TARGETDIR值。第一次调用VarRestore将恢复第三次调用VarSave时的值。下一次调用VarRestore将恢复第二次调用VarSave时的值。第三次调用VarRestore将恢复第一次调用VarSave时的值。这时堆栈变空。
22.10  VarSave
语法：VarSave (nType);
说明：VarSave函数保存系统变量SRCDIR 和 TARGETDIR的当前值（它们可以被许多其它InstallShield函数使用）。无论何时你要临时修改SRCDIR 和 TARGETDIR的值（例如在调用XcopyFile前设置源目录和目标目录），你都要调用VarSave。后面再调用VarRestore来把这些变量的值设置为它们原先的值。
参数：
nType
指定常量SRCTARGETDIR来表明你要保存系统变量SRCDIR 和 TARGETDIR的当前值。
返回值：
0：表明SRCDIR 和 TARGETDIR的当前值被保存。
< 0：表明因为一个内部错误未能保存这些值。仅当系统缺少可用内存时才发生该错误。
注解：
请参阅VarRestore的注解。