InstallShield.docx

InstallShield.docx

《InstallShield.docx》由会员分享，可在线阅读，更多相关《InstallShield.docx（30页珍藏版）》请在冰点文库上搜索。

InstallShield

InstallShield

内

部

库

函

数

全

集

︵

中

文

版

︶

1、库函数综述

InstallShield包含300多个内部库函数，用户可在安装脚本中调用它们来创建程序组，操作文件夹，处理目录，监督安装状态，创建对话框，操作文件及其它更多工作。

因为InstallShield脚本编译器已经识别这些库函数名，所以用户在使用它们之前无须说明。

为了成功调用一个内部库函数，用户必须知道库函数名称及使用格式。

InstallShield库函数参阅附录D库函数索引。

在接下去的几节中我们将对其中主要的一些库函数作详细介绍。

在这里先简单向用户描述一下库函数的构成。

如：

AskYesNo是一个库函数，它在对话框中显示一个询问，然后等待最终用户通过点击按扭来响应，Yes或No。

AskYesNo格式如下：

AskYesNo（szQuestion,nDefault）。

这个格式显示了正确的函数名，括号中显示了函数的参数列表。

在函数的详细说明帮助中，每个参数用匈牙利标记法表示，指出每个参数位置上可被接受的数值类型。

AskYesNo要求两个参数：

第一个是字符类型，第二个是数值型。

与C语言一样，InstallShield区分大小写，因此用户要严格注意库函数名称中大写字母。

在用户的脚本中使用任何库函数，传递的参数数目一定要正确，并且要确保传递的每个参数值符合该位置规定的类型。

如果用户传递了错误的参数数目或者在任何一个或几个参数位置传递了不相符的数值类型，脚本都不能被编译。

注意:

．作为参数传递的字符串必须包括在单引号或者双引号内。

如：

“Pleasewaitwhilefilesaretransferred”，或‘Thisisastring’或“c:

\\Myfolder\\myfile.txt”

．InstallShield不允许将一个赋值语句作为参数传递。

另外，用户在一个函数变量中不能使用&&或||运算符。

．由一个调用传递给一个函数的可变长字符串变量在被调用函数中不能自变长。

如果函数试图赋一个值，该值的长度超过参数的现有长度，则会发生401运行错误。

为避免这个错误，在调用将字符串传递给一个函数时就要为字符串指定一个特定长度。

2、用户界面函数

用户界面函数允许用户自定义特定的错误信息及错误框标题。

然而，一些在安装开发中遇到的内部错误信息是不能由用户界面函数来修改的。

这部分主要对用户界面函数的语法、描述、参数等作详细说明。

2、1Disable函数

语法：

Disable（nConstant）

说明：

Disable函数使由参数nConstant指定的用户界面对象或安装特性无效。

参数：

nConstant

指定用户界面对象或可操作特性使其无效，在这个参数位置传递下列预定义常量之一：

BACKBUTTON：

使在一些内部对话框中显示的Back按钮无效（即使其变灰显示），Back按钮缺省置为有效。

BACKGROUND：

使安装主背景窗口无效且隐藏。

注意：

当安装处于全屏幕方式时该参数不起作用。

BILLBOARD：

在安装过程中取消布告板的显示。

DIALOGCACHE：

使对话缓冲机制无效。

有关对话缓冲的详细说明，请参阅Enable。

HOURGLASS：

使光标由一个“忙”光标（缺省为沙漏光标）改变为标准光标（缺省为一个指针）。

INDVFILESTATUS：

使路径及文件名在文件传输时不显示在进度指示器（状态条）中。

LOGGING：

不记录卸载信息，使信息不记录在卸载日志文件中。

注意：

记录功能由函数DeinstallStart自动置为有效。

在调用DeinstallStart之前置记录卸载信息无效将不起任何作用，因为当DeinstallStart被调用时，记录功能将被自动激活，用户必须就在不应被记录的卸载操作执行之前手控禁止记录。

NEXTBUTTON：

使一些内部对话框的Next按钮无效（使其变灰显示）。

Next按钮缺省置为有效。

SELFREGISTERBATCH：

使注册自注册文件的批处理方法无效。

详细说明请参阅Enable。

SATAUS：

使标准进展指示器（状态条）无效且隐藏。

STATUSDLG：

使对话框形式的进展指示器（状态条）无效且隐藏。

STATUSEX：

禁止以显示安装状态对话框来取代进度指示器（状态条）。

STATUSOLD：

使原风格的进度指示器（状态条）无效且隐藏。

返回值：

 0：

说明函数成功禁止了由参数nConstant指定的用户界面对象或安装特性。

<0：

说明函数未能禁止由参数nConstant指定的用户界面对象或安装特性。

注解：

·如果用户的脚本中调用Disable函数来禁用Next或Back按钮，那么在函数被调用后的所有对话框中该按钮均被禁用，为激活Next或Back按钮，用户需带相应的常量来调用Enable。

·DIALOGCACHE在没有Next或Back按钮的对话框中不起作用。

2、2 Enable函数

语法：

Enable（nConstant）;

说明：

Enable函数激活由参数nConstant指定的用户界面对象或安装特性。

参数：

nConstant

指定你要激活的用户界面对象或操作特性。

在该参数位置传递下列预定义常量之一：

BACKBUTTON：

激活显示在一些内部对话框中的Back按扭。

缺省时Back按扭是被激活的，但可以通过调用Disable函数来禁用它。

BACKGROUND：

当安装是在窗口方式时，显示安装主背景窗口。

当安装是缺省的全屏幕方式时，该常量没有作用。

为激活窗口方式，你必须以常量DEFWINDOWMODE或FULLWINDOWMODE来调用Enable。

DEFWINDOWMODE：

配置主背景窗口为一个有标题栏的标准窗口。

如果背景窗口被激活，它的外观将会立即改变。

如果背景窗口被禁用，屏幕不会被修改直到带常量BACKGROUND调用Enable时。

DIALOGCACHE：

激活对话框缓冲机制，它可以消除在显示对话框之间出现的屏幕闪烁。

这种屏幕闪烁在运行于窗口方式的安装的标题栏中特别明显。

注意对话框缓冲机制仅工作于有BACK和NEXT按扭的对话框。

缺省时对话框缓冲被禁用。

FULLWINDOWMODE：

设置主背景窗口为一个有标题栏的最大化窗口。

如果背景窗口被激活，它的外观将会立即改变。

如果背景窗口被禁用，屏幕不会被修改直到带常量BACKGROUND来调用Enable时。

HOURGLASS：

使光标改变为“忙”光标，缺省为一个沙漏光标。

INDVFILESTATUS：

当调用ComponentTransferData、CopyFile、或XcopyFile并且进度指示器被激活时，激活显示每个文件的全限定名（在进度指示器的第二行中显示）。

注意，在一个运行基于事件的脚本的安装程序中，ComponentTransferData被自动调用。

LOGGING：

激活存入卸载记录功能。

当存入功能被激活时，InstallShield存入的卸载记录的操作结果将被记录在卸载日志文件中，并将在卸载过程中被反向。

自动调用DeinstallStart激活存入功能；因此，你不需要手动激活存入功能除非你先前用Disable函数禁用了它。

NEXTBUTTON：

激活显示在一些内部对话框中的Next按扭。

Next按扭缺省为激活。

SELFREGISTERBATCH：

激活注册自注册文件的批处理方法。

该方法使用来避免和自注册文件相关联的依赖性问题。

缺省为标准（非批处理）自注册。

   有关批处理方法的更多信息如下：

·在文件组窗格中，高亮显示你的自注册文件的文件组文件夹。

它的属性表在打开在右边。

·双击Self-Registered域，则自注册页打开。

·选择"Yes,allthefilesinthisfilegroupareself-registering"单选钮。

·打开你的安装脚本（在Scripts窗格中找到Setup.rul）。

 在你传输文件前，以SELFREGISTERBATCH选项调用Enable函数。

所有自注册文件放在一个内部队列中，也就是，当它们被安装时它们会被立即注册。

（在一个使用基于事件脚本的安装程序中，OnBegin处理程序被调用前，Enable（SELFREGISTERBATCH）会被自动调用。

）

传输文件后，以SELFREGISTRATIONPROCESS选项调用Do函数。

当你调用Do（SELFREGISTRATIONPROCESS）时，InstallShield注册所有自注册文件。

如果当Do被调用时，系统变量BATCH_INSTALL等于TRUE（表明需要一个重启来完成该安装）,则注册自注册文件被延迟到重启后。

　　在你调用Do（SELFREGISTRATIONPROCESS）后，你可以检查自注册是否成功。

如果因任何原因Do失败了，它会返回-1。

那些自注册失败的文件的名称被保存在系统变量ERRORFILENAME中，由一个分号分隔。

例如，下列代码将所有自注册文件注册在文件媒体库中。

//Enablebatchmethodtoqueueself-registeringfiles.

Enable（SELFREGISTERBATCH）;

//Installfiles.

nResult=ComponentTransferData（MEDIA）;

//Registerthefiles,checkforerrors.

ifDo（SELFREGISTRATIONPROCESS）<0then

szMsg="File（s）failedtoself-register:

\n"+ERRORFILENAME;

MessageBox（szMsg,WARNING）;

endif;

STATUS：

激活显示标准进度指示器（状态栏）。

STATUSDLG：

激活显示对话框风格的进度指示器（状态栏）。

STATUSEX：

激活显示安装状态对话框来取代进度指示器（状态栏）。

STATUSOLD：

激活显示旧风格进度指示器（状态栏），它没有一个Cancel按扭。

返回值：

0：

表明函数成功激活由参数nConstant指定的用户界面对象或安装特性。

<0：

表明函数未能激活由参数nConstant指定的用户界面对象或安装特性。

注解：

·缺省时，安装运行在全屏方式；主背景窗口显示为一个没有标题栏的全屏窗口。

这种方式中，主安装窗口不能被调整大小并且没有一个可见的标题栏。

为激活窗口方式，你必须以常量DEFWINDOWMODE或FULLWINDOWMODE来调用Enable。

·如果你的脚本中调用Disable函数来禁用Next或Back按钮，那么在函数被调用后的所有对话框中该按钮均被禁用，为激活Next或Back按钮，你需带相应的常量来调用Enable。

·DIALOGCACHE在没有Next或Back按钮的对话框中不起作用。

2、3 FindWindow

语法：

FindWindow（szClassName,szWinName）;

说明：

FindWindow函数通过指定一个窗口的窗口类和窗口名为高级开发人员提供一个得到窗口句柄的方法。

如果你知道了一个应用程序的窗口类和窗口名，就可得到它的句柄。

然后你可以通过这个句柄直接发送信息给该窗口。

参数：

szClassName

指定窗口所属类的名字。

若指定为“任意类”，则在该参数处传递一个空字符串。

szWinName

指定窗口标题。

为返回指定类中最顶层窗口的句柄，在该参数处传递一个空字符串（“”）。

返回值：

XXXX：

窗口的句柄。

NULL（0）：

FindWindow根据指定的窗口名和类名不能找到该窗口。

注解：

·要找到一个窗口的类和名字，可运行MicrosoftSpy.exe程序。

2、4 PlaceBitmap

语法：

PlaceBitmap（szName,nID_BITMAP,nDx,nDy,nDrawOp）;

说明：

PlaceBitmap函数在安装窗口中插入一个图象。

图象来源由szName指定，它可以是一个位图文件（.bmp），图元文件（.wmf），或者是动态链接库（.dll）。

InstallShield支持2色、16色、256色和真彩色位图（bitmap）。

2色、16色、256色位图可有透明部分。

   透明位图在显示可与背景窗口组合显示的图象时有用。

在位图中与指定的透明色匹配的像素不会被显示；在该位置的背景像素保持可见。

在安装中，一个有技巧的设计常常用包含有公司名称和徽标的透明位图来作为安装窗口的标题。

   为指定一个透明位图，你必须给参数nDrawOp位置传递一个常量BITMAPICON。

你也必须考虑在一个位图中什么颜色被置为透明。

缺省的透明色是purple（RGB（255,0,255））。

要指定一个不同的透明色，可用下面描述的参数szName来指定。

因为图元文件（metafile）是绘制的，而不是放置的，它们固有为透明。

如果BITMAPICON被指定为一个图元文件，则该参数被忽略。

   通过使用SetDisplayEffect函数可以显示非透明位图的许多特殊显示效果。

该函数也为图元文件提供了有限的显示效果。

窗口中位图的位置可以用两种方法中的一种来指定：

·通过参数nDrawOp来传递位置常数。

·通过参数nDx与nDy来传递距安装窗口边缘的垂直和水平位移。

通常可通过调用PlaceBitmap（将参数nDrawOp设置为REMOVE）来删除任何不再需要的位图文件和图元文件。

建议删除不需要的位图，即使该位图可以被其他位图完全覆盖，因为第一个位图的调色板入口只有在位图被删除后才会被释放。

　　一个真彩色位图显示在一个运行于16色或256色模式的系统上时，只用那些在调色板中有效的颜色；不会给位图分配附加的颜色，即使附加调色板入口是有效的。

若你希望含有24位位图的安装可在16色或256色的系统中运行，需要包含该位图的16色或256色的版本。

然后在选择要显示的位图前带参数COLORS调用GetSystemInfo来确定当前颜色模式。

参数：

szName

指定要被显示图象的位图文件、图元文件的全限定名或动态链接。

InstallShield通过扩展名来识别位图文件和图元文件。

位图文件必须有扩展名.bmp,图元文件必须有扩展名.wmf.动态链接必须有扩展名.dll。

如果一个文件名指定为没有扩展名，InstallShield将假定其扩展名为.dll。

　　为指定一个候选透明色，在文件名后放置一个分号（；），后随一组RGB颜色值（RGB颜色由三个数值指定，由逗号分隔）。

该颜色被用作由szName指定的位图的透明色。

注意它对于已经被显示的位图不起作用，也不会成为随后调用PlaceBitmap而显示的位图的缺省透明色。

下面的参数指定白色为透明色：

SUPPORTDIR^"Bitmap.bmp;255,255,255"

当nDrawOptions设置为REMOVE时，该参数被忽略。

nID_BITMAP

指定驻留在一个.dll中的位图的资源ID。

如果位图的源点是图元文件或位图文件，指定一个在当前显示的图象中没有使用的数值；所有同时显示的图象必须有其唯一的ID号。

当nDrawOptions设置为REMOVE，该参数必须包含显示的图象的ID。

nDx

当nDrawOp设置为LOWER_LEFT,LOWER_RIGHT,UPPER_LEFT,或UPPER_RIGHT时以像素点指定安装窗口边缘和图象边缘之间的水平距离；否则该参数被忽略。

nDy

当nDrawOp设置为LOWER_LEFT,LOWER_RIGHT,UPPER_LEFT,或UPPER_RIGHT时以像素点指定安装窗口边缘和图象边缘之间的垂直距离；否则该参数被忽略。

nDrawOp

指定位图放置的位置，设置放置选项，或者删除先前放置的位图。

给该参数传递下列预定义好的常数：

BITMAPICON：

指出位图有透明部分。

用户可以用按位或运算符（｜）来将该常量和其他常量（除TILED、FULLSCREEN或FULLSCREENSIZE外）组合。

当BITMAPICON和那些常量之一组合时，按位或运算被忽略，而只使用BITMAPICON。

TILED：

位图在主安装窗口平铺。

该常量通常被用来创建一个安装背景。

当该常量被指定时，即使位置选项被忽略，特殊效果已被SetDisplaytEffect激活，位图仍正常显示。

FULLSCREEN：

拖拉图象使其填充整个安装窗口。

拖拉时图象不会被调整大小。

如果一个位图图象比InstallShield主窗口小，它在窗口中被置中，背景由当前背景色填充。

缺省值为深青色（teal）；可以通过使用SetColor函数来改变。

当这个常量被指定时，位置选项被忽略，即使一个特殊效果已经被SetDisplayEffect激活，位图仍正常显示。

FULLSCREENSIZE：

拖拉和伸展图象使其填充满整个安装窗口。

当这个常量被指定时，位置选项被忽略，即使一个特殊效果已经被SetDisplayEffect激活，位图仍正常显示。

CENTERED：

将位图置于InstallShield安装窗口的中央。

LOWER_LEFT：

将位图置于InstallShield安装窗口的左下角。

LOWER_RIGHT：

将位图置于InstallShield安装窗口的右下角。

UPPER_LEFT：

将位图置于InstallShield安装窗口的左上角。

UPPER_RIGHT：

将位图置于InstallShield安装窗口的右上角。

REMOVE：

删除一个先前放置的位图或图元。

任何由SetDisplayEffect激活的特殊效果被忽略。

返回值：

0：

表明函数成功找到和放置图象。

<0：

表明函数未能找到或放置图象。

注解：

·调用SetDisplayEffect来为非平铺、全屏幕、透明位图设置特殊效果；用户也可以用它为图元设置有限的特殊效果。

·InstallShield不支持24位透明位图。

如果用户在一个24位位图中包含了透明色而且指定了BITMAPICON常量，该颜色将被正常显示。

·当你在运行256色模式的系统中放置一个256色的位图时，InstallShield将试图分配位图的调色板到系统调色板。

如果多个256色位图被放置，InstallShield将试图将所有可视位图的调色板合并到系统调色板，优先为最近放置的位图。

这种行为可能导致在其他位图被显示时先前放置的位图改变颜色。

·在一个运行在有256色抖动背景的256色模式的系统中，含有许多颜色的位图可能导致一些给背景使用的调色板入口被重新分配；这可引起在背景中出现一种梯度效果。

如果安装中包含了使用多种颜色的位图，则当它们运行在256色系统中时应不要使用256色抖动背景。

·系统调色板仅存在于运行在256色模式的系统中。

运行在windows95和其后高彩色或者真彩色模式下的系统及运行在65525（16位）色模式WindowsNT下的系统中都没有系统调色板。

这些系统中不用考虑调色板句柄问题。

颜色使用RGB值来直接显示。

·因为图元文件是被着色的，它们不包括一个自定义调色板。

当一个图元文件在一个256色系统中显示时，不发生调色板处理；图元文件是用当前调色板中有用的颜色绘制而成。

由此，若要运行在256色系统中，用户在安装程序中不应该使用显示颜色不同于标准16色的图元文件。

2、5 PlaceWindow

语法：

PlaceWindow（nObject,nDx,nDy,nCorner）;

说明：

PlaceWindow函数改变用户界面对象的位置，包括布告牌。

用nDx和nDy指定对象的边与屏幕边缘的距离。

参数：

nObject

指定要被改变位置的对象。

在该参数位置传递下列预定义的常量之一：

BACKGROUND：

移动背景窗口。

BILLBOARD：

设置在文件传输过程中使用的布告牌的位置。

MMEDIA_AVI：

设置要播放的下一个AVI文件的窗口位置。

缺省时，AVI文件将在InstallShield客户窗口的左边位置窗口中播放，从左起10个像素点，从上起10个像素点。

STATUS：

移动进度指示器。

STATUSDLG：

移动对话框风格的进度指示器。

STATUSEX：

移动安装状态对话框。

STATUSOLD：

移动旧风格的进度指示器。

当你调用PlaceWindow来移动进度指示器或者状态对话框时，确信为你在安装中激活的反馈对象传递了正确常量。

例如，如果你调用了Enable（STATUSOLD）,则你必须传递STATUSOLD给PlaceWindow。

nDx

以像素点指定对象的边与屏幕边缘之间的水平距离。

nDy

以像素点指定对象的边与屏幕边缘之间的垂直距离。

nCorner

指定用nDx和nDy表示的距离是从哪个角度量所得。

在该参数位置传递下列预定义的常量之一：

LOWER_LEFT：

从InstallShield主窗口的左边度量得nDx，从底端度量得nDy。

LOWER_RIGHT：

从InstallShield主窗口的右边度量得nDx，从底端度量得nDy。

UPPER_LEFT：

从InstallShield主窗口的左边度量得nDx，从顶端度量得nDy。

UPPER_RIGHT：

从InstallShield主窗口的右边度量得nDx，从顶端度量得nDy。

返回值：

0：

表明函数成功改变了对象的位置。

<0：

表明函数未能改变对象的位置。

注解：

·使用该函数时要意识到一个安装程序要运行在不同的屏幕分辨率下。

你在放置对象前可能要确定屏幕范围。

距离以像素点度量，是对象边缘与指定的屏幕角落边缘之间的距离。

·用户不能用该函数定位消息框，因为消息框是由本机的Windows/PMAPI创建。

一个消息框的位置由Windows/PM确定，而不是在InstallShield控制之下。

另外，用户不能用该函数定位一个自定义对话框。

2、6 PlayMMedia

语法：

PlayMMedia（nType,szFileName,nOperation,nReserved）;

说明：

PlayMMedia函数播放一个声音或AVI文件。

MIDI或WAVE类型的声音文件和AVI（视频）文件既可以以同步方式也可以以异步方式播放。

该函数也可以被用来连续播放一个文件。

为了实现这个目的，一个标志可被按位或，来指示该文件以连续方式被播放。

   由于AVI文件早被压缩而且往往大于1.4MB的软盘，因此,视频显示推荐于光盘安装。

参数：

nType

指定文件类型。

在该参数位置传递下列预定义的常量之一：

MMEDIA_WAVE：

文件是WAVE声音格式。

MMEDIA_MIDI：

文件是MIDI声音格式。

MMEDIA_AVI：

文件是一个AVI文件。

szFileName

指定要播放的声音/AVI文件的全限定名。

nOperation

指定播放方式。

在该参数位置传递下列预定义的常量：

MMEDIA_PLAYSYNCH：

同步播放。

MMEDIA_PLAYASYNCH：

异步播放。

该常量可以用或运算符（|）与MMEDIA_PLAYCONTINUOUS组合使用。

MMEDIA_PLAYCONTINUOUS：

连续循环播放。

当以同步方式播放一个声音/AVI文件时不能使用该值。

它只使用于以异步方式播放的文件。

用或运算符（|）将它与MMEDIA_PLAYASYNCH组合使用。

MMEDIA_STOP：

停止播放。

nReserved