InstallShield内部库函数

InstallShield内部库函数

下载资源:点击

1  库函数综述

InstallShield包含300多个内部库函数,用户可在安装脚本中调用它们来创建程序组,操作文件夹,处理目录,监督安装状态,创建对话框,操作文件及其它更多工作。因为InstallShield脚本编译器已经识别这些库函数名,所以用户在使用它们之前无须说明。

为了成功调用一个内部库函数,用户必须知道库函数名称及使用格式。InstallShield 库函数参阅附录D库函数索引。在接下去的几节中我们将对其中主要的一些库函数作详细介绍。在这里先简单向用户描述一下库函数的构成。

如:AskYesNo是一个库函数,它在对话框中显示一个询问,然后等待最终用户通过点击按扭来响应,Yes或No。AskYesNo格式如下: AskYesNo(szQuestion,nDefault)。这个格式显示了正确的函数名,括号中显示了函数的参数列表。在函数的详细说明帮助中,每个参数用匈牙利标记法表示,指出每个参数位置上可被接受的数值类型。AskYesNo要求两个参数:第一个是字符类型,第二个是数值型。

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

在用户的脚本中使用任何库函数,传递的参数数目一定要正确,并且要确保传递的每个参数值符合该位置规定的类型。如果用户传递了错误的参数数目或者在任何一个或几个参数位置传递了不相符的数值类型,脚本都不能被编译。

注意:

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

如:“Please wait while files are transferred”,或‘This is a string’或“c:\\Myfolder\\myfile.txt”

.InstallShield 不允许将一个赋值语句作为参数传递。另外,用户在一个函数变量中不能使用&&或||运算符。

.由一个调用传递给一个函数的可变长字符串变量在被调用函数中不能自变长。如果函数试图赋一个值,该值的长度超过参数的现有长度,则会发生401运行错误。为避免这个错误,在调用将字符串传递给一个函数时就要为字符串指定一个特定长度。

2  用户界面函数

用户界面函数允许用户自定义特定的错误信息及错误框标题。然而,一些在安装开发中遇到的内部错误信息是不能由用户界面函数来修改的。这部分主要对用户界面函数的语法、描述、参数等作详细说明。

2.1  Disable函数

语法: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:激活对话框缓冲机制,它可以消除在显示对话框之间出现的屏幕闪烁。这种屏幕闪烁在运行于窗口方式的安装的标题栏中特别明显。注意对话框缓冲机制仅工作于有BACKNEXT按扭的对话框。缺省时对话框缓冲被禁用。

FULLWINDOWMODE:设置主背景窗口为一个有标题栏的最大化窗口。如果背景窗口被激活,它的外观将会立即改变。如果背景窗口被禁用,屏幕不会被修改直到带常量BACKGROUND来调用Enable时。

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

INDVFILESTATUS:当调用ComponentTransferData、 CopyFile、 或XcopyFile并且进度指示器被激活时,激活显示每个文件的全限定名(在进度指示器的第二行中显示)。注意,在一个运行基于事件的脚本的安装程序中,ComponentTransferData被自动调用。

LOGGING:激活存入卸载记录功能。当存入功能被激活时,InstallShield存入的卸载记录的操作结果将被记录在卸载日志文件中,并将在卸载过程中被反向。自动调用DeinstallStart激活存入功能;因此,你不需要手动激活存入功能除非你先前用Disable函数禁用了它。

NEXTBUTTON:激活显示在一些内部对话框中的Next按扭。Next 按扭缺省为激活。

SELFREGISTERBATCH:激活注册自注册文件的批处理方法。该方法使用来避免和自注册文件相关联的依赖性问题。缺省为标准(非批处理)自注册。

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

·在文件组窗格中,高亮显示你的自注册文件的文件组文件夹。它的属性表在打开在右边。

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

·选择"Yes, all the files in this file group are self-registering"单选钮。

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

` 在你传输文件前,以SELFREGISTERBATCH选项调用Enable函数。所有自注册文件放在一个内部队列中,也就是,当它们被安装时它们会被立即注册。(在一个使用基于事件脚本的安装程序中,OnBegin处理程序被调用前,Enable(SELFREGISTERBATCH)会被自动调用。)

传输文件后,以SELFREGISTRATIONPROCESS选项调用Do函数。当你调用Do(SELFREGISTRATIONPROCESS)时,InstallShield注册所有自注册文件。如果当Do被调用时,系统变量BATCH_INSTALL等于TRUE(表明需要一个重启来完成该安装),则注册自注册文件被延迟到重启后。

  在你调用Do(SELFREGISTRATIONPROCESS)后,你可以检查自注册是否成功。如果因任何原因Do失败了,它会返回-1。那些自注册失败的文件的名称被保存在系统变量ERRORFILENAME中,由一个分号分隔。

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

// Enable batch method to queue self-registering files.

Enable ( SELFREGISTERBATCH );

// Install files.

nResult = ComponentTransferData( MEDIA );

// Register the files, check for errors.

if Do ( SELFREGISTRATIONPROCESS ) < 0 then

szMsg = "File(s) failed to self-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根据指定的窗口名和类名不能找到该窗口。

注解:

·要找到一个窗口的类和名字,可运行Microsoft Spy.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色模式的系统中。运行在windows 95和其后高彩色或者真彩色模式下的系统及运行在65525(16位)色模式Windows NT下的系统中都没有系统调色板。这些系统中不用考虑调色板句柄问题。颜色使用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/PM API创建。一个消息框的位置由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

给该参数传递0值,不允许其他值。

返回值:

0:表明函数成功播放文件。

< 0:表明函数不能播放文件。

2.7  RGB

语法:RGB (constRed, constGreen, constBlue);

说明:RGB函数创建一个自定义颜色值,该颜色可被SetColor和SetTitle使用。

参数:

constRed

指定一个数值型常数,值域为0..255,指示在自定义色中红色的数量。

constGreen

指定一个数值型常数,值域为0..255,指示在自定义色中绿色的数量。

constBlue

指定一个数值型常数,值域为0..255,指示在自定义色中蓝色的数量。

返回值:

该函数返回一个调用SetColor和SetTitle时可被使用的自定义颜色的数值。

2.8  SetColor 

语法:SetColor (nObject, nColor);

说明:SetColor函数设置主安装窗口的背景色。

参数:

nObject

指定要改变的用户界面对象。在该参数位置传递下列预定义的常量:

BACKGROUND

指示安装窗口的背景。缺省颜色为纯深青色(solid teal):RGB(0,128,128)。

nColor

为背景指定一种颜色。

对于一种过渡背景色,可传递下列常量之一:

BK_BLUE、BK_GREEN、BK_MAGENTA、BK_ORANGE

BK_PINK、BK_RED、BK_YELLOW  

对于一种纯背景色,可传递下列常量之一:

BK_SOLIDBLACK、BK_SOLIDBLUE、BK_SOLIDGREEN、BK_SOLIDMAGENTA

BK_SOLIDORANGE、BK_SOLIDPINK、BK_SOLIDRED、BK_SOLIDWHITE

BK_SOLIDYELLOW

对于一种自定义颜色,可在该参数位置传递RGB函数。

为了在使用自定义颜色绘制背景时得到光滑的效果(过渡),可将该颜色与预定义常量BK_SMOOTH按位或。注意当256色有效时光滑效果将更好。

返回值:

0:表明函数成功设置对象的颜色。

< 0:表明函数未能设置用户界面对象的颜色。

注解:

·当使用一个RGB值时,你可以应用Microsoft Windows的编程指南中描述的相同的方法。

你可以指定RED、GREENBLUE颜色的混合来“混合”颜色。用从0255的数之一来表示使用颜色的数量。在RGB宏中的参数必须使用字面数值。你可以使用一个表示RGB颜色的长整型数来代替RGB语句。

2.9  SetDialogTitle 

语法:SetDialogTitle (nDialogId, szTitle);

说明:SetDialogTitle函数改变显示在一些公用内部对话框标题栏的标题。用参数nDialogId指定对话框。如果你不使用SetDialogTitle,InstallShield显示缺省标题。一旦你为某一特定对话框设置了标题,除非你再次使用SetDialogTitle改变标题,否则InstallShield在每一个该类型对话框的实例中都使用该标题。

参数:

nDialogId

标识标题要被改变的内部对话框。在该参数位置传递下列预定义常量之一:

DLG_ASK_OPTIONS:改变AskOptions对话框标题。

DLG_ASK_PATH:改变AskPath对话框标题。

DLG_ASK_TEXT:改变AskText对话框标题。

DLG_ASK_YESNO:改变AskYesNo对话框标题。

DLG_ENTER_DISK:改变EnterDisk对话框标题。

DLG_MSG_INFORMATION:改变信息风格的消息框的标题。

DLG_MSG_SEVERE:改变严重警告风格的消息框的标题。

DLG_STATUS:改变对话风格进度指示器的标题。在带DLG_STATUS选项调用SetDialogTitle后,为了使标题修改有效,你必须通过调用Enable(STATUSDLG)来重新激活该对话风格进度指示器。

DLG_MSG_WARNING:改变警告风格的消息框的标题。

DLG_USER_CAPTION:当你使用用户定义的消息框风格时改变消息框的标题。

szTitle

指定新标题。

返回值:

0:表明函数成功修改了对话框标题。

< 0:表明函数未能修改对话框标题。

注解:

·你必须为每种你希望修改其标题的对话框分别调用SetDialogTitle。

·InstallShield使用标准Windows消息框函数创建消息框。Windows为这些消息框确定Ok和Cancel按扭文字。InstallShield不能控制在Windows 消息框中使用的按扭文字。

2.10  SetDisplayEffect 

语法:SetDisplayEffect (nEffect);

说明:SetDisplayEffect函数指定用PlaceBitmap函数显示位图文件或图元文件时使用的显示效果。一旦显示效果被设定,所有随后由PlaceBitmap显示的位图文件将一直使用该效果显示,直到另一个对SetDisplayEffect的调用来设定一个新的显示效果。

参数:

nEffect

指定一个显示效果。在该参数位置传递下列预定义的常量之一。注意这些常量具有互斥性;它们相互之间不能使用按位或。而且,当用PlaceBitmap显示一个位图文件时指定了BITMAPICON、 FULLSCREEN、 FULLSCREENSIZE或 TILED时该参数无效:

EFF_FADE:位图或布告牌淡入淡出。

EFF_REVEAL:位图或布告牌逐渐从中央向四周填充。

EFF_HORZREVEAL:位图或布告牌从它的中央逐渐水平滚动出来。

EFF_HORZSTRIPE:位图或布告牌的一部分从外往里水平填充,然后剩余部分从中央部分往外填充。

EFF_VERTSTRIPE:位图或布告牌的一部分从外往里垂直填充,然后剩余部分从中央部分往外填充。

EFF_BOXSTRIPE:位图或布告牌的一部分从四周向里填充,剩余部分向四周填充。

EFF_NONE:该选项是缺省设置。使用它来清除调用其它任一选项后的显示效果。

只有EFF_REVEAL和EFF_HORZREVEAL可用于图元文件。

返回值:

0:表明函数成功设置显示效果。

< 0:表明函数未能设置显示效果。

注解:

·当位图是由PlaceBitmap带选项BITMAPICON、FULLSCREEN、FULLSCREENSIZE或TILED显示时,该位图不会按显示效果显示,而是正常显示。更多的信息可查阅PlaceBitmap。

·显示效果仅当放置位图时出现,当删除位图时不能使用显示效果。

·只有展示(EFF_REVEAL)和水平展示(EFF_HORZREVEAL)效果可用于图元文件。

2.11  SetErrorMsg

语法:SetErrorMsg (nErrorID, szText);

说明:SetErrorMsg函数定制InstallShield缺省错误信息。你可以使用该函数来指定显示这些错误信息的消息框的标题文本。

参数:

nErrorID

指定要替换的错误信息。在该参数位置传递下列预定义的常量之一:

ERR_BOX_BADPATH:当EnterDisk检测到一个由用户输入的错误路径时显示该信息。

ERR_BOX_BADTAGFILE:当EnterDisk检测到指定的标签文件不存在于磁盘上时显示该信息。

ERR_BOX_DISKID:当EnterDisk检测到由用户指定的驱动器不存在时显示该信息。

ERR_BOX_DRIVEOPEN:当EnterDisk检测到磁盘驱动器未关闭时显示该信息。

szText

指定要在消息框中显示的错误信息。

返回值:

0:表明函数成功改变错误信息。

< 0:

表明函数未能改变错误信息。

2.12   SetErrorTitle 

语法:SetErrorTitle (nErrorID, szText);

说明:SerErrorTitle函数指定InstallShield内部错误消息框标题栏的自定义文本。你可以使用该函数来自定义错误消息文本。

参数:

nErrorID

指定标题要被替换的错误消息框。在该参数位置传递下列预定义的常量之一:

ERR_BOX_BADPATH:当EnterDisk检测到错误路径时显示该消息。

ERR_BOX_BADTAGFILE:当EnterDisk检测到指定的标签文件不存在于磁盘上时显示该消息。

ERR_BOX_DISKID:当EnterDisk检测到指定的驱动器不存在时显示该消息。

ERR_BOX_DRIVEOPEN:当EnterDisk检测到磁盘驱动器未关闭时显示该消息。

szText

指定显示在错误消息框中的标题。

返回值:

0:表明函数成功修改了标题栏的文本。

< 0:表明函数未能修改标题栏的文本。

2.13  SetFont

语法:SetFont (nItemID, nFontStyle, szFontName);

说明:SetFont函数设置显示的正文串的字体和风格。你可以在该函数使用标准Windows

      字体。

参数:

nItemID

指定其字体和字体风格要被设置的项。在该参数位置传递下列预定义的常量:

FONT_TITLE:指定安装过程的主标题,该主标题显示在安装窗口的左上角。

nFontStyle

指定字体风格。在该参数位置传递下列预定义的一个或多个常量。除STYLE_NORMAL之外的所有常量可以用按位或来指定多种风格:

STYLE_NORMAL:没有加粗、倾斜或阴影(不能被按位或)。

STYLE_BOLD:字体加粗。

STYLE_ITALIC:字体倾斜。

STYLE_SHADOW:字体有阴影底纹。

STYLE_UNDERLINE:加下划线。

szFontName

指定一个有效的Windows字体的名称。有效的字体名称包括Courier, Helv, Helvetica, Modern, Roman, Script, Terminal, Times 和TmsRmn。如果指定的字体没有找到指定的风格,就使用Arial。

返回值:

0:表明函数成功设置字体。

< 0:表明函数未能设置字体。

2.14  SetStatusWindow

语法:SetStatusWindow (nPercent, szString);

说明:SetStatusWindows函数为进度指示器(状态条)设置完成指示器的百分比的初始值或当前值,并指定在进度指示器(状态条)最高行显示的当前消息。

  通过调用ComponentTransferData或ComponentMoveData来传输文件的安装必须在文件传输开始之前调用SetStatusWindows,这是为了设置完成指示器百分比为0%而且清除指示器最高行。不再需要另外调用SetStatusWindows。每一个组件的文件被装入时,该组件的 ‘状态文本’字符串会在状态条最高行自动显示。

  使用CopyeFile或XcopyFile函数装入文件的安装程序在相继调用CopyFile或XcopyFile之间,可能需要多次调用SetStatusWindows来改变指示器最高行的信息。

  在传输文件前,你的安装程序还应该调用StatusUpdate函数激活文件传输过程中百分比完成指示器的自动更新。为了使得在状态条第二行显示正被安装文件的名称和路径,需在传输文件前带参数INDVFILESTATUS来调用Enable函数。在这些调用后,百分比完成指示器在文件传输过程中被平滑更新,每个文件的文件名在被传输时将显示。

参数:

nPercent

指定0100之间的一个数值来表示百分比完成指示器显示的百分比。若要改变显示在状态条最高行的信息而不改变百分比完成指示器,则指定该参数为-1

szString

指定显示在状态条最高行的字符串。注意如果一个'DisplayText'参数已被指定给该组件(在IDE中),那么当调用ComponentTransferData时该字符串将自动改写任何该参数指定的文本。

返回值:该函数没有返回值。

2.15  SetTitle

语法:SetTitle (szTitle, nPointSize, nColor);

说明:SetTitle函数根据nColor的值在主窗口标题栏或在主窗口内显示一个标题。

参数:

szTitle

指定在主窗口标题栏或主窗口内显示的一个标题。如果标题要显示在窗口的标题栏,你必须在第三个参数位置指定预定义常量BACKGROUNDCAPTION。如果一个标题栏的标题不符合可用空间,那将被从右截尾并以省略号终止。缺省标题栏标题为“安装”。

当给第三个参数传递一个颜色值时,标题在主窗口的顶端左对齐显示。相对主窗口太宽的标题将被从右截尾显示。为创建一个占据多行的标题,可在你希望的行断开处嵌入换行符。

nPointSize

以点数来指定一个在主窗口显示的标题的字号。建议字号为24点数。注意当第三个参数为BACKGROUNDCAPTION时该参数被忽略。

nColor

指定一个颜色或预定义常量BACKGROUNDCAPION。为指示szTitle值应该在主窗口标题栏显示,则在该参数位置传递预定义的常量BACKGROUNDCAPTION。当用户指定了BACKGROUNDCAPTIONnPointSize被忽略;标题栏标题的颜色和字号将由最终用户的系统设置决定。注意该选项在不运行在窗口模式的安装程序中无效;请查看下面的注解。

为指示szTitle值应该在主窗口中显示,通过在该参数位置传递下列预定义的常量之一来指定该标题的颜色:BLACKBLUEGREENMAGENTAREDYELLOWWHITE。用户也可以在该参数位置传递RGB函数来指定自定义颜色,如下面例子所示:

   SetTitle("FantasticApp", 24, RGB(78, 125, 161));

返回值:

0:表明函数成功设置安装的标题。

< 0:表明函数未能设置安装的标题。

注解:

·不运行于窗口模式下的安装中,第三个参数设置为BACKGROUNDCAPTION时调用SetTitle无效。为在一个标准窗口中运行安装程序,你必须首先以参数DEFWINDOWMODEFULLWINDOWMODE来调用Enable,然后以参数BACKGROUND调用Enable来显示窗口。

·用SetColor来设置你安装的背景色。

·用SetFont来设置在背景窗口中显示的标题的字体和字体风格。

2.16  SizeWindow

语法:SizeWindow (nObject, nDx, nDy);

说明:使用SizeWindow函数来改变一个特定用户界面元件的大小。以像素点来指定新的

  大小。

参数:

nObject

指定要调整大小的对象。在该参数位置传递下列预定义的常量之一:

BACKGROUND:标识为主背景窗口。

METAFILE:标识为在文件传输过程中使用的布告牌。SizeWindow不支持位图文件(.bmp)。该参数对用SdBitmap函数显示的图元文件不起任何作用。SdBitmap自动调整被显示的图元文件的大小。

MMEDIA_AVI:设置播放下一个AVI文件的窗口的大小。所有AVI视频以一个缺省大小来显示。改变大小可能会改变视频的有效分辨率和明快度。

nDx

以像素点指定对象的水平大小。

nDy

以像素点指定对象的垂直大小。

返回值:

0:表明函数成功调整窗口大小。

< 0:表明函数未能调整窗口大小。

注解:

·安装程序可能运行于多个不同的屏幕分辨率下。因此,你需要使用GetExtents函数来确定屏幕的全屏大小,然后在你的SizeWindows函数调用中参数使用比率来指定用户界面对象的大小。

·该函数仅推荐给高级开发人员。

2.17  StatusUpdate

语法:StatusUpdate (bLink, nFinalPercent);

说明:StatusUpdate函数激活或禁用文件传输操作和状态条进度指示器之间的连接。当bLink是ON,连接被激活并且nFinalPercent指示一个在下一个文件传输结束时显示的最后百分比。在文件传输过程中,状态条平滑地从它的当前值更新到由nFinalPercent指定的值。当bLink是OFF,连接被禁用并且状态条的进度指示器在随后的文件传输中不会被自动更新。

如果文件传输中状态条被激活,则在每次调用CopyFile 或 XcopyFile之前调用StatusUpdate。在调用ComponentTransferData传输文件之前,带参数为ON100来调用StatusUpdate;这将使状态条在安装的文件传输阶段平滑更新到100%。注意在一个运行基于事件脚本的安装中,ComponentTransferData被自动调用。

参数:

bLink

指定是否激活或禁用文件传输操作和状态条进度指示器之间的连接。在该参数位置传递下列预定义常量之一:

ON:指定状态条的进度指示器必须和文件传输操作相连接。

OFF:指定禁用状态条的进度指示器和文件传输操作之间的连接。连接保持为禁用直到它通过一个随后对StatusUpdate带参数bLink为ON的调用而得到重新建立。

状态条可以通过调用SetStatusWindow而被手动更新。

nFinalPercent

指定当bLink为ON时,状态条的进度指示器在下一个文件传输操作结束时必须达到的最后百分比。如果传递给nFinalPercent的值小于状态条的进度指示器的当前值,则进度指示器不会改变。当bLink为OFF时,该参数被忽略。

返回值:

0:表明函数成功。

< 0:表明函数不成功。

注解:

·该函数通过计算由任何文件传输函数传递的总的字节数来工作。然后它计算从进度指示器的当前位置开始到nFinalPercent中的最大值,需每隔多久增加一次进度指示器。

·StatusUpdate函数不能和VerUpdateFile 、VerSearchAndUpdateFile一起工作。当调用那些函数时,你必须禁用状态条或手动更新它。

·为设置状态条到一个初始百分比,在调用StatusUpdate之前调用SetStatusWindow。

3  信息函数

下列信息函数提供操作环境中有效资源的数据:磁盘空间,内存和操作模式:

s GetDiskSpace

返回指定磁盘的有效字节数(未使用的)(最高为2GB)。

s GetDiskSpaceEx

以bytes、kilebytes、megabytes或gigabytes为单位返回一个磁盘的空闲空间,。

s GetEnvVar

返回一个环境变量的当前值。

s GetExtents

返回屏幕大小。

s GetMemFree

返回运行在Microsoft Windows下的一个应用程序的可用内存。

s GetSystemInfo

检索系统信息。

s GetValidDrivesList

返回目标系统中所有有效驱动器。

s GetWindowHandle

返回主安装窗口的句柄。

s Is

提供文件和路径检查服务,查找一个数学协处理器,检测 Windows NT下的管理状态,确定Microsoft Windows是否从网络的共享版本运行。

3.1  GetDiskSpace

语法:GetDiskSpace (szDrive);

说明:GetDiskSpace函数返回指定驱动器上的空闲磁盘空间。

参数:

szDrive

指定一个驱动器指示符(驱动器字符后随一个冒号)。你也可在该参数位置指定一个通用导航计算机路径。

返回值:

XXXX:在指定驱动器上的空闲字节数。最大的返回值是2GB。超过2GB的空闲空间也返回2GB。当你需要检测超过2GB的空闲空间时需调用GetDiskSpaceEx。

< 0:表明GetDiskSpace未能获得空闲磁盘空间值。

3.2  GetDiskSpaceEx

语法:GetDiskSpaceEx (szDrive, nUnits);

说明:GetDiskSpaceEx函数返回指定驱动器的空闲磁盘空间值。传递给nUnits的值确定GetDiskSpaceEx的返回值是以bytes、 kilobytes、 megabytes 或 gigabytes度量。

参数:

szDrive

指定一个驱动器指示符(驱动器字符后随一个冒号)。用户也可在该参数位置指定一个通用导航计算机(UNC)路径。

nUnits

传递下列预定义常量之一来指明度量单位:

BYTES:指明GetDiskSpaceEx须返回空闲byte数。

KBYTES:指明GetDiskSpaceEx须返回空闲kilobyte数。

MBYTES:指明GetDiskSpaceEx须返回空闲megabyte数。

GBYTES:指明GetDiskSpaceEx须返回空闲gigabyte数。

返回值:

XXXX:在指定驱动器上的空闲bytes、kilobytes、megabytes或 gigabytes数,度量单位视nUnits值而定。

< 0:表明GetDiskSpaceEx未能获得空闲磁盘空间值。

3.3  GetEnvVar

语法:GetEnvVar (szParameter, svValue);

说明:GetEnvVar函数检索一个环境变量的当前值。

参数:

szParameter

指定其值要被检索的环境变量的名称。

svValue

返回该环境变量的当前值。

返回值:

0:表明函数检索到环境变量的值。

< 0:表明函数未能检索到环境变量的值。

注解:

·InstallShield没有提供一个改变一个环境变量值的机制。在Microsoft Windows 3.x  和 95环境中,建议用户不要改变环境变量值。如果用户需要设置一个新的环境变量,在Autoexec.bat文件中设置然后重启系统。对于Windows NT,查看如何在Windows NT下设置环境变量。

3.4  GetExtents

语法:GetExtents (nvDx, nvDy);

说明:GetExtents函数检索屏幕大小。屏幕宽以像素点为单位返回给nvDx,高以像素点为单位返回给nvDy。如:一个标准的VGA监控器返回nvDx为640nvDy为480

参数:

nvDx

以像素点为单位返回屏幕的宽。

nvDy

以像素点为单位返回屏幕的高。

返回值:

0:表明函数成功检索到屏幕的大小。

< 0:表明函数未能检索到这些值。

3.5  GetMemFree

语法:GetMemFree ( );

说明:GetMemFree函数返回运行在Microsoft Windows下的一个应用程序可用的内存大小。因为Microsoft Windows是一个虚拟内存系统,该函数不会返回实际物理内存(称为RAM)而是Windows应用程序可用的内存。要确定目标系统上可用的实际物理内存大小,可调用GetSystemInfo。

参数:

GetMemFree不带参数。以空参数表调用函数,如下所示:

   GetMemFree();

返回值:

XXXX:XXXX是应用程序可用的空闲内存的字节数。

< 0:GetMemFree未能返回空闲内存的大小。

注解:

·脚本每执行一个函数,InstallShield返回一个数值来指示函数运行结果。如果你要在该脚本后面部分要用到该函数的返回值,则将该值赋给一个数值型变量。

3.6  GetSystemInfo

语法:GetSystemInfo (nItem, nvResult, svResult);

说明:GetSystemInfo函数检索目标系统的信息。

参数:

第一个参数,nItem,用来指定要检索的信息的类型。参照下面这个你可传递给该参数的常量列表来检索系统信息。注意使用特定的常量时(如DISK_TOTALSPACE_EX),你必须在调用该函数前为参数nvResult和/svResult指定附加信息。

系统信息返回给nvResult和/svResult。数值型数据返回给nvResult。字符串型数据返回给svResult。下表列出了你可以传递给nItem的各个常量的返回值类型。

--------------------------------------------------------------------------------

nItem:BOOTUPDRIVE

nvResult:启动驱动器的 ID,1=A:,2=B:,3=C:。可以通过给该数值加上64(十进制)将该数字转换为相应的驱动器字符,然后给该值设置一个字符串变量。使用下面的语法进行转换:

svResult[0]=64+nvResult;

svResult:返回启动驱动器的驱动器指示符(驱动器字符后随一个冒号)。

--------------------------------------------------------------------------------

nItem:CDROM

nvResult: TRUEFALSE指示CD ROM是否可用。

SvResult: N/A

--------------------------------------------------------------------------------

nItem: COLORS

nvResult:返回用户系统可用颜色数目。结果从对目标系统的视频驱动器检索而得,而不是从视频卡得到。如果该卡支持256色但驱动器只能处理16色,返回的颜色值是16

svResult::N/A

--------------------------------------------------------------------------------

nItem:CPU

nvResult:返回下列常量之一:

IS_UNKNOWN    用户CPU未知。

IS_386           用户有一个386处理器。

IS_486           用户有一个486处理器。

IS_PENTIUM     用户有一个PENTIUM 处理器。

IS_ALPHA        用户有一个ALPHA处理器。

SvResult: N/A

--------------------------------------------------------------------------------

nItem:   DATE

nvResult: N/A

svResult: svResult:当前系统时间格式为MM-DD-YYYY。在月和日域的首零被删除。

--------------------------------------------------------------------------------

nItem:   DISK_TOTALSPACE

nvResult::返回由svResult指定的磁盘驱动器的总容量。最大返回值为2GB。总容量大于2GB的仍返回2GB

SvResult:驱动器字符。注意该参数是传递给该函数的;也就是说,你必须在调用GetSystemInfo前给svResult赋值。还要注意你必须在驱动器字符后加上冒号;否则函数执行会失败。你也可以在该参数位置指定一个通用导航计算机(UNC)路径。

--------------------------------------------------------------------------------

nItem:   DISK_TOTALSPACE_EX

nvResult: 指定度量单位;在该参数位置传递下列预定义的常量之一:BYTES, KBYTES, MBYTES 或GBYTES。在svResult返回指定磁盘驱动器的总容量。

SvResult:驱动器字符。注意该参数是传递给该函数的;也就是说,用户必须在调用GetSystemInfo前给svResult赋值。还要注意必须在驱动器字符后加上冒号;否则函数执行会失败。用户也可以在该参数位置指定一个通用导航计算机(UNC)路径。

--------------------------------------------------------------------------------

nItem:   DRIVE

nvResult::在svResult返回指定驱动器的类型。将返回下列常量之一:

IS_UNKNOWN -目标驱动器未知。

IS_REMOVABLE -目标驱动器是软盘驱动器。

IS_FIXED -目标驱动器是硬盘驱动器。

IS_CDROM -目标驱动器是光盘驱动器。

IS_REMOTE -目标驱动器是一网络驱动器。

SvResult:驱动器字符后随冒号。注意该参数是传递给该函数的;也就是说,用户必须在调用GetSystemInfo前给svResult赋值。用户也可以在该参数位置指定一个通用导航计算机(UNC)路径。

--------------------------------------------------------------------------------

nItem:   EXTENDEDMEMORY

nvResult: NvResult:返回安装在机器上的内存大小。由于操作系统的限制,返回值可能会和安装在机器上的实际物理内存大小稍有差异。该值通常比实际值小100K。注意返回值以kb来度量。

SvResult: N/A

--------------------------------------------------------------------------------

nItem:    LANGUAGE

nvResult: nvResult:该参数返回目标系统的InstallShield语言常量。返回的常量可以用来确定使用ComponentFilterLanguage函数的安装中装入哪些语言专用文件组。

 For information about determining the default language of the target system, click here. 

InstallShield International支持21种语言,Windows支持100多种语言。如果你想根据nvResult值筛选文件组,则必须使用一个开关语句根据该函数的返回常量来确定要使用的InstallShield语言标识号常量。带该参数时该函数的性能高度依赖于系统。

SvResult:该参数返回和nvResutl返回的语言常量等价的语言名称字符串。

--------------------------------------------------------------------------------

nItem:OS

nvResult:返回目标操作系统平台。返回下列常量之一:

IS_WINDOWSNT -  操作系统是Windows NT。

IS_WINDOWS9X -  操作系统是Windows 95或Windows 98。为确定是哪个,带WINMINOR调用GetSystemInfo来检测监控器版本。如果小于10,则操作系统是Windows 95;否则是Windows 98。

SvResult:N/A

--------------------------------------------------------------------------------

nItem:   PARALLEL

nvResult: 返回有效的物理并行口数目。

SvResult: N/A

--------------------------------------------------------------------------------

nItem:   SERIAL

nvResult: 返回有效的物理串行口数目。

SvResult: N/A

--------------------------------------------------------------------------------

nItem:   TIME

nvResult: N/A

svResult: 以HH:MM:SS格式返回当前系统时间。

--------------------------------------------------------------------------------

nItem: VIDEO

nvResult:nvResult:返回安装的视频适配器类型。(InstallShield不能检测CGA或单色视频驱动器)。返回下列常量之一:

IS_UNKNOWN -未知的用户视频适配器。

IS_EGA - EEGA分辨率。

IS_VGA - VGA分辨率。

IS_SVGA - SVGA800×600)分辨率。

IS_XVGA - XVGA1024×768)分辨率。

IS_UVGA -大于1024×768分辨率。

SvResult:N/A

--------------------------------------------------------------------------------

nItem:   VOLUMELABEL

nvResult: N/A

svResult: 传递你要检索其卷标号的驱动器的驱动器指示符(驱动器字符后随冒号)。该参数返回指定的驱动器的卷标号。如果该驱动器没有卷标号,返回空字符串。

--------------------------------------------------------------------------------

nItem:  WINMAJOR

nvResult:返回Windows的主版本号。

SvResult:以##.###格式返回一个字符串,指明Windows的主、次版本号。

--------------------------------------------------------------------------------

nItem:  WINMINOR

nvResult:返回Windows的次版本号。

SvResult:以##.###格式返回一个字符串,指明Windows的主、次版本号。

--------------------------------------------------------------------------------

返回值:

0:表明函数成功返回指定信息。

< 0:表明函数未能返回指定信息。

3.7  GetValidDrivesList

语法:GetValidDrivesList (listID, nDriveType, nMinDriveSpace);

说明:GetValidDrivesList函数检索目标系统的符合特定条件的所有驱动器列表。这个条件包括驱动器类型和驱动器的最小空间数。如果一个驱动器未关闭,该驱动器名仍加入列表。

你可以在驱动器罗列之前指定要查找的驱动器的类型(nDriveType)和可用的最小磁盘空间(nMinDriveSpace)。

参数:

listID

返回有效驱动器字符的一个列表。由listID标识的字符串列表必须通过对ListCreat的调用已被初始化。

nDriveType

指定要查找的驱动器的类型。在该参数位置传递下列预定义的常量之一:

-1:查找所有驱动器类型。

FIXED_DRIVE:仅查找硬盘驱动器。

REMOTE_DRIVE:仅查找远程驱动器。远程驱动器通常位于网络。

REMOVEABLE_DRIVE:仅查找可卸式驱动器。软盘驱动器是可卸式驱动器。

CDROM_DRIVE:仅查找光盘驱动器。

nMinDriveSpace

指定包括在返回列表中的驱动器所必须有的最小的空闲磁盘空间的字节数。如果nMinDriveSpace小于0GetValidDrivesList将不检测驱动器的最小空间。这对软盘驱动器有用。

返回值:

0:函数成功检索所要求的列表。

< 0:函数未能检索到要求的序列。

注解:

·网络映射驱动器也可作为远程驱动器返回。该函数不会返回所有网络上的驱动器,仅返回那些标识为映射驱动器的驱动器。

3.8  GetWindowHandle

语法:GetWindowHandle (nHwndFlag);

说明:GetWindowHandle函数得到安装主窗口的句柄。

参数:

nHwndFlag

指定InstallShield主窗口的窗口句柄。在该参数位置传递预定义的常量HWND_INSTALL。 

返回值:

X:X是窗口句柄。

< 0:函数未能检索到句柄。

3.9  Is

语法:Is (nIsFlag, szIsData);

说明:Is函数检索脚本中需要的公用信息。

参数:

nIsFlag

指定要检索的信息类型。在该参数位置传递下列预定义的常量之一:

DIR_WRITEABLE:能否写到由szIsData指定的目录?

FILE_EXISTS:由szIsData指定的文件是否存在?

FILE_LOCKED:文件是否锁定?

FILE_WRITEABLE:能否写到由szIsData指定的文件?

MATH_COPROCESSOR:在目标系统是否存在一个数学协处理器?

PATH_EXISTS:由szIsData 指定的路径是否存在?

USER_ADMINISTRATOR:当目标操作系统是Windows NT时,当前用户是否拥有管理员特权?运行于Windows 95或更高版本下的安装程序,Is通常在参数nFlag为 USER_ADMINISTRATOR时返回TRUE

VALID_PATH:由szIsData指定的路径是否一个合法路径?它不确认路径的存在与否,而仅检测它的语法。当你检索从用户处得到的路径信息时可以使用该常量。然后该函数会检测输入的路径信息是否正确。

WINDOWS_SHARED:Microsoft Windows是否从一个网络运行共享版本?

szIsData

指定信息,该信息依赖于传递给nIsFlag的常量,如下所示:

若nIsFlag是DIR_WRITEABLE,szIsData指定要被检测的全限定路径。

若nIsFlag是FILE_EXISTS,szIsData指定全限定文件名。

若nIsFlag是FILE_LOCKED,szIsData指定全限定文件名。

若nIsFlag是FILE_WRITEABLE,szIsData指定全限定文件名。

若nIsFlag是MATH_COPROCESSORszIsData指定的内容被忽略。

若nIsFlag是PATH_EXISTSszIsData指定全限定路径。 

若nIsFlag是USER_ADMINISTRATOR,szIsData被忽略。

若nIsFlag是VALID_PATH,szIsData指定全限定路径。

若nIsFlag是WINDOWS_SHARED,szIsData被忽略。

返回值:

TRUE (1):表明答复为真。

FALSE (0):表明答复为假。

< 0:函数未能答复问题。

注解:

·常量WINDOWS_SHARED仅能应用于Microsoft Windows版本。一个Microsoft Windows的共享版本安装于网络且有可被许多用户共享的公用文件。

4  内部对话框函数

   下列函数创建简单对话框,如Yes/No对话框和消息框。一些函数允许你简单地显示公用对话框的各种类型。

有Cancel按扭的内部对话框当该按扭被选中时不返回CANCEL(2)值。而是调用当前定义的退出处理程序。

注意:作为缺省,InstallShield  Professional 6Windows 2000 风格显示最终用户对话框,该风格遵照Windows用户界面的Microsoft的最新准则。为相应显示Windows 95风格的对话框,用户需做下列工作:

s 通过重命名或移至其它文件夹,将<InstallShield Professional 6文件夹>、Redistributable\Compressed Files\0009-English\Intel 32\_isres.dll备份。

s 将文件_isres.old 从<InstallShield Professional 6 文件夹>\Program\Migration\0009-English\Intel 32拷贝至<InstallShield Professional 6 文件夹>\Redistributable\compressed Files\0009-English\Intel 32。

s 改变文件名_isres.old为isres.dll。

s 单击建立工具栏Build toolbar'的建立当前媒体按钮Build Current Media或从建立菜单选择建立<媒体名称>媒体来建立用户的媒体。

具体函数包括以下这些:

s AskDestPath

显示一个要求目标路径信息的对话框。

s AskOptions

显示一个对话框,提示最终用户通过复选框或单选钮来选择选项。

s AskPath

显示提示最终用户输入一个路径的对话框。

s AskText

显示提示最终用户输入文本的对话框。

s AskYesNo

显示一个对话框,提示最终用户通过点击Yes或No按扭来响应问题。

s ComponentDialog

显示一个对话框,让最终用户选择组件和指定一个目标位置。

s EnterDisk

显示一个对话框,提示最终用户一个指定的磁盘。

s MessageBox

在对话框中显示一条信息。

s RebootDialog

显示一个对话框,使最终用户可以选择重启Windows或重启计算机。

s SelectDir

显示一个对话框,允许最终用户选择一个文件夹。当文件夹不存在时SelectDir创建该文件夹。

s SelectDirEx

显示一个对话框,允许最终用户选择一个文件夹。

s SelectFolder

显示一个对话框,允许最终用户从程序文件夹列表中选择一个文件夹。

s SetupType

显示一个对话框,允许最终用户选择典型、简易、自定义安装。

s SprintfBox

返回一个由一个或多个字符、数字或字符串值组成的格式化的字符串。

s Welcome

显示欢迎信息的对话框。

4.1  AskDestPath

语法:AskDestPath (szTitle, szMsg, svDir, nReserved);

说明:AskDestPath函数显示一个对话框,允许最终用户指定安装中文件安装到的目标文件夹。对话框还包括一个浏览按扭,允许最终用户选择一个存在的文件夹或指定一个新的文件夹。注意最终用户选择的文件夹必须可写;不可写的文件夹不被接受。如果你希望最终用户可以选择不可写的文件夹,可调用AskPath函数。

    为从选择目标位置对话框中打开选择文件夹对话框,最终用户必须点击浏览(Browse)按钮。选择文件夹对话框显示所有有效文件夹列表。最终用户可选择一个存在的文件夹或者输入一个新的文件夹名。如果最终用户输入一个不存在的文件夹名,该文件夹被创建。

参数:

szTitle

指定对话框标题。为显示缺省标题(“选择目标位置”),传递一个空字符串给该参数。

szMsg

指定要显示的消息。为在该参数传递多行静态文字,在行需要间断处插入新行转换符序列(\n)。为显示该对话框的缺省指令,传递空字符串(””)给该参数。

svDir

指定打开对话框时显示的缺省路径;返回到达最终用户选择的文件夹的路径。更多信息请看下面的注解。

nReserved

该参数的值必须是0

返回值:

NEXT (1):表明Next按钮被选中。

BACK (12):表明Back按钮被选中。

注解:

·如果由svDir指定的缺省文件夹不存在于最终用户系统中,它不会被创建,除非最终用户按下选择按钮并且从选择文件夹对话框中按步骤创建它。因此,当用户指定一个希望在调用ComponentTransferData(它在必要时会创建文件夹)前使用的缺省文件夹时,用户必须在AskDestPath返回时调用ExistDir以此来确定文件夹是否存在。如果它不存在,调用CreatDir来在最终用户系统中创建它。注意一个运行基于事件的脚本的安装程序会自动调用ComponentTransferData。

· 运行在静止方式(silent mode)的安装程序,若缺省文件夹不存在,则必须在调用AskDestPath前创建它。

4.2  AskOptions

语法:AskOptions (nValue, szMsg, szText1, bvCheck1, szText2, bvCheck2[, szTextn, bvCheckn] [,..., ]);

说明:AskOptiona 函数格式化并显示提示最终用户选择一个或多个选项的对话框。对话框的缺省标题是“选择组件”。为改变标题栏的内容,在调用AskOptions前调用SetDialogTitle。该对话框将显示多至九个选择控件,复选框或单选钮,根据nValue的值而定。

参数:

nValue

指定要显示的控件。在该参数位置传递下列预定义常量之一:

EXCLUSIVE:指定单选按钮,允许最终用户仅选择一个选项。

NONEXCLUSIVE:指定复选框,允许最终用户选择一个以上的选项。

szMsg

指定在对话框显示的消息。你可以使用该消息来描述选项和/或要求最终用户选择一个或多个选项。如果消息多于一行,使用换行符(\n)插入行的间隔处。

szText1

指定一个最多达47个字母的文本标签,它相邻显示于第一个复选框或单选钮。为建立一个快捷键,在用户为该目的指定的字母前插入一个“与符号”(&)。该字母带下划线显示来指示它的功能。例如,自定义Alt+C为快捷键,传递“&Custom”。自定义Alt+S为快捷键,传递”Cu&stom”。

bvCheck1

指定对话框打开时第一个选择框或单选钮的初始状态;对话框关闭时返回第一个选择框或单选钮的状态。在该参数位置传递下列常量:

TRUE:第一个选择框或单选钮被选。

FALSE:第一个选择框或单选钮未被选中。

szText2

指定相邻显示于第二个选择框/单选钮的最多达47个字母的文本标签。创建一个快捷键的方法同szText1处。

bvCheck2

指定对话框打开时第二个选择框或单选钮的初始状态;对话框关闭时返回第二个选择框或单选钮的状态。在该参数位置传递下列常量:

TRUE:第二个选择框或单选钮被选。

FALSE:第二个选择框或单选钮未被选。

    可以定义多达七个附加选项。每个附加选项由一对参数指示:一个字符串参数定义一个标签和一个数值型变量定义AskOptions返回时的选项状态。为设置一个选项的初始状态,在调用AskOptions前给数值型变量赋值为TRUE 或FALSE。

    若nValue是EXCLUSIVE并且一个以上的选项设置的初始状态设置为TRUE,AskOptions将预选设置为TRUE的参数序列的第一个选项。

返回值:

NEXT (1):表明Next按钮被选。控件的状态由各个bvCheck变量返回。

BACK (12):表明Back按钮被选。控制的状态由各个bvCheck变量返回。

4.3  AskPath

语法:AskPath (szMsg, szDefPath, svResultPath);

说明:AskPath函数指定一个对话框,提示最终用户输入目标位置的路径。对话框包括一个单行编辑区,你可以在此显示一个缺省路径。最终用户有三个选择:

s 接受缺省路径

s 编辑缺省路径

s 显示选择文件夹Choose Folder对话框来选择一个文件夹

  对话的缺省标题是选择目标位置Choose Destination Location。为改变该标题,在调用AskPath前调用SetDialogTitle。AskPath不检验最终用户输入路径的存在性。调用AskPath后调用CreatDir来创建该路径。

参数:

szMsg

指定显示在对话框中的消息。要显示该对话框的缺省指示,传递空字符串(“”)给该参数。

szDefPath

指定在编辑区显示的缺省路径。最终用户可以修改该字符串。

svResultPath

返回结果路径名,不管用户是否接受缺省路径,修改它,还是从选择文件夹Choose Folder对话框选择可选路径。AskPath在路径结尾加一个反斜杠,然后才把它赋给svResultPath。若必要,可在AskPath返回后通过调用StrResultPath 来删除反斜杠。如果用户按下返回按钮,svResultPath的值将不可预测。因此,如果用户在szDefPath和svResultPath使用相同的变量,那么确保当AskPath的返回值为BACK时重初始化该变量。

返回值:

NEXT (1):表明最终用户选择Next按钮。

BACK (12):表明最终用户选择Back按钮;svResultPath设置为空字符串(“”)。

注解:

·在对话框显示的编辑区可滚动以适应长字符串。

·因为可以输入至编辑区的字符数目不受限制,所以用户必须以不定长来说明svResultPath传递的变量。如果字符串变量不足以存储用户输入的文本,字符串将被截尾并且显示错误信息。同样要注意既然这个函数在字符串结尾附加一个反斜杠和一个空结束符,字符串的长度至少比用户输入的路径长两个字符。

·该函数将接受一个存在但不可写的文件夹。为限制最终用户只可选择可写的文件夹,可调用AskDestPath函数来替代。

4.4  AskText

语法:AskText (szQuestion, szDefault, svResult);

说明:AskText函数显示一个对话框,它包括一个静态文本区和一个编辑框。参数szQuestion指定静态文本区的缺省文本;参数szDefault指定编辑框的缺省文本。该对话框的缺省标题是输入信息Enter Information。为改变标题栏的内容,在调用AskText前调用SetDialogTitle。

参数:

szQuestion

指定要显示的问题或声明。如果该参数位置的字符串长度超过静态文本区宽度,一个或多个行分隔符将会被插入该字符串使得它在对话框多行显示。如果愿意,用户也可以自己通过插入换行符(\n)手动格式化该字符串。该参数没有一个缺省值。

szDefault

指定编辑区的缺省文本。

svResult

当Next按钮被用来关闭对话框时返回由最终用户输入的文本。如果用户按下Back按钮,svResult值将不可预测。因此,如果用户在szDefPath和svResultPath使用相同的变量,那么需确保当AskPath的返回值为BACK时重初始化该变量。

返回值:

NEXT (1):表明Next按钮被按下。

BACK (12):表明Back按钮被按下。

注解:

·用户在svResult传递的字符串变量必须足够大以适应输入到编辑区的文本。因此,用户必须使用自动调节大小的方法来声明变量。

·必要时,编辑区将会滚动来以适应一个长字符串。

4.5  AskYesNo

语法:AskYesNo (szQuestion, nDefault);

说明:AskYesNo函数呈现一个消息框,显示一个问题,最终用户可以通过单击Yes或No按钮来回答它。AskYesNo消息包含四个内容:

.问题标记图标  .问题文本  .Yes按钮  .No按钮

  缺省标题是Question。为改变标题栏的内容,在调用AskYesNo前调用SetDialogTitle。

AskYesNo消息框由直接调用相应的Windows API函数创建,它显示一个系统模态对话框。由于该对话框是由Windows显示的,按钮上的文本不能由安装改变。英语版本的文本’Yes’或’No’将由Windows 以适合运行安装的Windows版本的语言显示。如果用户需要显示另一个柔性对话框,直接调用一个Windows API函数或使用一个自定义对话框。

参数:

szQuestion

指定显示在消息框中的问题。如果消息超过一行,在消息中嵌入换行符(\n)来插入行间隔。

nDefault

指定缺省选定的按钮。在该参数位置传递下列预定义的常量之一:

YES:当对话框打开时Yes 按钮高亮显示。

NO:当对话框打开时No按钮高亮显示。

返回值:

YES (1):表明用户选择Yes 按钮。

NO (0):表明用户选择No按钮。

4.6  ComponentDialog

语法:ComponentDialog (szTitle, szMsg, svDir, szComponent);

说明:ComponentDialog函数显示一个对话框,允许最终用户从当前媒体上的组件列表中选择一项或多项。用户也可以选择一个目标位置。

    如果你的安装不使用一个安装类型对话,用户必须在调用ComponentDialog前调用ComponentTypeSet来指定一个已经在IDE安装类型窗格中定义的安装类型。

    当前媒体的名称存储在系统变量MEDIA中。在安装初始化过程中,InstallShield给MEDIA赋值为缺省媒体名称(“DATA”),它和用户文件媒体库(Data1.cab)相联系。显示脚本创建的组件时,按下列步骤进行:

s 保存MEDIA的当前值

s 将脚本创建组件组的名称赋给MEDIA

s 调用ComponentDialog得到最终用户的选择

s 将步骤1的值赋给MEDIA

    在安装初始化中系统变量MEDIA的值设置为’DATA’。如果用户改变该变量的值来引用脚本创建的组件组,用户必须在调用ComponentTransferData, CreateShellObjects 或CreateRegistrySet前将值改回’DATA’。注意在一个基于事件的脚本的安装中ComponentTransferData被自动调用。

    单击浏览按钮装入选择文件夹Choose Folder对话框,显示存在的文件夹列表。最终用户可以选择一个存在的文件夹或输入一个新的文件夹名称。ComponentDialog在svDir返回被选的文件夹名称。

如果用户输入一个不存在的文件夹,将出现一个消息框来询问最终用户是否要创建这个文件夹。如果是,则InstallShield创建指定的文件夹。

参数:

szTitle

指定对话框标题。为显示缺省标题(“选择组件Select Components”), 给该参数传递一个空字符串(””)。

szMsg

指定在对话框显示的消息。例如,消息可能为“请选择一个或多个下列组件安装在你的系统上” "Please select one or more of the following components to install on your system."。为显示该对话框的缺省指示,给该参数传递一个空字符串(””)。

svDir

指定缺省目标位置。返回最终用户选择的文件夹。注意在svDir 返回的位置值不影响文件传输除非用户将它赋值给系统变量TARGETDIR或调用ComponentSetTarget来将它和一个用户定义的变量联系起来。

    我们建议用户给该参数传递TARGETDIR而不是一个字符串变量。如果你在该参数不传递TARGETDIR,当最终用户在一个不同驱动器选择一个目标时显示在对话框的所需磁盘空间不会被重算。

szComponent

指定组件,其子部件被显示以供选择。给该参数传递一个空字符串(””)来显示所有顶层组件。

ComponentDialog在文件媒体库或脚本创建的组件组中查找由系统变量MEDIA指定的所需组件。

返回值:

NEXT (1):表明最终用户选择Next按钮。

BACK (12):表明最终用户选择Back按钮。

< 0:未能显示ComponentDialog对话框。调用ComponentError查看附加信息。

注解:

·组件大小显示为0直到它被选中。一旦它被选中,它的实际大小被显示。

·若有必要,组件名称被截尾来显示最大可能的组件大小。显示大小的必要空间依赖于组件最大大小本身(2GB),当前使用的组件大小选项,和用来在对话框显示组件信息的字体。组件大小选项由DialogSetInfo函数设置。一旦显示最大可能大小所需的空间被确定,若有必要,所有组件名均被截尾以适应剩余空间。这确保组件名不会覆盖组件大小。注意,在这种方法下需要较少空间显示大小(或没有被选)的组件的名称仍然会被截尾。为了最大化执行并确保组件名称完整显示,使组件名小于在组件对话框中的有效空间。

·如果由svDir指定的缺省文件夹不存在于最终用户系统,它不会被创建除非最终用户按下浏览按钮并按下列步骤从选择文件夹对话框创建它。因此,无论何时用户想在调用ComponentTransferData(必要时,它会创建文件夹)前指定一个要使用的缺省文件夹,为了确定该文件夹是否存在,当ComponentDialog返回时都必须调用ExistDir 。如果不存在,调用CreatDir在最终用户系统上创建它。

·运行在静止方式的安装如果在调用ComponentDialog前文件夹不存在必须创建该新文件夹。这样可以确保确认对话框不被显示。没有这一步,需要两个响应文件来处理两个可能情况。

4.7  EnterDisk

语法:EnterDisk (szMsg, szTagFile);

说明:EnterDisk函数显示一个对话框,提示最终用户插入下一张磁盘。缺省标题是安装需要下一张磁盘。为改变该标题,在调用EnterDisk前调用SetDialogTitle。系统变量SRCDIR包含缺省路径,该路径显示在对话框中。最终用户可以修改缺省路径并通过输入一个新路径和单击OK来修改SRCDIR值。

    EnterDisk通过在磁盘查找由szTagFile指定的标签文件识别正确磁盘。如果磁盘不包含标签文件,会有一个错误消息提示用户输入正确磁盘。

参数:

szMsg

指定提示用户插入正确磁盘的消息。

szTagFile

指定标签文件名。EnterDisk在插入磁盘上查找该文件。如果文件没有找到,会显示一个消息要求用户插入正确的磁盘。如果用户给该参数传递一个空字符串(“”),函数不查找任何文件;而是假定安装了正确的软盘。

返回值:

OK (1):表明用户选择了OK按钮。

< 0:表明发生了一个未确定错误。

注解:

·InstallShield媒体生成器不会自动在磁盘映像文件夹上生成标签文件。为使用标签文件,将它们加到创建好的磁盘映像文件夹中。

4.8  MessageBox

语法:MessageBox (szMsg, nType);

说明:MessageBox函数呈现一个对话框,包含一个消息,一个指示消息自然属性的图标(信息,警告,或严重警告),和一个OK按钮。缺省标题依赖于nType值,nType值也指示图标类型。为改变消息框标题栏的内容,在调用MessageBox前调用SetDialogTitle。

参数:

szMsg

指定要显示的消息。InstallShield不会自动分隔消息文本为单独的行来适应消息框。如果消息长于一行,通过在字符串的合适位置嵌入换行符(\n)来插入行间隔。

nType

指定要创建的消息框类型和显示在消息框的图标类型。在该参数位置传递下列预定义的常量之一(显示资源管理器对象处理程序图标):

   INFORMATION   WARNING   SEVERE

任何Windows API MessageBox类型也可在该参数指定。多种风格可以被逻辑或来产生所需的MessageBox类型(请看下面的注解)。

返回值:

    除非你使用标准Microsoft Windows 消息框风格,返回值没有意义。如果你使用这些风格,返回值和MessageBox API函数的返回值一样。

注解:

·该函数使用Microsoft Windows API MessageBox。操作环境,而不是InstallShield,确定消息框的大小和位置(例如,操作系统运行所在的语言)。你可以改变该按钮的文本。考虑使用Windows MessageBox类型的更多信息,请在适当的Windows SDK中咨询MessageBox Windows API 函数的描述。

·当使用Windows 消息框常量时注意下列情况:

·Windows MessageBox 类型常量在Windows.h文件中声明,它不能包括在InstallShield 脚本中。当使用这些常量,用户必须在安装脚本的声明区定义它们(使用#define)。赋给这些常量的值通常可在一个适当的Windows SDK或开发工具提供的包含文件中找到。对于Microsoft Visual C++,大多数常量可在 Winuser.h文件中找到,它位于DevStudio\Vc\include 文件夹。

·Windows 和InstallShield消息框常量不能在一个安装中一起使用。如果一个InstallShield消息框常量和一个 Windows 消息框常量用一个或运算符组合,Windows 消息框常量将被忽略。

·一些Windows 消息框风格在一些Windows 平台不受支持。为确定一个特定的风格是否受安装确定的操作系统支持,咨询适当的Windows SDK。

·当MessageBox函数使用一个Windows 消息框风格时,消息框的标题是“安装“。如果用户需要显示不同的标题,可使用SprintfBox函数来替代。

4.9  RebootDialog

语法:RebootDialog (szTitle, szMsg, nDefChoice);

说明:RebootDialog函数显示一个对话框,允许最终用户重启计算机。被选的选项在安装的最后被执行。

参数:

szTitle

指定对话框标题。为显示缺省标题(“重新启动”),给该参数传递一个空字符串(“”)。

szMsg

指定对话框显示的消息。为显示该对话框的缺省指示,给该参数传递一个空字符串(“”)。

nDefChoice

指定缺省选定的单选钮内容。在该参数位置传递下列预定义常量之一:

SYS_BOOTMACHINE:重启计算机选项("Yes, I want to restart my computer now.")将成为缺省单选按钮选定内容。

0:不重启计算机选项("No, I will restart my computer later.")将成为缺省单选按钮内容。

返回值:

WILL_REBOOT:表明用户选择标签为"Yes, I want to restart my computer now."的单选钮。

0:表明用户选择标签为"No, I will restart my computer later."的单选钮。

注解:

·当你带SHAREDFILELOCKEDFILE选项来调用一个函数并且锁定遇到的.dll或.exe文件,锁定的文件的更新版本被拷贝至目标系统并且系统变量BATCH_INSTALL设置为TRUERebootDialog当系统重启时自动提交被锁定的文件以更新,除非用户选择"No, I will restart my computer later."选项。

·RebootDialog函数的一个完美候选是SdFinishReboot,它比RebootDialog对话框一个更好的外观和感觉。

·因为当InstallShield的其它实例运行时InstallShield会尽力不重启系统,所以用户必须确保所有其它InstallShield的实例在调用RebootDialog前停止执行。另外,你给用户的消息需要求他们确保在重启系统前所有其它应用程序停止执行。

4.10  SelectDir

语法:SelectDir (szTitle, szMsg, svDir, bCreate);

说明:SelectDir函数显示一个对话框,允许最终用户指定应用程序将被安装到的文件夹。最终用户可以输入一个全限定文件夹名或从列表中选择一个存在的文件夹。如果最终用户输入一个无效文件夹名或一个未限定文件夹名,将显示一个消息框提示最终用户输入一个有效名。选择文件夹的全限定名返回给svDir。

    如果指定的文件夹不存在并且参数bCreate是TRUE,显示一个消息框询问是否要创建文件夹。如果最终用户单击Yes, SelectDir自动创建指定的文件夹。如果参数bCreate设置为FALSE并且一个不存在的文件夹被选中,最终用户不会被告之,并且SelectDir不创建它。这种情况下,该由用户处理包含在svDir的选项。

    当最终用户单击呈现在由AskDestPath, SdAskDestPath 和其它获得一个文件夹名的InstallShield函数显示的对话框中的Browse按钮时SelectDir 被自动调用。

参数:

szTitle

指定对话框标题。为显示缺省标题(“选择文件夹”),给该参数传递一个空字符串(””)。

szMsg

指定用户要在该对话框显示的消息。为显示该对话框的缺省指示,给该参数传递一个空字符串(“”)。

svDir

指定将作为缺省选项显示的文件夹名。返回由最终用户选定的文件夹的全限定名。

bCreate

指定你是否要求InstallShield在指定文件夹不存在时创建它。在该参数位置传递下列预定义常量之一:

TRUE:表明如果文件夹不存在则需被创建。

FALSE:表明如果文件夹不存在不需被创建。

返回值:

IDOK (1):表明OK按钮被按下。

IDCANCEL (2):表明CANCEL按钮被按下。

< 0:表明该函数未能显示对话框并/或不能创建文件夹。

4.11  SelectDirEx

语法:SelectDirEx (szTitle, szMsg, szEditBoxStaticText, szTreeControlStaticText, nFlags, svDir);

说明:SelectDirEx显示一个对话框,允许最终用户从一个显示存在文件夹的树形控件中选择一个存在的文件夹。也显示一个编辑框,允许最终用户指定一个新文件夹。

    该函数调用Windows API函数SHBrowserForFolder来显示对话框。为得到SHBrowseForFolder更多信息,可查看Win32 SDK或访问http://msdn.microsoft.com/library/ sdkdoc/ shellcc/shell/Function s/SHBrowseForFolder.htm.

参数:

szTitle

指定对话框标题。为显示缺省标题(“选择文件夹”),给该参数传递一个空字符串(””)。

szMsg

指定用户要在该对话框显示的消息。为显示该对话框的缺省指示(“请选择安装文件夹”),给该参数传递一个空字符串(“”)。

szEditBoxStaticText

当nFlags 为BIF_EDITBOX时指定伴随编辑框的静态文本。如果nFlag不指定BIF_EDITBOX,该参数被忽略。

szTreeControlStaticText

当nFlags 指定BIF_STATUSTEXT时,指定伴随对话框的树形控件的静态文本。如果nFlags不指定BIF_STATUSTEXT,该参数被忽略。

nFlags

指定函数显示的对话框的外观和功能。传递任何下列常量:

BIF_BROWSEFORCOMPUTER:允许最终用户选择网络上的一特定计算机。当传递该常量时,对话框有如下行为(性能):

s “网络邻居”文件夹在树形控件中被预选。

s 仅当选中树形控件中的一个有效计算机名时,OK按钮被激活。

s 即使BIF_EDITBOX指定时也不显示编辑框。

BIF_BROWSEFORPRINTER:允许最终用户选择一特定打印机。当传递该常量时,对话框有如下行为:

s “网络邻居”文件夹在树形控件中被预选。

s 仅那些包括至少一台打印机的计算机在网络邻居文件夹中显示。

s 仅当选中树形控件中的一个有效打印机时,OK按钮被激活。

s 即使BIF_EDITBOX指定时也不显示编辑框。

BIF_DONTGOBELOWDOMAIN:域层下的网络文件夹不在树形控件中显示。

BIF_RETURNFSANCESTORS:如果一个文件系统祖先以外的任何对象被选中时OK按钮被禁用。

BIF_RETURNONLYFSDIRS:非文件系统某部分的一个文件夹被选中OK按钮被禁用。.

下列常量指定对话框的其它特征:

BIF_EDITBOX:显示一个编辑框,允许用户输入一文件夹名,在编辑框上部显示szEditBoxStaticText中的文本(除非指定BIF_BROWSEFORCOMPUTER 或BIF_BROWSEFORPRINTER)。当最终用户单击OKSelectDirEx检查是否输入了一个有效文件夹名。如果不是(例如,如果输入了包含无效字符的名称),显示一个错误消息并且对话框不被消除。和SHBrowseForFolder不同,SelectDirEx对所有InstallShield支持的操作系统都支持该常量。

BIF_STATUSTEXT:在树形控件上部作为态文本显示szTreeControlStaticText。注意SelectDirEx不支持BIF_VALIDATE 和 BIF_USENEWUI常量,而SHBrowseForFolder支持它们。

svDir

指定作为缺省选择出现的文件夹名。返回由最终用户选择的文件夹的全限定名。如果该参数指定了一个存在于系统的有效文件夹名,该文件夹在树形控件中被预选。

返回值:

IDOK (1):表明OK按钮被按下。

IDCANCEL (2):表明CANCEL按钮被按下。

< 0:表明函数未能显示对话框。

4.12  SelectFolder

语法:SelectFolder (szTitle, szDefFolder, svResultFolder);

说明:SelectFolder函数显示一个对话框,允许最终用户在一个编辑区输入一个程序文件夹名或从一个列表中选择一个程序文件夹。该函数自动显示系统中所有的程序文件夹。SvDefFolder传递的一个缺省的文件夹名在编辑区显示。在svResultFolder返回被选的文件夹名。如果指定文件夹不存在,它不会被创建。

参数:

szTitle

指定对话框标题。为显示缺省标题(“选择程序文件夹”),给该参数传递一个空字符串(””)。

szDefFolder

指定作为缺省文件夹显示的文件夹名。

svResultFolder

返回由最终用户选中或指定的文件夹名。如果文件夹不存在,你必须调用CreateProgramFolder来创建它;SelectFolder不会创建该文件夹。

返回值:

NEXT (1):表明最终用户选择Next按钮。

BACK (12):表明最终用户选择Back按钮。

< 0:表明函数未能成功执行。

4.13  SetupType

语法:SetupType (szTitle, szMsg, szReserved, nType, nReserved);

说明:SetupType函数显示一个对话框允许最终用户选择三种标准安装类型之一。典型、简易或自定义。这些安装选项显示时有标准描述文本。如果你想加入其它安装类型或改变显示的安装类型名或描述,可调用SdSetupTypeEx。

    如果最终用户在使用组件对话框来选定和撤消选定与已选安装类型相联系的组件后,返回到安装类型对话框,那么那些选择将丢失。这种情况发生是因为SetupType函数每次被调用时自动根据选中的安装类型复位缺省组件选项。

参数:

szTitle

指定对话框标题。为显示缺省标题(“安装类型”) ,给该参数传递一个空字符串(””)。

szMsg

指定你要在对话框顶部显示的消息。为显示该对话框的缺省指示,给该参数传递一个空字符串(””)。

szReserved

给该参数传递一个空字符串(“”),不允许其它值。

nType

当对话框打开时指定缺省安装类型。在该参数位置传递下列预定义常量之一:

TYPICAL:定义缺省安装类型为典型。

COMPACT:定义缺省安装类型为简易。

CUSTOM:定义缺省安装类型为自定义。

nReserved

给该参数传递0,不允许其它值。

返回值:

TYPICAL (301):表明选择了典型安装类型。

COMPACT (302):表明选择了简易安装类型。

CUSTOM (303):表明选择了自定义安装类型。

BACK (12):表明选定了Back按钮。

4.14  SprintfBox

语法:SprintfBox (nType, szTitle, szFormat [,arg] [,...]);

说明:SprintfBox函数呈现一个消息框,它包含三个图标之一,一个标题,和一个格式化的消息。该消息可以包含根据你输入的命令格式化的变量。

    SprintfBox和MessageBox相似,但SprintfBox对显示的内容允许更多的弹性控制。

参数:

nType

指定显示在消息框中的图标类型。在该参数位置传递下列预定义的常量之一(显示Windows 95图标):

INFORMATION信息

WARNING警告

SEVERE严重警告

szTitle

指定消息框标题。为显示缺省标题(“错误”) ,给该参数传递一个空字符串(””)。

szFormat

指定一个包含一个格式说明符的字符串,格式说明符是针对包含在消息中的每个参数的。

arg

指定包含在消息中的参数,至多可达10个。对消息中每个格式说明符必须有一个参数;每个参数类型必须和它各自的格式说明符相匹配。SprintfBox在下列情况下将产生一个编译错误或在运行时失败:

·指定多于十个格式说明符和参数:编译错误。

·参数数目和格式说明符数目不匹配。当一个说明符没有相应的参数,结果字符串将在说明符位置包括不可预测的字符。当参数多于说明符,多余的参数将被插入到结果字符串中。

·一个变量和它各自的格式说明符不匹配。结果字符串将在说明符位置包含不可预测字符。

返回值:

除非你使用本机的Windows 消息框风格(描述如下),返回值是没有意义的。

注解:

·该函数使用Microsoft Windows API MessageBox来创建消息框。消息框的OK按钮包含操作环境产生的文本。是操作环境而不是InstallShield确定消息框的大小和位置。

·熟悉Windows API的高级开发者可以通过在参数nType使用本机消息框风格常量来指定任何风格的消息框。查看你的操作环境编程手册中MessageBox 或WinMessageBox的说明。如果你使用任何本机消息框风格,InstallShiled SprintfBox函数将返回Windows API的返回值。因此,你必须在你的脚本中使用Windows API的返回值。

  例如,如果你传递 YES|NO|CANCEL作为第一个参数,SprintfBox消息框将有Yes,No和Cancel按钮。各个按钮返回值,如Windows API MessageBox定义,是6 (IDYES), 7 (IDNO), 和2 (IDCANCEL)。你必须在你的脚本中使用适当的常量值,作为数字或作为在你的脚本的声明区中定义为数字的常量。

·高级开发者可以直接使用MB_STYLE作为SprintfBox函数的第一个参数来代替常量SEVERE, WARNING或 INFORMATION。MB_STYLE的值列在Windows.h中。你可以给参数nType直接输入值,或可以使用#define 预处理程序指令来定义和该值联系的常量。

·当使用Windows消息框常量时注意下列问题:

· Windows MessageBox类型常量在Windows.h文件中声明,它不能被包括在一个InstallShield脚本中。当使用这些常量时,你必须在安装脚本的声明区定义它们(用#define)。赋给这些常量的值通常可以在由适当的Windows SDK或开发工具提供的一个包含文件中找到。对于Microsoft Visual C++,大多数常量可以在位于DevStudio\Vc\include文件夹的Windows.h文件中找到。

·Windows 和InstallShield消息框常量不能在一个安装中一起使用。如果一个InstallShield消息框常量和一个 Windows 消息框常量用一个或运算符组合,Windows 消息框常量将被忽略。

·一些Windows 消息框风格在一些Windows 平台不受支持。为确定一个特定的风格是否受安装确定的操作系统支持,咨询适当的Windows SDK。

4.15  Welcome

语法:Welcome (szTitle, nReserved);

说明:Welcome函数显示一个对话框来欢迎最终用户。

参数:

szTitle

指定该对话框的标题。为显示缺省标题(“欢迎”) ,给该参数传递一个空字符串。

nReserved

给该参数传递0

返回值:

NEXT (1):表明最终用户选择NEXT按钮。

BACK (12):表明最终用户选择BACK按钮。

< 0:表明Welcome未能显示对话框。

注解:

·在一个过程脚本中,为使InstallShield可以在欢迎对话框的消息文本的第一段中插入产品名称,你必须在调用Welcome前调用SdProductName。(在一个基于事件的脚本中,在Begin事件前,SdProductName被自动调用,以PRODUCT_NAME字符串表入口为参数)。如果你不使用SdProductName来传递一个产品名称,InstallShield不能插入产品名称而是将插入一个附加的空格。

5  Sd对话框函数

    InstallShield提供一些Sd对话框函数,用户可自定义和显示。Sd对话框使用可以创建用户输入的对话框的特殊脚本定义函数来创建。然后该对话框根据所作选择返回值给脚本。

    Sd对话框有一个Cancel按钮,当它被选中时不返回一个CANCEL值。而是调用缺省的退出处理。

下面是所有有效的Sd对话框函数的列表:

s DialogSetInfo

改变由一些内部对话框函数呈现的对话框的显示元素。

s SdAskDestPath

呈现一个对话框,允许最终用户指定安装的一个目标位置。

s SdAskOptions

创建一个对话框,它比标准AskOptions函数更灵活。

s SdAskOptionsList

呈现一个对话框,允许最终用户选定和撤消选定一个列表中的项目。

s SdBitmap

在对话框中显示一个位图。

s SdComponentDialog

显示一个对话框,允许最终用户选择安装的组件和目标文件夹。

s SdComponentDialog2

显示一个对话框,允许最终用户选择要安装的文件夹、组件和子部件。

s SdComponentDialogAdv

显示一个对话框,允许最终用户选择安装的组件和目标文件夹。

s SdComponentMult

显示一个对话框,允许最终用户选择安装的组件和子部件。有关磁盘空间的附加信息也被提供来确定安装的最佳位置。

s SdComponentTree

显示一个有树形控制控件的对话框,允许最终用户选择安装的组件和子部件。有关磁盘空间的附加信息也被提供来确定安装的最佳位置。

s SdConfirmNewDir

提示用户确认文件夹的选择。

s SdConfirmRegistration

提示最终用户确认输入到由SdRegisterUser或SdRegisterUserEx呈现对话框中的信息。

s SdDisplayTopics

显示主题列表。

s SdExceptions

显示一个对话框,通知最终用户遇到一个共享、锁定(在使用中)或只读文件。

s SdFinish

显示一个对话框,通知最终用户安装完成并提供一个选项的选择,如是否要查看信息文件或运行一个应用程序。

s SdFinishEx

显示一个对话框,通知最终用户安装完成。

s SdFinishReboot

显示一个对话框,通知用户安装完成并提供一个重启Windows 和计算机选项的选择。

s SdInit

准备一个调用Sd对话框函数的安装。

s SdLicense

显示一个许可证协议并给最终用户一个接受或拒绝许可证条款的选项。

s SdLoadString

返回和一个指定资源ID相联系的字符串值。

s SdMakeName

创建一个自定义对话框的节名。该节名在向一个 .iss文件写或从一个.iss文件读时使用。.iss文件由 InstallShield Silent使用。

s SdOptionsButtons

显示一个有用户定义按钮的对话框,提供给最终用户不同选择。

s SdProductName

在脚本对话框的特定静态区中插入你的产品名。

s SdRegisterUser

显示一个可输入用户名和公司名的对话框。

s SdRegisterUserEx

显示一个对话框,最终用户可在里面输入用户姓名、公司名称和应用程序序列号。

s SdSelectFolder

呈现一个对话框,允许最终用户从程序文件夹列表中选择一个文件夹。

s SdSetupType

显示一个对话框,使最终用户能选择三种标准安装类型之一:典型、简易或自定义。

s SdSetupTypeEx

显示一个对话框,允许最终用户选择标准或自定义安装类型。

s SdShowAnyDialog

显示一个资源DLL的通用对话框。当用SdShowAnyDialog函数显示一个对话框时你不能从最终用户接受任何输入。

s SdShowDlgEdit1

显示一个对话框,它有一个单行的编辑区和其它静态控件。

s SdShowDlgEdit2

显示一个对话框,有两个单行的编辑区和其它静态控件。

s SdShowDlgEdit3

显示一个对话框,有三个单行的编辑区和其它静态控件。

s SdShowFileMods

呈现一个对话框,预览对文件的可能修改并允许最终用户同意修改、拒绝修改或要求将修改写到一个文件中。

s SdShowInfoList

在一个对话框中显示一个可滚动的消息列表。

s SdShowMsg

在一个小窗口中显示一个消息。

s SdStartCopy

呈现一个对话框,显示已经由最终用户指定的选项和设置。

s SdWelcome

显示一个通用欢迎。

s SdWelcomeMaint

显示一个在维护安装开始时使用的对话框。

5.1  DialogSetInfo

语法:DialogSetInfo (nInfoType, szInfoString, nParameter);

说明:DialogSetInfo函数修改下列在InstallShield对话框中显示的元件:

s 显示的图象;

s 得到最终用户选择的复选框的风格;

s 指示有效和所需磁盘空间值的精度。

    通过调用DialogSetInfo产生的修改对安装的剩余部分保持为有效或直到它们又被随后的对DialogSetInfo的调用修改。如果你的脚本在调用任何Sd对话框函数前调用DialogSetInfo,在 DialogSetInfo的调用前必须先调用SdInit。否则,对DialogSetInfo的调用无效。

参数:

nInfoType

指定要修改的显示特征。在该参数位置传递下列预定义的常量之一:

DLG_INFO_USEDECIMAL:缺省时,显示的指示组件大小、有效磁盘空间和所需磁盘空间的值被四舍五入到最近的KB或MB。下列对话框受该参数影响:ComponentDialog, SdComponentDialog, SdComponentDialog2, SdComponentDialogAdv 和SdComponentMult。

DLG_INFO_KUNITS:缺省时,显示的指示组件大小、有效磁盘空间和所需磁盘空间的值以KB为度量。传递该参数同时nParameter设置为FALSE时则以MB为度量显示这些值。下列对话框受该参数影响:SdComponentTree, ComponentDialog, SdComponentDialog, SdComponentDialog2, SdComponentDialogAdv 和SdComponentMult。

DLG_INFO_ALTIMAGE:指定一个显示在该对话框中的候选位图。如果nParameter设置为TRUEszInfoString必须指定在该对话框显示的图象。该参数应用于所有在对话框右上角显示标准安装图象的InstallShield对话框(和图象显示在对话框左边一个大图象的右上角的Welcome, SdWelcome和SdFinish对话框)。更多的信息可查看下面参数nParameter处描述的“当nInfoType是.DLG_INFO_ALTIMAGE”。

    由SetDisplayEffect设置的显示效果不能应用到交替图象,通常它们显示时没有任何特殊效果.

DLG_INFO_CHECKSELECTION:指定选择方法将由nParameter传递的常量确定。注意SdComponentTree不支持改变复选框类型。

szInfoString

当DLG_INFO_ALTIMAGE传递给nInfoType时,该参数指定要显示的候选位图的文件名和一组位图属性(可选)。如果包括了位图属性,传递给该参数的字符串必须如下格式化:

 “位图文件名;透明标志;<未用>;<未用>;透明色”

s 位图文件名:

指定位图文件名。如果文件名未限定(也就是说,如果它不包括一个驱动器指示符和路径),InstallShield在SUPPORTDIR查找该位图。

s 透明标志:

指示是否透明显示位图。当该标志是1(真)时,该位图中所有其颜色是由szInfoString的透明色参数指定的RGB值的部分都透明显示。该参数缺省为0(非透明)。

s 未用:

格式行的这些部分都被忽略,但它们必须被包括。也就是说,格式行串必须包括四个分号,三个分号在透明标志和透明色之间。

s 透明色:

指示透明显示的颜色。透明色必须用一个RGB值来表示,也就是,三个数值型值由逗号分隔。如果没有指定值,即使透明标志设置为1,位图也不会被透明显示。

    下面的例子将显示MyBitmap.bmp文件的位图,它位于SUPPORTDIR文件夹。位图所有黑色部分(RGB值为000)将被透明显示。

"MyBitmap.bmp;1;;;0,0,0"

注意:标准位图为57×53。一个候选位图必须也约是这个大小。如果位图大于这个大小,它会在标题区中垂直置中,位图的右边将和对话框的右边对齐。(在Welcome, SdWelcome, 和 SdFinish对话框中,位图的右边将和它所呈现在的更大的位图的右边对齐)。位图左边将尽可能扩展到对话框左边。位图扩展在对话框标题区下的任何部分将被剪切掉。如果位图小于57×53,它将被正确显示,但它将不被调整大小或被扩展。

    当缺省位图被重新装入或nInfoType不是DLG_INFO_ALTIMAGE时该参数被忽略

nParameter

和nInfoType相联系一起来指定对话框特性。

s 当nInfoType是DLG_INFO_CHECKSELECTION时,传递下列预定义常量之一来指定复选框风格:

CHECKBOX:指定Windows 3.1风格的复选框。

CHECKBOX95:指定标准(Windows 95 风格)复选框。如果不调用DialogSetInfo,这是缺省的复选框风格。

CHECKLINE:指定复选行风格的复选框。

CHECKMARK:指定复选标记风格的复选框。

s 当nInfoType是DLG_INFO_ALTIMAGE,传递下列预定义常量之一来指定显示位图:

-1:指定对话框必须显示缺省位图。

TRUE:指定由szInfoString指示的位图必须在随后的对话框中使用,就如前面在szInfoString下描述的一样。

s 当nInfoType是DLG_INFO_KUNITS 或DLG_INFO_USEDECIMAL时,传递下列预定义常量之一来指定大小如何显示:

TRUE:指定大小按照nInfoType指示的显示。

FALSE:指定大小按照缺省风格显示。

返回值:

0 表明函数成功设置了指定的风格。

< 0 表明函数未能设置该风格。

注解:

·为预览调用DialogSetInfo的效果,运行InstallShield范例,改变对话框的属性(通过单击属性按钮),然后检验如SdComponentDialog2和 SdComponentMult的对话框的改变。

·每次你要改变一个对话框的细节方面时都必须调用DialogSetInfo。

你可以使用DLG_INFO_ALTIMAGE参数来激活16色、256色或真彩色(24位)的位图。注意当256色的位图在16色系统中显示或真彩色位图在256色系统中显示时会有颜色失真。建议你指定一与目标系统的颜色模式兼容的候选图象。

5.2  SdAskDestPath

语法:SdAskDestPath (szTitle, szMsg, svDir, nReserved);

说明:SdAskDestPath函数创建一个对话框,允许最终用户选择一个候选目标路径。当你单击对话框中的浏览按钮,SelectDir函数被调用来打开一个二次对话框使最终用户可以选择一个存在的文件夹或输入一个新的文件夹名。

参数:

szTitle

指定对话框标题。为显示缺省标题(“选择文件夹”) ,给该参数传递一个空字符串(””)。

szMsg

指定显示在对话框的文本。该文本被考虑为一个静态控件。在你的消息字符串中使用%P位置夹来插入已经由先前的一个对SdProductName的调用指定的产品名称(如果有)。为显示对话框的缺省指示,传递一个空字符串(“”)。

svDir

指定缺省选定的目录名。返回由最终用户选定的目录名。

nReserved

给该参数传递0。不允许其它值。

返回值:

NEXT (1):指定Next按钮被单击。

BACK (12):指定Back按钮被单击。

注解:

·运行在静止方式的安装程序必须创建在调用SdAskDestPath前不存在的新文件夹。这样可以确保确认对话框不被显示。没有这一步骤,则需要两个响应文件来处理两种可能情况。

5.3  SdAskOptions

语法:SdAskOptions (szTitle, szMsg1, szMsg2, szId, szComponents, nExclusiveFlag);

说明:SdAskOptions 函数创建一个对话框,提供安装选项。你可以使用复选框或单选钮作为选择按钮。显示在按钮旁边的信息从一组选项中检索得到。选项的缺省数目是4。必要时你可以增加或减去组中选项的数目。

    SdAskOptions运行于由系统变量MEDIA指定的当前媒体上。在安装的初始化中,InstallShield给MEDIA赋缺省媒体名(“DATA”),它和你的文件媒体库(Data1.cab)相联系。为显示脚本创建的组件,可按4.6中的相同步骤进行:

  如果你的安装不使用一个安装类型的对话框,你必须在调用SdAskOptions之前调用ComponentSetupTypeSet来指定一个已经在IDE安装类型窗格中定义的安装类型

  系统变量MEDIA的值在安装初始化过程中被设置为’DATA’。如果你改变该变量的值来指向一个脚本创建组件组,你必须在调用ComponentTransferData, CreateShellObjects, 或 CreateRegistrySet前将值修改回’DATA’。注意运行一个基于事件的脚本的安装中,ComponentTransferData被自动调用。

参数:

szTitle

指定对话框标题。为显示缺省标题(“选择组件”) ,给该参数传递一个空字符串(””)。

szMsg1

指定显示在对话框的消息。该静态区的ID是801。为显示该对话框的缺省指示,给该参数传递一个空字符串(“”)。

szMsg2

指定在对话框显示的一个二次消息。该静态区的ID是802

SzId

指定一个候选数值型对话框ID。仅使用以字符串形式表示的数值型ID(例如,ID 13001 为“13001”)。你可以拷贝SdAskOptions对话框资源,对它做有限的修改,给它一个唯一数值型ID,并通过以字符串传递它的ID给szId来调用对话框。参考下面的注解部分。为创建标准的四选项的SdAskOptions对话框,给该参数传递一个空字符串(“”)。

szComponents

指定要显示的包含子部件的组件名称。子部件前面有复选框或单选钮。为显示所有顶层组件,给该参数传递一个空字符串(””)。

SdAskOptions在由系统变量MEDIA指定的文件媒体库或脚本创建组件组中查找所需组件。

nExclusiveFlag

指定你要在对话框中显示的按钮类型。在该参数位置传递下列预定义常量之一:

EXCLUSIVE:指定单选钮。

NONEXCLUSIVE:指定复选框。

  如果你的安装包括必需的可见的组件,不要调用SdAskOptions来得到安装选项。而是,以非静止方式调用ComponentDialog, SdComponentDialog, SdComponentDialogAdv, SdComponentMult 或SdAskOptionsList。

  必需组件可以这么理解:当活动组件(在组件窗格中被选择的组件)被安装时,你要添加组件到必须被安装的组件列表中或从该组件列表中删除组件。

其中控件有:

s 所需组件(列表框):列出活动组件要求的组件。

s 组件(列表框):列出所有定义的组件。活动组件有一个复选标记;所需组件有一个红圈和斜杠。

s 添加(按扭):将在组件列表框中选定的组件添加到所需组件列表框中。

s 删除(按扭):从所需列表框中删除选定的组件。

返回值:

NEXT (1):表明单击了Next按钮。

BACK (12):表明单击了Back按钮。

注解:

·你可以通过使用资源编辑器拷贝SdAskOptions对话框资源(位于_isres.dll),对拷贝作有限的修改,并给它一个唯一ID来创建多个SdAskOptions类型的对话框。当你调用SdAskOptions并在参数szId传递对话框的自定义拷贝时,自定义拷贝被显示。限制对存在的静态文本区作编辑修改和增加静态文本区。不建议添加需要处理程序的控件,因为它需要改变SdAskOptions的资源脚本。

5.4  SdAskOptionsList

语法:SdAskOptionsList (szTitle, szMsg, szComponents, nStyle);

说明:SdAskOptionsList函数创建一个对话框,显示一个自定义安装的组件列表。

SdAskOptionsList运行在由系统变量MEDIA指定的当前媒体上。在安装的初始化中,InstallShield给MEDIA赋缺省媒体名(“DATA”),它和你的文件媒体库(Data1.cab)相联系。为显示脚本创建的组件,按4.6中的相同步骤进行。

系统变量MEDIA的值在安装初始化过程中被设置为’DATA’。如果你改变该变量的值来指向一个脚本创建组件组,你必须在调用ComponentTransferData, CreateShellObjects, 或 CreateRegistrySet前将值修改回’DATA’。注意运行一个基于事件的脚本的安装中,ComponentTransferData被自动调用。

  如果你的安装不使用一个安装类型对话框,你必须在调用SdAskOptionsList前调用ComponentSetupTypeSet来指定一个已经在IDE安装类型窗格中定义的安装类型。

参数:

szTitle

指定对话框标题。为显示缺省标题(“选择组件”) ,给该参数传递一个空字符串(””)。

szMsg

指定对话框中显示的消息。为显示该对话框的缺省指示,给该参数传递一个空字符串(””)。

szComponents

指定要显示的包含子部件的组件名称。为显示所有顶层组件,给该参数传递一个空字符串。

SdAskOptionsList在由系统变量MEDIA指定的文件媒体库或脚本创建组件组中查找所需的组件。

nStyle

指定最终用户的选择是否受限。在该参数位置传递下列预定义常量之一:

EXCLUSIVE:允许最终用户仅从列表中选择一个项目。如果任何szComponents’的子部件是所需组件,则不使用EXCLUSIVE模式。

NONEXCLUSIVE:允许最终用户从列表中选择多个项目,包括多个非邻接的选项。两个按钮被显示:Select All 和Clear All,,允许通过单击一个按钮选择所有选项或清除所有选项。

返回值:

NEXT (1):表明单击了Next按钮。

BACK (12):表明单击了Back按钮。

5.5  SdBitmap

语法:SdBitmap (szTitle, szMsg, szBitmap);

说明:SdBitmap函数在一个对话框中显示一个位图。位图所允许的最大大小是宽440个像素点、高275个像素点。仅当你使用一个资源编辑器来修改SdBitmap对话框资源使得显示消息的控件成为可见时,你才可以在SdBitmap对话框中显示一个消息,查看下面注解。

参数:

szTitle

指定对话框标题。为显示缺省标题(“欢迎”) ,给该参数传递一个空字符串(””)。

szMsg

给该参数传递一个空字符串(“”),除非你使用一个资源编辑器修改SdBitmap对话框来显示一个消息,查看下面注解。

szBitmap

指定要显示的位图的文件名和一组位图属性(可选)。如果包括位图属性,传递给该参数的字符串必须如下格式化:

 “位图文件名;透明标志‘3-D标志;背景颜色

s 位图文件名

指定位图文件名。如果文件名未限定(也就是说,如果它不包括一个驱动器指示符和路径),InstallShield在SUPPORTDIR查找该位图。

s 透明标志

指示是否透明显示位图。当该标志是1(真)时,该位图所有紫红色(RGB值:2550255)部分都透明显示。该参数的缺省值是0(非透明)。

s 3-D 标志

指示是否要绕着包含位图的静态区的边缘增加一个3-D边框。缺省为0(非3D边框)。

s 背景色

指示作为静态文本区背景的颜色。 注意该颜色仅当位图小于它所显示在的静态文本区或透明标志设置为1并且位图有透明区域时才会可见。背景色必须以RGB值表示,也就是三个由逗号分隔的数值型的值。

  下面的例子将从MyBitmap.bmp文件显示位图,它位于SUPPORTDIR文件夹。该位图将被置于一个黑色背景上。它有一个3-D边框。该位图的任何紫红色的部分将被显示为背景色-黑色。

    "MyBitmap.bmp;1;1;0,0,0"

返回值:

NEXT (1):表明单击了Next按钮。

BACK (12):表明单击了Back按钮。

注解:

·你可以使用一个资源编辑器来修改SdBitmap对话框资源,使得一个传递给参数szMsg的消息字符串在SdBitmap对话框中显示。

·SdBitmap 对话框资源包括在_isres.dll中。该资源包含一个静态文本控件,它接收由参数szMsg传递的字符串。然而,该静态文本控件缺省为在SdBitmap对话框中不可查看(在对话框下)。SdBitmap也使用一个静态文本控件显示位图图象。你可以调整位图图象静态文本控件的大小和移动消息静态文本控件进入对话框来查看。

改变位图图象静态文本控制的大小可能影响你位图图象的显示。位图图象必须足够小来避免当它被SdBitmap在位图图象静态文本控制置中时被剪切掉。

·该函数不支持透明位图。如果你以该函数来使用一个透明位图,透明部分将被正常显示。

·SdBitmap不支持图元文件。

5.6  SdComponentDialog

语法:SdComponentDialog (szTitle, szMsg, svDir, szComponents);

说明:使用SdComponentDialog函数创建一个对话框。显示当前媒体上用户可以安装的的组件列表和每个组件将占用的磁盘空间。该函数和SdComponentDialogAdv相同。

    目标目录可以使用Browse按钮来修改;在其它驱动器上的可用磁盘空间可以使用Disk Space 按钮来检查。

SdComponentDialogt运行在由系统变量MEDIA指定的当前媒体上。在安装的初始化中,InstallShield给MEDIA赋缺省媒体名(“DATA”),它和你的文件媒体库(Data1.cab)相联系。为显示脚本创建的组件,按4.6中的相同步骤进行。

    如果你的安装不使用一个安装类型的对话框,你必须在调用SdComponentDialog之前调用ComponentSetupTypeSet来指定一个已经在IDE安装类型窗格中定义的安装类型。

    系统变量MEDIA的值在安装初始化过程中被设置为’DATA’。如果你改变该变量的值来指向一个脚本创建组件组,你必须在调用ComponentTransferData, CreateShellObjects, 或 CreateRegistrySet前将值修改回’DATA’。注意运行一个基于事件的脚本的安装中,ComponentTransferData被自动调用。

参数:

szTitle

指定对话框标题。为显示缺省标题(“选择组件”) ,给该参数传递一个空字符串(””)。

szMsg

指定对话框中显示的消息。为显示该对话框的缺省指示,给该参数传递一个空字符串(””)。

svDir

指定缺省选定的文件夹名;返回最终用户选择的文件夹名。注意由svDir指定的目标文件夹不会自动赋给TARGETDIR或其它任何系统变量。如果它要被使用,为将svDir值提供给安装,你必须将它赋给TARGETDIR或一个脚本定义的变量。

    我们建议用户给该参数传递TARGETDIR而不是一个字符串变量。如果你在该参数不传递TARGETDIR,当最终用户在一个不同驱动器选择一个目标时显示在对话框的所需磁盘空间不会被重算。

szComponents

指定其子部件要被显示的组件名称。为显示所有主组件,给该参数传递一个空字符串(“”)。

SdComponentDialog在由系统变量MEDIA指定的文件媒体库或脚本创建组件组中查找所需的组件。

返回值:

NEXT (1):表明单击了Next按钮。

BACK (12):表明单击了Back按钮。

注解:

·一个组件在被选定前,其大小都显示为0。一旦它已经被选定,它的实际大小被显示。

·若有必要,组件名被截尾来允许显示最大可能的组件大小。显示大小的必要空间依赖于最大组件大小本身(2GB)、当前使用的组件大小选项、和用来在对话框显示组件信息的字体。组件大小选项由DialogSetInfo函数设置。

·一旦显示最大可能大小所需的空间被确定,若有必要,所有组件名均自动被截尾以适应剩余空间。这确保组件名不会覆盖组件大小。

·注意在这种方法下需要较少空间显示大小(或没有被选)的组件的名称仍然会被截尾。为了最大化执行并确保组件名完整显示,使组件名小于在组件对话中的有效空间。

·如果由svDir指定的缺省文件夹不存在于最终用户系统,除非最终用户按下Browse按钮并按下列步骤从选择文件夹对话框创建它,否则它不会被创建。因此,无论何时用户想在调用ComponentTransferData(必要时,它会创建文件夹)前指定一个要使用的缺省文件夹,为了确定该文件夹是否存在,当SdComponentDialog返回时都必须调用ExistDir 。如果不存在,调用CreatDir在最终用户系统上创建它。

·运行在静止方式(silent mode )的安装,如果在调用SdComponentDialog前文件夹不存在,必须创建该新文件夹。这样可以确保确认对话框不被显示。没有这一步,需要两个响应文件来处理两个可能情况。

·Disk Space按钮的ID是101。该按钮自动显示有效磁盘空间对话框。如果愿意你可以删除该按钮/选项。目录静态区需要一个ID851。列表框ID有一个多选项风格。

5.7  SdComponentDialog2

语法:SdComponentDialog2 (szTitle, szMsg, szDir, szComponents);

说明:SdComponentDialog2函数创建一个对话框,显示一个用户可以安装的当前媒体上的组件列表。显示在组件窗口中的组件可以有子部件。如果一个组件有子部件,Change按钮将成为有效。单击Change按钮将生成选择子部件对话框,可以作进一步的选择。对每个组件和子部件,也提供说明。当用户选择或高亮显示组件时,其说明显示在对话框的说明区下。

    SdComponentDialog2运行在由系统变量MEDIA指定的当前媒体上。在安装的初始化中,InstallShield给MEDIA赋缺省媒体名(“DATA”),它和你的文件媒体库(Data1.cab)相联系。为显示脚本创建的组件,按4.6中的相同步骤进行。

    如果你的安装不使用一个安装类型的对话框,你必须在调用SdComponentDialog之前调用ComponentSetupTypeSet来指定一个已经在IDE安装类型窗格中定义的安装类型。

    系统变量MEDIA的值在安装初始化过程中被设置为’DATA’。如果你改变该变量的值来指向一个脚本创建组件组,你必须在调用ComponentTransferData, CreateShellObjects, 或 CreateRegistrySet前将值修改回’DATA’。注意运行一个基于事件的脚本的安装中,ComponentTransferData被自动调用。

参数:

szTitle

指定对话框标题。为显示缺省标题(“选择组件”) ,给该参数传递一个空字符串(””)

szMsg

指定对话框中显示的消息。为显示该对话框的缺省指示,给该参数传递一个空字符串(””)。

szDir

指定目标目录的名称(目标位置)。注意由svDir指定的目标文件夹不会自动赋给TARGETDIR或其它任何系统变量。如果它要被使用,为将svDir值提供给安装,你必须将它赋给TARGETDIR或一个脚本定义的变量。

szComponents

指定其子部件要被显示的组件名称。为显示所有主组件,给该参数传递一个空字符串(“”)。

    SdComponentDialog2在由系统变量MEDIA指定的文件媒体库或脚本创建组件组中查找所需的组件。

返回值:

NEXT (1):表明单击了Next按钮。

BACK (12):表明单击了Back按钮。

注解:

·一个组件在被选定前,其大小都显示为0。一旦它已经被选定,它的实际大小被显示。 

·若有必要,组件名称被截尾来允许显示最大可能的组件大小。显示大小的必要空间依赖于最大组件大小本身(2GB),当前使用的组件大小选项,和用来在对话框显示组件信息的字体。组件大小选项由DialogSetInfo函数设置。

·一旦显示最大可能大小所需的空间被确定,若有必要,所有组件名均自动被截尾以适应剩余空间。这确保组件名不会覆盖组件大小。

·注意在这种方法下需要较少空间显示大小(或没有被选)的组件的名称仍然会被截尾。为了最大化执行并确保组件名完整显示,使组件名小于在组件对话框中的有效空间。

·当且仅当被选定的组件有任何子部件时Change按钮才为有效。否则,它将变灰。

·如果一个组件被撤消选定,它的子部件也必须缺省为撤消选定。同样的,如果一个组件的所有子部件缺省为撤消选定,则父组件也必须缺省为撤消选定。有关组件和子部件的缺省选定设置请参考ComponentAddItem函数。

·当用户选定一个显示在对话框中的组件或子部件时,缺省选定设置被清除。如果用户撤消选定一个组件,所有它的子部件也将被撤消选定。如果用户撤消选定一个组件的所有子部件,该组件也将被撤消选定。

5.8  SdComponentDialogAdv

语法:SdComponentDialogAdv (szTitle, szMsg, svDir, szComponents);

说明:使用SdComponentDialogAdv函数创建一个对话框。显示当前媒体上用户可以安装的组件列表和每个组件将占用的磁盘空间。该函数和SdComponentDialog相同。

    目标目录可以使用Browse按钮来修改:同时在其它驱动器上的可用磁盘空间可以使用Disk Space 按钮来检查。

SdComponentDialogtAdv运行在由系统变量MEDIA指定的当前媒体上。在安装的初始化中,InstallShield给MEDIA赋缺省媒体名(“DATA”),它和你的文件媒体库(Data1.cab)相联系。为显示脚本创建的组件,按4.6中的相同步骤进行。

  如果你的安装不使用一个安装类型的对话框,你必须在调用SdComponentDialog之前调用ComponentSetupTypeSet来指定一个已经在IDE安装类型窗格中定义的安装类型。

    系统变量MEDIA的值在安装初始化过程中被设置为’DATA’。如果你改变该变量的值来指向一个脚本创建组件组,你必须在调用ComponentTransferData, CreateShellObjects, 或 CreateRegistrySet.前将值修改回’DATA’。注意运行一个基于事件的脚本的安装中,ComponentTransferData被自动调用。

参数:

szTitle

指定对话框标题。为显示缺省标题(“选择组件”) ,给该参数传递一个空字符串(””)。

szMsg

指定对话框中显示的消息。为显示该对话框的缺省指示,给该参数传递一个空字符串(””)。

svDir

指定缺省选定的文件夹名;返回最终用户选择的文件夹名。注意由svDir指定的目标文件夹不会自动赋给TARGETDIR或其它任何系统变量。如果它要被使用,为将svDir值提供给安装,你必须将它赋给TARGETDIR或一个脚本定义的变量。

    我们建议用户给该参数传递TARGETDIR而不是一个字符串变量。如果你在该参数不传递TARGETDIR,当最终用户在一个不同驱动器选择一个目标时显示在对话框的所需磁盘空间不会被重算。

szComponents

指定其子部件要被显示的组件名称。为显示所有主组件,给该参数传递一个空字符串(“”)。

SdComponentDialogAdv在由系统变量MEDIA指定的文件媒体库或脚本创建组件组中查找所需的组件。

返回值:

NEXT (1):表明单击了Next按钮。

BACK (12):表明单击了Back按钮。

注解:

请参阅5.7。

5.9  SdComponentMult

语法:SdComponentMult (szTitle, szMsg, szTargetDir, szComponents);

说明:SdComponentMult函数创建一个对话框,提供给最终用户一个选项来从当前媒体上的一个组件和子部件列表中选择。对话框有两个子窗口。如果被选定的组件有子部件,它们在第二个窗口中显示。对话框也显示所需的磁盘空间(依赖于被选定的组件和子部件)和目标目录的空闲磁盘空间来在安装过程中提供帮助。组件和/或子部件的说明可以通过单击它的名称在说明区中查看。

有关组件和子部件的详细情况请参阅7.1。

参数:

szTitle

指定对话框标题。为显示缺省标题(“选择组件”) ,给该参数传递一个空字符串(””)

szMsg

指定对话框中显示的消息。为显示该对话框的缺省指示,给该参数传递一个空字符串(””)。

szTargetDir

指定将应用程序安装到的目标文件夹名。注意由svTargetDir指定的目标文件夹不会自动赋给TARGETDIR或其它任何系统变量。如果它要被使用,为将svTargetDir值提供给安装,你必须将它赋给TARGETDIR或一个脚本定义的变量。

szComponents

指定其子部件要被显示的组件名称。为显示所有主组件,给该参数传递一个空字符串(“”)。

SdComponentMult在由系统变量MEDIA指定的文件媒体库或脚本创建组件组中查找所需的组件。

    太长不能适应选择窗口的组件名将被从右截尾以适应有效空间。

返回值:

NEXT (1):表明单击了Next按钮。

BACK (12):表明单击了Back按钮。

注解:

请参阅5.7。

5.10  SdComponentTree

语法:SdComponentTree (szTitle, szMsg, szDir, szComponents, nLevel);

说明:SdComponentTree函数显示一个对话框,它包含下列内容:

s 一个树形控件,最终用户可以在其中选定在他们系统上需要的组件和不选定在他们系统上不需要的组件。

s 选定组件的说明(组件属性说明文本)。

s 需要用来执行树形控件中指定的文件操作的磁盘空间,和由szDir指定路径的磁盘的有效空间。(所需磁盘空间的计算考虑在szDir指定的磁盘的簇的大小。)

SdComponentTree运行在由系统变量MEDIA指定的当前媒体上。在安装的初始化中,InstallShield给MEDIA赋缺省媒体名(“DATA”),它和你的文件媒体库(Data1.cab)相联系。为显示脚本创建的组件,按4.6中的相同步骤进行。

参数:

szTitle

指定对话框标题。为显示缺省标题(“选择组件”) ,给该参数传递一个空字符串(””)。

szMsg

指定对话框中显示的消息。为显示该对话框的缺省指示,给该参数传递一个空字符串(””)。szDir

指定在计算所需和有效磁盘空间中用到的磁盘的路径。

szComponents

指定其子部件要被显示的组件名称。为显示所有主组件,给该参数传递一个空字符串(“”)。

nLevel

指定当对话框第一次被显示时在树形控件中打开多少层组件和子部件。(例如,nLevel为2,则对话框首次显示时,第三和更低层的子部件在树形控件中被关闭。)

返回值:

NEXT (1):表明单击了Next按钮。

BACK (12):表明单击了Back按钮。

5.11  SdConfirmNewDir

语法:SdConfirmNewDir (szTitle, szDir, nReserved);

说明:SdConfirmNewDie函数创建一个对话框,显示一个文件夹名和一个确认的提示。如果最终用户单击Yes按钮,则一个新文件夹自动由该函数创建。

参数:

szTitle

指定对话框标题。为显示缺省标题(“确认新文件夹”) ,给该参数传递一个空字符串(””)。

szDir

指定要确认的目录名称。(通过调用SdAskDestPath来得到该信息)

nReserved

给该参数传递0。不允许其它值。

返回值:

YES (1):表明单击了Yes按钮并且目录已经被确认并将被创建。

NO (0):表明单击了No按钮,并且指定的目录不会被创建。

<0:表明Yes被选定了但函数未能创建新目录。

5.12  SdConfirmRegistration

语法:SdConfirmRegistration (szTitle, szName, szCompany, szSerial, nReserved);

说明:SdConfirmRegistration函数创建一个对话框,显示用户名、公司名称和序列号。如果在该对话框的任何区域输入一个空字符串(””),显示的区域将为空。

参数:

szTitle

指定对话框标题。为显示缺省标题(“注册认可”) ,给该参数传递一个空字符串(””)。

szName

指定最终用户姓名。

szCompany

指定公司名称。

szSerial

指定序列号。如果该参数包含一个空字符串(””),序列号区不在对话框显示。

nReserved

给该参数传递0。不允许其它值。

返回值:

YES (1):表明单击Yes按钮。

NO (0):表明单击No按钮。

注解:

·为得到序列号和最终用户的姓名和公司名,调用SdRegisterUserEx。只要得到姓名和公司名,调用SdRegisterUser。

5.13  SdDisplayTopics

语法:SdDisplayTopics (szTitle, szMsg, listTopics, listDetails, nReserved);

说明:SdDisplayTopics 函数创建一个对话框,显示基于主题数据(资料)的信息。对话框提供一个标题然后是标题的主题和说明。你可以修改说明文本的字体风格以让它和标题(主题)文本想区别。消息和主题标题通常是粗体。可使用该对话框显示帮助主题、例子等。

参数:

szTitle

指定对话框标题。为显示缺省标题(“自定义安装帮助”) ,给该参数传递一个空字符串(””)。

szMsg

指定对话框中显示的消息。为显示该对话框的缺省指示,给该参数传递一个空字符串(””)。

listTopics

指定要显示的包含主题的字符串列表。

listDetails

指定包含每个主题的说明的字符串列表。

nReserved

给该参数传递0。不允许其它值。

返回值:

NEXT (1):表明单击了Next按钮。

BACK (12):表明单击了Back按钮。

注解:

·消息静态区必须以801ID。主题标识符ID必须在802-849的范围之内。说明区ID必须在851-899的范围之内。

·静态说明区的空间由对话框的大小固定。你不能动态改变listDetails列表的空间。如果主题和说明的数目小于静态区的数目,在空白区不显示任何内容,但对话框大小不会改变。

5.14  SdExceptions

语法:SdExceptions (nExceptionType, szFilename);

说明:SdExceptions函数显示一个对话框,通知最终用户遇到一个共享,锁定(在使用中)或只读的文件并提供适当的选项。

参数:

nExceptionType

指定遇到文件问题的类型。在该参数位置传递下列预定义常量之一:

SHARED:一个共享的文件,其引用计数器已经减为0

READONLY:遇到一个只读文件。

LOCKED:遇到一个锁定文件。

szFilename

指定遇到问题的文件名。

返回值:

ERR_RETRY (4):表明选定了Retry按钮。

ERR_IGNORE (5):表明选定了Ignore按钮。

ERR_YES (6):表明选定了Yes按钮。

ERR_NO (7):表明选定了No按钮。

ERR_PERFORM_AFTER_REBOOT (100):表明选定了Reboot按钮。

<0:表明对话框不能被显示。

5.15  SdFinish

语法:SdFinish (szTitle, szMsg1, szMsg2, szOpt1, szOpt2, bvOpt1, bvOpt2);

说明:SdFinish函数显示一个对话框,通知最终用户安装已完成并给用户信息或选择。SdFinish对话框显示两个消息和两个复选框选择选项。例如,你可能想要提供给用户查看README文件或运行应用程序的选择。

    为在消息中或复选框说明中插入产品名称,在szMsg1, szMsg2, szOpt1, 和szOpt2传递的字符串中使用位置夹%P

参数:

szTitle

指定对话框标题。为显示缺省标题(“安装完成”) ,给该参数传递一个空字符串(””)。

szMsg1

指定在对话框顶端显示的消息。为显示通知用户安装完成的缺省指示,给该参数传递一个空字符串(””)。

szMsg2

指定在对话框底部显示的消息。为显示缺省指示(“单击Finish按钮完成安装”),给该参数传递一个空字符串(””)。

szOpt1

指定显示在第一个复选框旁边的文本。给该参数传递一个空字符串(“”)来隐藏复选框。

szOpt2

指定显示在第二个复选框旁边的文本。给该参数传递一个空字符串(“”)来隐藏复选框。

bvOpt1

返回第一个复选框的选择状态(TRUEFALSE)。

bvOpt2

返回第二个复选框的选择状态(TRUEFALSE)。

返回值:

NEXT (1):表明单击了Finish按钮。

注解:

·SdFinish没有选项来终止安装和重启最终用户的计算机。当SdFinish返回时,安装继续执行。当有必要提供给用户重启的选项时,可用调用SdFinishReboot来代替。

·因为SdFinish被设计为宣告安装结束,所以Back按钮被禁用。

5.16  SdFinishEx

语法:SdFinishEx (szTitle, szMsg1, szMsg2, szOpt1, szOpt2, bvOpt1, bvOpt2);

说明:SdFinishEx函数调用SdFinish或SdFinishReboot来显示一个对话框,通知最终用户安装已完成并给用户信息或选择。如果系统变量BATCH_INSTALL等于FALSE(表明安装过程中没有遇到锁定文件),SdFinishEx调用SdFinish来显示对话框。如果BATCH_INSTALL等于TRUESdFinishEx调用SdFinishReboot来显示对话框。

    为在消息中或复选框说明中插入产品名称,在szMsg1, szMsg2, szOpt1, 和szOpt2传递的字符串中使用位置夹%P

参数:

参数和SdFinish的相同。如果BATCH_INSTALL等于TRUE,这些参数被忽略并调用 SdFinishReboot(“”,””,SYS_BOOTMACHINE,””,0)。

返回值:

0:表明调用了SdFinish。

NEXT (1):表明调用SdFinishReboot并且最终用户不重启计算机。

<0:表明调用SdFinishReboot并且最终用户选择重启计算机,但重启失败。

5.17  SdFinishReboot

语法:SdFinishReboot (szTitle, szMsg1, nDefOption, szMsg2, nReserved);

说明:SdFinishReboot函数在你的安装结尾宣告安装完成并提供给用户重启系统的选项。重启系统允许修改Autoexec.bat,Config.sys和一些.ini文件使其起作用。

    SdFinishReboot对话框在静态文本区中显示两个消息。用参数szMsg1和szMsg2来设置这些区域的值。为在消息中或复选框说明中插入产品名称,在szMsg1和szMsg2传递的字符串中使用位置夹%P

参数:

szTitle

指定对话框标题。为显示缺省标题(“安装完成”) ,给该参数传递一个空字符串(””)。

szMsg1

指定在对话框顶端显示的消息。为显示通知用户安装完成的缺省指示,给该参数传递一个空字符串(””)。

nDefOption

指定一个缺省单选按钮选项选择。在该参数位置传递下列预定义常量之一:

SYS_BOOTMACHINE:安装结束时重启计算机。

0:不重启计算机。.

szMsg2

指定显示在对话框底部的文本,提供用户要做什么的信息。为显示缺省指示,传递一个空字符串(””)。

nReserved

给该参数传递0。不允许其它值。

返回值:

WILL_REBOOT:表明用户选择重启系统。

NEXT (1):表明用户没有选择重启系统或Windows。

<0:表明用户选择重启系统或Windows,但重启失败。

注解:

·因为当其它InstallShield实例运行时,InstallShield将尽力不重启计算机,所以你必须在允许SdFinishReboot重启Windows或系统前关闭所有其它InstallShield实例。另外,你给用户的消息必须要求他们以后若要重启系统,则他们必须确保首先关闭所有其它的应用程序。

·InstallShield自动确保锁定的.dll和.exe文件在下一次系统启动时将被更新。

·因为SdFinishReboot被设计为宣告安装结束,所以Back按钮被禁用。

5.18  SdInit

语法:SdInit ( );

说明:SdInit函数准备一个调用Sd对话框函数的安装:装入所需的资源字符串,还原最小化的InstallShield窗口,并指定在Sd对话框中Windows 95风格的复选框。

参数:

该函数没有参数。

返回值:

0:表明安装为调用Sd对话框函数作好初始化。

1:表明为调用Sd对话框函数,安装已经被初始化。

注解:

·该函数由每个Sd函数自动调用。没有必要显式调用SdInit,除非你的脚本在调用任何Sd对话框函数前调用了DialogSetInfo。这种情况下,你的脚本必须在调用DialogSetInfo前调用SdInit;否则对DialogSetInfo的调用不起任何作用。

5.19  SdLicense

语法:SdLicense (szTitle, szMsg, szQuestion, szLicenseFile);

说明:SdLicense函数显示一个对话框,包含一个在多行编辑区的许可证协议。许可证协议保存在一个由参数szLicenseFile指定的文本文件中。

    用户可以上下滚动来阅读协议,然后必须选择Yes、No或Enable、Back按钮。因为这可能是你将显示的第一个对话框,你可能要禁止Back按钮。如果用户选择了Yes,安装将继续。如果用户选择了No,InstallShield将显示退出安装对话框。

参数:

szTitle

指定对话框标题。为显示缺省标题(“软件许可证协议”) ,给该参数传递一个空字符串(””)。

szMsg

指定显示在多行编辑区上方的静态文本区中的消息。为显示缺省指示,传递一个空字符串。

szQuestion

指定显示在多行编辑区下方的静态文本区中的文本。你可能在这儿放置一个问题,用户必须选择Yes 或 No来响应它。为显示缺省指示,给该参数传递一个空字符串(“”)。

szLicenseFile

指定包含许可证协议的文本文件名。该文件必须被加到安装文件窗格中适当语言文件夹中。

返回值:

YES (1):表明用户选择了Yes按钮。

BACK (12):表明用户选择了Back按钮。

注解:

·该函数不能返回NO,因为,如果用户选择了No按钮,将显示退出安装对话框。

·你也可以通过输入全限定名,在引号中,或一个Universal Naming Convention (UNC)路径来指定szLicenseFile。

·在szLicenseFile中的文本在超过1024个字符的一行后必须包含硬回车。该文件的文本必须以1024字节为间隔读入字符串列表。如果从szLicenseFile的文本不包含硬回车,单词会在SdLicense对话框中意外地回绕。

5.20  SdLoadString

语法:SdLoadString (nID);

说明:SdLoadString函数返回与指定的资源ID相联系的字符串值。安装引擎首先在_isuser.dll(如果该文件存在)中查找资源;如果资源没有找到,安装引擎在_isres.all中查找。

参数:

nID

指定一个在_isuser.dll或 _isres.dll中的字符串资源的标识符。一些nID的有效值可以在InstallShield  Professional  文件夹的 Script\Ifx\Include 的子文件夹的 Ifx.h文件中找到。

返回值:

非空字符串值

SdLoadString成功检索到字符串值。

空字符串值(“”)

表明SdLoadString失败。

5.21  SdMakeName

语法:SdMakeName (svSection, szDlg, szUnused, nvDlgName);

说明:SdMakeName函数为一个自定义对话框创建一个节名。该节名在写到一个.iss文件或从中读出时被使用,由InstallShiled Silent使用。

参数:

svSection

指定节名(InstallShield使用变量szDlg和 nvDlgName来给该变量置一个值)。该值由SilentReadData和 SilentWriteData.使用。

szDlg

指定自定义对话框的名称。

szUnused

该参数不使用,给它传递一个空字符串(“”)。

nvDlgName

指定记录SdMakeName被由szDlg命名的对话框调用的次数的计数器。InstallShield自动增加该计数器。为每个自定义对话框使用一个唯一的变量名。(可参阅下面的注解)

返回值:  无。

注解:

·为使节被适当命名,你必须在每个不同的自定义对话框的第四个参数使用一个唯一的变量名。做到这一点的简单方法是在szDlg使用对话框名来命名该变量。例如,当szDlg是“MyDlgOne”,命名在第四个参数的变量为nvMyDlgOne;当szDlg是“MyDlgTwo”,命名该变量为nvMyDlgTwo。

5.22  SdOptionsButtons

语法:SdOptionsButtons (szTitle, szMsg, listButtons, listDescription);

说明:SdOptionsButtons函数显示一个对话框,包含一到四个位图按钮和一个简短的对每个按钮的文本说明。

参数:

szTitle

指定对话框标题。为显示缺省标题(“选择组件”) ,给该参数传递一个空字符串(””)。

szMsg

指定显示在对话框的消息。为显示该对话框缺省指示(“请选择你要安装的组件”),给该参数传递一个空字符串(””)。

listButtons

指定一个包含一到四个元素的字符串列表。每个元素是一个格式化的指定显示在按钮上的位图的字符串。一个按钮将被用来显示列表中的每个字符串元素。字符串列表元素必须有下列格式:

 “@<位图ID>;<位图图标标志>;<透明颜色>”

由@符号开始字符串并后随位图ID<位图图标标志>域是1(真)或0(假),表明位图被显示时在<透明颜色>域指定的颜色是否要透明显示。<透明颜色>域指定一个RGB值,它是位图的透明颜色。注意分号将ID和图标标志、图标标志和透明颜色分隔。

更多的信息可参阅下面的注解部分。

listDescription

指定一个包含一到四个字符串元素的字符串列表,每个相对应于参数listButtons中的一个字符串。每个字符串是一个和它相应按钮一起显示的文本说明。

返回值:

NEXT (1):表明单击了NEXT按钮。

BACK (12):表明单击了Back按钮。

101:对应于listButtons中的第一个字符串元素的按钮被选定。

102:对应于listButtons中的第二个字符串元素的按钮被选定。

103:对应于listButtons中的第三个字符串元素的按钮被选定。

104:对应于listButtons中的第四个字符串元素的按钮被选定。

注解:

·虽然SdOptionsButtons可以被使用为一个安装类型对话框,但还是推荐使用SdSetupTypeEx对话框来允许最终用户选择一个安装类型,因为它不需要任何用户化。注意如果你调用SdOptionsButtons来得到最终用户的安装类型选择,你必须然后调用ComponentButtons来为你的安装建立选择的安装类型。

·InstallShield提供可以被该函数调用的四个_isres.dll中的缺省位图。这些位图有从1200112004ID和在脚本范例中相应的典型、可移植、简易和自定义安装类型。

·如果你使用该对话框作其它用途或你想要使用_isres.dll中提供的类型之外的安装类型,你必须将你自己的自定义按钮加入到_isuser.dll对话框模板中并且然后在你的安装中包含自定义的_isuser.dll。

·为防止用户没有单击一个特定按钮时就退出对话框,在你调用SdOptionsButtons前调用Disable函数来禁止Next按钮。

5.23  SdProductName

语法:SdProductName (szProductName);

说明:SdProductName函数使得你的产品名对所有的%P位置夹都有效。%P位置夹在一些Sd对话框中的静态文本区中找到。另外,一些Sd对话框函数,如SdFinish,允许你在作为函数参数的字符串中包含%P。

参数:

szProductName

指定被安装的产品名。该名称将取代在Sd对话框的适当静态区出现的任何产品名位置夹(%P)。

返回值:

该函数没有返回值。

5.24  SdRegisterUser

语法:SdRegisterUser (szTitle, szMsg, svName, svCompany);

说明:SdRegisterUser函数创建一个对话框,检索用户姓名和公司名称。如果svName和svCompany都包含空字符串,InstallShield将从注册表中得到用户姓名和公司名称。

    仅当两个编辑区都存在数据时Next按钮才被激活。如果InstallShield可以从系统查找缺省姓名和公司名称,Next按钮被自动激活。完成时,SdRegisteruser调用RegDBSetDefaultRoot来将注册表开关键设置给HKEY_CLASSES_ROOT。

参数:

szTitle

指定对话框标题。为显示缺省标题(“用户信息”) ,给该参数传递一个空字符串(””)。

szMsg

指定显示在对话框的消息。该文本被看作为一个静态控制。为显示该对话框缺省指示,给该参数传递一个空字符串(””)。

svName

返回由用户输入的姓名。注意SdRegisterUser显示该参数的初始值由用户进行编辑。如果svName和svCompany都是空字符串,在目标系统注册表中被找到的用户姓名将被显示来进行编辑。

svCompany

返回由用户输入的公司名称。注意SdRegisterUser显示该参数的初始值由用户进行编辑。如果svName和svCompany都是空字符串,在目标系统注册表中被找到的公司名称将被显示来进行编辑。

返回值:

NEXT (1):表明单击了NEXT按钮。

BACK (12):表明单击了Back按钮。

5.25  SdRegisterUserEx

语法:SdRegisterUserEx (szTitle, szMsg, svName, svCompany, svSerial);

说明:SdRegisterUserEx函数创建一个对话框,检索用户姓名、公司名称和序列号。如果svName和svCompany都包含空字符串,InstallShield将从注册表得到用户姓名和公司名称。

    仅当三个编辑区都存在数据时Next按钮才被激活。你不能让任何区域空白。

完成时,SdRegisteruser调用RegDBSetDefaultRoot来将注册表开关键设置给HKEY_CLASSES_ROOT。

参数:

szTitle

指定对话框标题。为显示缺省标题(“用户信息”) ,给该参数传递一个空字符串(””)。

szMsg

指定显示在对话框的消息。该文本被看作为一个静态控件。为显示该对话框缺省指示,给该参数传递一个空字符串(””)。

svName

返回由用户输入的姓名。注意SdRegisterUserEx显示该参数的初始值由用户进行编辑。如果svName和svCompany都是空字符串,在目标系统注册表中被找到的用户姓名将被显示来进行编辑。

svCompany

返回由用户输入的公司名称。注意SdRegisterUserEx显示该参数的初始值由用户进行编辑。如果svName和svCompany都是空字符串,在目标系统注册表中被找到的公司名称将被显示来进行编辑。

svSerial

返回用户输入的序列号。你可以使用该信息并把它写入一个文件或者把它显示在一个确认对话框中。

返回值:

NEXT (1):表明单击了NEXT按钮。

BACK (12):表明单击了Back按钮。

5.26  SdSelectFolder

语法:SdSelectFolder (szTitle, szMsg, svDefGroup);

说明:SdSelectFolder函数显示供选择的程序文件夹。SdSelectFolder允许你提供一个缺省选择。用户也可以输入一个新的文件夹名。SdSelectFolder将仅返回被选择的或输入的文件夹名。它不能创建文件夹。

参数:

szTitle

指定对话框标题。为显示缺省标题(“选择程序文件夹”) ,给该参数传递一个空字符串(””)。

szMsg

指定显示在对话框的消息。该文本被看作为一个静态控件。为显示该对话框缺省指示,给该参数传递一个空字符串(””)。

svDefGroup

返回被选文件夹的名称。

返回值:

NEXT (1):表明单击了NEXT按钮。

BACK (12):表明单击了Back按钮。

注解:

·运行在Windows NT下的一个安装中,如果在调用SdSelectFolder前调用ProgDefGroup,由SdSelectFolder显示的程序文件夹(公用或专用)将依赖于传递给ProgDefGroupType的参数。

5.27  SdSetupType

语法:SdSetupType (szTitle, szMsg, svDir, nReserved);

说明:SdSetupType函数显示一个对话框允许最终用户选择三种标准安装类型之一:典型、简易或自定义。这些安装选项显示时有标准描述文本。如果你想加入其它安装类型或改变显示的安装类型名或描述,调用SdSetupTypeEx来替代。

    对话框也显示一个缺省的目标路径。一个Browse按钮装入一个对话框,允许最终用户通过输入一个新文件夹名或从一个列表中选择存在的文件夹来修改目标路径。如果最终用户输入一个不存在的文件夹名,将显示一个消息框来询问是否要创建该文件夹。如果最终用户单击Yes,该函数自动创建指定文件夹。指定文件夹的全限定路径在svDir返回。

如果最终用户在使用组件对话框来选定和撤消选定与已选安装类型相联系的组件后,返回到安装类型对话框,那么那些选择将丢失。这种情况发生是因为SdSetupType函数每次被调用时自动根据选中的安装类型复位缺省组件选项。

参数:

szTitle

指定对话框标题。为显示缺省标题(“安装类型”) ,给该参数传递一个空字符串(””)。

szMsg

指定显示在对话框的消息。该文本被看作为一个静态控件。为显示该对话框缺省指示,给该参数传递一个空字符串(””)。

svDir

指定一个缺省文件夹名。返回最终用户所选的文件夹名。

nReserved

保留为将来使用。给该参数传递0

返回值:

TYPICAL (301):表明用户选择典型安装。

COMPACT (302):表明用户选择简易安装。

CUSTOM (303):表明用户选择自定义安装。

BACK (12):表明单击Back按钮。

5.28  SdSetupTypeEx

语法:SdSetupTypeEx (szTitle, szMsg, szReserved, svSetupType, nReserved);

说明:SdSetupTypeEx函数显示一个对话框,当你指定除典型、简易和自定义之外的安装类型时,允许最终用户选择安装类型。

参数:

szTitle

指定对话框标题。为显示缺省标题(“安装类型”) ,给该参数传递一个空字符串(””)。

szMsg

指定显示在对话框的消息。为显示该对话框缺省指示,给该参数传递一个空字符串(””)。

szReserved

给该参数传递一个空字符串(“”)。不允许其它值。

svSetupType

指定一个缺省安装类型和返回由最终用户选择的安装类型。为使在列表中的第一次安装为缺省选择,给该参数传递一个空字符串(“”)。在该参数返回的字符串将和在IDE中指定的安装类型名相匹配。

nReserved

给该参数传递0。不允许其它值。

返回值:

0:表明SdSetupTypeEx成功。

BACK (12):表明单击了Back按钮。

5.29  SdShowAnyDialog

语法:SdShowAnyDialog (szTitle, szID, nID, nReserved);

说明:SdShowAnyDialog函数显示一个自定义或改进型对话框。该函数仅推荐给高级用户使用。

参数:

szTitle

指定对话框标题。为显示缺省标题(“欢迎”) ,给该参数传递一个空字符串(””)。

szID

指定标识对话框的标识符字符串。如果该参数包含一个空字符串(“”),SdShowAnyDialog使用nID的值。

nID

指定标识对话框的数值型值。如果szID包含一个空字符串(“”),该参数被忽略。

nReserved

给该参数传递0。不允许其它值。

返回值:

NEXT (1):表明单击了Next按钮。

BACK (12):表明单击了Back按钮。

注解:

·为了使用SdShowAnyDialog函数,你必须知道你希望显示的_isres.dll中的改进型对话框或_isuser.dll中的自定义对话框的ID。

·如果对话框只有静态控件,你不需要修改SdShowAnyDialog脚本文件。但如果你的对话框有其它控件,为了处理用户的反馈,你必须修改Sdsadlg.rul文件,位于你的InstallShield程序文件夹中的Script/Srt文件夹,

5.30  SdShowDlgEdit1

语法:SdShowDlgEdit1 (szTitle, szMsg, szField1, svEdit1);

说明:SdShowDlgEdit1函数创建一个通用对话框,显示一个消息和一个单行编辑区。你可以为该对话框指定一个标题。

参数:

szTitle

指定对话框标题。为显示缺省标题(“编辑数据”) ,给该参数传递一个空字符串(””)。

szMsg

指定显示在对话框的消息。为在该消息包含由先前调用SdProductName设置的产品名称,在该消息的任何地方插入位置夹%P。当消息被显示时,%P由产品名称代替。

szField1

指定显示在编辑区左边的域名。缺省的域名是“域1:”;为显示缺省名称,给该参数传递一个空字符串(“”)。可以被显示的字符数最大约为10。实际的最大值依赖于域名中每个字符的组合宽度。如果域名超出有效空间,则当对话框被显示时它将从右被截尾。

svEdit1

指定编辑区的初始值;当对话框被关闭时,返回编辑区的值。

返回值:

NEXT (1):表明单击了Next按钮。

BACK (12):表明单击了Back按钮。

5.31  SdShowDlgEdit2

语法:SdShowDlgEdit2 (szTitle, szMsg, szField1, szField2, svEdit1, svEdit2);

说明:SdShowDlgEdit2函数创建一个通用对话框,显示一个消息和两个单行编辑区。你可以为该对话框指定一个标题。

参数:

szTitle

指定对话框标题。为显示缺省标题(“编辑数据”) ,给该参数传递一个空字符串(””)。

szMsg

指定显示在对话框的消息。为在该消息包含由先前调用SdProductName设置的产品名称,在该消息的任何地方插入位置夹%P。当消息被显示时,%P由产品名称代替。

szField1

指定显示在第一个编辑区左边的域名。缺省的域名是“域1:”;为显示缺省名称,给该参数传递一个空字符串(“”)。可以被显示的字符数最大约为10。实际的最大值依赖于域名中每个字符的组合宽度。如果域名超出有效空间,则当对话框被显示时它将从右被截尾。

szField2

为第二个编辑区指定域名。缺省为“域2:”。

svEdit1

指定第一个编辑区的初始值;当对话框被关闭时,返回第一个编辑区的值。

svEdit2

指定第二个编辑区的初始值;当对话框被关闭时,返回第二个编辑区的值。

返回值:

NEXT (1):表明单击了Next按钮。

BACK (12):表明单击了Back按钮。

5.32  SdShowDlgEdit3

语法:SdShowDlgEdit3 (szTitle, szMsg, szField1, szField2, szField3, svEdit1, svEdit2, svEdit3);

说明:SdShowDlgEdit2函数创建一个通用对话框,显示一个消息和三个单行编辑区。你可以为该对话框指定一个标题。

参数:

szTitle

指定对话框标题。为显示缺省标题(“编辑数据”) ,给该参数传递一个空字符串(””)。

szMsg

指定显示在对话框的消息。为在该消息包含由先前调用SdProductName设置的产品名称,在该消息的任何地方插入位置夹%P。当消息被显示时,%P由产品名称代替。

szField1

指定显示在第一个编辑区左边的域名。缺省的域名是“域1:”;为显示缺省名称,给该参数传递一个空字符串(“”)。可以被显示的字符数最大约为10。实际的最大值依赖于域名中每个字符的组合宽度。如果域名超出有效空间,则当对话框被显示时它将从右被截尾。

szField2

为第二个编辑区指定域名。缺省为“域2:”。

szField3

为第二个编辑区指定域名。缺省为“域2:”。

svEdit1

指定第一个编辑区的初始值;当对话框被关闭时,返回第一个编辑区的值。

svEdit2

指定第二个编辑区的初始值;当对话框被关闭时,返回第二个编辑区的值。

svEdit3

指定第三个编辑区的初始值;当对话框被关闭时,返回第三个编辑区的值。

返回值:

NEXT (1):表明单击了Next按钮。

BACK (12):表明单击了Back按钮。

5.33  SdShowFileMods

语法:SdShowFileMods (szTitle, szMsg, szTargetFile, szAltFile, listChanges, nvSelection);

说明:SdShowFileMods函数创建一个对话框,显示你想要对一个文件进行的修改。下面这些选择是有效的:

s 修改目标文件。

s 修改替代文件,它是目标文件的拷贝,但非联合修改。

s 不作任何修改。SdShowFileMods不对文件作修改。你必须使用适当的文件函数把那些修改写入你的脚本。

参数:

szTitle

指定对话框标题。为显示缺省标题(“修改文件”) ,给该参数传递一个空字符串(””)。

szMsg

指定显示在对话框的消息。为显示该对话框的缺省指示,给该参数传递一个空字符串(“”)。

szTargetFile

指定要修改的文件名。它将和第一个单选按钮一起显示。

szAltFile

如果最终用户决定要作修改,指定该文件的替代名。这将和第二个单选按钮一起显示。为使用sztargetFile指定的扩展名为.bak的文件名,给该参数传递一个空字符串(””)。

listChanges

指定字符串列表名,它包含对文件所作修改的列表。该列表位于一个多行编辑区,允许最终用户选择要实现的修改。

nvSelection

返回最终用户选择的按钮的ID:

101: “让安装修改<szTargetFile>文件。”

102: “保存对<szAltFile>所要求的修改。”

103: “不作任何修改。”

返回值:

NEXT (1):表明单击了Next按钮。

BACK (12):表明单击了Back按钮。

5.34  SdShowInfoList

语法:SdShowInfoList (szTitle, szMsg, listID);

说明:SdShowInfoList函数创建一个对话框,显示一个可滚动的消息列表。

参数:

szTitle

指定对话框标题。为显示缺省标题(“信息”) ,给该参数传递一个空字符串(””)。

szMsg

指定显示在信息框上方一行的消息。如果消息长于一行,将被从右截尾。如果消息包含一个换行符(\n),换行符后的文本不被显示。为显示缺省消息(”Text”),给该参数传递一个空字符串(“”)。

listID

指定显示在对话框的消息列表。所有显示在对话框的消息为只读。

返回值:

NEXT (1):表明单击了Next按钮。

BACK (12):表明单击了Back按钮。

注解:

·多行编辑区必须为只读。

·SdShowInfoList可以显示大约多达57200个字符的列表。

5.35  SdShowMsg

语法:SdShowMsg (szMsg, bShow);

说明:SdShowMsg函数打开或关闭一个小的非模态窗口,显示由szMsg指定的消息。当bShow为TRUE,窗口被打开,消息显示在窗口中,并且继续脚本中下一个语句的处理。注意SdShowMsg窗口被置于安装窗口的中央。当bShow为FALSE时,szMsg被忽略并且关闭SdShowMsg窗口。

参数:

szMsg

指定显示在窗口的消息。为显示缺省消息(“安装正查找已安装的组件”),给该参数传递一个空字符串(“”)。当bShow为FALSE时该参数被忽略。

bShow

指定是否要打开或关闭窗口。在该参数位置传递下列预定义常量之一:

TRUE:如果窗口没有打开则打开它。

FALSE:如果窗口打开了则关闭它。

返回值:

返回值总为0

注解:

·SdShowMsg函数提供了一个简单方法使得脚本进程继续的同时,可以将一个显示丰富资料的消息保留在屏幕上。

·当SdShowMsg窗口是打开的,随后的对SdShowMsg(第二个参数为TRUE)的调用被忽略。为改变消息,你必须首先以第二个参数为FALSE调用SdShowMsg来关闭窗口,然后以第二个参数为TRUEszMsg为新的消息再次调用SdShowMsg。

·SdShowMsg窗口水平调整大小来在一行上显示szMsg的值。如果消息的长度超过窗口的最大宽度,消息被截尾以适应窗口。

·SdShowMsg被设计为单行显示消息。不要在szMag中嵌入换行符(\n)

5.36 SdStartCopy

语法:SdStartCopy (szTitle, szMsg, listData);

说明:SdStartCopy函数创建一个多行编辑区,显示安装过程中所作的设置和选择。为按需改变设置,用户可以单击对话框的Back按钮来返回到以前的对话框。在检索用户的选择后,开始文件传输处理之前调用SdStartCopy。

    使用一个字符串列表来收集安装过程中得到的信息。然后你可以将该字符串列表传递给SdStartCopy的参数listData。SdStartCopy将显示该列表并允许用户在继续文件传输处理之前确认这些信息是正确的。

参数:

szTitle

指定对话框标题。为显示缺省标题(“开始拷贝文件”) ,给该参数传递一个空字符串(””)。

szMsg

指定显示在多行编辑区上方的静态文本区的消息。为显示该对话框的缺省指示,给该参数传递一个空字符串(“”)。

listData

指定从最终用户检索得的信息字符串列表。SdStartCopy会自动将每个元素放置到多行编辑区。如果列表为空,该多行编辑区将被隐藏并且只有静态文本区为可见。

返回值:

NEXT (1):表明用户选定了Next按钮。

BACK (12):表明用户选定了Back按钮。

5.37  SdWelcome

语法:SdWelcome (szTitle, szMsg);

说明:SdWelcome函数显示一个对话框,欢迎最终用户。

参数:

szTitle

指定显示在对话框标题部分的文本。为显示缺省标题(“欢迎”) ,给该参数传递一个空字符串(””)。

szMsg

指定显示在欢迎对话框中的消息。为在该消息中包含先前调用SdProductName而设置的产品名称,在该消息的任意位置插入一个位置夹%P。当该消息被显示时,%P被产品名称代替。为显示缺省欢迎消息(“欢迎进入%P安装程序。该程序将在你的计算机上安装%P”),给该参数传递一个空字符串(“”)。

返回值:

NEXT (1):表明单击了Next按钮。

5.38  SdWelcomeMaint

语法:SdWelcomeMaint (szTitle, szMsg, nType);

说明:SdWelcomeMaint函数显示一个对话框 ,在一个维护型安装(也就是,一个已经被运行的安装的重运行)的开始时使用。该对话框包含修改、修复、删除选项按钮。

参数:

szTitle

指定对话框标题。为显示缺省标题(“欢迎”) ,给该参数传递一个空字符串(””)。

szMsg

指定显示在对话框的消息。为显示该对话框的缺省指示,给该参数传递一个空字符串(“”)。

nType

指定哪个选项按钮为缺省选择。你必须在该参数位置传递下列预定义常量之一,使在对话框中正确显示:

MODIFY:修改按钮为缺省选择。

REPAIR:修复按钮为缺省选择。

REMOVEALL:删除按钮为缺省选择。

返回值:

MODIFY (301):表明当单击Next按钮后修改按钮被选定。

REPAIR (302):表明当单击Next按钮后修复按钮被选定。

REMOVEALL (303):表明当单击Next按钮后删除按钮被选定。

6  自定义对话框函数

    下列函数处理自定义对话框进程。你使用一个资源编辑器来创建对话框并可用这些函数把它插入脚本中。

    任何你可以创建的Windows对话框都可以被使用在一个安装脚本中。对话框可以有单行或多行编辑框,单个或多个选择列表框,组合框,单选钮,复选框和下按按扭作为标准控件。对于更复杂的控件,则提供高级函数,如CmdGetHwndDlg, LOWORD和HIWORD。

s CmdGetHwndDlg

检索一个对话框的句柄。

s CtrlClear

删除一个编辑、静态、列表框或组合框控件。

s CtrlDir

用一个目录列表或一个文件列表来填充一个列表框或组合框。

s CtrlGetCurSel

从一个列表框或组合框中选择项目。

s CtrlGetMLEText

从一个多行编辑或静态区域中检索文本。

s CtrlGetMultCurSel

从一个多选列表框中返回选定项目。

s CtrlGetState

从一个对话框中检索一个单选扭,复选框或下按按扭控件的状态。

s CtrlGetSubCommand

检索在一个WaitOnDialog函数调用后对控件执行的操作。

s CtrlGetText

从一个编辑区,一个静态区或一个组合框的编辑区中检索文本。

s CtrlPGroups

检索在目标系统上存在的程序组列表。

s CtrlSelectText

选择显示在一个编辑区中文本。

s CtrlSetCurSel

在一个列表框或组合框中查找和设置当前选择。

s CtrlSetFont

指定对话框中一个控件的字体。

s CtrlSetList

把一个列表的内容放至一个列表框或组合框中。

s CtrlSetMLEText

设置在一个多行编辑区中的文本。

s CtrlSetMultCurSel

设置在一个多选列表框中的当前选择。

s CtrlSetState

设置一个复选框,单选钮或下按按扭的当前状态。

s CtrlSetText

设置在一个编辑区,一个静态文本区或一个组合框的编辑区中的文本。

s DefineDialog

用InstallShield注册一个自定义对话框。

s EndDialog

关闭一个自定义对话框。

s EzDefineDialog

用InstallShield注册一个自定义对话框。

s GetFont

检索一个字体的处理程序。

s HIWORD

从一个32位的整数中检索高位字。

s LOWORD

从一个32位的整数中检索低位字。

s ReleaseDialog

释放一个对话框的关联内存。

s SdMakeName

SdMakeName为一个自定义对话框创建一个节名。该节名在向一个.iss文件写或从一个.iss文件中读时使用,.iss文件由InstallShield Silent使用。

s SilentReadData

指示InstallShield Silent为一个自定义对话框读取.iss文件对话数据。

s SilentWriteData

指示InstallShield Silent为一个自定义对话框写对话数据到.iss文件。

s WaitOnDialog

显现一个自定义对话框。

6.1  CmdGetHwndDlg

语法:CmdGetHwndDlg (szDialogName);

说明:CmdGetHwndDlg函数检索由szDialogName标识的对话框的窗口句柄。该对话框必须已经由EzDefineDialog (或DefineDialog)定义,并以通过调用WaitOnDialog而被初始化。

参数:

szDialogName

指定已经由EzDefineDialog (或DefineDialog)定义的对话框的名称。

返回值:

> 0:由szDialogName指定的对话框的窗口句柄。

< 0:CmdGetHwndDlg未能检索到句柄。请确认szDialogName指向的是一个已经正确定义并已被初始化的对话框。

注解:

·当一个对话框用WaitOnDialog函数初始化时,则为它分配一个窗口句柄;该句柄只和该对话框关联,直到一个对EndDialog的调用来关闭该对话框。如果你调用WaitOnDialog来打开在你脚本中先前已经被打开和关闭的一个对话框,你必须再次调用CmdGetHwndDlg来得到新句柄。老的句柄不再有效。

·通常,CmdGetHwndDlg在一个自定义对话框的DLG_INIT例程中被调用。该对话框的句柄被赋给HWND变量来供其它需要它的函数使用。

6.2  CtrlClear

语法:CtrlClear (szDialogName, nControlID);

说明:CtrlClear函数清除各种控件的内容;它删除一个自定义对话框中一个单行或多行编辑区,静态文本区,单或多选列表框或一个组合框的编辑区的内容。

参数:

szDialogName

指定包含有要被删除控件的对话框的名称。

nControlID

指定由szDialogName标识的对话框的控件ID

返回值:

0:CtrlClear成功删除指定控件的内容。

< 0:CtrlClear未能删除对话框的内容。

6.3  CtrlDir

语法:CtrlDir (szDialogName, nControlID, szDir, nItems);

说明:CtrlDir函数用一个与szDir指定的路径或文件名相匹配的文件列表来填充一个列表框或一个组合框控件。你可以在列表中包括文件名,子目录名和磁盘驱动器名。CtrlDir函数仅工作于自定义对话框。

参数:

szDialogName

指定一个对话框的名称。

nControlID

指定列表框或组合框控件的资源ID

szDir

指定全限定路径或全限定文件名,可以包括通配符。

nItems

指定在控件中显示的列表的类型。在该参数位置传递下列预定义常量之一。为包含多个元素类型,将这些常量用按位或操作符(|)组合起来:

DLG_DIR_FILE:创建一个与文件说明szDir匹配的文件的列表。

DLG_DIR_DIRECTORY:创建一个存在于路径说明szDir中的子目录的列表。

DLG_DIR_DRIVE:创建一个驱动器列表。

返回值:

0:CtrlDir成功填充一个对话框中指定的控件。

< 0:CtrlDir未能填充指定控件。

6.4  CtrlGetCurSel

语法:CtrlGetCurSel (szDialogName, nControlID, svText);

说明:CtrlGetCurSel函数从一个自定义对话框中的一个单选列表框或组合框控件中检索当前选定的项目。调用CtrlGetMultCurSel来从多选列表框中检索项目。

参数:

szDialogName

指定包含要被检索的项目的自定义对话框的名称。

nControlID

指定单选框或组合框控件的资源ID

svText

返回nControlID指定的控件中当前被选定的项目。

返回值:

0:CtrlGetCurSel成功检索对话框中当前被选定的项目。

< 0:CtrlGetCurSel未能检索被选定的项目。

6.5  CtrlGetMLEText

语法:CtrlGetMLEText (szDialogName, nControlID, listID);

说明:CtrlGetMLEText函数检索一个自定义对话框中一个多行编辑控件的内容。InstallShield把多行编辑区中的每行放到由listID标识的一个字符串列表中。调用CtrlGetText来检索一个单行编辑区控件的内容。

参数:

szDialogName

指定一个自定义对话框的名称,该对话框包含了其内容要被检索的多行编辑控件。

nControlID

指定多行编辑控件的资源ID

listID

返回nControlID标识的编辑区中的行的一个字符串列表。由listID标识的字符串列表必须已经通过调用ListCreate而被初始化。

返回值:

0:CtrlGetMLEText成功检索一个多行编辑区的内容。

< 0:CtrlGetMLEText未能检索控件的内容。

6.6  CtrlGetMultCurSel

语法:CtrlGetMultCurSel (szDialogName, nControlID, listID);

说明:CtrlGetMultCurSel函数检索一个多选列表框控件中的当前被选定的行。多选列表框的每个被选定行被放到由listID标识的一个字符串列表中。为从一个单选列表框控件中检索被选定的文本,调用CtrlGetCurSel。CtrlGetMultCurSel只使用于自定义对话框。

参数:

szDialogName

指定一个自定义对话框的名称,该对话框包含了其内容要被检索的列表框控件。

nControlID

指定多行编辑控件的资源ID

listID

返回由nControlID标识的列表框中的行。由listID标识的字符串列表必须已经通过调用ListCreat而被初始化。

返回值:

0:CtrlGetMultCurSel成功检索当前选定项目。

< 0:CtrlGetMultCurSel未能检索项目。

6.7  CtrlGetState

语法:CtrlGetState (szDialogName, nControlID);

说明:CtrlGetState函数得到一个自定义对话框中一个复选框或单选钮的当前状态。

参数:

szDialogName

指定包含该控件的对话框的名称。

nControlID

指定其状态要被检索的复选框或单选钮的资源ID

返回值:

BUTTON_CHECKED (-1001):复选框或单选钮被选定。

BUTTON_UNCHECKED (-1002):复选框或单选钮未被选定。

DLG_ERR (-1):CtrlGetState不能确定控件状态。

6.8  CtrlGetSubCommand

语法:CtrlGetSubCommand (szDialogName);

说明:CtrlGetSubCommand函数检索对一个自定义对话框中的一个控件所执行的操作。例如,CtrlGetSubCommand可以告诉你用户单击或双击了一个列表框或组合框控件。它也可以告诉你一个编辑区的内容被修改了。

    高级开发人员可以调用CmdGetHwndDlg来处理附加信息。

参数:

szDialogName

指定自定义对话框的名称。

返回值:

EDITBOX_CHANGE (-1007):编辑框的内容已经改变。

LISTBOX_ENTER (-1008):用户双击了一个列表框项目。

LISTBOX_SELECT (-1009):用户单击了一个列表框项目。

6.9  CtrlGetText

语法:CtrlGetText (szDialogName, nControlID, svText);

说明:CtrlGetText函数从一个自定义对话框中的一个编辑区,静态文本区或按扭控件中检索文本。为从多行编辑区控件中检索文本,调用CtrlGetMLEText。

参数:

szDialogName

指定一个对话框的名称,该对话框包含了其文本要被检索的区域或控件。

nControlID

指定编辑区,静态文本区或下按按扭控件的资源ID

svText

从由nControlID标识的控件或区域中返回的文本。

返回值:

0:CtrlGetText成功检索控件的内容。

< 0:CtrlGetText未能检索内容。

6.10  CtrlPGroups

语法:CtrlPGroups (szDialogName, nControlID);

说明:CtrlPGroups函数将一个现存程序文件夹列表放到一个列表框或组合框控件中。该函数仅工作于自定义对话框。

参数:

szDialogName

Specifies the name of a custom dialog box that contains the control to use.

指定自定义对话框的名称,该对话框包含要使用的控件。

nControlID

指定一个列表框或组合框控件的资源ID

返回值:

0:CtrlPGroups成功把指定的程序文件夹列表放到控件中。

< 0:CtrlPGroups未能把指定的程序文件夹列表放到控件中。

6.11  CtrlSelectText

语法:CtrlSelectText (szDialogName, nControlID);

说明:CtrlSelectText函数选定一个编辑区或一个组合框的编辑区中的所有文本。如果该控件是一个多行编辑区,该函数选定所有行的所有文本。该函数仅工作于自定义对话框。

参数:

szDialogName

指定一个有效对话框的名称,该对话框包含要被选定的编辑区。

nControlID

指定要被选定的编辑区或组合框控件的资源ID

返回值:

0:CtrlSelectText成功选定了区域中的所有文本。

< 0:CtrlSelectText未能选定文本。

6.12  CtrlSetCurSel

语法:CtrlSetCurSel (szDialogName, nControlID, szText);

说明:CtrlSetCurSel函数在指定的列表框或组合框控件中查找一个字符串。如果找到,CtrlSetCurSel选定(高亮显示)该项目。对多选列表框和组合框则调用CtrlSetMultCurSel。CtrlSetCurSel函数仅使用于自定义对话框。

参数:

szDialogName

指定一个有效自定义对话框的名称,该对话框包含要被查找的控件。

nControlID

指定包含查找字符串的控件的资源ID

szText

指定查找字符串。如果该字符串被找到,则被选定(高亮显示)。

返回值:

0:CtrlSetCurSel成功找到和选定了指定的字符串。

< 0:CtrlSetCurSel未能找到和选定指定的字符串。

6.13  CtrlSetFont

语法:CtrlSetFont (szDialogName, hFont, nControlID);

说明:CtrlSetFont函数指定一个自定义对话框中一个控件的字体。在对话框消息处理循环中的DLG_INIT例程中调用该函数。

参数:

szDialogName

指定一个有效对话框的名称。

hFont

指定已经通过调用GetFont而被创建的一个字体的处理程序。

nControlID

指定其字体要被设置的控件的资源ID。为给对话框中的所有控件设置字体,给该参数传递预定义常量ALLCONTROLS。

返回值:

0:CtrlSetFont成功在一个对话框中设置所要求的字体。

< 0:CtrlSetFont未能在一个对话框中设置所要求的字体。

6.14  CtrlSetList

语法:CtrlSetList (szDialogName, nControlID, listID);

说明:CtrlSetList函数把一个字符串列表中的内容放到指定的单或多选列表框或组合框控件中。任何原先存在的内容被包含在listID中的项所置换。InstallShield将字符串列表中的每个元素放到列表框或组合框控件中的每个元素中。

参数:

szDialogName

指定包含列表框或组合框的对话框的名称。

nControlID

指定列表框或组合框的资源ID

listID

指定一个字符串列表的名称,该列表包含要被拷贝到列表框或组合框控件中的元素。

返回值:

0:CtrlSetList成功将字符串的内容放到控件中。

< 0:CtrlSetList未能将字符串的内容放到控件中。

6.15  CtrlSetMLEText

语法:CtrlSetMLEText (szDialogName, nControlID, listID);

说明:CtrlSetMLEText函数设置一个多行编辑框控件中的文本。InstallShield 将listID中的每个字符串分别放进该多行编辑框控件中。该函数仅使用于自定义对话框。

参数:

szDialogName

指定一个对话框的名称。

nControlID

指定一个对话框中的多行编辑框控件的资源ID

listID

指定一个有效字符串列表的名称 ,该列表包含了要被拷贝到多行编辑控件中的元素。

返回值:

0:CtrlSetMLEText将文本设置到控件中。

< 0:CtrlSetMLEText未能设置控件中的文本。

6.16  CtrlSetMultCurSel

语法:CtrlSetMultCurSel (szDialogName, nControlID, szText, nSelectFlag);

说明:CtrlSetMultCurSel函数查找指定的多选列表框或组合框控件。如果nSelectFlag 被设置为TRUE,CtrlSetMultCurSel选定(高亮显示)被找到的项目。该函数仅使用于自定义对话框。

参数:

szDialogName

指定一个自定义对话框的名称。

nControlID

指定对话框中多选列表框或组合框控件的资源ID

szText

指定查找字符串。

nSelectFlag

指示当CtrlSetMultCurSel找到一个项目时是否要高亮显示它。在该参数位置传递下列预定义常量之一:

TRUE:表明该项目要被高亮显示。

FALSE:表明该项目不被高亮显示。

返回值:

0:CtrlSetMultCurSel在控件中找到文本,并根据nSelectFlag所指示的高亮显示它或不高亮显示它。

< 0:CtrlSetMultCurSel未能在控件中找到文本。

6.17  CtrlSetState

语法:CtrlSetState (szDialogName, nControlID, nState);

说明:CtrlSetState函数设置一个自定义对话框中的一个复选框或单选钮的当前状态。当你用一个资源编辑器或对话框编辑器创建单选钮和复选框时,你可以设置它们的某些特性。如果你因一个按扭的性能遇到了困难,则在编辑器中检查该控件的特性。

参数:

szDialogName

指定一个对话框的名称,该对话框包含复选框或单选钮控件。

nControlID

指定复选框或单选钮控件的资源ID

nState

指定按扭控件的新状态。在该参数位置传递下列预定义常量之一:

BUTTON_CHECKED:设置按扭状态为CHECKED。

BUTTON_UNCHECKED:设置按扭状态为UNCHECKED。

返回值:

0:CtrlSetState成功设置复选框或单选钮控件的状态。

< 0:CtrlSetState未能设置该控件的状态。

6.18  CtrlSetText

语法:CtrlSetText (szDialogName, nControlID, szText);

说明:CtrlSetText函数设置一个自定义对话框中一个单行编辑区,静态文本区或按扭控件的文本。为设置多行编辑区中的文本,调用CtrlSetMLEText。

参数:

szDialogName

指定一个对话框的名称。

nControlID

指定其中的文本要被设置的单行编辑区,静态文本区或按扭控件的资源ID

szText

指定放到控件中的文本。

返回值:

0:CtrlSetText成功设置控件中的文本。

< 0:CtrlSetText未能设置控件中的文本。

6.19  DefineDialog

语法:DefineDialog (szDialogName, hInstance, szDLLName, nDialogID, szDialogID, 

  nReserved, hwndOwner, lMsgLevel);

说明:DefineDialog函数定义一个自定义对话框。当你需要指定一个其属性不能由EzDefineDialog指定的对话框的属性时,调用该函数而不是EzDefineDialog。注意DefineDialog不显示自定义对话框。为显示一个自定义对话框,你必须调用WaitOnDialog。

参数:

szDialogName

指定你要定义的自定义对话框的名称。该名称标识该对话框并使用在所有随后对自定义对话框函数的调用中。该对话框的名称是区分大小写的,你必须完全按照你在该参数指定的那样来使用它。

hInstance

指定对话框驻留其中的DLL的实例句柄。如果你在szDLLName指定DLL的全限定名,你可以将该参数指定为0。为得到一个DLL的实例句柄,调用Microsoft Windows API LoadLibrary。

szDLLName

指定包含对话框资源的DLL文件的全限定名。如果你不指定一个路径,InstallShield在Windows 文件夹中查找该DLL。如果在那儿没有找到,InstallShield查找在查找路径中指定的文件夹。如果你用参数hInstance指定DLL的实例句柄,你可以给该参数传递一个空字符串。当对话框位于_isuser.dll时,你可以为该参数指定一个空字符串。如果该参数指定为一个空字符串,InstallShield将自动检测_isuser.dll。

nDialogID

如果你使用一个数字(而不是一个字符串)来标识对话框资源时,该参数指定资源ID。该参数只在szDialogID是一个空字符串时被使用。建议使用该参数而不是szDialogID来标识对话框资源。

szDialogID

如果你使用一个字符串(而不是一个数字)来标识对话框资源时,该参数指定资源ID。如果该参数是一个空字符串,nDialogID被用来标识对话框资源。强烈提议使用nDialogID而不是szDialogID来标识对话框资源。

nReserved

给该参数传递0。不允许其它值。

hwndOwner

指定主窗口的窗口句柄。将该参数指定为HWND_INSTALL来使得InstallShield主安装窗口成为对话框的主窗口。

lMsgLevel

该参数指定哪些窗口消息要被发送到该对话框。你必须用或操作符来将下列常量之一和常量DLG_CENTERED组合:

DLG_MSG_STANDARD:筛选掉大多数Windows消息;只有那些直接和对话框控件关联的被传递到对话框。

DLG_MSG_ALL :传递大多数Windows消息。

返回值:

0:DefineDialog成功定义对话框。

DLG_ERR_ALREADY_EXISTS (-3):你正试图定义一个已经由DefineDialog定义的对话框。你不能用相同的名称定义两个对话框。

DLG_ERR (-1):表示发生一个未确定的错误。

6.20  EndDialog

语法:EndDialog (szDialogName);

说明:EndDialog函数关闭一个自定义对话框。它删除对话框并启动对话框关闭进程。当下列任意一种情况存在时,使用EndDialog:

s Next按扭或其等效已经被处理。

s Cancel按扭或其等效已经被处理。

s Close系统菜单选项已经被选定(该行为发送DLG_CLOSE消息)。

s 用户结束对话框操作的任何其它情况。

参数:

szDialogName

指定要关闭的对话框的名称。

返回值:

0:EndDialog成功关闭对话框。

< 0:EndDialog未能关闭对话框。

注解:

·在调用EndDialog关闭一个自定义对话框后,调用ReleaseDialog函数来释放与该自定义对话框关联的内存。

·只要你还没有调用ReleaseDialog来把对话框从内存删除,你可以就通过调用WaitOnDialog来重新显示一个已经由调用EndDialog关闭的自定义对话框。然而要注意,如果你调用WaitOnDialog来打开一个在你脚本中已经被打开和关闭的对话框时,你必须再次调用CmdGetHwndDlg来得到新句柄。老的句柄不再有效。

6.21  EzDefineDialog

语法:EzDefineDialog (szDialogName, szDLLName, szDialogID, nDialogID);

说明:EzDefineDialog函数定义一个自定义对话框。注意EzDefineDialog不显示自定义对话框。为显示一个自定义对话框,你必须调用WaitOnDialog。

参数:

szDialogName

指定和由szDialogID 或 nDialogID指定的对话框相关联的名称。为处理该对话框,在随后的对自定义对话框函数的调用中使用该名称。注意该对话框的名称是区分大小写的,你必须完全按照你在该参数指定的那样来使用它。

szDLLName

指定包含对话框资源的DLL文件的全限定名。如果你不指定一个路径,InstallShield在Windows 文件夹中查找该DLL。如果在那儿没有找到,InstallShield查找在查找路径中指定的文件夹。如果你用参数hInstance指定DLL的实例句柄,你可以给该参数传递一个空字符串。当对话框位于_isuser.dll时,你可以为该参数指定一个空字符串。如果该参数指定为一个空字符串,InstallShield将自动检测_isuser.dll。

szDialogID

如果你使用一个字符串(而不是一个数字)来标识对话框资源时,该参数指定资源ID。如果该参数是一个空字符串,nDialogID被用来标识对话框资源。强烈提议使用nDialogID而不是szDialogID来标识对话框资源。

nDialogID

如果你使用一个数字(而不是一个字符串)来标识对话框资源时,该参数指定资源ID。该参数只在szDialogID是一个空字符串时被使用。建议使用该参数而不是szDialogID来标识对话框资源。

返回值:

0:EzDefineDialog成功定义对话框。

DLG_ERR_ALREADY_EXISTS (-3):你正试图定义一个已经由EzDefineDialog定义的对话框。你不能用相同的名称定义两个对话框。

DLG_ERR (-1):表示发生一个未确定的错误。

6.22  GetFont

语法:GetFont (szFontName, nPointSize, nAttributes);

说明:GetFont函数建立一个字体并检索它的句柄,你可以使用字体句柄来指定在一个自定义对话框中的控件使用的字体。

参数:

szFontName

指定你要建立的字体的名称。

nPointSize

指定你要建立的字体的点数。

nAttributes

指定字体风格。在该参数位置传递下列预定义常量之一。可以用按位或操作符(|)组合常量来指定多种风格:

STYLE_BOLD:指定一个粗体风格的字体。

STYLE_ITALIC:指定斜体风格。

STYLE_NORMAL:指定一个正常的系统字体。

STYLE_UNDERLINE:指定字符被加下划线。

返回值:

XXXX:XXXX是该字体的句柄。

0:GetFont未能建立所要求的字体。

注解:

·当安装中止时,InstallShield将删除所有由该函数创建的字体。另外,中止时,InstallShield释放所有系统资源。

6.23  HIWORD

语法:HIWORD (lValue);

说明:HIWORD函数从由lValue指定的32位整型值中析取和返回高位字(高16位)。

参数:

lValue

指定要从中析取高16位的32位整数。

返回值:

HIWORD返回lValue的高位字(高16位)。

注解:

·InstallShield的 HIWORD因使用符号扩展而和相应的C的宏不同。因此,如果lValue是一个负数,则由HIWORD返回的值的高位字节用1填充。如有必要,你可以将结果和0xFFFF按位与(AND)来生成一个正数,如下所示:

lValue = HIWORD(lValue);

lValue = lValue & 0xFFFF;

6.24  LOWORD

语法:LOWORD (lValue);

说明:LOWORD函数从由lValue指定的32位整型值中析取和返回低位字(低16位)。

参数:

lValue

指定要从中析取低16位的32位整数。

返回值:

该函数返回整数的低位字(低16位)。

6.25  ReleaseDialog

语法:ReleaseDialog (szDialogName);

说明:ReleaseDialog 函数释放与szDialogName标识的自定义对话框相关联的所有内存。调用EndDialog后调用该函数。在消息处理的case语句外面调用该函数。

参数:

szDialogName

指定要消除的对话框的名称。

返回值:

0:表明函数成功释放和对话框相关联的所有内存。

DLG_ERR (-1):函数失败。对话框名可能是无效的。

DLG_ERR_ENDDLG (-2):在调用EndDialog前调用了ReleaseDialog。你必须首先调用EndDialog来删除对话框。

6.26  SdMakeName

语法:SdMakeName (svSection, szDlg, szUnused, nvDlgName);

说明:SdMakeName函数为一个对话框创建一个节名。该节名在向一个.iss文件写或从一个.iss文件中读时使用,.iss文件由InstallShield Silent使用。

参数:

svSection

指定节名。InstallShield使用变量szDlg 和 nvDlgName来给该变量置一个值。该值由SilentReadData 和SilentWriteData使用。

szDlg

指定对话框的名称,用来创建一个节名。

szUnused

该参数未用;给该参数传递一个空字符串。

nvDlgName

指定计数器,它记录针对szDlg指定的对话框而调用SdMakeName的次数。InstallShield自动递增该计数器。为每个自定义对话框使用一个唯一的变量名。(看下面的注解)

返回值:

无。

注解:

·为正确命名节,你必须为每个不同的自定义对话框在第四个参数使用一个唯一的变量名。要做到这一点的简单的方法是:使用szDlg的对话框名来命名变量。例如,当szDlg 是 "MyDlgOne"时,命名第四个参数的变量为nvMyDlgOne;当szDlg 是 "MyDlgTwo"时,命名变量为nvMyDlgTwo。

6.27  SilentReadData

语法:SilentReadData (szSection, szValName, nValType, svVal, nvVal);

说明:当一个安装运行于静止方式(silent mode)时(带-s开关运行Setup.exe时),SilentReadData函数指示InstallShield Silent如何为一个自定义对话框读取.iss文件对话框数据。注意你可以通过调用SilentWriteData来创建一个.iss文件。

为在你的脚本中使用SilentReadData,构造逻辑结构因而它首先检测来确认安装运行于静止方式。把SilentReadData函数的调用放置在一个测试系统变量MODEif-else语句中,如下所示:

if (MODE=SILENTMODE) then

// 在此调用SilentReadData。

else

// 在此调用一个正常的,non-silent 函数。

endif;

自定义对话框可以是在你的安装脚本中使用函数(如EzDefineDialog 和WaitOnDialog)调用和处理的资源,也可以完全是外部的,如调用DLL中的函数一样被执行。另外一种情况是,你必须使用SilentReadData从.iss文件中检索对话框按扭的返回值(Next、Back、Cancel等等。)和在变量中被设置或返回的值。

参数:

szSection

指定.iss文件中的对话框数据的节的名称。不要包括方括号([ ])。参数szSection的格式为<functionname>-<number>,<functionname>是在脚本中使用的对话框函数名,<number>是在脚本中对话框出现的次数,从0开始。例如,MyDialog函数对话框的第一次出现会有一个szSection值"MyDialog-0",第二次出现则为"MyDialog-1",第三次为"MyDialog-2",如此继续。

szValName

指定出现在.iss文件的对话框数据的节中的值名。每个对话框至少有一个给szValName的值,来标识对话框按扭控件(BACK, NEXT 或 OK, 或 CANCEL)返回的值。其它值名用来标识和其它对话框控件相关联的值和数据。

nValType

标识赋给szValName中的值名的值的数据类型。值本身被保存在svVal 或 nvVal中,视nValType的值而定。在该参数位置传递下列预定义常量之一:

DATA_STRING:赋给szValName中的值名的值是STRING类型。它的值将保存在svValue中。

DATA_NUMBER:赋给szValName中的值名的值是NUMBER类型。它的值将保存在nvValue中。

DATA_COMPONENT:赋给szValName中的值名的值是一个组件名。它的值将保存在svValue中。

DATA_LIST:赋给szValName中的值名的值是一个InstallShield列表的列表ID。它的值将保存在nvValue中。

svVal

指定当nValType是 DATA_STRING 或DATA_COMPONENT时,赋给szValName中的值名的值。

nvVal

指定当nValType是DATA_NUMBER 或 DATA_LIST时,给szValName中的值名的值。

返回值:

0:SilentReadData成功指示InstallShield Silent如何为自定义对话框读取对话框数据。

< 0:SilentReadData未能指示InstallShield Silent如何为自定义对话框读取对话框数据。

注解:

下列情况下SilentReadData将失败(返回值小于0):

s .iss文件未找到。

s 脚本中的对话框次序没有和.iss文件中指定的对话框次序完全匹配。

s 指定的对话框数据节在.iss文件中没有被找到。

s 指定的关键字名没有在指定的对话框数据节中找到。

s 赋给指定的关键字名的值的数据类型和在SilentReadData调用中指定的不匹配。

6.28  SilentWriteData

语法:SilentWriteData (szSection, szValName, nValType, szVal, nVal);

说明:SilentWriteData函数记录安装过程中自定义对话框中所作的选择。该选择数据被写到一个.iss文件中,供InstallShield Silent使用。为在一个安装过程中写写一个.iss文件,带-r开关项运行Setup.exe。

    自定义对话框可以是在你的安装脚本中使用函数(如EzDefineDialog 和WaitOnDialog)调用和处理的资源,也可以完全是外部的,如调用DLL中的函数一样被执行。另外一种情况是,你必须使用SilentReadData从.iss文件中检索对话框按扭的返回值(Next, Back, Cancel,等等。)和在变量中被设置或返回的值。

参数:

与SilentReadData函数的参数相同。

返回值:

0:SilentReadData成功写自定义对话框的对话框数据到Setup.iss中。

< 0:SilentReadData未能写自定义对话框的对话框数据到Setup.iss中。

6.29  WaitOnDialog

语法:WaitOnDialog (szDlgName);

说明:WaitOnDialog函数显示一个自定义对话框。你的脚本可以根据该函数的返回值来处理用户的不同响应。

参数:

szDlgName

指定要显示的对话框的ID。

返回值:

dialog控件ID:接收到WM_COMMAND消息的对话框控件的ID

DLG_CLOSE (-200):该消息作为对话框将要被关闭的信号。

DLG_ERR (-1):如果发生任何错误,则接收到该消息。

DLG_INIT (-100):就在对话框要被显示前接收到该消息。

7  组件函数

下列函数允许你控制文件媒体、创建和处理脚本创建的组件组:

s ComponentAddItem

增加一个新的组件到脚本创建的组件组中。

s ComponentCompareSizeRequired

确定是否有足够的空闲磁盘空间给选定的组件。

s ComponentDialog

呈现一个对话框,允许最终用户选择组件和指定一个目标位置。

s ComponentError

当一个组件函数失败时,返回附加的错误信息。

s ComponentFilterLanguage 

激活和禁用基于语言的筛选(程序)。

s ComponentFilterOS

激活或禁用基于操作系统的筛选。

s ComponentGetData

检索一个组件的有关信息。

s ComponentGetItemSize

确定一个指定组件的大小。

s ComponentGetTotalCost

确定已经被指定的组件安装和卸载所需的总的空间。

s ComponentInitialize

准备供存取的文件媒体库。

s ComponentIsItemSelected

确定指定的组件是否已由最终用户选定。

s ComponentListItems

创建一个文件媒体库中或一个脚本创建的组件组中的组件列表。

s ComponentMoveData

传输和解压缩与文件媒体库中被选组件相关联的文件。

s ComponentReinstall

配置安装,使得下一个对ComponentTransferData的调用执行上一次安装运行时指定的文件传输。

s ComponentRemoveAll

配置安装,使下一个对ComponentTransferData的调用卸载掉安装。

s ComponentSelectItem

选定或撤消选定组件。

s ComponentSetData

为指定的组件设置属性和数据。

s ComponentSetTarget

指定一个用户定义的变量,放置在一个组件的<TARGETDIR>域。

s ComponentTransferData

执行已经被指定的组件安装和卸载。

s ComponentSetupTypeEnum

列举与指定的文件媒体库相关联的安装类型。

s ComponentSetupTypeGetData

检索和一个指定的已经在InstallShield IDE中创建的安装类型相关联的数据。

s ComponentSetupTypeSet

选择与指定的安装类型相关联的所有组件。

s ComponentTotalSize

以字节为单位计算选定的组件和子部件的总的大小。

s ComponentValidate

确认整个文件媒体库的或在文件库媒体中的一个指定组件的口令。

s SdSetupType

显示一个对话框,使最终用户选择三个标准安装类型:典型、简明或自定义中的一个。

s SdSetupTypeEx

显示一个对话框,使最终用户选择标准和自定义的安装类型。

7.1  ComponentAddItem

语法:ComponentAddItem (szComponentSet, szComponent, nDataSize, bSelected);

说明:ComponentAddItem函数增加一个组件到一个脚本创建的组件组中。如果一个由szComponentSet指定的脚本创建组件组不存在,它将被创建。每次要增加一个组件到给定的脚本创建组件组中,都要调用ComponentAddItem。你可以创建多个脚本创建组件组,每个都有一个唯一的名称(参数szComponentSet)。

    为显示一个供选择的单级组件,使用ComponentDialog, SdComponentDialog, 或SdComponentDialogAdv。使用SdComponentDialog2或r SdComponentMult来显示组件和它们的子部件。

    该函数不能使用到文件媒体库。

参数:

szComponentSet

指定要增加一项的脚本创建的组件组的名称。如果脚本创建组件组不存在,ComponentAddItem将创建它。

szComponent

指定要增加的组件名称。不要使用一个空字符串(“”)。

下面是有关指定在函数调用中的组件和子部件的信息:

(指在函数调用中的组件和子部件) 

s 组件是一个涉及一组文件组和/或子部件的通用术语。一个子部件也只是一个组件。它位于其它组件下面,这与和文件夹和子文件夹的关系相似。

s “顶层组件”是在分层结构中的最高层组件。顶层组件从不作为子部件被引用。

s 一些InstallShield组件函数要求你指向一单个组件,而其它的要求你指向多个组件。

为指向一单个组件,使用该组件的名称。为指向一个子部件,使用一个路径形式的表达式,其中分层结构中引向该组件的每个组件的名称由双反斜杠分隔。例如,为指定顶层组件帮助文件下的子部件教学,在你的脚本中使用下列表达式。

szComponent = "Help Files\\Tutorials";

为引用教学下的子部件CBT,使用下列表达式:

szComponent = "Help Files\\Tutorials\\CBT";

s 一些组件和安装类型对话框函数,如SdComponentMult,显示多个组件和它们的子部件。这些情况下,你可指向多个组件,只要指定在分层结构中就在它们上层的组件即可。如果组件是顶层组件,使用一个空字符串(“”)来引用它们。

例如,如果你传递一个空字符串给SdComponentMult函数,在组件窗口中将显示你的文件媒体库中的所有顶层组件或你的脚本创建的组件组中的所有顶层组件,依赖于系统变量MEDIA的值。所有子部件将显示在Subcomponents窗口中。

s 另一方面,如果你传递一单个顶层组件(如上例中的帮助文件)给SdComponentMult函数,它将在Components窗口中显示它的子部件(如上例,在教学层)和在Subcomponents窗口中显示它的下一个更低层的子部件(如上例,在CBT层)。

nDataSize

以字节数指定组件代表的数据的大小。如果组件是一个文件序列,该参数指定所有文件的总的非压缩大小。

bSelected

指定组件的缺省选择设置。在该参数位置传递下列预定义的常量之一:

TRUE:表明该组件缺省为选定。如果TRUE传递给一个子部件,而它的父亲组件是撤消选定的,则尽管给参数bSelect传递了TRUE,该子部件也将被撤消选定。

FALSE:表明组件缺省为撤消选定。

当用户选择显示在对话框中的一个组件或子部件时,缺省选择设置被清除。如果用户撤消选定一个组件,所有它的子部件将被撤消选定。如果用户撤消选定一个组件的所有子部件,该组件将被撤消选定。

返回值:

0:ComponentAddItem成功将数据项加入到组件或子部件。

< 0:ComponentAddItem未能将数据项加入到组件或子部件。调用ComponentError看附加信息。

注解:

·组件名必须不包含这些字符,它们是在资源管理器处理程序下的非法文件名字符;包括下列字符:/ \ ·? “ < > |。试图创建一个包含一个或多个这些字符的组件名将导致ComponentAddItem失败。

·你可以使用ComponentAddItem和脚本创建的组件组来允许用户从文件媒体组件选项之外的选项中选择。

·由调用ComponentAddItem开始,创建一个脚本创建的包含你需要的选项的组件组。

然后通过调用SdAskOptions 或 SdAskOptionsList来显示那些供选择的选项,它们的参数szComponent传递脚本创建的组件组的名称。最后,通过调用ComponentIsItemSelected确定被选定的选项。

7.2  ComponentCompareSizeRequired

语法:ComponentCompareSizeRequired (szMediaLibrary, svTarget, nvSize);

说明:ComponentCompareSizeRequired 函数确定目标文件夹是否能提供给选定组件足够空闲空间,这些组件由szMediaLibrary(必须是一个文件媒体库)指定。如果目标文件夹没有足够空闲空间,由参数svTarget返回全限定文件夹名,并且由参数nvSize返回所需空闲空间大小。

    注意参数svTarget仅被用来返回一个文件夹名。你不能使用该参数来指定一个目标文件夹。ComponentCompareSizeRequired检查目标文件夹指示的驱动器,目标文件夹是你为每个组件在属性表上指定的。如果szMediaLibrary是一个文件媒体库,它有要被安装在通用应用目的文件夹上的组件,你必须在调用ComponentCompareSizeRequired 前将目标路径赋给TARGETDIR。你可以通过调用AskDestPath或一个组件对话框从一个最终用户那儿得到一个目标路径。

    如果你的安装程序将在运行时为一个文件库中的一个组件指定一个目标文件夹,它必须在用ComponentCompareSizeRequired检查空闲空间前,通过调用ComponentSetTarget来做到这一点。

    该函数不能使用到脚本创建的组件组。

参数:

szMediaLibrary

指定文件媒体库的媒体名,该库所包含的组件的总的大小将和目标驱动器上的空闲空间进行比较。如果该参数包含一个脚本创建的组件组的名称,该函数将失败。

svTarget

如果在目标驱动器上有足够的有效空闲空间,返回一个空字符串(“”)。如果在目标驱动器上没有足够空闲空间,返回目标路径。

nvSize

如果在目标驱动器上有足够有效空闲空间,返回0。如果在目标驱动器上没有足够空闲空间,返回所需的大小(字节数)。

返回值:

0:ComponentCompareSizeRequired 成功。

< 0:ComponentCompareSizeRequired 失败。调用ComponentError看附加信息。

7.3  ComponentDialog

请参阅4.6

7.4  ComponentError

语法:ComponentError (svComponentSource, svComponent, svFileGroup, svFile, nvError);

说明:当一个组件函数返回值小于0时ComponentError函数得到辅助错误信息。下列代码段显示一个典型的ComponentError的实现:

   nResult = ComponentTransferData(MEDIA);

   if(nResult < 0) then

      ComponentError(svComponentSource, svComponent, svFileGroup, svFile, nvError);

      SprintfBox(INFORMATION, "ComponentTransferData Error Information",

         "ComponentTransferData had the following error:\n\n" +

         "Media Name: %s\nComponent: %s\nFile Group: %s\n" +

         "File: %s\nError Number: %ld"

         svComponentSource, svComponent, svFileGroup, svFile, nvError);

   endif; 

    ComponentError函数必须只有在另一个组件函数返回值小于0时才被调用。如果当另一个组件函数没有返回小于0的值时调用ComponentError函数,则可能返回无效的错误代码。

    调用下列函数时ComponentError不返回有关发生的错误的辅助信息:

s ComponentSetupTypeEnum

s ComponentSetupTypeSet

参数:

svComponentSource

返回与由nvError指定的错误相关的文件媒体库或脚本创建的组件组的媒体名。

svComponent

返回与由nvError指定的错误相关的组件名。

svFileGroup

返回与由nvError指定的错误相关的文件组名。

svFile

返回与由nvError指定的错误相关的文件名。

nvError

返回一个代码,它标识先前调用一个组件相关函数时发生的错误类型。这些错误的代码描述如下:

下表描述了由ComponentError返回的错误代码。注意在纠正了涉及媒体的错误后,你必须重建工程。

代码

   描   述 

        原   因

-101 

不能添加组件。

ComponentAddItem不能添加一个组件到脚本创建的组件组中。

-102 

指定的组件已经存在。

ComponentAddItem被用相同的媒体名和组件名调用了两次。

-104 

指定的组件名不是有效的。

传递给ComponentInitialize第二个参数的值不是有效的。

-105 

指定的组件不能在媒体上找到。

试图访问一个不存在于指定媒体上的组件。当调用一个组件函数,而没有正确指定一个组件名时发生该错误。被指定的组件名必须和显示在组件窗格中或在对ComponentAddItem的调用中的完全相同。区分大小写。

-106 

不能解压缩一个文件。

发生一个内部错误。技术支持请联系:http://support.installshield.com/contact/req_sup.asp.

-107 

在ComponentMoveData调用中,指定了一个无效的磁盘ID。

ComponentMoveData已经被调用来传输文件而还没有被重新初始化。为重新初始化ComponentMoveData,

以第一个参数为一个空字符串来调用该函数。

-108 

磁盘空间溢出。

目标磁盘或目录没有足够的空闲空间;因为TARGETDIR无效,磁盘空间不能被确定;或一个组件的脚本创建的文件夹还没有被设置。

-109 

EnterDisk函数调用失败。

发生内部错误。 

-112 

不能找到指定的文件。

为确定丢失了哪个文件,检查ComponentError返回的参数svFile的值。

-113 

指定的文件为只读,不能被打开。

Data1.cab文件(或其它数据cab文件之一)丢失或破坏;或一个CD-ROM上的解压缩数据文件丢失。

-114 

指定的文件不能以读/写打开。

不能增补到分类文件。技术支持请联系:http://support.installshield.com/contact/req_sup.asp. 

-115 

指定的文件不能以写打开。

试图改写一个文件组中的一个锁定文件,该文件组没有锁定位(potentially locked )或共享属性设置为Yes或到目标文件夹的路径是无效的。

-117 

不能读指定文件。

一个数据cab文件(.cab)或一个解压缩数据文件可能已毁坏。

-118 

不允许试图操作脚本创建的组件组。

一个脚本创建的组件组名被传递给一个只在文件媒体上执行的组件函数。

-119 

不能正确自注册一个文件。

该错误有许多可能的原因。详细情况可参阅InstallShield Knowledge Base中的Q101538文档。

-120 

不能对ComponentMoveData中的共享文件进行更新。

内部错误。

-121 

不能写文件。

内部错误。

-123 

不能找到一个文件组。

不能找到指定的文件组。丢失的文件组名由ComponentError返回在参数svFileGroup。

-125 

组件函数中指定的列表无效。

当调用ComponentListItems,ComponentSetupTypeEnum

时,确认你传递给函数的列表是有效的。

-126 

不允许试图操作文件媒体库。

一个文件媒体名传递给一个只在脚本创建的组件集上执行的组件函数(如,ComponentAddItem)。

-127 

媒体已经初始化。

ComponentInitialize被调用来初始化一个已经被初始化了的媒体。

-128 

指定的文件媒体库没有由InstallShield媒体向导生成。

Data1.cab文件被破坏,或调用ComponentInitialize中指定的文件不是一个InstallShield生成的cab文件。

-132 

指定的媒体没有被找到。

媒体已经被声明但还没有和任何组件相关联。确保脚本创建的组件或文件媒体组件和该媒体相关联。

-133 

指定媒体发生一个错误。

ComponentMoveData已经被调用来传输文件但还没有被重新初始化。如果你的脚本调用ComponentMoveData超过一次,你必须每次调用后重新初始化它,可通过让它的第一个参数为一个空字符串来再次调用它而实现重新初始化。

-136 

不能分配内存。

安装没有足够的有效内存。显示一个消息给最终用户,关闭所有其它的应用程序或取消安装,重启系统和重新开始安装。

-137 

指定的选项是无效的。

给一个组件函数指定了一个无效的选项,例如,当一个文件组和文件名都需要时,只指定了一个文件组。

-139 

指定的口令不符。

指定的口令与保存在指定的文件媒体库或组件中的口令不符。

-141 

指定的口令不能被找到。

ComponentValidate被调用来验证一个没有被设置口令的组件或文件媒体库。

-142 

媒体或组件的口令没有被确认。

在用ComponentMoveData传输那些组件前没有调用ComponentValidate来验证组件和/或文件媒体库。

-145 

组件的目标路径没有找到。

一个脚本定义的文件的目标目录没有被设置或是无效的。增加或改正对ComponentSetTarget的调用;然后重建。

-147 

传递无效值给一个组件有关函数。

传递给一个组件有关函数的一个值无效。例如,传递一个空字符串给ComponentAddItem函数的第二个参数可以引起该错误。

-148 

数据不能从互联网读得。

当使用InstallFromTheWeb与InstallShield5连接时发生该错误。由于文件被破坏或Internet连接丢失并且不能通过InstallFromTheWeb重新建立连接,InstallShield不能从Internet读取数据

-149 

Internet已经被断开。

当使用InstallFromTheWeb与InstallShield5连接时发生该错误。Internet连接已经丢失并且不能通过InstallFromTheWeb重新建立连接。

-150 

cab文件(.cab)由InstallShield5的旧版本生成。

确保工程是由你的InstallShield5最新版本建立的。确保你不在使用由InstallShield5的不同版本生成的不匹配的cab文件(.cab)。

-620 

第三方(third-party)外壳程序错误

咨询有问题的外、外壳程序的有关文档来确定它是否是100%兼容的开发人员外壳程序。

-623 

重命名文件错误。

没有将Potentially Locked属性设置为Yes时,试图传递一个可执行文件(一个.exe或.cm文件)。

返回值:

0:ComponentError成功。

< 0:ComponentError失败。

7.5  ComponentFilterLanguage

语法:ComponentFilterLanguage(szMediaLibrary, nLangID, bFiltered);

说明:ComponentFilterLanguage函数从基于语言的文件传输中筛选(排除)文件。缺省时,包含在媒体库中的所有语言都是不筛选的(包含的)。给参数nLangID使用的语言ID选项不能用按位或操作(|)联接。你必须为你所希望筛选或不筛选的每个语言都调用ComponentFilterLanguage。

    当安装程序第一次运行时所做的任何筛选在一个维护安装程序中也必须做。确定在初始安装和维护安装过程中被执行的代码中都调用该函数。不要从下列事件处理程序中调用该函数:OnAppSearch, OnCCPSearch, OnFirstUIBefore, OnFirstUIAfter, OnMaintUIBefore, or OnMaintUIAfter。

在安装过程中,筛选语言具体文件组的最简单的方法如下所示:

通过调用ComponentFilterLanguage(参数nLangID为ISLANG_ALL,参数bFilter设置为TRUE时)来筛选(排除)所有语言。

对每个你要安装的语言,都需在nLangID设置为合适的语言常量并且参数bFiltered设置为FALSE时调用ComponentFilterLanguage。每个调用将不筛选(包含)nLangID指定的语言的文件组。

你不能通过或操作(|)在参数nLangID位置指定多个语言常量。指定多个语言常量将导致函数执行不正确。

当使用ComponentFilterLanguage时,记住在程序块前加入#include “Sdlang.h”。如果你使用由工程向导生成的Setup.rul,该行已经为你包括在里面了。

该函数不能工作于脚本创建的组件组。

参数:

szMediaLibrary

指定文件媒体库的媒体名。

nLangID

指定要筛选或不筛选的语言的ID。注意对每次函数调用仅能指定一个语言常量。为筛选所有语言,给该参数传递ISLANG_ALL。

bFiltered

指定是否筛选(排除)或不筛选(包含)nLangID指定的语言。在该参数位置传递下列预定义常量之一:

TRUE:筛选nLangID指定的语言;也就是,在文件传输中不包含它。

FALSE:不筛选nLangID指定的语言;也就是,在文件传输中包含它。

返回值:

0:ComponentFilterLanguage成功。

< 0:ComponentFilterLanguage失败。

注解:

·当将该函数与GetSystemInfo函数一起使用时,你必须考虑下列情况:被用来指定语言特定文件组的语言常量只是可以由GetSystemInfo返回的语言常量的一个小的子集。

·如果你的安装包含基于这些返回值的语言筛选,你必须使用一个switch语句来转换由该函数返回的常量为支持语言筛选的常量之一。

·任何InstallShield版本将允许你指定任何语言的文件组或由Windows支持的子语言;然而,对一个由媒体向导建立的语言具体文件组,你使用的InstallShield版本必须支持该文件组的语言。你的安装必须也支持文件组的语言。

·如果你的安装包含语言具体文件组,它被具体指定到一个不被你正使用的InstallShield或你的安装支持的语言,文件组将被媒体向导筛选(不包含)。

7.6  ComponentFilterOS

语法:ComponentFilterOS (szMediaLibrary, nUpperOS, nLowerOS, bFiltered);

说明:ComponentFilterOS函数筛选标志为指定操作系统的文件组。缺省时,不筛选操作系统。该函数不能使用到脚本创建的组件组。

安装初次运行时的任何筛选在一个维护安装时也必须做。确认在初始和维护安装中执行的代码中都调用了该函数。不要从下列事件处理程序中调用该函数:OnAppSearch, OnCCPSearch, OnFirstUIBefore, OnFirstUIAfter, OnMaintUIBefore, 或 OnMaintUIAfter。

参数:

szMediaLibrary

指定文件媒体库的媒体名。

nUpperOS

指定一个64位操作系统标识符域的高32位。目前,nUpperOs没有被使用。给该参数传递0。不允许其它值。

nLowerOS

指定一个64位操作系统标识符域的低32位。nLowerOS指定你希望筛选的操作系统。你可以使用按位或操作符(|)将值组合。

ISOSL_ALL、ISOSL_WIN95、ISOSL_WIN98、ISOSL_WIN2000

ISOSL_WIN2000_ALPHA、ISOSL_NT40、ISOSL_NT40_ALPHA、bFiltered

指定是否要筛选(排除)或不筛选(包括)在n LowerOS指定的操作系统。在该参数位置传递下列预定义常量之一:

TRUE:筛选指定的操作系统;也就是,在文件传输中不包括它们。

FALSE:不筛选指定的操作系统;也就是,在文件传输中包括它们。

返回值:

0:ComponentFilterOS 成功。

< 0:ComponentFilterOS 失败。调用ComponentError查看附加信息。

7.7  ComponentGetData

语法:ComponentGetData (szComponentSource, szComponent, nInfo, nvResult, svResult);

说明:ComponentGetData函数检索一个组件的信息。当szComponentSource指向一个脚本创建组件组时,一些信息不能被检索。

参数:

szComponentSource

指定其信息要被检索的组件所在的文件媒体库或脚本创建组件组的媒体名。

szComponent

指定其信息要被检索的组件名。参阅。

nInfo

指定要检索的信息类型。在该参数位置传递下列预定义常量之一:

COMPONENT_FIELD_DESCRIPTION:当组件在一个组件对话框中被选定时显示的说明。对于一个在文件媒体库中的组件,这是保存在组件属性窗口中说明域中的值。

COMPONENT_FIELD_FILENEED:定义组件文件对于安装的关键性程度。下列值之一将被设置到nvResult:

COMPONENT_VALUE_CRITICAL:该组件包含关键性文件。

COMPONENT_VALUE_HIGHLYRECOMMENDED:该组件被高度推荐。

COMPONENT_VALUE_STANDARD:该组件可以被包括也可以不包括。

COMPONENT_FIELD_FTPLOCATION:在组件窗格中指定FTP位置属性的内容。

COMPONENT_FIELD_HTTPLOCATION:在组件窗格中指定HTTP位置属性的内容。

COMPONENT_FIELD_STATUS(不针对脚本创建组件组):文件传输过程中显示在进度指示器中的状态文本。这是保存在组件属性窗口中状态文本域中的值。

COMPONENT_FIELD_VISIBLE:确定在一个组件选择对话框中组件是否可见。对于一个文件媒体库中的一个组件,这是保存在组件属性窗口中可见域的值。下列值之一将被设置到nvResult:

s TRUE:组件可见。

s FALSE:组件不可见。

COMPONENT_FIELD_PASSWORD (不针对脚本创建组件组):是否有一个口令和组件相联系(在组件属性窗口中的口令域中)。下列值之一将被设置到nvResult:

s TRUE:该组件有一个口令。如果组件是口令保护的,你必须从最终用户处得到正确的口令并且在调用ComponentTransferData传输文件媒体库中的文件前用ComponentValidata检验它。

s FALSE:该组件没有一个口令。

COMPONENT_FIELD_SELECTED:确定组件是否被选定:

s TRUE:该组件被选。

s FALSE:该组件没有被选。

COMPONENT_FIELD_SIZE(不针对文件媒体):指定组件的原始文件大小。你也可以使用ComponentGetItemSize来确定一个组件(不包括子部件)的大小。使用ComponentTotalSize确定所有选定组件和子部件的总的大小。

COMPONENT_FIELD_MISC:杂项文本。该域在运行时非常有用,因为你可以使用它用你希望的任何信息来标记或者标识组件。

COMPONENT_FIELD_DISPLAYNAME:显示在组件选择对话框中的组件名。对于在文件媒体库中的组件,这是组件属性窗口中显示名称域的值。

COMPONENT_FIELD_CDROM_FOLDER (不针对脚本创建组件组):仅对CD-ROM库类型。当“文件数据”在媒体向导的磁盘类型窗格中被检验时,指示与指定组件相联系的解压缩文件的位置。

nvResult

当nInfo产生一个数值型结果时返回一个数值型值。

svResult

当nInfo产生一个字符串型结果时返回一个字符串型值。

返回值:

0:ComponentGetData成功。

< 0:ComponentGetData失败。调用ComponentError查看附加信息。

7.8  ComponentGetItemSize

语法:ComponentGetItemSize (szMediaLibrary, szComponent, nvSize);

说明:ComponentGetItemSize 函数以字节数为单位检索一个指定组件的大小。子部件大小不包括在内。

该函数不能被使用到脚本创建组件组。

参数:

szMediaLibrary

指定包含了其大小要被检索的组件的文件媒体库的媒体名。

szComponent

指定其大小要被检索的组件的名称。

nvSize

以字节数为单位返回指定组件的大小。你也可以调用ComponentGetData来得到指定组件的原始文件的总的大小。调用ComponentTotalSize来确定所有被选组件和子部件的总的大小。

返回值:

0:ComponentGetItemSize成功。

< 0:ComponentGetItemSize失败。调用ComponentError查看附加信息。

7.9  ComponentGetTotalCost

语法:ComponentGetTotalCost (szMediaLibrary, szDir, nvTotalRequiredSpace);

说明:ComponentGetTotalCost函数确定在目标驱动器上对已指定组件(例如,由最终用户在组件和安装类型对话框中选择)进行安装和卸载所需的总空间(以字节数为单位)。确定所需驱动器空间时,该函数考虑在目标驱动器上的簇的大小。

参数:

szMediaLibrary

指定其组件已经被指定来安装和卸载的文件媒体库的媒体名。典型地,你必须给该参数传递系统变量MEDIA

szDir

指定使用的驱动器,或者被使用驱动器的路径,以此来确定所需的驱动器空间。

nvTotalRequiredSpace

返回所需的驱动器空间。

返回值:

0:表明函数成功确定所需驱动器空间。

<0:表明函数未能确定所需驱动器空间。

7.10  ComponentInitialize

语法:ComponentInitialize (szMediaLibrary, szMediaLibraryFile);

说明:ComponentInitialize函数仅支持与InstallShield先前版本创建的脚本的兼容性。我们建议你不要在InstallShield Professional 6.0中使用多个文件媒体库。

ComponentInitialize函数将一个媒体名和一个文件媒体库联系起来并且准备该媒体库被访问。该函数不能被使用到脚本创建的组件组。

参数:

szMediaLibrary

指定其文件要由ComponentMoveData传输的文件媒体库的媒体名。

szMediaLibraryFile

指定文件媒体库中的要被初始化的文件名。文件名必须是xxx1.cab的格式。不要指定一个路径;该文件必须驻留在安装资源文件夹(SRCDIR)。

返回值:

0:ComponentInitialize成功。

< 0:ComponentInitialize失败。

注解:

·在访问使用缺省媒体名”Data”的缺省文件媒体库(Data1.cab)之前,没有必要调用ComponentInitialize。缺省媒体在安装初始化过程中被自动初始化。文件媒体库必须驻留在安装资源文件夹。该文件夹的名称在安装初始化过程中被赋给系统变量SRCDIR

·文件名必须是xxx1.cab格式;例如,second1.cab 或 wow1.cab。

·媒体名”Data”被保留给和缺省文件媒体库Data1.cab一起使用。你不可以给参数szMediaLibrary传递”Data”。

7.11  ComponentIsItemSelected

语法:ComponentIsItemSelected (szComponentSource, szComponent);

说明:ComponentIsItemSelected函数仅支持与InstallShield先前版本创建的脚本的兼容性。建议你把代码放置在组件事件处理器函数中来执行组件具体任务。

ComponentIsItemSelected函数确定一具体组件是否被选定。该组件通常是由最终用户在一个组件选择对话框中选定的一个。

参数:

szComponentSource

指定其设置要被检验的文件媒体库或脚本创建组件组的媒体名。

szComponent

指定要被检验的组件名。

返回值:

TRUE (1):szComponent被选定。

FALSE (0):SzComponent没有被选定。

< 0:函数没有能确定组件是否被选定。调用ComponetError 查看附加信息。

你也可以使用ComponentGetData来确定一个组件是否被选定。

7.12  ComponentListItems

语法:ComponentListItems (szComponentSource, szComponent, listComponents);

说明:ComponentListItems函数罗列由szComponentSource指定的文件媒体库或脚本创建组件组中的所有组件到szComponent下。全限定子部件名列表保存在listComponents。如果szComponent没有孩子,则listComponents将是一个空列表。

参数:

szComponentSource

指定其子部件要被罗列的文件媒体库或脚本创建组件组的媒体名。

szComponent

指定其子部件要被罗列的组件。给该参数传递一个空字符串(“”)来罗列所有顶层组件。有关函数调用中指定组件和子部件的更多信息,参阅前面。

listComponents

返回组件列表。由listComponents指定的字符串列表必须已经通过调用ListCreat被初始化。

返回值:

0:ComponentListItems罗列组件。

< 0:ComponentListItems不能罗列组件。调用ComponentError查看附加信息。

7.13  ComponentMoveData

语法:ComponentMoveData (szMediaLibrary, nvDisk, nReserved );

说明:ComponentMoveData 函数仅支持与InstallShield先前版本创建的脚本的兼容性。在一个基于事件的脚本中,文件传输自动被执行。(我们建议你把代码放置在组件事件处理器函数中来执行组件具体任务。)

ComponentMoveData函数传输/解压缩与szMediaLibrary指定的文件媒体库中的被选组件相关联的文件。你可以在相同媒体上调用ComponentMoveData多次,但你必须在第二次和随后的调用前复位内部结构,可通过调用ComponentMoveData来实现复位(调用时将其第一个参数置为一个空字符串(“”))。

该函数不能被使用到脚本创建的组件组。

参数:

szMediaLibrary

指定其文件要被传输的文件媒体库的媒体名。

nvDisk

返回最后被访问的磁盘号。在调用ComponentMoveData前你不需要初始化nvDisk。

nReserved

给该参数传递0。不允许其它值。

返回值:

0:ComponentMoveData成功。

< 0:ComponentMoveData失败。调用ComponentError查看附加信息。

7.14  ComponentReinstall

语法:ComponentReinstall ( );

说明:ComponentReinstall引起下一个对ComponentTransferData的调用会重新安装所有组件,这些组件在调用ComponentTransferData时已经被安装。ComponentReinstall通常在最终用户选择SdWelcomeMaint对话框中的“修复”按钮时的一个维护安装过程中被调用。

参数:

无。

返回值:

0:表明函数为重新安装作好准备。

<0:表明函数未能为重新安装作好准备。

7.15  ComponentRemoveAll

语法:ComponentRemoveAll ( );

说明:一个已经被运行的安装中,在ComponentRemoveAll 函数被调用后,接下去对ComponentTransferData的调用将卸载安装。

参数:

无。

返回值:

0:表明函数成功准备卸载的初始化。

<0:表明函数没有能准备卸载的初始化。

7.16  ComponentSelectItem

语法:ComponentSelectItem (szComponentSource, szComponent, bSelect);

说明:ComponentSelectItem 函数仅支持与InstallShield先前版本创建的脚本的兼容性。我们建议你把代码放置在组件事件处理器函数中来执行组件具体任务。

ComponentSelectItem 函数设置一个组件的选定状态来选定或撤消选定。在组件对话框中显示组件之前,你可以使用ComponentSelectItem  来修改选定状态,而且以后你可以根据你的需要使用它来修改或覆盖选择。

参数:

szComponentSource

指定其选定状态要被设置的组件所属文件媒体库或脚本创建组件集的媒体名。

szComponent

指定其选定状态要被设置的组件。

bSelected

指定组件是否要被选定或撤消选定。在该参数位置传递下列预定义常量之一:

TRUE:选定指定的组件。

FALSE:撤消选定指定的组件。

返回值:

0:ComponentSelectItem成功设置项目的选定状态。

< 0:ComponentSelectItem未能设置项目的选定状态。调用ComponentError查看附加信息。

7.17  ComponentSetData

语法:ComponentSetData (szComponentSource, szComponent, nInfo, nData, szData);

说明:ComponentSetData 函数为指定的组件设置属性和数据。对多数部分,设置和在组件属性窗口中的域设置相一致,从InstallShield  IDE中的组件窗格中可达。注意一些域不能为脚本创建的组件组设置。

参数:

szComponentSource

指定其属性和数据要被设置的组件所属文件媒体库或脚本创建组件集的媒体名。

szComponent

指定组件名。

nInfo

指定要被设置的信息类型。在该参数位置传递下列预定义常量之一:

COMPONENT_FIELD_DESCRIPTION:该文本被显示在组件选择对话框中的说明域。

COMPONENT_FIELD_FTPLOCATION:一个FTP位置。

COMPONENT_FIELD_HTTPLOCATION:一个HTTP位置。

COMPONENT_FIELD_STATUS (不适用与脚本创建组件):文件传输过程中该文本被显示在进度指示器中。

COMPONENT_FIELD_VISIBLE:指示该组件是否可见。参数nData可为下列数之一:

s TRUE:组件可见。

s FALSE:组件不可见。

COMPONENT_FIELD_SELECTED:设置组件的选定状态。该设置和ComponentSelectItem的效果一样。参数nData可以是下列数之一:

s TRUE:选定该组件项目。

s FALSE:撤消选定该组件项目。

COMPONENT_FIELD_SIZE (不对文件媒体库):组件的总的原始文件大小。

COMPONENT_FIELD_MISC:杂项文本。

COMPONENT_FIELD_DISPLAYNAME:确定在组件选择对话框中显示的组件名。

COMPONENT_FIELD_CDROM_FOLDER(不对脚本创建的组件组):仅对CD-ROM分布媒体库。CD上的组件数据的定位。

COMPONENT_FIELD_IMAGE:覆盖一个组件的缺省图标赋值。在nData传递显示的图标的索引。为指示组件不显示图标,在nData传递-1。

nData

当由nInfo指示的信息是数值时,指定一个数值型值。

szData

当由nInfo指示的信息是字符串时,指定一个字符串值。

返回值:

0:ComponentSetData成功。

< 0:ComponentSetData失败。调用ComponentError查看附加信息。

7.18  ComponentSetTarget

语法:ComponentSetTarget (szMediaLibrary, szPropertyVar, szLocation);

说明:ComponentSetTarget  函数将szLocation的值赋给由szPropertyVar指定的属性变量。属性变量可以在文件组窗口的Destionation域中和简捷属性窗口的Target域中使用。SzLocation的值必须是一个完整路径(包含驱动器字母和冒号)或一个部分路径,依赖于szPropertyVar 如何被使用。你必须确认szLocation是路径表达式的正确形式。在调用ComponentTransferData之前调用ComponentSetTarget 。

该函数不能被使用到脚本创建的组件组。

参数:

szMediaLibrary

指定要设置其用户定义的变量的文件媒体库的媒体名。

szPropertyVar

指定用户定义的变量。在InstallShield  IDE中,用户定义的变量用<变量名>的格式。将用户定义的变量表示为一个字符串,包含中括号。例如:

   szPropertyVar = "<szVar>";

szLocation

指定路径表达式来代替用户定义的变量。该字符串必须包含附加引号,即使它指定一个长路径。

返回值:

该函数总返回0

7.19  ComponentSetupTypeEnum

语法:ComponentSetupTypeEnum (szMediaLibrary, listSetupTypes);

说明:ComponentSetupTypeEnum 函数列举所有和指定媒体相联系的安装类型。这些安装类型可以由你在IDE中定义并保存在文件媒体库中。ComponentSetupTypeEnum 不能工作在脚本创建的组件组上。你必须使用ListCreat函数创建listSetupTypes字符串列表。

参数:

szMediaLibrary

指定安装类型要被列举的文件媒体库的媒体名。

listSetupTypes

返回一个在指定媒体上的所有安装类型的列表。由listSetupType标识的字符串列表必须已通过调用ListCreate被初始化。

返回值:

0:ComponentSetupTypeEnum成功。

< 0:ComponentSetupTypeEnum失败。

7.20  ComponentSetupTypeGetData

语法:ComponentSetupTypeGetData (szMediaLibrary, szSetupType, nInfo, nvResult, svResult);

说明:ComponentSetupTypeGetData函数检索和一个指定的安装类型相联系的数据。然后你可以任意使用该数据。该函数不能被使用到脚本创建的组件组。

参数:

szMediaLibrary

指定文件媒体库的媒体名,从该库中检索和一个安装类型相关联的数据。

szSetupType

指定安装类型名。该名必须指定为和显示在InstallShield IDE中的完全一样,例如,”典型”。

nInfo

指定要检索的信息。在该参数位置传递下列预定义常量之一:

SETUPTYPE_INFO_DESCRIPTION:检索指定安装类型的说明。说明由参数svResult返回。

SETUPTYPE_INFO_DISPLAYNAME:检索安装类型显示的名称。名称由参数svResult返回。

nvResult

当nInfo指定一个数值型或长整数型的信息时,返回该类型的值。

svResult

当nInfo指定一个字符串型的信息时,返回该类型的值。

返回值:

0:ComponentSetupTypeGetData成功。

< 0:ComponentSetupTypeGetData失败。调用ComponentError查看附加信息。

注解:

·ComponentSetupTypeGetData的一个典型的应用可能是在一个自定义安装类型相关的对话框中显示安装类型信息。你将在显示自定义对话框的WaitOnDialog后在switch-case语句中调用ComponentSetupTypeGetData。

7.21  ComponentSetupTypeSet

语法:ComponentSetupTypeSet (szMediaLibrary, szSetupType);

说明:ComponentSetupTypeSet函数设置在由szMediaLibrary指示的文件媒体库中的指定的安装类型。你可以使用ComponentSetupTypeSet来覆盖在一个安装类型对话框(如SdSetupTypeEx)中所作的选择。

该函数不能使用到脚本创建的组件组。

参数:

szMediaLibrary

指定要设置安装类型的文件媒体库的媒体名。

szSetupType

指定设置为何种安装类型。

返回值:

0:ComponentSetupTypeSet成功。

< 0:ComponentSetupTypeSet失败。

7.22  ComponentTotalSize

语法:ComponentTotalSize (szMediaLibrary, szComponent, bIncludeSubcomp, bTargetSize);

说明:ComponentTotalSize函数以字节数返回由szComponent指定的被选组件的总的大小。为在大小计算中包含子部件,设置bIncludeSubcomp为TRUE。为得到指定媒体中所有组件的总的大小,设置szComponet为一个空字符串(“”)并设置bIncludeSubcomp为TRUE

如果你将ComponentTotalSize的返回值和显示在SdComponentDialog, SdComponentDialog2, SdComponentDialogAdv和SdComponentMult对话框中的的所需空间值比较,你可能注意到一个小的差异。该差异归根于当这些对话框计算它们的值时发生的舍入。

参数:

szMediaLibrary

指定文件媒体库的文件名,从该媒体库中被选定的组件的总的大小被返回。

szComponent

指定其大小要被检索的组件名。为检索整个媒体的大小,给该参数传递一个空字符串(“”)。有关函数调用中组件和子部件的更多信息,同前面。

bIncludeSubcomp

指示是否要包括szComponent的选择的子部件。在该参数位置传递下列预定义常量之一:

TRUE:在大小计算中包括选择的子部件。

FALSE:在大小计算中不包括选择的子部件。

bTargetSize

指示是否要检索原始/非压缩大小或媒体库的大小。在该参数中传递下列预定义常量之一:

TRUE:检索原始/非压缩大小;

FALSE:检索在媒体库中的大小。

返回值:

XXXX:被选定组件的总的大小(字节数)。

< 0:ComponentTotalSize失败。调用ComponentError查看附加信息。

7.23  ComponentTransferData

语法:ComponentTransferData (szMediaLibrary);

说明:在一个基于事件的脚本中,ComponentTransferData 函数在First UI Before事件后被自动调用,并和Moving、Moved和组件事件进行适当交互。ComponentTransferData 根据组件的选定状态和当前是否被安装来适当安装或卸载组件。ComponentTransferData 做到下列事情:

s 安装被选定的(例如,最终用户在组件或安装类型对话框中的选择)并且当前没有安装的组件。

s 卸载没有被选定并且当前已安装的组件。

安装程序通过读现存的安装初始化过程中的日志文件来确定一个组件当前是否是被安装的。

参数:

szMediaLibrary

指定其组件已经被指定来安装或卸载的文件媒体库的媒体名。典型地,你可以传递系统变量MEDIA给该参数。

返回值:

0:表明函数成功执行组件的安装和卸载。

<0:表明函数没有能执行组件的安装和卸载。

7.24  ComponentUpdate

语法:ComponentUpdate ( );

说明:ComponentUpdate 引起下一个对ComponentTransferData的调用来重新安装所有已经在调用ComponentTransferData时被安装的组件,除了那些包含有维护安装时和卸载时所需的文件的组件(注意这些组件由媒体生成器自动放置到你的.cab文件,而不是显示在IDE中)。ComponentUpdate通常在一个修补程序或维护组件安装中被调用。

ComponentUpdate 和ComponentReinstall相似,但ComponentReinstall也重新安装那些包含有维护安装时和卸载时所需的文件的组件。

参数:

无。

返回值:

0:表明函数成功准备好更新安装。

<0:表明函数未能准备好更新安装。

7.25  ComponentValidate

语法:ComponentValidate (szMediaLibrary, szComponent, szPassword);

说明:ComponentValidate 函数验证文件媒体库或一个指定组件的口令。

该函数不能被使用到脚本创建的组件组。

参数:

szMediaLibrary

指定要验证口令的文件媒体库名。

szComponent

指定组件名。如果该参数是一个空字符串(“”),则假定为整个媒体库。有关函数调用中组件和子部件的更多信息请参阅7.1。

szPassword

指定要验证的口令。

返回值:

0:ComponentValidate 成功。

< 0:ComponentValidate 失败。调用ComponentError查看附加信息。

7.26  SdSetupType

请参阅5.27

7.27  SdSetupTypeEx

请参阅5.28

8  文件配置函数

8.1  高级配置文件函数

    高级配置文件函数比Ez配置文件函数提供给高级开发人员更大的灵活性和对系统配置的更多控制。为使用这些高级函数访问和编辑一个系统配置文件,可通过调用ConfigFileLoad开始。大多数其它函数只有在系统配置文件已经由ConfigFileLoad打开后才能被调用。当你结束编辑系统配置文件时,调用ConfigFileSave来保存你的修改。注意函数ConfigGetFileName 和ConfigSetFileName既可以和高级配置文件函数也可以和Ez配置文件函数一起使用。

不要把Ez配置文件函数和高级配置文件函数混合起来。调用ConfigFileLoad之后,直到你调用了ConfigFileSave保存你的修改后,你才能使用Ez配置文件函数。

s ConfigAdd

添加一个语句到一个已经被装入内存的系统配置文件。

s ConfigDelete

从一个系统配置文件中删除一项。

s ConfigFileLoad

把一个系统配置文件装入内存来编辑。

s ConfigFileSave

保存一个已经由ConfigFileLoad装入内存的系统配置文件。

s ConfigFind

在一个系统配置文件中查找一个项目。

s ConfigGetFileName

检索缺省系统配置文件的全限定名。

s ConfigGetInt

从一个系统配置文件中检索一个值。

s ConfigMove

在一个系统配置文件中移动一项。

s ConfigSetFileName

指定一个系统配置文件的全限定名。

s ConfigSetInt

在系统配置文件中设置一个值。

相关函数:

s SdShowFileMods

创建一个对话框,显示建议的文件修改和提供如何进行的选项。

8.1.1  ConfigAdd 

语法:ConfigAdd (szKey, szValue, szRefKey, nOptions);

说明:ConfigAdd函数添加一个语句到一个已经被ConfigFileLoad装入内存的系统配置文件中。你可以指定该语句相对于一个参考字的位置,或者你可以在文件首行或末行添加语句。你也可以置换文件中已经存在的一行。调用ConfigAdd前,你必须调用ConfigFileLoad把系统配置文件装入到内存。在你编辑文件后,调用ConfigFileSave 保存文件。

参数:

szKey

指定被添加到系统配置文件中的语句的关键词。

szValue

指定被添加到系统配置文件中的关键词的值。

szRefKey

指定在系统配置文件中与你添加的szKey相对的参考字。如果给该参数传递一个空字符串(“”),该行被添加为文件的首行或末行,具体依赖于传递给nOptions的预定义常量。

nOptions

指定该行是被添加到包含参考字的行的前面还是后面,或者该行是否置换一存在行。在该参数位置传递下列预定义常量之一:

BEFORE:该语句被添加到包含szRefKey的行的前面。如果szRefKey是一个空字符串(“”),该语句被添加到文件首行。

AFTER:该语句被添加到包含szRefKey的行的后面。如果szRefKey是一个空字符串(“”),该语句被添加到文件末行。

REPLACE:该语句将置换文件中已存在的一行。如果存在多行有相同的字,仅最后一行被置换。如果要被置换的一行不存在于文件中,新行添加为文件末行。

返回值:

0:ConfigAdd成功添加语句到指定的系统配置文件。

< 0:ConfigAdd未能添加语句到指定的系统配置文件。

注解:

·当ConfigAdd函数置换一系统配置文件中的一行时,它比较两行中的参考字:

·一个参考字是一个标识该行的一个子串。例如,在下列例子中,参考字是Kybrd.drv。

   DEVICE=C:\Windows\System\Kybrd.drv /1024 /C:345

在下一语句中,参考字是PATH:

   SET PATH=C:\Windows;C:\Windows\System

8.1.2  ConfigDelete

语法:ConfigDelete (szKey);

说明:ConfigDelete函数删除已经被ConfigFileLoad装入内存的系统配置文件中的行。参数szKey指定一个用来标识要被删除行的参考字。在使用高级配置文件函数编辑文件后,你调用ConfigFileSave 保存文件。

参数:

szKey

指定标识要被删除行的参考字。常用参考字包括Himem.sys, FILES, 和 STACKS。

返回值:

0:ConfigDelete成功删除系统配置文件中包含参考字的行。

< 0:ConfigDelete没有能删除指定行。

8.1.3  ConfigFileLoad

语法:ConfigFileLoad (szConfigFile);

说明:ConfigFileLoad函数装入一个指定系统配置文件的拷贝到内存,因而其它高级配置文件函数可以被调用来操作该文件。在参数szConfigFile指定你要编辑的系统配置文件的名称或给szConfigFile传递一个空字符串来编辑缺省系统配置文件(由InstallShield初始设置为系统使用的自举Config.sys文件)。

为得到缺省系统配置文件的全限定名,调用ConfigGetFileName。为时另一个文件为缺省系统配置文件,调用ConfigSetFileName。

注意:你可以调用ConfigFileLoad来创建一个新配置文件。为了这么做,你可以给szConfigFile传递一个不存在的文件名。然后调用其它配置函数来编辑新文件。最后,调用ConfigFileSave将新文件保存到磁盘。

    使用任何高级配置文件函数之前,你必须首先调用ConfigFileLoad将系统配置文件装入到内存。在你修改文件后,调用ConfigFileSave将它保存到磁盘。

参数:

szConfigFile

指定装入内存的系统配置文件的全限定名。为装入缺省系统配置文件,给该参数传递一个空字符串(“”)。

返回值:

0:ConfigFileLoad成功将指定的系统配置文件装入到内存。

< 0:ConfigFileLoad未能将指定的系统配置文件装入到内存。

8.1.4  ConfigFileSave

语法:ConfigFileSave (szBackupFile);

说明:ConfigFileSave函数将由ConfigFileLoad函数装入内存的系统配置文件保存到磁盘。文件保存为它的原始名。如果在szBackupFile指定一个文件名,在被编辑的文件被写到磁盘前原始名被更名为该文件名。如果szBackupFile包含一个空字符串(“”),原始文件被该修改的文件置换。如果你结束用高级配置文件函数修改一个系统配置文件时没有调用ConfigFileSave,所有修改将被丢失。

参数:

szBackupFile

指定在编辑被保存前是否要备份原始文件的一个拷贝。

如果无需创建备份文件,给该参数指定一个空字符串。

如果原始文件必须用一个特定名备份,给该参数传递该文件名。该文件名必须是非限定的(也就是,不限定一个驱动器和/或路径)。注意如果具有指定名称的文件已经存在,ConfigFileSave将生成一个唯一的文件扩展名,如接下去布告牌项目中描述。

    如果原始文件备份时必须带有一个安装生成的文件的扩展名,指定通配符””作为文件扩展名(例如,”Config.”)。然后安装将赋一个数值型值,从1001开始,作为扩展名。如果一个有该扩展名的文件已经存在,扩展名值将被增加一直到产生一个唯一的文件名。

一旦创建了备份,InstallShield保存备份文件名到系统变量INFOFILENAME

注意下列重要事实:1)如果上一次对ConfigFileLoad的调用指定的配置文件不存在,备份文件将和由调用ConfigFileSave创建的配置文件相同。2)如果szBakupFile指定原始配置文件名,那么将不会创建一个备份文件。

返回值:

0:ConfigFileSave成功将文件从内存写到磁盘。

< 0:ConfigFileSave未能将文件写到磁盘。

8.1.5  ConfigFind

语法:ConfigFind (szRefKey, svResult, nOptions);

说明:ConfigFind函数查找一个已经由函数ConfigFileLoad装入到内存的系统配置文件。参数szRefKey是一个参考字,来指定在文件中的查找目标。如果该参考字被找到,它的值返回到参数svResult。为找到所有出现szRefKey的地方,将参数nOptions设置为CONTINUE重复调用该函数。为从文件头部开始查找,将nOptions指定为常量RESTART。你编辑该文件后,调用ConfigFileSave来保存它。

参数:

szRefKey

指定要查找的参考字。如果参考字是一个没有文件扩展名的文件名,查找中将包括所有文件扩展名。例如,如果你指定Win.com,查找仅对该参考字。如果你指定WINWin.exe文件,Win.dll文件,Win.sys文件等等都被返回。

svResult

返回在系统配置文件中找到的参考字的值。

nOptions

指示是否从文件开始处开始查找还是从上一个查找中断处继续。在该参数位置传递下列预定义常量之一:

RESTART:从文件开始处开始查找。

CONTINUE:从系统配置文件当前位置开始查找。

COMMAND:指示szRefKey处的参考字是一个命令,而不是一个环境变量。COMMAND常量可以通过使用按位或操作符(|)来和RESTART常量或 CONTINUE常量结合,如下例所示:

ConfigFind("Vga.drv", svResult, CONTINUE | COMMAND);

返回值:

0:ConfigFind成功找到指定的参考字,并在svResult返回。

< 0:ConfigFind未能找到指定的参考字。

注解:

一个系统配置文件可以包含环境变量和命令。为区别相同名称的环境变量和命令,使用COMMAND常量来指定你在寻找一个可执行命令。

8.1.6  ConfigGetFileName

语法:ConfigGetFileName (svFileName);

说明:ConfigGetFileName函数检索缺省系统配置文件(由InstallShield初始设置为当目标系统启动时被执行的Config.sys文件)的全限定名。

参数:

svFileName

返回缺省系统配置文件的全限定名。

返回值:

0:ConfigGetFileName成功检索缺省系统配置文件的全限定名。

< 0:ConfigGetFileName未能检索缺省系统配置文件的全限定名。

注解:

很少情况下InstallShield可能不能确定缺省配置文件的全限定名。这种情况下,svFileName将是一个空字符串(“”)。

8.1.7  ConfigGetInt

语法:ConfigGetInt (szKey, nvValue);

说明:ConfigGetInt函数检索一个由函数ConfigFileLoad装入到内存的系统配置文件中的参考字的整型值。ConfigGetInt从等号右边只有一个值的命令中检索值。ConfigGetInt不工作在一个有不止一个值的命令中。例如,ConfigGetInt识别语句FILES=20并返回数字20,但它不识别语句STACKS=9128

    在调用ConfigGetInt前,你必须首先调用ConfigGetLoad将系统配置文件装入到内存。在你编辑文件后,调用ConfigFileSave来保存文件。

参数:

szKey

指定要从中检索整型值的语句的参考字。

nvValue

返回参考字的整型值。

返回值:

0:ConfigGetInt成功检索整型值。

< 0:ConfigGetInt未能检索整型值。

8.1.8  ConfigMove

语法:ConfigMove (szMove, szRefKey, nOptions);

说明:ConfigMove函数移动一个由函数ConfigFileLoad装入到内存的系统配置文件中的一行。该行可以被移动到文件最前面和最后面的位置,或者在文件中一特定行的前面或后面。

在调用ConfigMove函数前,你必须首先调用ConfigFileLoad来将Config.sys文件装入到内存。在你编辑文件后,调用ConfigFileSave 来保存文件。

参数:

szMove

指定要移动的行。

szRefKey

指定标识参考行的关键字,参考行用来定位要被移动的行。要移动的行的位置由参数nOptions的值确定。

nOptions

指定你要移动参数szMove指定的行到包含szRefKey指定的参考字的行的前面或后面。在该参数位置传递下列预定义常量之一:

BEFORE:由szMove指定的行被放置到包含szRefKey的行前面。如果szMove是一个空字符串(“”),该行被放置到系统配置文件首行的前面。

AFTER:由szMove指定的行被放置到包含szRefKey的行后面。如果szMove是一个空字符串(“”),该行被放置到系统配置文件末行的后面。

返回值:

0:ConfigMove成功移动系统配置文件中的指定行。

< 0:ConfigMOve未能移动该行。

8.1.9  ConfigSetFileName

语法:ConfigSetFileName (szConfigFile);

说明:ConfigSetFileName函数指定你要使用为缺省系统配置文件的文件的全限定名。在安装的初始化过程中,InstallShield标识目标系统启动时执行的Config.sys文件并且将它作为缺省系统配置文件。如果这是你安装中将编辑的唯一的系统配置文件,则没必要调用该函数。Ez配置文件将使用该文件,高级配置文件函数ConfigFileLoad当其参数是一个空字符串(“”)时将打开该文件。

    然而,如果你想要使用Ex配置文件函数来修改一个自举Config.sys文件之外的配置文件,你必须调用ConfigSetFileName来修改缺省系统配置文件。例如,假定你要在目标系统上创建一个在自举时不使用的Config.sys文件。你必须在应用程序目录中设置一个文件名。Ez配置文件函数然后将在该文件上操作;如果你用一个空字符串调用ConfigFileLoad ,该文件将被装入内存,可以用高级文件函数来编辑它。

参数:

szConfigFile

指定设置为缺省系统配置文件的文件的全限定名。

返回值:

0:ConfigsetFileName成功检索指定的缺省系统配置文件。

< 0:ConfigsetFileName未能检索指定的文件。

注解:

·ConfigSetFileName函数不能将一个系统配置文件装入到内存。你必须使用ConfigFileLoad来将一个文件装入到内存。

·ConfigSetFileName不验证你指定的文件名。如果你指定一个无效文件名,所有以后的配置文件函数将失败。

8.1.10  ConfigSetInt

语法:ConfigSetInt (szKey, nValue);

说明:ConfigSetInt函数修改一个由函数ConfigFileLoad装入到内存的系统配置文件中的指定的整型值。ConfigSetInt只设置等号右边只有一个值的命令中的值。ConfigSetInt不工作在一个有不止一个值的命令中。例如,ConfigSetInt识别语句FILES=20并修改20为其它值,但它不能识别语句STACKS=9128

在调用ConfigSetInt前,你必须首先调用ConfigSetLoad将系统配置文件装入到内存。在你编辑文件后,调用ConfigFileSave来保存文件。

参数:

szKey

指定要其整型值要被设置的命令的参考字。

nValue

指定你要在szKey 为命令设置的整型值。

返回值:

0:ConfigSetInt成功设置系统配置文件中的指定整数。

< 0:ConfigSetInt未能设置指定整数。

8.2  Ez配置文件函数

  Ez配置文件函数修改缺省系统配置文件。除非调用ConfigSetFileName来修改,该文件就是在启动时被执行的Config.sys文件。

  不要把Ez配置文件函数和高级配置文件函数混合起来。调用ConfigFileLoad之后,直到你调用了ConfigFileSave保存你的修改后,你才能使用Ez配置文件函数。

  这些函数每个都打开缺省系统配置文件,执行它指定的任务,然后把文件保存回磁盘。你不能如你在高级配置文件函数中所做的那样装入和保存配置文件。

s EzConfigAddDriver

在缺省系统配置文件中添加一个设备驱动器语句。

s EzConfigAddString

在缺省系统配置文件中添加一个语句或一行文本。

s EzConfigGetValue

检索系统配置文件参数的值,比如FILESBUFFERS

s EzConfigSetValue

设置系统配置文件参数的值,比如FILESBUFFERS

8.2.1  EzConfigAddDriver

语法:EzConfigAddDriver (szDriver, szRefKey, nPosition); 

说明:EzConfigAddDriver函数在缺省系统配置文件中添加一个设备驱动程序语句。你可以指定驱动程序语句相对于另一个驱动程序语句的位置。例如,一个应用程序可以要求在Windows Himem.sys驱动程序后装入一个设备驱动程序。

除非通过调用ConfigSetFileName来修改,缺省系统配置文件是启动时执行的Config.sys文件。为将另一个文件作为缺省系统配置文件,调用ConfigSetFileName。为确定缺省系统配置文件的全限定名,调用ConfigGetFileName。

参数:

szDriver

指定要加入到文件中的驱动程序的全限定名。如果驱动程序已经存在于系统配置文件的一个或多个位置,该函数仅置换包含驱动程序名的最后一行。

szRefKey

Specifies the name of the device driver relative to which you are adding szDriver.

指定相对于你要添加的szDriver的参考设备驱动程序名。

nPosition

指示szDriver要添加到szRefKey指定的驱动程序的前面还是后面。在该参数位置传递下列预定义常量之一:

BEFORE:语句添加到包含szRefKey的行的前面。如果szRefKey包含一个空字符串(“”),驱动程序作为第一个驱动程序插入到系统配置文件中。

AFTER:语句添加到包含szRefKey的行的后面。如果szRefKey包含一个空字符串(“”),驱动程序作为最后一个驱动程序插入到系统配置文件中。

返回值:

0:EzConfigAddDriver成功添加设备驱动程序语句到文件中。

< 0:EzConfigAddDriver was unable to add the driver statement.

EzConfigAddDriver未能添加驱动程序语句。

8.2.2  EzConfigAddString

语法:EzConfigAddString (szLine, szRefKey, nOptions);

说明:EzConfigAddString函数添加一行文本到缺省系统配置文件。你可以指定你要添加的行相对于文件中另一个语句的位置。

除非通过调用ConfigSetFileName来修改,缺省系统配置文件是启动时执行的Config.sys文件。为将另一个文件作为缺省系统配置文件,调用ConfigSetFileName。为确定缺省系统配置文件的全限定名,调用ConfigGetFileName。

参数:

szLine

指定添加到系统配置文件中的文本行。

szRefKey

指定在系统配置文件中相对于你要放置的szLine的参考字。EzConfigAddString在系统配置文件中查找参考字并在包含该字的行前或后放置参数szLine的内容,依赖传递给nOptions的内容。

nOptions

指示由szLine指定的行要添加到包含szRefKey的行的前面还是后面。在该参数位置传递下列预定义常量之一:

BEFORE:将由szLine指定的行添加到包含szRefKey的行的前面。如果szRefKey包含一个空字符串(“”),szLine作为首行插入到系统配置文件中。

AFTER:将由szLine指定的行添加到包含szRefKey的行的后面。如果szRefKey包含一个空字符串(“”),szLine作为末行插入到系统配置文件中。

返回值:

0:EzConfigAddString成功添加字符串到缺省系统配置文件中。

< 0:was unable to add the text string.

EzConfigAddString未能添加文本行。

8.2.3  EzConfigGetValue  

语法:EzConfigGetValue (szRefKey, nvValue);

说明:EzConfigGetValue函数检索缺省系统配置文件中的一个参数的数值型值,如FILESBUFFERS。除非通过调用ConfigSetFileName来修改,缺省系统配置文件是启动序列中执行的Config.sys文件。为将另一个文件作为缺省系统配置文件,调用ConfigSetFileName。为确定缺省系统配置文件的全限定名,调用ConfigGetFileName。

参数:

szRefKey

指定其值要被检索的参数名。

nvValue

返回由szRefKey指定的关键字的数值型值。

返回值:

0:EzConfigGetValue成功检索该值。

< 0:EzConfigGetValue未能检索该值。

8.2.4  EzConfigSetValue

语法:EzConfigSetValue (szRefKey, nValue);

说明:EzConfigSetValue函数设置缺省系统配置文件中的一个命令值。除非通过调用ConfigSetFileName来修改,缺省系统配置文件是启动时执行的Config.sys文件。为将另一个文件作为缺省系统配置文件,调用ConfigSetFileName。为确定缺省系统配置文件的全限定名,调用ConfigGetFileName。

参数:

szRefKey

指定其值要被修改或添加到缺省系统配置文件中的命令。如果文件中不存在该关键字,将被添加。

nValue

指定由szRefKey指定的命令的新值。

返回值:

0:EzConfigSetValue成功设置该值。

< 0:EzConfigSetValue没有能够设置该值。

9  文件和文件夹函数

    文件和文件夹函数提供一个全面的方法来处理文本文件,二进制文件和文件夹。许多函数使用变量TARGETDIR 和SRCDIR作为路径并只接受文件名作为参数。适当时也接受通配符。

s ChangeDirectory

使指定的目录为当前目录。

s CloseFile

关闭一个打开的文件。

s CopyFile

将一个文件从一个文件夹拷贝到另一个。

s CreateDir

创建一个新文件夹。

s CreateFile

创建一个指定文件名的文件。

s DeleteDir

删除一个文件夹。

s DeleteFile

删除一个文件。

s ExistsDir

确定指定目录是否存在。

s ExistsDisk

确定指定磁盘是否存在。

s FileCompare

将一个文件和另一个比较。

s FileDeleteLine

删除一个文本文件中的一行。

s FileGrep

在一个文本文件中查找指定文本。

s FileInsertLine

在一个文本文件中插入一行。

s FindAllDirs

查找指定文件夹下的所有子文件夹。

s FindAllFiles

查找指定文件夹中的所有和一个文件说明匹配的文件和它的子文件夹。

s FindFile

查找在指定文件夹中和一个文件说明匹配的第一个文件。

s GetFileInfo

检索一个文件的属性,日期,时间和大小。

s GetLine

从一个打开的文件中检索一行文本。

s OpenFile

打开一现存文件。

s OpenFileMode

用OpenFile函数设置文件打开的方式。

s ReadBytes

从一个二进制文件中读取指定的字节数。

s RenameFile

更名一个文件。

s SeekBytes

在一个二进制文件中定位文件指针。

s SetFileInfo

设置一个文件的属性,日期和时间。

s WriteBytes

在一个二进制文件的当前文件指针位置写入指定数目的字节。

s WriteLine

将一个字符串写入一个文本文件。

s XCopyFile

将一个或多个文件从一个源文件夹拷贝到一个目标文件夹,如果指定则包括子文件夹。

相关函数

s SelectDir

请参阅4.10。

9.1  ChangeDirectory

语法:ChangeDirectory (szPath);

说明:ChangeDirectory函数设置当前目录。

参数:

szPath

指定要被设置为当前目录的目录名。该名可以是一个全限定路径名或一个UNC路径;它必须不包括一个尾随反斜杠。如有必要,在调用ChangeDirectory前调用StrRemoveLastSlash。

返回值:

0:ChangeDirectory成功设置指定目录为当前目录。

< 0:ChangeDirectory未能设置指定目录为当前目录。

注解:

·注意在你调用ChangeDirectory将一个指定目录设为当前目录后,该目录不能被删除。在你可以删除该目录前,你必须再次调用ChangeDirectory来设置一个不同的当前目录。

9.2  CloseFile

语法:CloseFile (nvFileHandle);

说明:CloseFile函数关闭一个已经由调用OpenFile打开的文件。在你关闭一个文件后,你不能从中读或写到该文件。

参数:

nvFileHandle

指定要关闭的文件的句柄。

返回值:

0:表明该函数成功关闭该文件。

< 0:表明该函数未能关闭该文件。

9.3  CopyFile

语法:CopyFile (szSrcFile, szTargetFile);

说明:CopyFile函数创建一个由参数szSrcFile指定的文件的拷贝。新文件由参数szTargetFile指定文件名。

参数:

szSrcFile

指定要拷贝的文件的文件名。如果该文件名是限定的,也就是,如果它包括一个路径,CopyFile将从指定位置拷贝该文件。如果szSrcFile包含一个未限定文件名,也就是,没有路径信息,CopyFile将从由系统变量SRCDIR标识的路径拷贝。为拷贝一组文件,在该参数位置使用通配符。

szTargetFile

指定给由szSrcFile标识的文件的拷贝的名称。如果文件名是限定的,也就是,如果它包含一个路径,CopyFile将把文件拷贝到路径指定的位置。如果szSrcFile包含一个未限定文件名,也就是,没有路径信息,拷贝将被创建在由系统变量TARGETDIR指定的目录中。如果目标目录不存在,它将被创建。

    当由szSrcFile指定的文件名中包含一个通配符时,szTargetFile的文件名部分被忽略;每个源文件以它的现存名被拷贝到由szTargetFile指定的路径。如果szTargetFile包含一个未限定文件名,文件将被拷贝到由系统变量TARGETDIR指定的目录中。因此,CopyFile不能被用来拷贝和重命名一组文件。当szSrcFile包含一个或多个通配符时,源目录和目标目录必须不同。

返回值:

0:表明函数成功地从源目录拷贝文件至目标目录。

< 0:表明函数因下列情况之一未能拷贝所要文件:

COPY_ERR_CREATEDIR (-27):目标目录不能被创建。确保系统变量TARGETDIR中的路径语法正确并且你有权访问目标驱动器。

COPY_ERR_MEMORY (-6):函数未能分配完成拷贝文件进程所需的内存。尽可能多地终止正在运行的应用程序以释放内存。

COPY_ERR_NODISKSPACE (-38):函数未能在目标驱动器上找到足够的磁盘空间来拷贝文件。在目标驱动器上释放磁盘空间。

COPY_ERR_OPENINPUT (-2):函数未能打开系统变量SRCDIR指定的输入文件。确保源文件有一个有效的文件名并且源文件和目标目录都存在。

COPY_ERR_OPENOUTPUT (-3):函数未能拷贝所要文件。

COPY_ERR_TARGETREADONLY (-46):TARGETDIR中的文件是只读文件。删除目标文件的只读属性并重试。

所有其它负值:表明发生一些其它不确定错误。

注解:

·如果你使用未限定文件名并在使用CopyFile时设置SRCDIR和 TARGETDIR的值,在调用CopyFile前用VarSave保存当前值并然后用VarRestore重新设置。如果目标目录不存在,CopyFile创建它。

·你不能通过调用CopyFile时使用通配符来重命名一组文件。然而,单独一个文件时你可以使用CopyFile来做到。

·为包括子目录,调用XcopyFile函数。

·对于文件传输,XCopyFile 是CopyFile的一个完美替换。XCopyFile可以做版本检测,标记锁定的.dll和.exe文件待系统重启后更新,并且递增共享的.dll和.exe文件的注册表访问计数器。

·因为Windows 95及更高版本不允许一个空文件被拷贝,Windows NT不允许创建空文件,CopyFile在这些平台下当被用来拷贝空文件(Size=0KB)时将不工作。

· 在用WriteProfString 或 WriteProfInt修改.ini文件后, Windows 95及更高版本下,你必须在使用CopyFile前刷新高速缓存。所有.ini文件在Windows 95及更高版本下被放在高速缓存中;这种特性可能导致延迟将修改写到指定文件。这接着可能妨碍随后的文件操作。为避免这个问题,简单地以空参数调用WriteProfString来强制Windows 95 及更高版本立即写数据到.ini文件,如下所示:

    WriteProfString ("C:\\Test.ini", "Windows", "KeyboardDelay", "100");

    //null string ("") for all four parameters

    WriteProfString ("", "", "", ""); 

    //CopyFile should now have access to updated file.

    CopyFile ("C:\\Test.ini", "C:\\Temp\\Test.ini");

9.4  CreateDir

语法:CreateDir (szDirPath);

说明:CreateDir函数在目标驱动器上创建一个或多个子目录。你可以使用一个包含多层子目录的路径,如C:\Programs\Winapps\Myapp。任何路径中不存在的子目录,CreatDir将创建它。例如,如果C:\Programs\Winapps 和 C:\Programs\Winapps\Myapp都不存在,这些子目录将都被CreatDir创建。

参数:

szDirPath

指定要创建的子目录的全限定路径。将路径中的每层用一个反斜杠分隔(通过使用反斜杠转义符(\\))。

返回值:

0:表明函数在目标驱动器上成功创建指定目录或指定目录已经存在。

< 0:表明指定目录不存在并且函数未能创建指定它。

注解:

下列情况下CreatDir将失败:

s 路径非法;

s 驱动器或路径上的任何子目录是写保护的;

s 驱动器名无效;

s 你没有网络特权来创建子目录。

9.5  CreateFile

语法:CreateFile (nvFileHandle, szPath, szFileName);

说明:CreateFile函数创建一个新文件。如果相同名的文件已经存在,CreateFile改写它。在你用CreateFile创建一个文件前,你必须用OpenFileMode设置文件方式。

    CreateFile将新创建的文件打开为读/写(二进制文件)或添加(文本文件)方式,因此你可以使用其它函数,如GetLine, ReadBytes, WriteLine和 WriteBytes.来从文件中读或写到文件中。

    除了读/写或添加方式,所有新创建文件自动打开为OF_SHARE_DENY_NONE方式。这意谓着文件被打开为不拒绝其它程序对它的读或写。这种方式的根段记录在Windows OpenFile API中。当你结束从一个文件读或对它写时,你必须使用CloseFile函数来关闭该文件。

参数:

nvFileHandle

返回新文件的句柄。

szPath

指定新文件创建所在的子目录的全限定路径。

szFileName

指定创建的文件的文件名。

返回值:

0:表明函数成功创建新文件。

< 0:表明函数未能创建新文件。

注解:

·CreateFile创建一个新文件并把它打开以便你可以从新文件中读或写到新文件中。为写到一个现存文件中,你必须首先用OpenFileMode 和OpenFile函数以FILE_MODE_APPEND方式打开文件。

·当操作日志被激活时,CreateFile的函数操作不存入到卸载记录中。如果你想要一个由CreatFile创建的文件被存入到卸载记录中,则当存入功能被激活时,使用XcopyFile传输一个启动程序文件(以你要的文件名)到目标系统。你用Enable 和Disable函数激活和禁用存入功能。当存入功能被激活时,XcopyFile操作被存入,启动程序文件被存入后,你可以使用CreatFile和其它文件相关函数来写或改写被存入的启动程序文件。文件名必须保持不变否则它不会在卸载记录中找到。

9.6  DeleteDir

语法:DeleteDir(szDir, nFlag);

说明:DeleteDir函数删除一个子目录。根据你在参数nFlag使用的值,你可以仅当子目录为空时删除它,即使子目录包含文件也删除它,或删除整个根目录。设置nFlag需特别谨慎。

参数:

szDir

指定要被删除的目录的全限定名。

nFlag

指定删除选项。在该参数位置传递下列预定义常量之一:

ALLCONTENTS:删除szDir指定的目录,包括其下的所有子目录和文件。你删除的目录必须是一个子目录,不能是驱动器上的一个根目录。

ONLYDIR:仅当szDir指定的目录为空时才删除它。否则函数失败。

ROOT:即使szDir指定的目录是根目录也要删除它。如果szDir是一个根目录,DeleteDir将删除磁盘上一切东西。

返回值:

0:表明函数成功删除子目录。

< 0:表明函数未能删除子目录。

注解:

·你不能删除当前目录。

·你不能删除一个网络系统上你没有适当权利的文件。

·DeleteDir不能删除只读,隐藏或系统文件。

·如果DeleteDir遇到一个只读文件,该函数可能在只删除子目录中一些文件后失败。

9.7  DeleteFile

语法:DeleteFile (szFile);

说明:DeleteFile函数删除一个或多个文件。注意DeleteFile不能删除只读,隐藏或系统文件。如果你试图删除一个网络系统上你没有适当文件权利的文件时,该函数不起作用。

参数:

szFile

指定要删除文件的名称。如果szFile指定一个全限定名,也就是,包括一个路径,DeleteFile将从指定目录删除该文件。如果szFile包含一个未限定文件名,也就是,没有路径信息,DeleteFile将从由系统变量TARGETDIR指定的目录中删除文件。可以在szFile中包含通配符来删除多个文件。

返回值:

0:表明函数成功删除指定文件。

< 0:表明函数未能删除指定文件。

注解:

你在使用FindFile时可以使用通配符来定位文件然后用DeleteFile删除它们。

9.8  ExistsDir

语法:ExistsDir (szPath);

说明:ExistsDir函数在目标系统上检测指定目录的存在性。

参数:

szPath

指定要在目标系统上找到的目录的全限定路径。

返回值:

EXISTS (0):表明指定目录存在于目标系统上。

NOTEXISTS (-1):表明指定目录不存在于目标系统上。

9.9  ExistsDisk

语法:ExistsDisk (szDisk);

说明:ExistsDisk函数在目标系统上检测指定磁盘驱动器的存在性。

参数:

szDisk

指定磁盘驱动器字符。

返回值:

EXISTS (0):表明目标系统上存在指定驱动器。

NOTEXISTS (-1):表明目标系统上不存在指定驱动器。

9.10  FileCompare

语法:FileCompare (szFileName1, szFileName2, nCompareFlag);

说明:FileCompare函数比较两个文件的大小,日期或版本。

参数:

szFileName1

指定要比较的第一个文件的全限定名。

szFileName2

指定要比较的第二个文件的全限定名。

nCompareFlag

指定比较选项。在该参数位置传递下列预定义常量之一:

COMPARE_SIZE:比较两个文件的大小。

COMPARE_DATE:比较两个文件的日期。

COMPARE_VERSION:比较两个文件的版本资源。

返回值:

EQUALS (2):第一个文件的日期,大小或版本和第二个的相等。

FILE_NOT_FOUND (-2):函数未能找到一个文件或都未能找到。

GREATER_THAN (0):第一个文件比第二个文件更新或更大,根据在参数nCompareFlag使用的常量:

.COMPARE_VERSION

文件一比文件二新。

.COMPARE_DATE

文件一比文件二日期后。

.COMPARE_SIZE 

文件一比文件二大。

.LESS_THAN (1)

文件一比文件二旧或小。

OTHER_FAILURE (-1)

发生不确定错误。

9.11  FileDeleteLine

语法:FileDeleteLine (szFileName, nStartLineNum, nEndLineNum);

说明:FileDeleteLine函数从一个文本文件中使用一个起始行和结束行行号来删除该区域的行(包括起始行和结束行)。该函数作用于面向行的文本文件;它不作用于二进制文件。你可以使用FileDeleteLine 和FileGrep函数来查找和删除一个文件中的文本行。

    由szFileName指定的文件必须尚未通过调用OpenFile被打开。如果szFileName已经被打开,在调用FileDeleteLine前调用CloseFile。

参数:

szFileName

指定文件的全限定名,它位于系统变量SRCDIR指定的目录中。如果该文件存在,由nStartLineNum 和nEndLineNum指定的行将从该文件中删除。

nStartLineNum

指定要从文件中删除的第一行的行号。注意行从0开始编号。

nEndLineNum

指定要从文件中删除的最后一行的行号。注意行从0开始编号。为了从nStartLineNum指定的行开始删除到文件结尾,给该参数传递预定义常量DELETE_EOF。

返回值:

0:FileDeleteLine从该文件成功删除指定行。

< 0:FileDeleteLine因为下列情况之一而失败:

FILE_NOT_FOUND (-2):InstallShield未能找到szFileName指定的文件。

FILE_RD_ONLY (-5):文件是写保护的。

LINE_NUMBER (-7):一个你所指定的行号小于0,或者文件中没有该行号。

OUT_OF_DISK_SPACE (-6):没有足够的磁盘驱动器空间来完成指定操作。

OTHER_FAILURE (-1):发生其它一些不确定错误。

9.12  FileGrep

语法:FileGrep (szFileName, szSearchStr, svReturnLine, nvLineNumber, nFlag);

说明:FileGrep函数在一个文本文件中查找一个指定字符串。如果字符串被找到,包含该字符串的行被返回到参数svReturnLine,该行的行号被返回到参数nvLineNumber。查找不区分大小写。FileGrep作用于面向行的文本文件;它不作用于二进制文件。

    在用FileGrep查找一个文件之前没有必要打开它;你也无须在调用FileGrep之后关闭它。文件打开和文件关闭由FileGrep自动执行。虽然多数情况下,FileGrep对一个已经被打开的文件(先前调用OpenFile的结果)将成功执行,但如果文件是以添加方式打开时,FileGrep将返回FILE_NOT_FOUND。

参数:

szFileName

指定要查找的文件的全限定名。

szSearchStr

指定查找字符串。

svReturnLine

返回szSearchStr被找到的行。

nvLineNumber

返回szSearchStr被找到的行的行号。行以0开始编号。

nFlag

指定查找选项。在该参数位置传递下列预定义常量之一:

CONTINUE:检索查找字符串的下一个出现(如果有)。

RESTART:检索查找字符串的第一次出现。

返回值:

0:FileGrep找到指定字符串。

< 0:FileGrep因下列情况之一而失败:

END_OF_FILE (-4):没有找到查找字符串而已到文件尾。

FILE_NOT_FOUND (-2):InstallShield未能找到szFileName指定的文件。

FILE_LINE_LENGTH (-3):行超过允许的最大长度。

OTHER_FAILURE (-1):发生一个不确定错误。

9.13  FileInsertLine

语法:FileInsertLine (szFileName, szInsertLine, nLineNumber, nInsertFlag);

说明:FileInsertLine函数通过指定行号来插入或置换一行。你可以将FileInsertLine 和 FileGrep一起使用,FileGrep找到行并返回它们的行号。

  FileInsertLine工作于面向行的且每行不超过1024字节的文本文件。InstallShield假定任何长于最大允许长度的行表明了这是一个二进制文件而导致FileInsertLine失败。

  由szFileName指定的文件必须尚未通过调用OpenFile被打开。如果szFileName已经被打开,在调用FileInsertLine前调用CloseFile。

参数:

szFileName

指定文件的全限定名,它位于系统变量SRCDIR指定的目录中。如果该文件存在,则将szInsertLine的值插入其中。

szInsertLine

指定插入到文件中的字符串。

nLineNumber

指定你要将szInsertLine插入到的行号。第一行行号是0

nInsertFlag

指定一个插入位置选项。在该参数位置传递下列预定义常量之一:

BEFORE:在nLineNumber前插入。

AFTER:在nLineNumber后插入。

APPEND;将szInsertLine添加到nLineNumber指定的行。

REPLACE:用szInsertLine 置换nLineNumber指定的行。

返回值:

0:FileInsertLine成功插入行到指定文件。

FILE_LINE_LENGTH (-3):表明行长超过文本文件允许的最大长度。

FILE_NOT_FOUND (-2):FileInsertLine未能找到szFileName指定的文件。

FILE_RD_ONLY (-5):表明文件写保护。

LINE_NUMBER (-7):表明你指定的行号之一小于0,或在文件中不存在该行号。

OUT_OF_DISK_SPACE (-6):表明没有足够的磁盘驱动器空间来完成指定操作。

OTHER_FAILURE (-1):发生一个不确定错误。

9.14  FindAllDirs

语法:FindAllDirs (szDir, nOp, listDirs);

说明:FindAllDirs查找整个磁盘或目录的结构并返回一个子目录名的字符串列表。如果nOp 是INCLUDE_SUBDIR,查找从szDir指定的目录开始并继续查找子目录结构。

参数:

szDir

指定查找的目录名。

nOp

指定是否要查找szDir下的所有子目录。在该参数位置传递下列预定义常量之一:

EXCLUDE_SUBDIR:不包括子目录。

INCLUDE_SUBDIR:包括子目录。

listDirs

返回全限定目录名列表。listDirs标识的字符串列表必须已经通过调用ListCreat被初始化。

返回值:

0:FindAllDirs成功生成子目录名列表。

< 0:FindAllDirs未能生成一个列表。

注解:

·FindAllDirs从指定目录开始查找一个分层子目录结构。如果指定目录是一个根目录并且nOp 包含INCLUDE_SUBDIR,则返回整个磁盘上的所有目录名。你可以使用FindAllDirs来找到一个特定目录的子目录,或你可以使用它来找到一个磁盘上的所有目录。

9.15  FindAllFiles

语法:FindAllFiles (szDir, szFileName, svResult, nOp);

说明:FindAllFiles函数查找一个整个子目录结构并返回第一个有特定文件说明的文件的文件名。如果传递给nOp的变元是RESET,InstallShield在参数szDir指定的目录中开始查找并继续在其子目录结构中查找直到它找到与szFileName匹配的一个文件。如果nOp等于CONTINUE,查找从函数上次被调用时离开的地方继续。重复调用该函数来找到所有出现的与szFileName匹配的文件。

参数:

szDir

指定要查找的目录名。

szFileName

指定要查找的文件说明。该参数允许通配符。

svResult

如果找到则返回第一个匹配文件的全限定名。如果FindAllFiles失败,svResult保持不变。

nOp

指示查找选项。在该参数位置传递下列预定义常量之一:

CONTINUE:在前一个查找停止的位置继续查找。

RESET:在szDir指定的目录开始处开始查找。

CANCEL:释放先前调用FindAllFiles时访问的所有文件和文件夹。运行在Windows NT下的安装中,以该参数调用FindAllFiles来确保随后的对已经由FindAllFiles访问过的文件和文件夹的操作成功。

为找到所有与文件说明匹配的文件,可按下列步骤进行:

1. 将要查找的文件夹名赋给szDir。

2. 将文件说明赋给szFileName,如IS5*.txt。

3. 将nOp设置为RESET,调用FindAllFiles。

4. 当FindAllFiles的返回码是0时,保存svResult返回的文件名;然后调用FindAllFiles, nOp 设置为 CONTINUE.。

5. 最后,运行在Windows NT下的安装中,调用FindAllFiles ,nOp设置为CANCEL

返回值:

0:表明函数检索并返回一个与说明匹配的文件。

< 0:表明函数未能找到一个与说明匹配的文件。

注解:

·该函数从指定目录开始查找一个分层子目录结构。如果指定目录是一个根目录,InstallShiled查找整个磁盘。函数在它找到的第一个匹配文件名处停止。

·第一次你调用该函数来开始一个新的查找,设置nOp为RESET。你可以通过设置nOp为CONTINUE来继续查找指定文件的所有其它出现,并可把该函数调用放在一个循环中,以 FindAllFiles函数失败为结束。

·你不能在一个FindAllFiles(..., RESET)和FindAllFiles(..., CONTINUE) 循环中使用Xcopyfile函数。如果你在一个FindAllFiles循环中调用XcopyFile,由FindAllFiles(..., CONTINUE)返回的文件名可能不正确。

9.16  FindFile

语法:FindFile (szPath, szFileName, svResult);

说明:FindFile函数在一个目录中查找一指定文件。InstallShield在参数svResult返回第一个匹配的文件。

参数:

szPath

指定要查找的目录名。该目录下的子目录不被查找。

szFileName

指定要查找的文件名。该参数允许通配符。

svResult

返回与szFileName匹配的第一个文件的文件名。该参数包含未限定文件名(也就是,不包括驱动器指示符和路径)。

返回值:

0:表明函数成功找到并返回指定文件。

< 0:表明函数未能找到文件。

注解:

·该函数只查找指定子目录。它不查找整个磁盘或目录树。

9.17  GetFileInfo

语法:GetFileInfo (szPathName, nType, nvResult, svResult);

说明:调用GetFileInfo函数来确定一个文件的属性,日期,时间或大小。每个GetFileInfo语句中,你只可以要求这些数据项中的一个。例如,为得到一个文件的日期和时间信息,你必须调用GetFileInfo两次,一次取得日期,一次取得时间。

参数:

szPathName

指定你要检索其信息的文件的全限定名。

nType

指定要检索的信息类型。如果该信息是一个数字,GetFileInfo把它放到nvResult。如果信息是一个字符串,GetFileInfo把它放到svResult。在该参数位置传递下列预定义常量之一:

FILE_ATTRIBUTE:文件属性在nvResult返回。看注解。

FILE_DATE:文件日期以YYYY\MM\DD格式返回到svResult。

FILE_SIZE:大小以字节数返回到nvResult。

FILE_TIME:文件时间以HH:MM:SS格式返回到svResult。

nvResult

返回数值型信息。

svResult

返回字符串型信息。

返回值:

0:表明函数成功检索所需文件信息。

< 0:表明函数未能检索所需文件信息。

注解:

·在以FILE_ATTRIBUTE为第二个参数(nType),调用GetFileInfo后,使用if-then-else逻辑来确定文件属性。如果nvResult = FILE_ATTR_NORMAL,那么没有设置文件属性。如果nvResult <> FILE_ATTR_NORMAL,对nvResult和一个或多个文件属性常量用按位与操作符来确定设置了哪个属性。

if (nvResult = FILE_ATTR_NORMAL) then

//The file is NORMAL.

else

if (FILE_ATTR_HIDDEN & nvResult) then

//The file is HIDDEN.

endif;

if (FILE_ATTR_READONLY & nvResult) then

//The file is READ-ONLY.

endif;

endif;

9.18  GetLine

语法:GetLine (nvFileHandle, svLine);

说明:GetLine函数从一个只读方式打开的文本文件中读取一行。在你调用GetLine之前,你必须首先调用openFileMode来设置文件方式为只读,然后调用OpenFile来打开该文件。对GetLine的第一次调用从文件中读取第一行文本。读取一行后,GetLine把文件指针重新定位到下一行。对GetLine的第二次调用读取第二行,如此继续。GetLine从它返回的行中去除回车和换行字符。

    为写到一个文本文件,使用WriteLine函数。WriteLine总是生成在行尾有一个回车和换行字符组合的行。

参数:

nvFileHandle

指定已经由调用OpenFile打开的文件的句柄。

svLine

返回从nvFileHandle指定的文件中返回的一行文本。

返回值:

0:表明函数从一个打开的文本文件中成功检索一行文本。

< 0:表明函数因到文件尾或其它错误情况而失败。这种情况也表明GetLine已经读取了该文件中的所有行。

注解:

·一行的最大长度是4096个字符。为从一个文件中读取多行,每读一行都单独调用一次GetLine或把GetLine语句放在一个循环中。

·当GetLine已经读取了文件中的所有行,则返回一个文件尾(end-of-file)的错误。注意如果你以添加方式打开一个文件,你调用GetLine函数时将失败因为文件指针在文件尾。如果由nvFileHandle指定的文件以二进制方式打开,则该函数也会失败。

9.19  OpenFile

语法:OpenFile (nvFileHandle, szPath, szFileName);

说明:OpenFile函数打开一个文本文件或二进制文件。在你打开该文件前,你必须通过调用OpenFileMode设置文件方式。

    你打开一个文本文件后,调用GetLine 和 WriteLine来对文件读和写。你打开一个二进制文件后,调用ReadBytes 和 WriteBytes来对文件读和写。在对一个二进制文件写之前,你可能需要使用SeekBytes来定位文件指针。

    你也可以使用FileGrep, FileInsertLine, 和 FileDeleteLine函数来对文本文件进行查找,读和写。然而,这些函数不要求你打开或关闭文件(这被内部处理)。根据你的需要,这些函数可以提供给你更好的服务。当你用GetLine 或 WriteLine完成对一个文件的读或写后,你必须调用CloseFile函数来关闭该文件。

    使用CreateFile来创建一个文件。CreateFile以添加方式(文本文件)或读/写方式(二进制文件)打开新文件。

参数:

nvFileHandle

返回被打开文件的句柄。当你调用InstallShield中其它文件相关函数时,使用该句柄来标识该文件。

szPath

指定你要打开的文件的路径(可能包含一个驱动器指示符)。

szFileName

指定你要打开的文件的未限定名(也就是,没有一个驱动器指示符或路径)。

返回值:

0:表明函数成功打开文件。

< 0:表明函数未能打开文件。

9.20  OpenFileMode

语法:OpenFileMode (nMode);

说明:OpenFileMode函数设置你要打开或创建的文件的方式。你传递给参数nMode的变元设置文件方式为下列之一:

s 文本文件为添加方式;

s 文本文件为只读方式;

s 二进制文件为读/写方式;

s 二进制文件为只读方式。

    你设置文件方式后,调用OpenFile 来打开一个现存文件或调用CreateFile来创建和打开一个新文件。

参数:

nMode

指定以何种方式打开一个文件。在该参数位置传递下列预定义常量之一:

FILE_MODE_APPEND:该常量允许一个文本文件以添加方式被打开或被创建。当一个文件以添加方式由OpenFile打开时,文件指针在文件尾。你可以使用WriteLine函数添加行到文件尾。用CreateFile创建的文件是新的(空的),因此添加到文件中的行被写到文件的开始。注意如果你以添加方式打开一个文件,如果你调用GetLine函数,它会失败,因为文件指针在文件尾。

FILE_MODE_NORMAL:该常量允许一个文本文件以只读方式被打开。当一个文件以只读方式由OpenFile打开时,文件指针在文件头。你可以使用GetLine函数来读文件。当FILE_MODE_NORMAL有效时,用CreateFile创建的文件实际将以FILE_MODE_APPEND方式创建。

FILE_MODE_BINARY:该常量允许一个二进制文件以读/写方式打开或创建。当你用OpenFile 或 CreateFile打开或创建一个二进制方式文件时,你可以调用ReadBytes从该文件读和调用WriteBytes来写到该文件。写到一个二进制文件中时从当前的文件指针位置开始,对于一个新打开或创建的文件该位置是0,即文件的开始。如果你要添加到一个用OpenFile打开的二进制文件时,你必须在写之前使用SeekBytes来定位文件指针。为打开一个CD-ROM或一个只读驱动器上的文件时,调用OpenFileMode来设置文件方式为只读(FILE_MODE_BINARYREADONLY)。

FILE_MODE_BINARYREADONLY:该常量和FILE_MODE_BINARY常量类似,除了它以只读方式打开二进制文件。当打开CD-ROM或只读驱动器上的一个二进制文件时,使用该常量来打开一个二进制文件。FILE_MODE_BINARY会在打开CD-ROM或只读驱动器上的二进制文件时失败。

返回值:

0:表明函数成功设置文件方式。

< 0:表明函数未能设置文件方式。

9.21  ReadBytes

语法:ReadBytes (nFileHandle, svString, nIndex, nBytes);

说明:ReadBytes函数从一个文件中当前文件指针开始读取指定数目的字节。当该函数返回时,InstallShield将文件指针重新定位到从文件中读取字节的结束位置。

  你必须调用OpenFileMode 和 OpenFile以二进制方式打开文件,然后才能从中读取。

  参数nIndex是svString指定的值中的下标。使用参数nBytes来指定在文件中从参数 nIndex指定处开始读取多少字节。如果nIndex加上nBytes的值大于svString的长度,只从文件中读出字符串中指定下标开始到字符串结尾的字节数。例如,如果svString声明为100个字节长,参数nIndex声明为50字节,参数nBytes为75字节,则只有4999之间的字节(50个字节,而不是75个字节)被读出。

参数:

nFileHandle

指定以二进制方式打开的文件的文件句柄。

svString

返回从文件中读出的字节。传递给该参数的变量必须已经被声明为显式大小,并且它必须足够大来容纳由nBytes指定数目的字节。

nIndex

指定svString中的一个下标;文件中的数据在这个位置被插入到字符串。

nBytes

指定从文件中读取的字节数。字节从文件指针当前位置开始读取。字节被读取时,InstallShield重新定位文件指针。

返回值:

X:表明函数从文件中成功读取字节,X是实际返回到svString的字节数。

< 0:表明函数未能从文件中读取字节。

9.22  RenameFile

语法:RenameFile (szSrcFile, szTargetFile);

说明:RenameFile函数修改文件名和/或将一个文件从一个目录移动到另一个目录。

参数:

szSrcFile

指定要被更名或移动的文件的文件名。如果szSrcFile指定一个全限定名,也就是,如果它包括一个路径,RenameFile将更名或移动指定目录下的文件。如果szSrcFile包含一个未限定名,也就是,没有路径信息,RenameFile将更名或移动到系统变量SRCDIR指定的目录下的文件。注意不允许通配符;每次调用RenameFile只能更名或移动一个文件。

szTargetFile

为文件指定一个新名和/或新位置。如果szTargetFile指定一个全限定名,也就是,如果它包括一个路径,RenameFile将更名或移动文件到指定目录下。如果szTargetFile包含一个未限定名,也就是,没有路径信息,RenameFile将文件更名或移动到系统变量SRCDIR指定的目录下。看下面的注解。

返回值:

0:表明函数成功修改文件名或移动文件。

< 0:表明函数未能修改文件名或移动文件。

注解:

·如果szSrcFile 和 szTargetFile指向相同目录(或当使用未限定名时,SRCDIR 和 TARGETDIR指向相同目录),则由szSrcFile指定的文件将被更名,除非由szTargetFile指定的文件已经存在于该目录下。

·如果szSrcFile 和 szTargetFile指向不同目录(或当使用未限定名时,SRCDIR 和 TARGETDIR指向不同目录),则由szSrcFile指定的文件将被移动到新目录并命名为由szTargetFile指定的名称,除非由szTargetFile指定的文件已经存在于该目录下。

9.23  SeekBytes

语法:SeekBytes (nFileHandle, nBytes, nPosition);

说明:SeekBytes函数在一个打开的二进制文件中重新定位文件指针。你可以以相对于当前位置或相对于文件头或尾一个特定字节数来移动文件指针。调用SeekBytes前,你必须通过OpenFileMode 和 OpenFile以二进制方式打开文件。当你结束写字节到文件时,调用CloseFile来关闭文件。

参数:

nFileHandle

指定以二进制方式打开的文件的文件句柄。

nBytes

指定文件指针相对于nPosition指定的位置要移动的字节数。如果nBytes是一个整数,文件指针向文件尾移动。如果nBytes是一个负数,文件指针向文件头移动。

nPosition

指定文件中的位置,指针从该位置移动nBytes。在该参数位置传递下列预定义常量之一:

FILE_BIN_CUR:从当前位置开始指针移动nBytes。

FILE_BIN_END:从文件尾开始指针移动nBytes。

FILE_BIN_START:从文件头开始指针移动nBytes。

返回值:

0:表明函数成功重新定位指针。

< 0:表明函数未能重新定位指针。

9.24  SelectDir

请参阅4.10。

9.25  SetFileInfo

语法:SetFileInfo (szPathFile, nType, nAttribute, szValue);

说明:SetFileInfo函数设置一个现存文件的日期或时间,或修改该文件的属性。为修改一个文件的日期和时间,你必须调用SetFileInfo两次,依次修改日期,一次修改时间。然而你可以通过在参数nAttribute位置把常量用或操作符(|)组合起来,仅调用SetFileInfo一次而设置文件的多个属性。

参数:

szPathFile

指定你要修改其日期,时间或属性的文件的全限定名。

nType

指定要修改的文件特性。在该参数位置传递下列预定义常量之一:

FILE_ATTRIBUTE:表明文件的一个或多个属性将被修改。

FILE_DATE:表明文件的日期将被修改。

FILE_TIME:表明文件的时间将被修改。

nAttribute

当nType 是FILE_ATTRIBUTE时,指定文件属性(当nType 是 FILE_DATE 或 FILE_TIME时,给该参数传递0)。为指定多个文件属性,将下列预定义常量用或操作符(|)组合起来:

FILE_ATTR_ARCHIVED:设置存档属性。

FILE_ATTR_HIDDEN:设置隐藏属性。

FILE_ATTR_READONLY:设置只读属性。

FILE_ATTR_SYSTEM:设置系统属性。

FILE_ATTR_NORMAL:当该常量被单独指定时,所有文件属性被清除。当该常量和其它文件属性常量有或操作符组合时,那些不包含在或表达式中的属性被清除。

szValue

指定下列之一:

s 当nType是FILE_DATE时,以YYYY/MM/DD 或 YYYY\MM\DD格式指定一个日期。该日期必须不早于"1980/01/01"。当使用反斜杠为分隔符时,记住一个反斜杠是作为一个转义符插入到一个字符串中的,如,"1980\\01\\01"。

s 当nType是FILE_TIME,以HH:MM:SS格式指定一个时间,使用一个24-hour时钟格式;注意秒数必须是2的倍数。

s 当nType是 FILE_ATTRIBUTE时,给该参数传递一个空字符串。

返回值:

0:表明函数成功设置文件的日期,时间或属性。

< 0:表明函数未能设置文件的日期,时间或属性。

9.26  WriteBytes

语法:WriteBytes (nFile, svString, nIndex, nBytes);

说明:WriteBytes函数写指定数目的字节到一个以二进制方式打开的文件中。该函数从文件指针当前位置开始写字节。在调用WriteBytes前,你必须调用OpenFileMode(FILE_MODE_BINARY) 来打开文件,然后调用OpenFile.。

    参数nIndex是svString中的下标。使用参数nBytes来指定从参数 nIndex指定处开始多少字节写到文件中。如果nIndex加上nBytes的值大于svString的长度,InstallShield只将字符串中指定下标开始到字符串结尾的字节数写到文件中。例如,如果svString声明为100个字节长,参数nIndex为50,参数nBytes为75,则只有51100之间的字节(50个字节,而不是75个字节)被被写到文件中。

参数:

nFile

指定以二进制方式打开的文件的文件句柄。

svString

指定包含要写到输出文件中的字节的字符串变量。

nIndex

指定svString中的一个下标;从该位置开始的字节被写到输出文件。注意第一个字节是在下标位置0

nBytes

指定你要写到输出文件中的字节数。

返回值:

X:X是实际被写的字节数。

< 0:表明函数未能写这些字节。

9.27  WriteLine

语法:WriteLine (nvFileHandle, szLine);

说明:WriteLine函数将一行文本写到以添加方式打开的文本文件中。在调用WriteLine前,你必须首先用OpenFileMode设置文件方式为添加方式,然后用CreateFile创建文件,或用OpenFile打开文件。该函数把行放置在文件尾。

   WriteLine生成行尾有一个回车和换行符的行。为写到一个二进制文件,使用WriteBytes。

   该函数不工作于只读方式打开的文件。

参数:

nvFileHandle

指定一个打开文件的文件句柄。句柄从OpenFile 或 CreateFile中获得。

szLine

指定包含要被写到文件中的文本的字符串。

"one" and "This": 

不要试图通过在你传递到szLine的字符串中嵌入换行符来写多行。下列代码将字符串写为一行,以一个非打印字符在"one" 和 "This"之间: 

     szString = "This is line one\nThis is two";

WriteLine(nvFileHandle, szString);

来只调用WriteLine一次而写两行 ,你必须插入一个回车和一个换行符(以这样的次序):

szString = "This is line one\r\nThis is two";

返回值:

0:表明函数将行成功写到文件中。

< 0:表明函数未能将行写到文件中。

注解:

·你可以通过用单引号分隔字符串来在一个字符串中嵌入双引号。例如,如果你想要写字符串"This string contains a double "quotation mark." ",你可以用下列代码:

   WriteLine(nvFileHandle, 'This string contains a double "quotation mark."');

9.28  XCopyFile

语法:XCopyFile (szSrcFile, szTargetPath, nOp);

说明:XcopyFile函数将一个或多个文件从源目录拷贝到目标目录。该函数也可以象拷贝文件一样拷贝子目录。当常量INCLUDE_SUBDIR传递到参数nOp时,如有必要, XcopyFile在目标目录上创建子目录。

    你不能用XcopyFile重命名文件。为在文件拷贝操作中重命名一个文件,使用CopyFile函数。

参数:

szSrcFile

指定要拷贝的文件。如果该文件名是限定的,也就是,如果它包括一个路径,XCopyFile将从指定位置拷贝文件。如果szSrcFile包含一个未限定文件名,也就是,没有路径信息,CopyFile将从由系统变量SRCDIR标识的路径拷贝。为拷贝多个文件,在该参数位置使用通配符。

szTargetPath

指定由szSrcFile指定的文件要被拷贝的目录。如果该参数包含一个空字符串,文件将被拷贝到由系统变量TARGETDIR指定的目录中。

nOp

指定要执行的拷贝操作类型。在该参数位置传递下列预定义常量之一。为指定多个选项,用或操作符组合常量:

COMP_NORMAL:拷贝文件到目标系统,更新现存的相同名称的文件,不考虑日期,时间或版本信息。

COMP_UPDATE_SAME:更新文件,即使源文件的日期,时间或版本都和目标文件的相同。你必须和该常量一起也指定COMP_UPDATE_DATE 或 COMP_UPDATE_ VERSION,否则,InstallShield忽略该常量。

COMP_UPDATE_DATE:根据文件日期和时间更新文件。如果源文件比目标文件新时,该常量更新文件。

COMP_UPDATE_VERSION:根据文件版本更新文件。如果源文件比目标文件新时,该常量更新文件。如果源文件和目标文件都不存在文件版本时,日期和时间来作比较。如果仅一个文件不存在文件版本,InstallShield假定包含版本信息的文件是较新的文件。

SELFREGISTER:当使用“非批处理方法“安装自注册文件时,立即进行自注册处理。

当你已经调用Enable(SELFREGISTERBATCH),该选项将自注册文件排队等待注册。当使用“批处理方法“安装自注册文件时,一旦调用Do(SELFREGISTRATIONPROCESS),这些文件被登记。总是将SELFREGISTER和常量SHAREDFILE用按位或操作符组合一起使用。

SHAREDFILE:将共享和锁定文件处理组合起来,通过让XcopyFile将所有文件处理为共享并标记锁定的.dll和.exe文件待Windows或系统重启后更新。查看RebootDialog 和 SdFinishReboot。SHAREDFILE选项使XcopyFile将所有文件处理为共享文件,并且当文件存在于目标目录并有一个大于0的访问计数器时,注册表访问计数器自动递增一。如果共享文件不存在于目标目录并没有访问计数器时,InstallShield创建该计数器并设置它为1。如果共享文件已经存在于目标目录但没有访问计数器时,InstallShield创建该计数器并初始化为2作为一个防止卸载过程中意外删除的预防措施。

LOCKEDFILE:使XCopyFile标记锁定的.dll和.exe文件待Windows或系统重启时更新。一个锁定文件是一个当InstallShield试图要访问或更新时而正在被一个应用程序或系统使用的文件。LOCKEDFILE选项和 SHAREDFILE一样工作,除了LOCKEDFILE不创建注册表表目或修改注册表访问计数器。你使用SHAREDFILE选项时不能使用LOCKEDFILE选项。有一些非共享文件,对它们脚本作者不要注册表表目和访问计数器。这些文件除非由应用程序本身,否则永不被卸载。LOCKEDFILE允许XCopyFile处理非共享的锁定文件。

EXCLUDE_SUBDIR:指定不包括在源路径中包含的子目录。

INCLUDE_SUBDIR:指定源路径下的子目录必须也被拷贝。

返回值:

0:表明函数成功拷贝文件。

< 0:表明函数因下列情况之一未能拷贝文件:

COPY_ERR_CREATEDIR (-27):目标目录不能被创建。确保系统变量TARGETDIR中的路径语法正确并且你有权访问目标驱动器。

COPY_ERR_MEMORY (-6):函数未能分配完成拷贝文件进程所需的内存。尽可能多地终止正在运行的应用程序以释放内存。

COPY_ERR_NODISKSPACE (-38):函数未能在目标驱动器上找到足够的磁盘空间来拷贝文件。在目标驱动器上释放磁盘空间。

COPY_ERR_OPENINPUT (-2):函数未能打开系统变量SRCDIR指定的输入文件。确保源文件有一个有效的文件名并且源文件和目标目录都存在。

COPY_ERR_OPENOUTPUT (-3):函数未能拷贝所要文件。

COPY_ERR_TARGETREADONLY (-46):TARGETDIR中的文件是只读文件。删除目标文件的只读属性并重试。

-51:一个自注册文件没有成功注册。

所有其它负值:表明发生一些其它未确定错误。

注解:

·当使用XcopyFile时,若你使用未限定文件名并为SRCDIR 和TARGETDIR设置值时,在调用XcopyFile前调用VarSave保存当前值,然后用VarRestore恢复它们。

·因为Windows 95及更高版本不允许一个空文件被拷贝,Windows NT不允许创建空文件,XCopyFile在这些平台下当被用来拷贝空文件(Size=0KB)时将不工作。

·在用WriteProfString修改.ini文件后, Windows 95及更高版本下,你必须在使用XCopyFile前刷新高速缓存。所有.ini文件在Windows 95及更高版本下被放在高速缓存中;这种特性可能导致延迟将修改写到指定文件。这接着可能妨碍随后的文件操作。为避免这个问题,简单地以空参数调用WriteProfString来强制Windows 95 及其后版本立即写数据到.ini文件,如下所示:

         WriteProfString ("C:\\Test.ini", "Windows", "KeyboardDelay", "100");

         WriteProfString ("","","","");  //null string ("") for all four parameters

         //XCopyFile should now have access to updated file.

         XCopyFile ("C:\\Test.ini", "C:\\Temp", EXCLUDE_SUBDIR);

10  长文件名函数

    下列函数从短文件名创建长文件名,将短文件名转换到长文件名,并且将长文件名用双引号括起使得处理长文件名的操作系统可以识别它们。

s LongPathFromShortPath

从一个短文件名创建一个长文件名。

s LongPathToQuote

插入或删除环绕一个长文件名的双引号。

s LongPathToShortPath

从一个长文件名创建一个短文件名。

10.1  LongPathFromShortPath

语法:LongPathFromShortPath (svPath);

说明:使用LongPathFromShortPath函数转换一个短文件名到它的等价长文件名。

参数:

svPath

指定一个短文件名并且返回它的相关的长文件名。

返回值:

0:表明函数成功。

< 0:表明函数没有成功。

注解:

对于长文件名的解释,请看下面:

s Windows 95和其后版本和Windows NT 4.0支持长文件名。长文件名允许用户给目录和文件更多有意义的名称。“长文件名”项指向长文件名和长路径。

s InstallShield提供长文件名函数来给不识别长文件名的16位应用程序和32位应用程序的安装提供便利。你有责任确定你的应用程序的要求。 InstallShield提供工具帮助你安装任何类型的应用程序。

10.2  LongPathToQuote

语法:LongPathToQuote (svPath, nParameter);

说明:LongPathToQuote函数放置双引号环绕一个长文件名或从一个长文件名删除双引号。

    在传递长文件名给命令行之前添加双引号到包含空格的长文件名。在用函数LongPathToShortPath将长文件名转换为短文件名前,你必须从长文件名中删除双引号。如果你不这么做,被括起的长文件名保持无效。

    该函数仅当文件名中有一个空字符时将添加引号。例如,引号将不会被加到C:\\ThisismyApp,因为它是一个没有空格的长文件名。

参数:

svPath

指定一个长文件名并返回包含或不包含引号的该名称,依赖于传递给参数nParameter的值。

nParameter

指定引号是否要被添加到长路径或从长路径删除。在该参数位置传递下列预定义常量之一:

TRUE:添加引号到长路径。

FALSE:从长路径删除引号。

返回值:

0:表明函数成功。

< 0:表明函数没有成功。

注解:

请参阅LongPathFromShortPath的注解。

10.3  LongPathToShortPath

语法:LongPathToShortPath (svPath);

说明:LongPathToShortPath函数将一个长文件名转换到它等价的短文件名。短文件名和16位程序兼容,如Notepad.exe 或Mviewer2.exe。16位程序不接受长文件名。参数svPath可以是一个绝对路径或一个相对路径,并且它可以包括一个文件名;但它指定的文件夹或文件必须存在于目标系统。

参数:

svPath

指定一个长文件名并返回它相联系的短文件名。

LongPathToShortPath从长文件名中删除尾随反斜杠。

返回值:

0:表明函数成功。

< 0:表明函数没有成功。

注解:

·请参阅LongPathFromShortPath。

·因为仅当指定的文件夹或文件可以在目标系统上找到时LongPathToShortPath才能成功,你通常必须在指定一个相对路径前设置当前文件夹。例如,如果svPath包含相对路径"InstallShield\InstallShield5 Professional Edition",它存在于文件夹"C:\Program Files",安装将不能找到它除非当前文件夹是"C:\Program Files"。在调用LongPathToShortPath前如有必要使用ChangeDirectory函数来修改当前文件夹,因而目标文件夹或路径能被找到。

·使用ChangeDirectory来指定一个新目录。

11  INI文件函数

    INI文件函数从初始化和配置文件中获得信息或拷贝信息到这些文件。一个初始化文件是一个特殊的包含关键字名-值对的ASCII文件。关键字名-值对代表运行时对应用程序的选项。你也可以访问和修改专用的初始化文件和系统初始化文件。下面的列表简要描述了每个INI文件函数。

    由AddProfString, ReplaceProfString, 或 WriteProfString对.ini文件所做的修改可以存入卸载记录中。然而,必须知道一些重要的限制。更多信息,可查看卸载.ini文件的条目。

s AddProfString

在.ini文件的一段中添加一个非唯一键。

s GetProfInt

从一个.ini文件中返回一个整数。

s GetProfString

从一个.ini文件中返回一个字符串。

s GetProfStringList

从一个.ini文件中返回键名和字符串值的列表。

s ReplaceProfString

置换一个配置文件(.ini文件)中一个字符串。

s WriteProfInt

将一个有整数的字符串写到一个.ini文件中。

s WriteProfString

将一个字符串写到一个.ini文件中。

相关函数

s SdShowFileMods

创建一个对话框,提议修改文件和提供如何进行的选项。

11.1  AddProfString

语法:AddProfString (szFileName, szSectionName, szKeyName, szValue);

说明:AddProfString函数无条件地添加一个配置字符串到一个.ini文件。使用AddProfString仅添加非唯一键,如那些在System.ini文件的[386Enh]段找到的(device = ...)。AddProfString添加KEY=VALUE行到指定的.ini文件的段的结尾。它不置换或更新一个现存键。为更新一个现存的非唯一键,调用ReplaceProfString。为在一个.ini文件中添加一个唯一键或更新一个唯一键的值,调用WriteProfString。

  对.ini文件所做的修改可以存入到卸载记录中。然而,必须知道一些重要的限制。更多信息,可查看卸载.ini文件的条目。

参数:

szFileName

指定要添加配置字符串的.ini文件的名称。如果szFileName是未限定名(也就是,不包括一个驱动器指示符和路径),InstallShield在Windows文件夹中查找该文件。如果文件不存在,它被在指定文件夹中创建,如果文件名中不包括路径,该文件被创建在Windows文件夹中。注意如果文件名限定在一个不存在的路径中,AddProfString将失败。

szSectionName

指定.ini文件中的一个段名。配置字符串被插入在该段的结尾。如果该段不存在,InstallShield创建它。段名必须不被包围在定界中括号中([ ])。注意即使该段中由szKeyName指定的键已经存在,配置字符串仍被插入。

szKeyName

指定要插入的键名。该参数的值将显示在配置字符串中等号左边。

szValue

指定赋给该键的值。该参数的值将显示在配置字符串中等号右边。

返回值:

0:AddProfString成功添加指定的配置字符串到.ini文件。

< 0:AddProfString未能添加指定的配置字符串到.ini文件。

注解:

s AddProfString不使用Windows API来修改.ini文件。Windows API 不能处理用AddProfString可能实现的修改类型。

11.2  GetProfInt

语法:GetProfInt (szFileName, szSectionName, szKeyName, nvValue);

说明:GetProfInt函数从一个.ini文件中检索一个整数。参数nDefault指定为0时,GetProfInt和Windows API GetPrivateProfileInt一样工作。

参数:

szFileName

指定一个.ini文件名,从中得到一个键的当前整型值。如果szFileName是未限定名(也就是,不包括一个驱动器指示符和路径),InstallShield在Windows文件夹中查找该文件。

szSectionName

指定.ini文件中的一个段名,从中查找szKeyName。段名必须不被包围在定界中括号中([ ])。

查找该名称时不区分大小写。

szKeyName

指定一个键,其整型值被返回到nvValue。查找该键不区分大小写。

nvValue

返回一个当前赋给szKeyName的整型值。由于GetPrivateProfileInt函数的限制,该函数只可以从该配置文件中返回一个16位的值。

因此,可以被返回的最大值是65,535;更大的值可能不会被正确返回。如果你需要返回一个更大的值,使用通常的文件处理函数,如FileGrep 和 FileInsertLine,然后通过调用StrToNum把返回的字符串转换成一个整型值。

返回值:

GetProfInt总返回0

注解:

·如用Windows API 函数GetPrivateProfileInt一样,如果因不能找到文件,段或键名而发生的错误不会被返回;而是nvValue包含0。因此,不可能辨别一个错误和一个0的返回值。为辨别0和一个错误,直接调用GetPrivateProfileInt并指定一个候选的缺省值。

·在Windows NT(不是Windows 95及更高版本)下,一些对GetPrivateProfileInt函数(因此也是GetProfInt函数)的调用被自动映象到Windows注册表而不是配置文件。

11.3  GetProfString

语法:GetProfString (szFileName, szSectionName, szKeyName, svResult);

说明:GetProfString函数从一个指定的.ini文件中检索一个配置字符串。GetProfString和Windows API GetPrivateProfileString一样工作。

参数:

szFileName

指定一个.ini文件名,从中得到一个键的当前值。如果szFileName是未限定名(也就是,不包括一个驱动器指示符和路径),InstallShield在Windows文件夹中查找该文件。

szSectionName

指定.ini文件中的一个段名,从中查找szKeyName。段名必须不被包围在定界中括号中([ ])。

查找该段名时不区分大小写。为得到一个INI文件中的所有段名列表,给该参数传递一个空字符串。更多信息请看下面的注解。

szKeyName

指定一个键,它的值被返回到svResult。查找该键时不区分大小写。为得到一个段中所有键名的列表,给该参数传递一个空字符串。更多信息请看下面的注解。

svResult

如果szSectionName指定一个段名,szKeyName指定一个键名,该键的值被返回到该参数。如果szSectionName指定一个空字符串,所有段名返回到svResult。如果szKeyName指定一个空字符串,该段中的所有键名返回找svResult。

返回值:

0:GetProfString成功返回配置字符串的值。

< 0:GetProfString未能返回配置字符串的值。

-2:该键的值的长度超过2048个字符(可以由GetProfString返回到svResult的最大字符数)。

注解:

·为得到一个INI文件中所有段名的列表,该参数szSectionName传递一个空字符串。由空字符定界的段名返回到参数svResult。SvResult必须足够长来接受所有的段名。使用StrGetTokens函数来从该字符串中析取单个段名。

·为得到由szSectionName指定的段中的所有键名的列表,给参数szKeyName传递一个空字符串。由空字符定界的键名返回到参数svResult。SvResult必须足够长来接受所有的键名。使用StrGetTokens函数来从该字符串中析取单个键名。

·GetProfString使用你的操作环境的API提供的函数来访问.ini文件。因此,InstallShield的函数功能性可能受操作环境的限制。

11.4  GetProfStringList

语法:GetProfStringList (szFileName, szSectionName, listKeyNames, listValues);

说明:GetProfStringList函数从指定的INI文件中的指定段中检索键名和字符串值列表。

参数:

szFileName

指定一个.ini文件名,从中得到键名和字符串值。如果szFileName是未限定名(也就是,不包括一个驱动器指示符和路径),InstallShield在Windows文件夹中查找该文件。

szSectionName

指定.ini文件中的一个段名,从中查找键名和字符串值。段名必须不被包围在定界中括号中([ ])。查找该段名时不区分大小写。

listKeyNames

返回一个键名列表。由listKeyNames标识的字符串列表必须已经通过调用ListCreate而被初始化。

listValues

返回一个字符串值的列表。由listValues标识的字符串列表必须已经通过调用ListCreate而被初始化。

返回值:

0:表明函数成功读段并将键名和字符串值插入到指定列表中。

-2:表明一个或所有列表的ID是无效的。其它负值表明函数未能读段或未能将键名和字符串值插入到指定列表中。

11.5  ReplaceProfString

语法:ReplaceProfString (szFileName, szSectionName, szKeyName, szOrigValue, 

  szReplaceValue);

说明:ReplaceProfString函数置换.ini文件中的一个配置字符串。该函数可以置换重复键(非唯一键)的值,如在System.ini文件中[386Enh]段中找到的那些(device = ...)。该函数查找一个szKeyName = szOrigValue,,并置换该行。如果它没有找到,它就在szSectionName段开始添加zKeyName = szReplaceValue行。

  如果你添加唯一键(就是,对一个给定的段,所有键都不同),使用WriteProfString函数。使用该函数只置换非唯一键名,如System.ini文件中的device=行。

  对.ini文件所做的修改可以存入卸载记录中。然而,必须知道一些重要的限制。更多信息,可查看卸载.ini文件的条目。

参数:

szFileName

指定要置换配置字符串的.ini文件的名称。如果szFileName是未限定名(也就是,不包括一个驱动器指示符和路径),InstallShield在Windows文件夹中查找该文件。如果文件不存在,它被在指定文件夹中创建,如果文件名中不包括路径,该文件被创建在Windows文件夹中。注意如果文件名限定在一个不存在的路径中,ReplaceProfString将失败。

szSectionName

指定.ini文件中的一个段名,从中查找szKeyName。段名必须不被包围在定界中括号中([ ])。查找该段名时不区分大小写。

szKeyName

指定要被置换的键名。如果该键不存在,则被创建。

szOrigValue

标识由szKeyName指定的键的当前值。

szReplaceValue

指定赋给szKeyName的新值。该参数的值将显示在配置字符串(szKeyName = szValue)等号右边。

返回值:

0:表明函数成功置换或添加配置字符串。

< 0:表明函数未能置换或添加配置字符串。

注解:

·Windows .ini是文本文件。你必须在每个操作系统中使用InstallShield的合适版本。

11.6  WriteProfInt

语法:WriteProfInt (szFileName, szSectionName, szKeyName, iValue);

说明:WriteProfInt函数通过插入或更新一个配置字符串(整型值赋给键),来修改一个.ini文件。注意下列要点:

s 因为Windows 高速缓存保存文件的方法改变,你必须在调用WriteProfString后刷新高速缓存。(看下面的注解部分。)

s 对.ini文件所做的修改可以存入到卸载记录中。然而,必须知道一些重要的限制。更多信息,可查看卸载.ini文件的条目。

s 为写一个字符串值到一个.ini文件,则调用WriteProfString。

s 当你想修改System.ini文件时使用AddProfString 和 ReplaceProfString函数。

参数:

szFileName

指定要置换配置字符串的.ini文件的名称。如果szFileName是未限定名(也就是,不包括一个驱动器指示符和路径),InstallShield在Windows文件夹中查找该文件。如果文件不存在,它被在指定文件夹中创建,如果文件名中不包括路径,该文件被创建在Windows文件夹中。注意如果文件名限定在一个不存在的路径中,Write ProfInt将失败。

szSectionName

指定.ini文件中的一个段名,szKeyName将要被插入其中或将要被修改。段名必须不被包围在定界中括号中([ ])。查找该段名时不区分大小写。

szKeyName

指定要更新的唯一键。如果要被更新的键不存在于指定段中,则它被创建。

为从一个.ini文件中删除一整个段,给参数szKeyName传递一个空字符串。为从一个.ini文件的一个段中删除一个或多个键,使用WriteProfString。

iValue

指定赋给由szKeyName标识的唯一键的整型值。

返回值:

0:表明函数成功更新指定的.ini文件。

< 0:表明函数未能更新指定的.ini文件。

注解:

·WriteProfInt函数使用Windows API WritePrivateProfileString来访问.ini文件。因此,它的函数功能性受Windows API提供的函数功能的限制。.ini文件的更多信息可查询Microsoft Windows手册。

·.ini文件在Windows 95及更高版本下被放在高速缓存中,这种特性可能导致延迟将修改写到指定文件。这接着可能妨碍随后的文件操作,如调用CopyFile 和 XCopyFile。因此如果你随后要用到文件操作,则你必须在使用 WriteProfInt后,刷新高速缓存。简单地以空参数调用WriteProfInt来强制Windows 95 及更高版本立即写数据到.ini文件,如下所示:

   WriteProfInt ("c:\\test.ini", "Windows", "KeyboardDelay", 100);

   WriteProfInt ("","","",0); //null string ("") in first three parameters

   //CopyFile should now have access to updated file.

   CopyFile ("c:\\test.ini", "d:\\test.ini");

11.7  WriteProfString

语法:WriteProfString (szFileName, szSectionName, szKeyName, szValue);

说明:WriteProfString函数写一个配置字符串到一个.ini文件。根据传递给WriteProfString的值,它可以创建一个段,删除一整个段,创建一个唯一的KEY=VALUE条目,删除一个KEY=VALUE条目,或更新一个键的值。

注意要点同WriteProfInt中的注意要点。

参数:

szFileName

指定.ini文件的名称。如果szFileName是未限定名(也就是,不包括一个驱动器指示符和路径),InstallShield在Windows文件夹中查找该文件。如果文件不存在,它被在指定文件夹中创建,如果文件名中不包括路径,该文件被创建在Windows文件夹中。注意如果文件名限定在一个不存在的路径中,Write ProfString将失败。

szSectionName

指定.ini文件中的一个段名,szKeyName将要被插入其中或将要被修改。段名必须不被包围在定界中括号中([ ])。查找该段名时不区分大小写。

szKeyName

指定要更新或删除的唯一键。如果要被更新的键不存在于指定段中,则它被创建。为删除该键,给参数szValue传递一个空字符串。为删除由szSectionName指定的整个段(包括它里面的所有条目),给参数szKeyName传递一个空字符串。

szValue

指定赋给由szKeyNamw标识的唯一键的值。为删除该键,给该参数传递一个空字符串。为删除该键的值而保留键本身,则给该键传递一个空格。

返回值:

0:表明函数成功写字符串到指定的.ini文件。

< 0:表明函数未能写字符串到指定的.ini文件。

注解:

请参阅WriteProfInt的注解。

12  共享和锁定文件函数

  一个共享文件是一个可以被多个应用程序使用的文件,如.dll,.vbx或驱动程序。InstallShield保护共享文件在卸载过程中不被删除。

  使用SHAREDFILE选项的函数把所有的文件都视为共享文件,因而为所有包含的文件递增注册表引用计数器。如果文件存在于目标目录并且它的注册表引用计数器大于0,则InstallShield将其注册表引用计数器增一。如果共享文件不存在于目标目录并且它没有引用计数器,InstallShield创建该计数器并设置它为1。如果共享文件已经存在于目标目录当没有引用计数器,InstallShield创建该计数器并初始化它为2,作为防止在卸载过程中意外删除的预防措施。

  共享文件当它们被锁定时不能被更新。一些InstallShield文件传输函数使用SHAREDFILE选项,因而在文件传输过程中被锁定的.dll和.exe文件可以被记录并在Windows 或系统重启时被更新。

  InstallShield将一个正被一个应用程序或系统使用的文件视为锁定。锁定文件不必要是共享文件。

下列函数处理共享和锁定文件:

s Is

请参阅3.9。

s RebootDialog

请参阅4.9。

s SdFinishReboot

请参阅5.17。

s VerUpdateFile

请参阅21.5。

s XCopyFile

请参阅9.28。

13  字符串函数

  字符串函数提供处理字符串变量和文字的功能。字符串函数与标准C语言函数相似。返回值也遵守C语言的规定。

s CopyBytes

从一个字符串中拷贝指定字节数到另一个。

s GetDir

从一个路径名或全限定文件名中删除驱动器标识。

s GetDisk

从一个路径名或全限定文件名中检索磁盘驱动器标识。

s NumToStr

将一个数字转换为一个字符串。

s ParsePath

从一个路径中检索驱动器,路径,文件名或扩展名。

s StrCompare

将一个字符串和另一个比较。

s StrFind

在另一个字符串中查找一个字符串。

s StrGetTokens

基于指定定界符从一个字符串中得到一个令牌。

s StrLength

返回一个字符串中的字节数。

s StrLengthChars

返回一个字符串中的字符数。

s StrRemoveLastSlash

删除一个路径字符串中的最后的反斜杠。

s StrSub

从一个字符串中返回一个子串。

s StrToLower

转换字符串中的所有字母字符为小写。

s StrToNum

转换字符串为一个数字。

s StrToUpper

转换字符串中的所有字母字符为大写。

13.1  CopyBytes

语法:CopyBytes (svDest, nIndexDest, svSrc, nIndexSrc, nCount);

说明:CopyBytes函数从一个字符串中拷贝指定的字节数到另一个字符串。你可以在源和目标字符串中指定偏移下标。

参数:

svDest

指定目标字符串。

nIndexDest

指定在目标字符串中的偏移下标(开始点),从这个位置开始插入这些字节。字符串的第一个字节是在位置0

svSrc

指定源字符串。不要传递一个大小大于256个字符的自动调整大小的字符串。而应该用一个显式大小声明字符串。nIndexSrc

指定源字符串的偏移下标(开始点),从这个位置开始拷贝这些字节。字符串的第一个字节是在位置0

nCount

指定你要从svSrc拷贝到svDest的总的字节数。该值必须不大于svSrc-1的大小。例如,如果svSrc被声明为大小为512(给它最大字符串长度511),则传递给nCount的值必须是511或更少。

返回值:

0:CopyBytes成功地从一个字符串拷贝指定数目的字节到另一个字符串。

< 0:CopyBytes没有能拷贝这些字节。

注解:

当你工作在二进制文件时,CopyBytes有用。

13.2  GetDir

语法:GetDir (szPath, svDir);

说明:GetDir函数从由szPath指定的全限定路径或文件名中删除驱动器指示符,并在参数svDir返回路径或文件名的余项。路径名必须包含一个驱动器指示符。它可以是一个UNC(通用导航计算机)路径。

在下面的例子中,全限定路径C:\Windows在svDir返回为\Windows。

   GetDir("C:\\Windows", svDir);

在下一个例子中,UNC路径\\TheServer\TheSharedDevice\Programs在svDir返回为\Programs。

   GetDir("\\\\TheServer\\TheSharedDevice\\Programs", svDir);

参数:

szPath

指定包含一个驱动器指示符的路径。

svDir

返回没有驱动器指示符的路径。如果szPath是一个UNC路径,GetDir将返回没有服务器名和共享设备名的路径。

返回值:

0:表明函数成功返回没有驱动器指示符的路径名。

<0:表明函数未能返回没有驱动器指示符的路径名。

13.3  GetDisk

语法:GetDisk (szPath, svDisk);

说明:GetDisk函数从由szPath指定的全限定路径或文件名中析取磁盘驱动器指示符。

参数:

szPath

指定一个包含一个驱动器指示符的全限定路径或文件名。如果不包含一个驱动器指示符,GetDisk将失败。传递给szPath的值可以是一个UNC路径。

svDisk

返回驱动器指示符(包含冒号)。如果szPath是一个UNC路径,GetDisk以”\\服务器\共享设备”格式返回服务器名和共享设备名。

返回值:

0:表明函数成功返回驱动器指示符。

< 0:表明函数未能返回驱动器指示符。

13.4  NumToStr

语法:NumToStr (svString, nValue);

说明:NumToStr函数将一个数字转换为一个字符串。

参数:

svString

返回nValue的字符串等价值(等效字符串)。

nValue

指定要转换为一个字符串的数字。

返回值:

0:表明函数成功将数字转换为一个字符串。

< 0:表明函数未能将数字转换为一个字符串。

13.5  ParsePath

语法:ParsePath (svReturnString, szPath, nOperation);

说明:ParsePath函数检索一个存在路径的指定部分。函数可工作于任何有效路径,包括短路径,长路径和UNC路径,它们可能包含或不包含一个具体文件名。下面是可以用该函数分析的一些路径样本:

\Path1\Path2\Filename.exe 

Filename 

Filename.exe 

\Path1\Path2\Filename 

D: 

D:\ 

\\Server Name\Share Name\Share Directory 

其它任何合法DOS路径。

参数:

svReturnString

返回参数szPath中的路径由参数nOperation所指定的部分。

szPath

指定要分析的路径。当指定一个不包含一个文件名的路径时,你必须在把它传递给ParsePath之前在路径结尾添加一个反斜杠;否则路径的最后部分会被解释为一个文件名。

nOperation

指定返回路径的哪个元素。在该参数位置传递下列预定义常量之一:

DIRECTORY:表明必须在svReturnString返回路径中去除磁盘驱动器字符和文件名。当该选项使用在一个UNC路径时,ParsePath返回没有服务器和共享设备名的路径,并且没有文件名(可能被指定)。例如,UNC路径\\TheServer\TheSharedDevice\TheApp\TheFile.exe在svReturnString返回\TheApp\。

DISK:表明必须在svReturnString返回磁盘驱动器指示符(驱动器字符后随一个冒号)。当该选项使用在一个UNC路径时,ParsePath返回服务器名和共享设备名。例如,UNC路径\\TheServer\TheSharedDevice\TheApp\TheFile.exe在svReturnString返回\\TheServer\TheSharedDevice。

EXTENSION_ONLY:表明必须在svReturnString返回文件扩展名。它不包括句点。

FILENAME:表明必须在svReturnString返回完整的文件名(也就是说,包括它的文件扩展名)。

FILENAME_ONLY:表明必须在svReturnString仅返回文件名(也就是说,不包括它的文件扩展名)。

PATH:表明必须在svReturnString返回路径中去除文件名。该选项和DIRECTORY不同,因为驱动器指示符(如果在szPath中被指定)包括在返回路径中。当szPath指定一个UNC路径时,服务器名和共享设备名被包括在返回路径中。例如,UNC路径\\TheServer\TheSharedDevice\TheApp\TheFile.exe在svReturnString返回\\TheServer\TheSharedDevice\TheApp\

返回值:

0:表明函数成功分析路径字符串。

< 0:表明函数未能分析路径字符串。

13.6  StrCompare

语法:StrCompare (szStringA, szStringB);

说明:StrCompare函数比较两个字符串。比较不区分大小写。

参数:

szStringA

指定要比较的第一个字符串。

szStringB

指定要比较的第二个字符串。

返回值:

< 0:表明szStringA的字符串的值小于szStringB的字符串的值。

= 0:表明两个字符串相等。

> 0:表明szStringA的字符串的值大于szStringB的字符串的值。

注解:

·StrCompare函数比较两个字符串,通过检验每个字符串中的第一个字符,然后每个字符串中的第二个字符,以次类推,直到它找到一个不相等的字符或到达了字符串结尾。

·你选择的语言的语言驱动程序确定哪个字符串大或字符串相等。如果你不使用一个语言驱动程序,Windows使用一个内部函数。对于一个双字节字符集(DBCS)版本的Windows,该函数可以比较两个DBCS字符串。

13.7  StrFind

语法:StrFind (szString, szFindMe);

说明:StrFind函数确定传递给参数szFindMe的字符串能否在传递给参数szString的字符串中找到。如果szFindMe 在szString 中找到,StrFind返回szFindMe的第一个字符在 szString 中的位置。注意 szString 中第一个字符的位置是0。该函数不区分大小写并且只可以用来找到szFindMe 在szString中首次出现。

下面的例子中,StrFind将返回值13

   nStartPos = StrFind("Scripting is fun","fun"); 

如果只需要一个TRUEFALSE的返回值来指示一个字符串是否包含另一个字符串,(也就是,如果子串的位置是不重要的),使用字符串查找操作符(%),如下所示:

   if (szString % szFindMe) then ...

在if语句中可以被解析的布尔表达式中,你可以只使用字符串查找操作符。你不能在repeat语句或while语句中使用它。

参数:

szString

指定要查找的字符串。

szFindMe

指定要在szString中查找的字符串。

返回值:

X:如果szString包含szFindMe,XszFindMe中第一个字符的数值位置。SzString中第一个字符是在位置0

< 0:表明szString不包含szFineMe。

13.8  StrGetTokens

语法:StrGetTokens (listID, szString, szDelimiterSet);

说明:StrGetTokens函数从szString指定的字符串中析取子串(称为令牌)并且把它们放置到listID指定的列表中。SzString中的子串必须被由szDelimiterSet指定的一个或多个字符分隔(相互分隔)。

    例如,如果你调用StrGetTokens,字符串"One;Two;Three;Four;Five"作为第二个参数,";"为第三个参数,"One", "Two", "Three", "Four", 和 "Five"这五个字符串将被返回到listID。使用列表函数,如ListGetFirstString和 ListGetNextString来访问列表中的每个令牌。

    如果szString中的第一个字符与szDelimiterSet中的一个字符匹配,一个空字符串将被插入为列表的第一个元素。同样,如果szString中的最后一个字符与szDelimiterSet中的一个字符匹配,一个空字符串将被插入为列表的最后一个元素。

参数:

listID

返回令牌列表。由listID标识的字符串列表必须已经通过对ListCreate的调用而初始化。

szString

指定要被分析的字符串。

szDelimiterSet

指定一个或多个分隔符的集合。每个分隔符是一个字符(1字节)。如果你在该参数传递一个空字符串,该函数以空字符为分隔符来查找。当你使用GetProfString函数时有用。

当一个空格被指定为分隔符,StrGetTokens将连续的空格处理作一个单独的分隔符。

返回值:

0:表明函数成功分隔字符串并把令牌(token)插入到指定列表中。

< 0:表明函数未能分隔字符串并把令牌插入到指定列表中。

13.9  StrLength

语法:StrLength (szString);

说明:使用StrLength函数得到一个字符串中的字节数。为确定一个字符串中的字符数,使用StrLengthChars。

参数:

szString

指定要确定其大小的字符串。

返回值:

X:X是字符串中的字节数。

< 0:表明函数未能确定字符串中的字节数。

13.10  StrLengthChars

语法:StrLengthChars (szString);

说明:使用StrLengthChars函数得到一个字符串中的字符数。为确定一个字符串中的字节数,使用StrLength。

参数:

szString

指定要确定其大小的字符串。

返回值:

X:X是字符串中的字符数。

< 0:表明函数未能确定字符串中的字符数。

13.11  StrRemoveLastSlash

语法:StrRemoveLastSlash (svPath);

说明:StrRemoveLastSlash函数从一个路径说明中删除结尾反斜杠。

参数:

svPath

指定一个字符串,其值必须是一个路径说明;返回没有结尾反斜杠的路径。注意如果路径不包含一个反斜杠,它不作修改就被返回。

返回值:

0:表明函数成功删除结尾反斜杠或路径不包含一个结尾反斜杠。

< 0:表明函数未能删除结尾反斜杠。

注解:

·StrRemoveLastSlash给将AskPath 或ParsePath返回的路径剪裁掉结尾反斜杠提供了一个便利的途径。因为它的目的是产生一个有效路径名,StrRemoveLastSlash不从一个根目录说明中删除反斜杠,如"A:\"或 "C:\";这样做可将一个有效路径名转换到一个驱动器说明(标识)。你是否需要在任何情况下剪裁掉一个路径的结尾反斜杠,可参考下面的脚本片段。

    AskPath("", "", svPath);

    if (StrLength(svPath) = 3) 

       && (svPath[1] = ":")

       && (svPath[2] = "\\") then

       svTempString = svPath;

       StrSub(svPath,svTempString,0,2);

    else

       StrRemoveLastSlash(svPath);

    endif;

13.12  StrSub

语法:StrSub (svSubStr, szString, nStart, nLength);

说明: StrSub函数拷贝szString指定的字符串的部分,从nStart指定的位置开始。参数nLength指定要拷贝的字符数。

参数:

svSubStr

返回从szString拷贝的子串。

szString

指定要从中拷贝子串的字符串。

nStart

指定一个szString中的偏移量来标识要被拷贝的第一个字符。注意szString中的第一个字符的位置是0。如果传递给nStart的值等于或大于szString的长度,在svSubStr返回一个空字符串。

nLength

指定从szString拷贝的字符数。如果该值指定了多于nStart和szString结尾之间的字符数,在svSubStr返回从nStart到字符串结尾的所有字符。

返回值:

X:X等于svSubStr的字符数。

13.13  StrToLower

语法:StrToLower (svTarget, szSource);

说明:StrToLower函数将一个字符串中的所有字母转换为小写。该函数不影响非字母字符。

参数:

svTarget

返回szSource中的字符串,其所有字符均已转换为小写。

szSource

指定均要转换为小写字符的字符串。

返回值:

0:表明函数成功修改了字符串的大小写。

< 0:表明函数未能修改了字符串的大小写。

13.14  StrToNum

语法:StrToNum (nvVar, szString);

说明:StrToNum函数将一个字符串转换为一个数字,与C函数atol()相似。它检查svString,从位置0的字符开始,在字符串中继续直到它到达字符串结尾或遇到一个不在"0".."9"范围内的一个字符。(字符串中的第一个字符可能是一个加号或减号。)将出现下列处理过程:

s 如果字符串中的所有字符在"0".."9"范围中,由字符串代表的数字赋给nvVar。

s 如果字符串以一个或多个"0".."9"范围内的字符开始但也包含一个或多个非数字字符,则将出现的第一个非数字字符的左边的所有字符赋给nvVar。例如,如果szString是 "-123ABC456", nvResult将是 –123。

s 如果字符串的第一个字符不在"0".."9"范围内并且不是一个加号或减号,该函数失败。

s 如果字符串的第一个字符是一个加号或减号,并且第二个字符不在"0".."9"范围内,该函数失败。

参数:

nvVar

返回从szString的字符串生成的数字。

szString

指定要转换为一个数字的字符串。

返回值:

0:表明函数成功将字符串转换为数值型值。

< 0:表明函数未能将字符串转换为数值型值。

13.15  StrToUpper

语法:StrToUpper (svTarget, szSource);

说明:StrToUpper函数将一个字符串中的所有字母转换为大写。该函数不影响非字母字符。

参数:

svTarget

返回szSource中的字符串,其所有字符均已转换为大写。

szSource

指定均要转换为大写字符的字符串。

返回值:

0:表明函数成功修改了字符串的大小写。

< 0:表明函数未能修改了字符串的大小写。

14  路径缓冲函数

    路径缓冲函数有助于你处理包含查找路径的字符串。路径缓冲函数工作在一个唯一的作为路径缓冲的临时字符串变量。该路径缓冲在InstallShield内部被定义;所有路径字符串函数对路径缓冲中的内容起作用。 

   这些函数不支持长文件名。在将长文件名传递到一个路径缓冲函数前调用LongPathToShortPath将它转换到等价的短文件名。

    路径函数帮助你操作和创建路径字符串。你一旦创建一个路径字符串,你可以把它保存到合适的文件中。

s PathAdd

将一个路径添加到路径缓冲中的查找路径。

s PathDelete

从路径缓冲中删除一个目录。

s PathFind

在路径缓冲中找到一个特定路径或任何包含一个特定名称的路径。

s PathGet

检索路径缓冲的当前值。

s PathMove

重新整理路径缓冲。

s PathSet

分配一个值给路径缓冲。

14.1  PathAdd

语法:PathAdd (szDir, szRefDir, bRefDir, bPosition);

说明:PathAdd函数添加一个路径到路径缓冲中的查找路径。使用该函数你可以指定和路径缓冲中的一个现存目录相关联的目录位置。另外,你可以添加该路径作为路径缓冲中的第一个或最后一个目录。

  该函数和Autoexec.bat文件中的路径语句或路径环境变量无关。它仅作用在路径缓冲,帮助你创建,修改和操作查找路径。然后你可以通过使用不同的批处理文件函数将修改的路径缓冲字符串添加到Autoexec.bat文件。该函数不支持长文件名。在将长文件名传递到一个路径缓冲函数前调用LongPathToShortPath将它转换到等价的短文件名。

参数:

szDir

指定要添加到路径缓冲中的路径。

szRefDir

指定当前路径缓冲中与将要被添加的新路径相关的路径。

bRefDir

指定szRefDir是否是一个全限定路径。在该参数位置传递下列预定义常量之一:

FULL:SzRefDir是一个全限定路径(也就是,包括一个驱动器指示符和到一个目录的完整路径)。

PARTIAL:SzRefDir仅是目录名(没有驱动器和路径信息)。

bPosition

指定szDir要被插入到的相对于szRefDir的位置。在该参数位置传递下列预定义常量之一:

AFTER:指定szDir被插入到szRefDir 之后。如果szRefDir指定一个空字符串,szDir被插入到路径缓冲中的路径结尾。

BEFORE:指定szDir被插入到szRefDir 之前。如果szRefDir指定一个空字符串,szDir被插入到路径缓冲中的路径前面。

返回值:

0:表明函数成功添加一个目录到路径缓冲。

< 0:表明函数未能添加一个目录到路径缓冲。

注解:

·如果你在szDir指定了一个当前已经存在于路径缓冲中的目录,InstallShield将复制它,并且前面存在的目录位置不被修改。 InstallShield忽略在目录名结尾的反斜杠。

14.2  PathDelete

语法:PathDelete (szDir, bDir);

说明:PathDelete函数删除路径缓冲中的一个特定路径。你可以指定路径名或输入一个全限定路径。

  该函数和Autoexec.bat文件中的路径语句或路径环境变量无关。它仅作用在路径缓冲,帮助你创建,修改和操作查找路径。调用PathGet得到路径缓冲中的内容,调用PathSet设置路径缓冲中的内容。该函数不支持长文件名。在将长文件名传递到PathDelete前调用LongPathToShortPath将它转换到等价的短文件名。

参数:

szDir

指定要从路径缓冲中删除的路径。

bDir

指定szRefDir是否是一个全限定路径。在该参数位置传递下列预定义常量之一:

FULL:SzRefDir是一个全限定路径(也就是,包括一个驱动器指示符和到一个目录的完整路径)。

PARTIAL:SzRefDir仅是目录名(没有驱动器和路径信息)。

返回值:

0:表明函数成功从路径缓冲中删除一个目录。

< 0:表明函数未能从路径缓冲中删除一个目录。

14.3  PathFind

语法:PathFind (szDir, svResult, bDir, bSearch);

说明:PathFind函数从路径缓冲中查找一个特定目录。你可以以一个全限定名或仅目录名来指定目录。

  该函数和Autoexec.bat文件中的路径语句或路径环境变量无关。它仅作用在路径缓冲,帮助你创建,修改和操作查找路径。然后你可以通过使用不同的批处理文件函数添加该临时路径字符串到Autoexec.bat文件。该函数不支持长文件名。在将长文件名传递到PathFind前调用LongPathToShortPath将它转换到等价的短文件名。

参数:

szDir

指定要在路径缓冲中查找的路径。

svResult

返回由该函数返回的路径缓冲中的完整目录和路径。

bDir

指定szRefDir是否是一个全限定路径。在该参数位置传递下列预定义常量之一:

FULL:SzRefDir是一个全限定路径(也就是,包括一个驱动器指示符和到一个目录的完整路径)。

PARTIAL:SzRefDir仅是目录名(没有驱动器和路径信息)。

bSearch

指定从哪儿开始查找。在该参数位置传递下列预定义常量之一:

CONTINUE:从路径缓冲中的前一个查找结束处继续查找。

RESTART:从路径缓冲的开头开始查找。

返回值:

0:表明函数在路径缓冲中成功查找一个目录。

< 0:表明函数在路径缓冲中未能查找到一个目录。

14.4  PathGet

语法:PathGet (svString);

说明:PathGet函数检索当前保存在路径缓冲(一个由调用PathSet所创建的临时存储区)中的查找路径。路径缓冲使你能创建和编辑一个查找路径。当你编辑完路径,调用PathGet把查找路径放置到一个字符串变量,因而你可以把它传递到你的安装程序中的其它函数。

  该函数和Autoexec.bat文件中的路径语句或路径环境变量无关。它仅作用在路径缓冲,帮助你创建,修改和操作查找路径。然后你可以通过使用不同的批处理文件函数添加该临时路径字符串到Autoexec.bat文件。该函数不支持长文件名。在将长文件名传递到PathFind前调用LongPathToShortPath将它转换到等价的短文件名。

参数:

svString

返回路径缓冲中的内容。

返回值:

0:表明函数成功检索当前保存在路径缓冲中的路径。

< 0:表明函数未能检索当前保存在路径缓冲中的路径。

注解:

PathGet从路径缓冲中检索查找路径并释放分配给路径缓冲的内存。除非通过调用PathSet来重新初始化路径缓冲,否则随后对PathGet的调用将会失败。

14.5  PathMove

语法:PathMove (szDir, szRefDir, bDir, bRefDir, bPosition);

说明:PathMove函数重新定位路径缓冲中的一个目录到另一个位置。你也可以使用该函数来定位一个目录,相对于另一个目录或作为路径字符串中的第一项或最后一项。

    调用PathGet得到路径缓冲中的内容,调用PathSet设置路径缓冲中的内容。该函数和Autoexec.bat文件中的路径语句或路径环境变量无关。它仅作用在路径缓冲,帮助你创建,修改和操作查找路径。然后你可以通过使用不同的批处理文件函数添加该临时路径字符串到Autoexec.bat文件。该函数不支持长文件名。在将长文件名传递到PathMove前调用LongPathToShortPath将它转换到等价的短文件名。

参数:

szDir

指定在路径缓冲中重新定位的完整路径或部分路径。

szRefDir

指定当前路径缓冲中和将要被移动的szDir中的路径相关的路径。为移动szDir中的路径到路径缓冲中路径的开始或结尾,给该参数传递一个空字符串。

bDir

指定szDir是否是一个全限定路径。在该参数位置传递下列预定义常量之一:

FULL:表明szDir包含一个全限定目录名。

PARTIAL:表明szDir仅包含目录名。

bRefDir

指定szRefDir是否是一个全限定路径。在该参数位置传递下列预定义常量之一:

FULL:表明SzRefDir包含一个全限定路径名。

PARTIAL:表明SzRefDir仅包含目录名。

bPosition

指定szDir要被插入到的相对于szRefDir的位置。在该参数位置传递下列预定义常量之一:

AFTER:指定szDir被插入到szRefDir 之后。如果szRefDir指定一个空字符串,szDir被插入到路径缓冲中的路径结尾。

BEFORE:指定szDir被插入到szRefDir 之前。如果szRefDir指定一个空字符串,szDir被插入到路径缓冲中的路径前面。

返回值:

0:表明函数成功在路径缓冲中重新定位一个目录。

< 0:表明函数未能在路径缓冲中重新定位一个目录。

14.6  PathSet

语法:PathSet (szString);

说明:PathSet函数保存一个查找路径字符串到路径缓冲中。然后你可以使用其它路径函数来操作该缓冲。szString的值必须是一个绝对路径。

    该函数和Autoexec.bat文件中的路径语句或路径环境变量无关。它仅作用在路径缓冲,帮助你创建,修改和操作查找路径。然后你可以通过使用不同的批处理文件函数添加该临时路径字符串到Autoexec.bat文件。该函数不支持长文件名。在将长文件名传递到PathSet前调用LongPathToShortPath将它转换到等价的短文件名。

参数:

szString

指定一个要保存在路径缓冲中的查找路径。该查找路径必须是全限定的;也就是它必须包含一个驱动器指示符和到一个目录的完整路径。

返回值:

0:表明函数成功保存一个查找路径到路径缓冲中。

< 0:表明函数未能保存一个查找路径到路径缓冲中。

15  注册表函数

下列函数允许你访问注册表,读、创建和删除注册表项,和为卸载建立注册表相关参数。

s CreateCreateInstallationInfo

为你安装的程序创建一个应用程序信息项和一个每应用程序路径项。

s CreateRegistrySet

创建在资源窗格的注册表入口文件夹中指定注册表入口的一组或所有组。

s DeinstallSetReference

指定在卸载进程开始前要检测的参考文件。

s DeinstallStart

创建应用程序卸载项和设置该项下的[UninstallString]值。

s InstallationInfo

根据公司名、产品名和产品版本号来创建注册表项。

s MaintenanceStart

通过创建注册表项来激活卸载功能。

s RegDBConnectRegistry

打开到一个远程注册表的连接。

s RegDBCreateKeyEx

在注册表中创建一项。也允许你将一个类对象和一个注册表项联系起来(仅对高级用户)。

s RegDBDeleteKey

从注册表中删除指定项。

s RegDBDeleteValue

从一个指定注册表项中删除一个值。

s RegDBDisConnectRegistry

关闭到一个远程注册表的连接。

s RegDBGetAppInfo

在一个应用程序信息项下检索一个值。

s RegDBGetItem

在每应用程序路径项或应用程序卸载项下检索值。

s RegDBGetKeyValueEx

从注册表的一项中检索一个值。

s RegDBKeyExist

检测注册表项的存在。

s RegDBQueryKey

对一项的子项和值名进行排队。

s RegDBSetAppInfo

设置应用程序信息项下的一个值。

s RegDBSetDefaultRoot

设置开关键。

s RegDBSetItem

在每应用程序路径项或应用程序卸载项下赋值。

s RegDBSetKeyValueEx

设置注册表入口。

s SetInstallationInfo

指定CreateInstallationInfo使用的公司和产品信息。

15.1  CreateRegistrySet

语法:CreateRegistrySet (szRegistrySet);

说明:CreateRegistrySet函数创建由当前媒体中的一个或所有注册表组指定的注册表信息。当前媒体的名称保存在系统变量MEDIA中。一个注册表组可以和一个文件组相联系,因此仅当文件组已经被安装到目标系统上时,对CreateRegistrySet的调用才创建注册表组。如果你正使用一个基于事件的脚本,任何和一个或多个文件组相联系的注册表组(使用注册表组的文件组属性)当安装那些文件组的任何一个时,它都被自动创建。

参数:

SzRegistrySet

指定当前媒体上的注册表组名。为创建所有当前媒体上定义的注册表组,给该参数传递一个空字符串。

返回值:

0:表明函数成功。

-7:创建一项失败。

-8:不能设置一个注册表项的值。

-9:文本替换失败。

-10:内存溢出。

-11:未能从字符串表中取得一个值。

-12:该函数在当前媒体上调用ComponentTransferData之前被调用。注意ComponentTransferData在一个运行基于事件的脚本的安装中被自动调用。

-13:未知错误。

注解:

·系统变量MEDIA的值在安装初始化过程中被设置为‘DATA’。如果你修改该变量的值来指向一个脚本创建的组件组,则你在调用CreateRegistrySet之前必须把值修改回‘DATA’。

·该函数仅在已经调用ComponentTransferData后才能被调用。

15.2  CreateInstallationInfo

语法:CreateInstallationInfo ( );

说明:在一个基于事件的脚本中,CreateInstallationInfo函数在First UI Before事件之后被自动调用。它使用已经由SetInstallationInfo指定的信息来创建你正在安装的程序的一个应用程序信息项和每应用程序路径项。应用程序信息项作为调用InstallationInfo的结果立即被创建。每应用程序路径项则直到随后调用RegDBSetItem设置该项下的一个[Path] 或 [DefaultPath]值后才被创建。

    CreatInstallationInfo提供显示在欢迎对话框中的产品名,也提供MaintenanceStart使用来初始化卸载日志文件的公司名,产品名和版本号。如果脚本中在MaintenanceStart 之前没有调用CreateInstallationInfo,则MaintenanceStart将失败。在一个安装中只能调用CreateInstallationInfo一次。如果你运行多个使用DoInstall的安装,每个安装当然可以有它自己的对CreateInstallationInfo的调用。CreateInstallationInfo是一个特殊的注册表相关函数,设计为处理特定的预定义注册表项。

参数:

无。

返回值:

0:表明函数成功。

< 0:表明函数未能创建一个或多个注册表项。

注解:

·你必须在调用下列要使用由SetInstallationInfo提供的信息的函数之前调用CreateInstallationInfo:RegDBSetAppInfo, RegDBGetAppInfo, RegDBSetItem, RegDBGetItem。更多信息可查看这些函数的说明。

·由传递给SetInstallationInfo的值指定的每应用程序路径项直到调用RegDBSetItem设置该项下的值之后才真正被创建。

DeinstallSetReference

语法:DeinstallSetReference (szReferenceFile);

说明:指定在卸载进程开始前要检测的参考文件。如果该文件正被使用,卸载不执行。最终用户必须关闭使用该文件的进程并再开始卸载。你必须在调用DeinstallSetReference前调用DeinstallStart。

因为Windows和 Windows应用程序中的特定限制,在很少情况下一个由DeinstallSetReference指定的文件可能看似被锁定。

参数:

szReferenceFile

指定在卸载进程开始前要检测的文件的全限定名。该文件是只被要卸载的应用程序使用的一个程序或一个DLL

返回值:

0:表明函数成功。

< 0:表明函数失败。

注解:

·为指定要检测的多个文件,可为每个文件调用该函数。不要指定一个正被操作系统或其它应用程序使用的文件;如果你这么做,最终用户将不能继续卸载。

15.4  DeinstallStart

语法:DeinstallStart (szObsolete, svObsolete, szObsolete, lReserved);

说明:DeinstallStart函数仅支持和由InstallShield先前版本创建的脚本兼容。我们建议你使用MaintenanceStart函数来代替。

DeinstallStart函数通过在注册表项HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\ CurrentVersion\Uninstall\<PRODUCT_GUID>下创建下列值来激活卸载功能:

UninstallString  系统变量UNINST的值

DisplayName  传递给InstallationInfo第二个参数的值

LogFile  <DISK1TARGET>\Setup.ilg

DeinstallStart在一个安装脚本中必须只被执行一次。然而,如果你运行多个使用DoInstall的脚本,那么你可以在一个安装中调用DeinstallStart多次,因为每个单个脚本可以调用DeinstallStart一次。

参数:

szObsolete

该参数的值被忽略。

svObsolete

你必须给该参数传递一个字符串值。不返回有用信息。

szObsolete

该参数的值被忽略。

lReserved

给该参数传递0。不允许其它值。

返回值:

0:表明函数成功创建注册表项值。

< 0:表明函数未能创建一个或多个注册表项值。

注解:

·RegDBSetItem 和 RegDBGetItem函数设置和检索应用程序卸载项下的卸载图标名([DisplayName]值),它由调用DeinstallStart函数创建。因此,根据要被设置或检索的值,RegDBSetItem和 RegDBGetItem要求在它们被使用之前调用DeinstallStart。

·在调用任何使用SHAREDFILE或 LOCKEDFILE选项的函数前,并在调用SdFinishReboot前,应用程序信息项必须用InstallationInfo创建,应用程序卸载项必须用DeinstallStart函数创建。

·Enable(LOGGING)激活记录卸载信息。缺省时它被激活;你需要调用Enable(LOGGING)仅更正前一个Disable(LOGGING)调用的影响。

15.5  InstallationInfo

语法:InstallationInfo (szCompany, szProduct, szVersion, szProductKey);

说明:InstallationInfo函数指定一个公司名,一个产品名,一个产品版本号和一个程序可执行文件名。你指定的信息被用来为你安装的程序创建一个应用程序信息项和一个每应用程序路径项。应用程序信息项作为调用InstallationInfo的结果立即被创建。每应用程序路径项则直到随后调用RegDBSetItem设置该项下的一个[Path] 或 [DefaultPath]值后才被创建。

    InstallationInfo提供显示在欢迎对话框中的产品名。InstallationInfo提供DeinstallStart使用来初始化卸载日志文件的公司名,产品名和版本号。如果脚本中在DeinstallStart 之前没有调用InstallationInfo,则DeinstallStart将失败。

    在一个安装中只能调用InstallationInfo一次。如果你运行多个使用DoInstall的安装,每个安装当然可以有它自己的对InstallationInfo的调用。

InstallationInfo是一个特殊的注册表相关函数,被设计来处理特定的预定义注册表项。

参数:

szCompany

指定公司名。InstallShield使用szCompony来在注册表中的[HKEY_LOCAL_MACHINE] \Software项下创建一个\<company>项。

szProduct

指定要被安装的产品名。InstallShield使用szProduct来在注册表中的[HKEY_LOCAL_ MACHINE]\Software\<company>项下创建一个\<product>项。SzProduct的值也被插入到欢迎对话框中的消息文本的第一段中。

szVersion

指定产品的版本号。InstallShield使用szVersiont来在注册表中的[HKEY_LOCAL_MACHINE] \Software\<company>\<product>项下创建一个\<version>项。合在一起,\<company>项 (szCompany), \<product> 项(szProduct), 和\<version> 项(szVersion)被指定为应用程序信息项。应用程序信息项在调用InstallationInfo时立即被创建。

szProductKey

应用程序的主可执行文件的文件名。如果你使用几个可执行文件,指定最能代表产品的可执行文件。InstallShield 使用szProductKey来在项[HKEY_LOCAL_MACHINE]\Software \Microsoft\Windows\CurrentVersion\App Paths下创建一个每应用程序路径项。每应用程序路径项知道你调用RegDBSetItem创建该项下的一个数值名和数值数对后才真正在注册表中被创建。

返回值:

0:表明函数成功。

< 0:表明函数未能如设置那样使用参数。确认你使用了正确的语法。该函数的任何参数都不允许空字符串。

注解:

·你必须在调用下列函数之前调用InstallationInfo,因为它们使用InstallationInfo提供的信息:RegDBSetAppInfo, RegDBGetAppInfo, RegDBSetItem, RegDBGetItem。更多信息请查看这些函数的说明。

·由传递给InstallationInfo的值指定的每应用程序路径项直到调用RegDBSetItem设置该项下的值之后才真正被创建。

15.6  MaintenanceStart

语法:MaintenanceStart ( );

说明:MaintenanceStart函数创建在维护安装或卸载的初始化过程中使用的一个注册表项和相应值,并为添加/删除程序对话框提供应用程序信息。如果你使用一个基于事件的脚本,MaintenanceStart在First UI Before事件后被自动调用。

MaintenanceStart在注册表项HKEY_LOCAL_MACHINE\Software\Microsoft\Windows \CurrentVersion\Uninstall\<PRODUCT_GUID>下创建下列值:

UninstallString  系统变量UNINSTALL_STRING的值。

DisplayName  传递给SetInstallationInfo 或 InstallationInfo的第二个参数的值。

  (SetInstallationInfo函数在Begin事件之前被自动调用,它的第二个参数等于PRODUCT_NAME字符串表入口。)

LogFile  <DISK1TARGET>\Setup.ilg 

参数:

无。

返回值:

0:表明函数成功创建注册表项和它相应值。

< 0:表明函数未能创建注册表项和它相应值。

15.7  RegDBConnectRegistry

语法:RegDBConnectRegistry (szRemoteSystem, nKeyType, nReserved);

说明:RegDBConnectRegistry函数创建一个到一个远程注册表的连接。如果你试图打开一个远程Windows NT 系统的注册表,你必须拥有管理员的特权。如果你试图打开一个远程Windows 95 和更高的系统的注册表,则必须已经激活了远程管理。该函数是给系统管理员使用来进行网络安装的。

    一旦你已经打开了连接,你可以象对一个本地注册表一样对一个远程注册表进行创建、删除或检索注册表项、数值名和数值对。RegDBConnectRegistry允许你每次打开远程注册表时只编辑一个注册表开关键,你只可以编辑HKEY_LOCAL_MACHINE 或 HKEY_USERS下的项和值。当你调用RegDBConnectRegistry时,你必须指定你希望能编辑哪个开关键。如果你想要编辑另一个开关键或它的一个子项,你必须关闭并重新打开该连接。

为编辑一个远程注册表,你必须只使用通用注册表相关函数(如下所列),它们被设计为可以处理所有注册表项:

RegDBCreateKeyEx、RegDBDeleteKey、RegDBDeleteValue、RegDBGetKeyValueEx

RegDBKeyExist、RegDBQueryKey、RegDBSetKeyValueEx

参数:

szRemoteSystem

指定要连接的系统名,如"RemoteSys"。

nKeyType

指定下列常量之一:

HKEY_LOCAL_MACHINE 或 HKEY_USERS.

nReserved

给该参数传递0。不允许其它值。

返回值:

0:表明函数成功建立一个到系统注册表的连接。

REGDB_ERR_CONNECTIONEXISTS (-6):一个到一个远程注册表的连接早已存在。在你再次调用RegDBConnectRegistry之前必须用RegDBDisConnectRegistry关闭它。

REGDB_ERR_CORRUPTEDREGISTRY (-4):表明远程注册表被破坏,不能被访问。

REGDB_ERR_INITIALIZATION (-2):表明注册表服务不能被初始化。确认远程管理已经被激活并且你有可以写注册表的适当特权。

REGDB_ERR_INVALIDHANDLE (-5):提供给远程注册表的项名不被允许。

REGDB_ERR_INVALIDNAME (-3):表明在szRemoteSystem中的系统不能被找到。检查名称并重试。

-1:其它错误。

注解:

·自从你通过调用RegDBConnectRegistry设置了开关键,一旦你已经建立了一个到远程注册表的连接,你就不能调用RegDBSetDefaultRoot。一旦你已经调用了RegDBDisConnectRegistry,所有对注册表相关函数的调用都会影响本地注册表,并且然后你可以调用RegDBSetDefaultRoot来修改开关键。

·在一个卸载中,InstallShield将卸载为存入卸载记录中的任何项下的所有项。由InstallShield自动创建的项将为存入卸载记录。当你调用RegDBSetKeyValueEx创建项,在这些项以上没有存入卸载记录的项,你的项不会被卸载掉,不管存入是否被激活(你可以Enable和Disable登记)。然而,当你调用RegDBCreateKeyEx来创建一个项,当存入被激活时,该项上没有存入卸载记录的项,你的项会存入卸载记录。当存入项被删除时,你创建在该项下的所有项会被卸载。更多信息可查询各个函数的说明。

15.8  RegDBCreateKeyEx

语法:RegDBCreateKeyEx (szKey, szClass);

说明:RegDBCreateKeyEx函数创建注册表中的一项。你也可以将一个类对象和新创建的项联系起来(仅对高级用户)。新创建的项没有一个和它相联系的值。除非你另外指定,InstallShield将该项创建为HKEY_CLASSES_ROOT的子项。你可以使用RegDBSetDefaultRoot来指定一个不同的开关键。

    在一个项-子项表达式中用一个双反斜杠来分隔不同层。如果它们不存在时,InstallShield将立即创建所有层。

  当存入功能被激活时,由RegDBCreateKeyEx创建的项存入卸载记录。然而,记住在一个多项表达式如Key1\Key2\Key3中,RegDBCreateKeyEx识别Key3为该函数调用所关系的项。如DOS命令DIR C:\Windows\System列出 Windows系统文件夹中的文件,而不是Windows文件夹中的。因此,Key3将被存入到卸载记录,但Key1和Key2不会。有关Windows 系统文件夹的信息,请查阅InstallShield 系统变量WINSYSDIR的文档。

  为在RegDBCreateKeyEx创建一个项和子项时确保正确地存入卸载记录,首先创建父项(存入功能激活时)。当项的链中父项或高层项被创建后,然后创建父项下的子项。被各自创建的父项的下面所有子项当父项被卸载时也会被卸载。

例如,为确保Key1和所有它的子项会被卸载,首先当存入被激活时用RegDBCreateKeyEx创建Key1。然后你可以在一个单独的函数调用中或在各自的函数调用中创建Key2,Key3等等项。当Key1被卸载,它下面的所有子项将被卸载。

  记住当一个项被卸载时,它的所有子项也被卸载。因此,如果你使用RegDBCreateKeyEx来创建一个已经被存入卸载记录的项下的项,那么当更高层的项被卸载时你所创建的项也被卸载,不管当你创建你的项时存入功能是否被激活,也不管你以什么次序创建你的项。

  如果你正用RegDBCreateKeyE创建的项已经存在并且你没有禁用存入功能,则其它应用程序使用的项将被存入卸载记录。在一个卸载过程中,该项将被卸载,这给那些使用该项的应用程序造成问题。为避免该问题,在创建一个项前用RegDBKeyExist来检测它的存在性。如果该项已经存在,使用RegDBCreateKeyEx来创建一个对你的应用程序唯一的子项。然后,当卸载发生时,只有子项被删除。如果你不希望首先检测项的存在性,当你创建该项时,你可以使用Disable函数来禁用存入功能。在项被创建后再激活存入功能。然而,记住该项不会和你的应用程序一个被卸载。

RegDBCreateKeyEx是一个通用注册表相关函数,设计为可工作于所有注册表项,包括那些由特殊注册表相关函数处理的项。

参数:

szKey

指定要在四个开关键中的一个之下创建的项的名称。用一个双反斜杠来分隔子项中的不同层。

szClass

指定和该项相联系的类名。

返回值:

0:表明函数成功创建该子项。

< 0:表明函数未能创建该子项。

注解:

·Windows NT 4.0不允许在HKEY_LOCAL_MACHINE下直接创建一个项。

15.9  RegDBDeleteKey

语法:RegDBDeleteKey (szSubKey);

说明:RegDBDeleteKey函数从注册表中删除一个特定项和与它相联系的值。被删除项的所有子项及与它们相联系的值也被删除。

    InstallShield假定由szSubKey指定的项是HKEY_CLASSES_ROOT的一个子项。你可以使用RegDBSetDefaultRoot来指定另一个开关键。

RegDBDeleteKey是一个通用注册表相关函数,设计为可工作于所有注册表项,包括那些由特殊注册表相关函数处理的项。

参数:

szSubKey

指定要删除的项的名称。用一个双反斜杠来分隔子项中的不同层。

返回值:

0:表明函数成功删除该项。

< 0:表明函数未能删除该项。

15.10  RegDBDeleteValue

语法:RegDBDeleteValue (szSubKey, szValue);

说明:RegDBDeleteValue函数从一个注册表的一个特定项中删除一个值。InstallShield假定由szSubKey指定的项是HKEY_CLASSES_ROOT的一个子项。你可以使用RegDBSetDefaultRoot来指定另一个开关键。

参数:

szSubKey

指定注册表项的名称,该项包含要删除的值名。用一个双反斜杠来分隔子项中的不同层。

szValue

指定你要删除的值的名称。

返回值:

0:表明函数成功删除该值。

< 0:表明函数未能删除该值。

15.11  RegDBDisConnectRegistry

语法:RegDBDisConnectRegistry (nReserved);

说明:RegDBDisConnectRegistry函数关闭调用RegDBConnectRegistry建立的到一个远程注册表的一个连接。

    调用RegDBDisConnectRegistry后,所有对安装脚本注册表相关函数的调用都会影响本地系统注册表。更多信息请查阅特殊注册表相关函数。

参数:

nReserved

给该参数传递0。不允许其它值。

返回值:

0:表明函数成功关闭一个到远程系统上的注册表的连接。

< 0:表明函数未能关闭注册表连接。

15.12  RegDBGetAppInfo

语法:RegDBGetAppInfo (szName, nvType, svValue, nvSize);

说明:RegDBGetAppInfo函数从注册表中检索你的主应用程序的应用程序信息项下的一个特定数值名的值。应用程序信息项由InstallShield创建,作为调用InstallationInfo的结果。在调用RegDBGetAppInfo之前,你必须调用InstallationInfo来创建一个应用程序信息项。

RegDBGetAppInfo是一个特殊的注册表相关函数,被设计来处理特定的预定义注册表项。

参数:

szName

指定要检索的值的数值名。

nvType

返回下列预定义常量之一,它们标识在svValue返回的数据的类型:

REGDB_STRING:字符串变量,不允许换行符。

REGDB_STRING_EXPAND:字符串变量保持一种可扩展的环境变量表达式,如"%MYPATH%"。

REGDB_STRING_MULTI:字符串变量,允许换行符。

REGDB_NUMBER:看作为一个字符串的数字表达式,并可传递给字符串变量。

REGDB_BINARY:将二进制数据保存在一个字符串中。

svValue

返回由szName指定的数值名的值。

nvSize

以字节数返回返回值的大小。

返回值:

0:表明函数成功检索该值。

< 0:表明函数未能检索该值。

15.13  RegDBGetItem

语法:RegDBGetItem (nItem, svValue);

说明:RegDBGetItem函数根据nItem的值检索每应用程序路径项或应用程序卸载项下的值。这些项InstallShield 创建,作为调用InstallationInfo的结果。在调用RegDBGetItem之前,你必须调用InstallationInfo来创建一个应用程序信息项。

RegDBGetItem是一个特殊的注册表相关函数,被设计来处理特定的预定义注册表项。

参数:

nItem

指定要检索的项。在该参数位置传递下列预定义常量之一:

REGDB_APPPATH:每应用程序路径项下[Path]的值。

REGDB_APPPATH_DEFAULT:每应用程序路径项下[DefaultPath]的值。

REGDB_UNINSTALL_NAME:卸载项下[DisplayName]的值。当该常量被使用时,szValue指定显示在控制面板中可卸载应用程序列表中的应用程序名。

svValue

返回该项的值。

返回值:

0:表明函数成功检索该项目的值。

< 0:表明函数未能检索该项目的值。确认你在使用该函数之前使用了InstallationInfo函数。

注解:

·在调用RegDBGetItem函数(nItem为REGDB_APPPATH 或 REGDB_APPPATH_DEFAULT选项)前,你必须用InstallationInfo函数创建每应用程序路径项。在调用RegDBGetItem函数(nItem为REGBD_UNINSTALL_NAME)前,你必须调用DeinstallStart函数来创建卸载项,并给应用程序卸载项下的[DisplayName]赋一个值。

15.14  RegDBGetKeyValueEx

语法:RegDBGetKeyValueEx (szKey, szName, nvType, svValue, nvSize);

说明:RegDBGetKeyValueEx函数检索注册表中一个指定项下一个特定数值名的值。缺省时,InstallShield假定该项是HKEY_CLASSES_ROOT下的一个子项。你可以用RegDBSetDefaultRoot来指定另一个开关键。

RegDBGetKeyValueEx是一个通用注册表相关函数,设计为可工作于所有注册表项,包括那些由特殊注册表相关函数处理的项。

参数:

szKey

指定其值要被检索的项的名称。用一个双反斜杠来分隔子项中的不同层。

szName

指定在szKey下其值要被检索的数值的数值名。要检索项的缺省值,则传递一个空字符串。

nvType

返回下列预定义常量之一,它们标识在svValue返回的数据的类型:

请参阅15.12中该部分的说明。

svValue

返回由szKey和svName 指定的值。注意一个数值型值以一个字符串返回。

nvSize

以字节数返回在svValue返回的值的大小。

返回值:

0:表明函数成功检索该值。

< 0:表明函数未能检索该值。

注解:

一个Windows NT平台上,当检索REGDB_STRING_MULTI数据类型时,带空字符串为参数调用StrGetTokens来将多个以空字符串为中止的字符串分析到一个字符串列表。也就是,如果svValue在调用RegDBGetKeyValueEx后有多个结果字符串,StrGetTokens( listID, svValue, "")可以被使用来分析字符串并把它们放到一个由listID指向的字符串列表。

15.15  RegDBKeyExist

语法:RegDBKeyExist (szSubKey);

说明:RegDBKeyExist函数检测注册表中一个特定项的存在性。缺省时,InstallShield假定该项是HKEY_CLASSES_ROOT下的一个子项。你可以用RegDBSetDefaultRoot来指定另一个开关键。

RegDBKeyExist是一个通用注册表相关函数,设计为可工作于所有注册表项,包括那些由特殊注册表相关函数处理的项。

参数:

szSubKey

指定要查找的项的名称。你不必要在该参数包括HKEY_CLASSES_ROOT项(或你指定的其它项)。用一个双反斜杠来分隔子项的不同层。

返回值:

1:表明函数成功找到注册表中的项。

< 0:表明函数未能找到注册表中的项。

15.16  RegDBQueryKey

语法:RegDBQueryKey (szSubKey, nItem, listResults);

说明:RegDBQueryKey函数允许用户排队一个项的子项和值名。使用该函数可以在运行时动态列举这些项。

RegDBQueryKey是一个通用注册表相关函数,设计为可工作于所有注册表项,包括那些由特殊注册表相关函数处理的项。

参数:

szSubKey

指定先前调用RegDBSetDefaultRoot设置的开关键中某一个的子项。使用反斜杠来指定子项的更深层。为检索开关键,传递一个空字符串。

nItem

指定必须被放置在列表中的项目。在该参数位置传递下列预定义常量之一:

REGDB_KEYS:在listResult 返回的字符串列表将包含一个该项下的所有子项的列表。

REGDB_NAMES:在listResult 返回的字符串列表将包含该项的所有命名值的名。

listResults

返回在一个字符串列表中排队的结果。由listResult标识的列表必须已经通过调用ListCreat而被初始化。

返回值:

0:表明函数成功。

< 0:表明函数失败。

15.17  RegDBSetAppInfo

语法:RegDBSetAppInfo (szName, nType, szValue, nSize);

说明:RegDBSetAppInfo函数设置注册表中应用程序信息项下的一个特定数值名的值。你在调用RegDBSetAppInfo前必须调用InstallationInfo来创建一个应用程序信息项。

RegDBSetAppInfo是一个特殊的注册表相关函数,被设计来处理特定的预定义注册表项。

参数:

szName

指定其信息要被设置的数值名。

nType

指定你要设置的数据的类型,在该参数位置传递下列预定义常量之一:

请参阅15.12中该部分的说明。

szValue

指定为数值名设置的值。

nSize

以字节数返回传递给RegDBSetAppInfo的数据的大小。给该参数传递-1来表明InstallShield应该确定该数据的大小。

返回值:

0:表明函数成功给数值名赋值。

< 0:表明函数未能赋值。

15.18  RegDBSetDefaultRoot

语法: RegDBSetDefaultRoot (nRootKey);

说明:RegDBSetDefaultRoot函数设置一个被其它注册表函数使用的开关键。大多数InstallShield注册表函数工作在以HKEY_CLASSES_ROOT为注册表树的缺省根。使用该函数,你可以指定另一个项,如HKEY_LOCAL_MACHINE 或 HKEY_CURRENT_USER 或 HKEY_USERS为开关键。

RegDBGetKeyValueEx是一个通用注册表相关函数,设计为可工作于所有注册表项,包括那些由特殊注册表相关函数处理的项。

你可以使用RegDBSetDefaultRoot来修改使用特殊注册表相关函数创建或处理项的开关键。

参数:

nRootKey

指定设置为开关键的项的名。

返回值:

0:表明函数成功设置项。

< 0:表明函数未能设置项。

注解:

·Windows NT 4.0不允许在HKEY_LOCAL_MACHINE下直接创建一个项。

15.19  RegDBSetItem

语法:RegDBSetItem (nItem, szValue);

说明:RegDBSetItem函数给每应用程序路径项或应用程序卸载项下赋值,根据nItem的值而定。以REGDB_APPPATH或 REGDB_APPPATH_DEFAULT选项调用RegDBSetItem则结果创建每应用程序路径项。注意你必须在调用RegDBSetItem之前调用InstallationInfo来创建这些项。

RegDBSetItem是一个特殊的注册表相关函数,被设计来处理特定的预定义注册表项。

参数:

nItem

指定要设置的项目(条目)。在该参数位置传递下列预定义常量之一:

REGDB_APPPATH:在每应用程序路径项下的[Path]值。

REGDB_APPPATH_DEFAULT:在每应用程序路径项下的[DefaultPath]值。

REGDB_UNINSTALL_NAME:卸载项下的[DisplayName]值。当使用该常量时,szValue指定在控制面板中卸载应用程序列表中的显示的应用程序名。

szValue

指定赋给指定项目的值。

返回值:

0:表明函数成功设置值。

< 0:表明函数失败。最通常的失败原因是没有前调用InstallationInfo函数。该函数只有在你调用InstallationInfo后才能被执行。

注解:

·在使用REGDB_APPPATH 或REGDB_APPPATH_DEFAULT选项(它们将影响创建每应用程序路径项,也影响在其下写一个值)调用RegDBSetItem函数之前,你必须调用InstallationInfo函数来提供被使用来创建该项的信息。

·当你调用MaintenanceStart 或DeinstallStart函数时,[UninstallString]值被创建。

15.20  RegDBSetKeyValueEx

语法:RegDBSetKeyValueEx (szKey, szName, nType, szValue, nSize);

说明:RegDBSetKeyValueEx函数设置注册表中一个项下指定的数值名的值。如果该项不存在,RegDBSetKeyValueEx将会为你创建它。然而,新创建的项不会存入卸载记录除非它是一个已经存入卸载记录的项的子项。如下情况项会存入卸载记录:

s 当它们使用RegDBCreateKeyEx而被创建。

s 当存入功能被激活时。

s 当它们在安装进程中由InstallShield自动被创建。

s 当它们作为调用一个特殊注册表相关函数的结果而被创建。

如果数值名不存在,RegDBSetKeyValueEx创建它。如果数值数已经存在,RegDBSetKeyValueEx改写它。InstallShield假定szKey中的数值名是HKEY_CLASSES_ROOT项的一个子项。如果你想要使用一个不同的主项,则使用RegDBSetDefaultRoot函数来设置该主开关键。

RegDBSetKeyValueEx是一个通用注册表相关函数,设计为可工作于所有注册表项,包括那些由特殊注册表相关函数处理的项。

参数:

szKey

指定要设置的项的名;该项必须已经由RegDBCreateKeyEx创建。你不必要在该参数包括HKEY_CLASSES_ROOT项(或你指定的其它项)。用一个双反斜杠来分隔子项的不同层。

szName

指定要被设置的数值数的数值名。为设置在szKey指定的项的缺省值,给该参数传递一个空字符串。

nType

指定你要设置的数据的类型,在该参数位置传递下列预定义常量之一:

请参阅15.12中该部分的说明。

szValue

指定和数值名相联系的值。所有值必须以字符串变量传递。数字必须表示为字符串(InstallShield内部将它们转换为数字)。

nSize

以字节数指定要被设置的数据的大小。当nType是REGDB_STRING, REGDB_STRING_EXPAND, 或 REGDB_NUMBER时,你可以将该参数指定为-1InstallShield会设置其大小。然而,当nType为REGDB_BINARY和 REGDB_STRING_MULTI时,你必须总指定你在保存的二进制数据的字节数。

返回值:

0:表明函数成功设置该项。

< 0:表明函数未能设置该项。

15.21  SetInstallationInfo

语法:SetInstallationInfo (szCompany, szProduct, szVersion, szProductKey);

说明:在一个基于事件的脚本中,SetInstallationInfo函数在 Begin事件之前被自动调用,以字符串表表目COMPANY_NAME, PRODUCT_NAME, PRODUCT_VERSION, 和 PRODUCT_KEY为其参数。SetInstallationInfo指定该信息由CreateInstallationInfo(它在一个基于事件脚本中就在First UI Before事件后被自动调用来创建你正在安装的程序的一个应用程序信息项和一个每应用程序路径项)使用。

SetInstallationInfo是一个特殊注册表相关函数,设计为可工作于特定预定义的注册表项。

参数:

szCompany

指定公司名。CreateInstallationInfo使用szCompany来创建注册表中[HKEY_LOCAL_ MACHINE]\Software项下的\<company>项。

szProduct

指定被安装的产品的名称。CreateInstallationInfo使用szProduct来创建注册表中[HKEY_LOCAL_MACHINE]\Software\<company>项下的\<product>项。SzProduct的值也被插入到欢迎对话框中消息文本的第一段中。

szVersion

指定产品的版本号。InstallShield使用szVersiont来在注册表中的[HKEY_LOCAL_MACHINE] \Software\<company>\<product>项下创建一个\<version>项。合在一起,\<company>项 (szCompany), \<product> 项(szProduct), 和\<version> 项(szVersion)被指定为应用程序信息项。应用程序信息项在调用InstallationInfo时立即被创建。

szProductKey

应用程序的主可执行文件的文件名。如果你使用几个可执行文件,指定最能代表产品的可执行文件。InstallShield 使用szProductKey来在项[HKEY_LOCAL_MACHINE]\Software \Microsoft\Windows\CurrentVersion\App Paths下创建一个每应用程序路径项。每应用程序路径项知道你调用RegDBSetItem创建该项下的一个数值名和数值数对后才真正在注册表中被创建。

返回值:

该函数总返回0

16  列表处理函数

    列表被使用来保存相关信息组。在InstallShield中,有两类列表:字符串列表和数字列表。提供两组函数来处理列表:每个处理一种类型。以”Item”结尾的列表函数处理数字列表。以”String”结尾的列表函数处理字符串列表。你不能将数字列表函数使用到字符串列表,反之亦然。下面是在一个安装脚本中处理列表的函数。

s ListAddItem

添加一项到一个列表。

s ListAddString

添加一个字符串到一个列表。

s ListCount

返回在一个指定列表中字符串或数值型元素的数目。

s ListCreate

创建一个新的字符串或数字列表。

s ListCurrentItem

返回一个列表中的当前项目。

s ListCurrentString

返回一个列表中的当前字符串。

s ListDeleteItem

删除一个列表中当前项目。

s ListDeleteString

删除一个列表中的当前字符串。

s ListDestroy

消除一个列表。

s ListFindItem

使指定项目成为一个数字列表中的当前项目。

s ListFindString

使指定项目成为一个字符串列表中的当前项目。

s ListGetFirstItem

从一个数字列表中检索第一个元素。

s ListGetFirstString

从一个字符串列表中检索第一个元素。

s ListGetNextItem

从一个数字列表中检索当前元素后的元素。

s ListGetNextString

从一个字符串列表中检索当前元素后的元素。

s ListReadFromFile

读一个文本文件到一个列表。

s ListSetCurrentItem

设置一个数字列表中的当前元素。

s ListSetCurrentString

设置一个字符串列表中的当前元素。

s ListSetIndex

使用一个索引来设置一个列表的当前元素。

s ListWriteToFile

写一个字符串列表到一个文件。

16.1  ListAddItem

语法:ListAddItem (listID, nItem, nPlacementFlag);

说明:ListAddItem函数将一个数值型元素添加到一个数字列表中当前元素的前面或后面。为遍历一个列表,首先调用ListGetFirstItem得到列表的第一个元素;然后重复调用ListGetNextItem直到你到达列表尾。为使列表中的一个特定元素成为当前元素,调用ListSetIndex。

参数:

listID

指定一个数字列表的名称。由listID标识的列表必须早已由ListCreate函数初始化。

nItem

指定要添加到列表中的数值型元素。

nPlacementFlag

指定在哪儿放置和当前元素相关的nItem。新元素可以在当前元素之前或之后。在该参数位置传递下列预定义常量之一:

AFTER:将新元素添加到列表中当前元素之后。

BEFORE:将新元素添加到列表中当前元素之前。

返回值:

0:ListAddItem成功添加元素到一个数字列表。

< 0:ListAddItem未能添加元素到一个数字列表。

注解:

·ListAddItem仅工作于数字列表。

16.2  ListAddString

语法:ListAddString (listID, szString, nPlacementFlag);

说明:ListAddString函数添加一个字符串到一个字符串列表中当前元素之前或之后。为遍历一个列表,首先调用ListGetFirstItem得到列表的第一个元素;然后重复调用ListGetNextItem直到你到达列表尾。为使列表中的一个具体元素成为当前元素,调用ListSetIndex。

参数:

listID

指定一个字符串列表的名称。由listID标识的列表必须早已由ListCreate函数初始化。

szString

指定添加到列表中的字符串。

nPlacementFlag

指定在哪儿放置和当前元素相关的szString。新字符串可以在当前元素之前或之后。在该参数位置传递下列预定义常量之一:

AFTER:将新字符串添加到列表中当前元素之后。

BEFORE:将新字符串添加到列表中当前元素之前。

返回值:

0:ListAddString成功添加字符串到列表。

< 0:ListAddString未能添加字符串到列表。

注解:

·ListAddString仅工作于字符串列表。

16.3  ListCount

语法:ListCount (listID);

说明:ListCount函数返回一个列表中的元素数目。

参数:

listID

指定一个字符串或数字列表的名称。

返回值:

>= 0:列表中的项目数。

< 0:ListCount未能确定列表中的元素数。

注解:

·该函数工作于字符串和数字列表。

16.4  ListCreate

语法:ListCreate (nListType);

说明:ListCreate函数创建一个空的字符串或数字列表。记住一个列表不能包括两个类型的元素。InstallShield提供不同的函数组来工作于字符列表和数字列表。你必须不能将一个数字列表的ID用于字符串列表函数,反之亦然。以”Item”结尾的列表函数处理数字列表。以”String”结尾的列表函数处理字符串列表。

    当你不再需要列表时,你可以用ListDestroy函数来消除列表。每个列表都有一个指针来标识一个元素为列表的当前元素。不同的列表函数重新定位列表的当前元素。调用任何列表函数时,你必须给该函数传递列表的一个有效ID。确定该函数创建列表成功。否则,所有列表函数因无效列表而失败。

参数:

nListType

指定要创建的列表类型。在该参数位置传递下列预定义常量之一:

NUMBERLIST:指定一个数字列表。

STRINGLIST:指定一个字符串列表。

返回值;

ListID:新创建的空列表的ID。无论何时你要在其它InstallShield列表函数中使用该列表,你都必须使用该ID。你必须检测该变量并确认函数没有返回LIST_NULL。

LIST_NULL (-1):表明InstallShield未能创建一个列表。那是一个严重内存问题的结果,这是很少见的一种情况。有这样的内存问题时你要继续安装可能会很困难。

注解:

·在你传递一个有效列表ID给任何需要一个列表的函数时,你必须使用ListCreat创建该列表。你可以在一个脚本中创建任意个列表。一个列表可能包含任意个元素。唯一的限制是有效空闲内存的大小。

16.5  ListCurrentItem

语法:ListCurrentItem (listID, nvItem);

说明:ListCurrentItem函数从listID指定的数字列表中检索当前元素。

参数:

listID

指定一个数字列表。

nvItem

返回列表中当前元素的值。

返回值;

0:表明函数成功在一个数字列表中检索当前元素。

< 0:表明函数未能在一个数字列表中检索当前元素。

END_OF_LIST (1):表明列表为空因而没有一个当前元素。

注解:

·该函数仅工作于数字列表。

·你也可以使用ListGetFirstItem 和ListGetNextItem函数来遍历列表并使任何元素为当前元素。

16.6  ListCurrentString

语法:ListCurrentString (listID, svString);

说明:ListCurrentString函数从listID指定的字符串列表中检索当前元素。

参数:

listID

指定一个字符串列表。

svString

返回列表当前元素的值。

返回值:

0:表明函数成功在一个字符串列表中检索当前元素。

< 0:表明函数未能在一个字符串列表中检索当前元素。

END_OF_LIST (1):表明列表为空因而没有一个当前元素。

注解:

·该函数仅工作于字符串列表。

·你也可以使用ListGetFirstString 和ListGetNextString函数来遍历列表并使任何元素为当前元素。

16.7  ListDeleteItem

语法:ListDeleteItem (listID);

说明:ListDeleteItem函数从你在listID指定的数字列表中删除当前元素。

参数:

listID

指定从中删除当前元素的数字列表。

返回值:

0:表明函数从一个数字列表中成功删除当前元素。

< 0:表明函数未能从一个数字列表中删除当前元素。

END_OF_LIST (1):表明列表为空因而没有一个当前元素。

注解:

请参阅ListCurrentItem的注解。

16.8  ListDeleteString

语法:ListDeleteString (listID);

说明:ListDeleteString函数从你在listID指定的字符串列表中删除当前元素。

参数:

listID

指定从中删除当前元素的字符串列表。

返回值:

0:表明函数从一个字符串列表中成功删除当前元素。

< 0:表明函数未能从一个字符串列表中删除当前元素。

END_OF_LIST (1):表明列表为空因而没有一个当前元素。

注解:

请参阅ListCurrentString的注解。

16.9  ListDestroy

语法:ListDestroy (listID);

说明:ListDestroy函数消除一个列表的内容及列表本身。使用该函数来删除一个listID指定的字符串或数字列表。

参数:

listID

指定要消除的字符串或数字列表。

返回值:

0:表明函数成功消除列表,把它从内存中删除。

< 0:表明函数未能消除列表。

注解:

·该函数既可作用于字符串列表,也可作用于数字列表。一旦一消除了一个列表,不要再在任何列表函数中使用该listID。

·当你不再需要时或在安装脚本结尾时,消除你创建的所有列表。当你消除一个列表,你就释放了和该列表联系的所有内存。

16.10  ListFindItem

语法:ListFindItem (listID, nItem);

说明:ListFindItem函数在一个数字列表中查找一个特定元素,从当前元素开始并从该点继续往下。如果你想从列表头开始查找,使用ListGetFirstItem函数。当ListFindItem找到元素时,它就成为列表的当前元素。

参数:

listID

指定要查找的数字列表。

nItem

指定要在列表中查找的项目。

返回值:

0:表明函数成功找到所要求的元素。

< 0:表明一个错误阻止函数查找指定列表。如,如果由listID指定的列表不存在则会发生错误。

END_OF_LIST (1):表明InstallShield查找到了列表结尾但没有找到所要求的元素。

注解:

·该函数仅工作于数字列表。

16.11  ListFindString

语法:ListFindString (listID, szString);

说明:ListFindString函数在一个字符串列表中查找一个特定元素,从当前元素开始并从该点继续往下。如果你想从列表头开始查找,使用ListGetFirstString函数。当ListFindString找到元素时,它就成为列表的当前元素。

    该函数对字符串比较时区分大小写。

参数:

listID

指定要查找的字符串列表。

szString

指定要在列表中查找的字符串。当查找该字符串时,InstallShield执行一个区分大小写的比较。

返回值:

0:表明函数成功找到所要求的元素。

< 0:表明一个错误阻止函数查找指定列表。如,如果由listID指定的列表不存在则会发生错误。

END_OF_LIST (1):表明InstallShield查找到了列表结尾但没有找到所要求的元素。

注解:

·该函数仅工作于字符串列表。

16.12  ListGetFirstItem

语法:ListGetFirstItem (listID, nvItem);

说明:ListGetFirstItem函数从一个数字列表中检索第一个元素。该第一个项目成为该列表中的当前元素。

参数:

listID

指定要检索其第一个元素的数字列表。

nvItem

返回数字列表的第一个元素。

返回值:

0:表明函数成功检索了一个数字列表的第一个元素。

-1:表明发生了一个错误阻止函数检索一个数字列表中的第一个元素。

END_OF_LIST (1):表明列表为空。

注解:

·该函数仅工作于数字列表。

16.13  ListGetFirstString

语法:ListGetFirstString (listID, svString);

说明:ListGetFirstString函数从一个字符串列表中检索第一个元素。该第一个项目成为该列表中的当前元素。

参数:

listID

指定要检索其第一个元素的字符串列表。

svString

返回字符串列表的第一个元素。

返回值:

0:表明函数成功检索了一个字符串列表的第一个元素。

-1:表明发生了一个错误阻止函数检索一个字符串列表中的第一个元素。

END_OF_LIST (1):表明列表为空。

注解:

·该函数仅工作于字符串列表。

16.14  ListGetNextItem

语法:ListGetNextItem (listID, nvItem);

说明:ListGetNextItem函数检索一个数字列表中当前元素之后的项目。被检索的项目成为该列表中的当前元素。

参数:

listID

指定要从中检索下一个元素的数字列表。

nvItem

返回在数字列表中紧随当前元素的项目。该项目成为列表中的当前元素。

返回值:

0:表明函数成功检索一个数字列表中当前元素之后的元素。

-1:表明发生一个错误阻止函数检索一个数字列表中的指定元素。

END_OF_LIST (1):表明当前项目是列表中的最后一个元素。

注解:

·该函数仅工作于数字列表。

16.15  ListGetNextString

语法:ListGetNextString (listID, svString);

说明:ListGetNextString函数检索一个字符串列表中当前元素之后的项目。被检索的项目成为该列表中的当前元素。

参数:

listID

指定要从中检索下一个元素的字符串列表。

svString

返回在数字列表中紧随当前元素的项目。该项目成为列表中的当前元素。

返回值:

0:表明函数成功检索一个字符串列表中当前元素之后的元素。

-1:表明发生一个错误阻止函数检索一个字符串列表中的指定元素。

END_OF_LIST (1):表明当前项目是列表中的最后一个元素。

注解:

·该函数仅工作于字符串列表。

16.16  ListReadFromFile

语法:ListReadFromFile (listID, szFile);

说明:ListReadFromFile函数读一个文本文件到一个列表。一旦你把一个文本文件装入一个列表,你就可以在安装中把它用到不同的函数,如在安装结尾显示一个README文件或用ListWriteToFile写一个字符串列表到磁盘。

    该函数让你可以很方便地把整个文件装入到一个列表,而不是一次创建一个列表项。

参数:

listID

返回一个从szFile指定的文件中读入行的列表。由listID 标识的列表必须已经由ListCreat初始化。

szFile

指定将要被读入列表的文件的全限定名。

返回值:

0:表明函数成功将一个文件中的文本行读入到一个列表。

< 0:表明函数未能将一个文件中的文本行读入到一个列表。

注解:

·该函数检测每个字符串结尾的换行符并使用这些字符作为列表中每个元素的分界符。

·该函数仅作用于字符串列表和文本文件。

16.17  ListSetCurrentItem

语法:ListSetCurrentItem (listID, nItem);

说明:ListSetCurrentItem函数将nItem的值赋给一个数字列表中的当前元素。

参数:

listID

指定其当前元素要被更新的数字列表的名称。由listID标识的列表必须早以由ListCreat初始化。

nItem

指定将要置换当前元素的数值型值。

返回值:

0:表明函数成功更新数字列表中的当前元素。

< 0:表明函数未能更新数字列表中的当前元素。

END_OF_LIST (1):表明列表为空。

注解:

·该函数仅工作于数字列表。

16.18  ListSetCurrentString

语法:ListSetCurrentString (listID, szString);

说明:ListSetCurrentString函数将szString的值赋给一个字符串列表中的当前元素。

参数:

listID

指定其当前元素要被更新的字符串列表的名称。由listID标识的列表必须早以由ListCreat初始化。

szString

指定将要置换当前元素的字符串型值。

返回值:

0:表明函数成功更新字符串列表中的当前元素。

< 0:表明函数未能更新字符串列表中的当前元素。该错误的通常的原因是下标超出有效列表元素的范围。

注解:

·该函数仅工作于字符串列表。

16.19  ListSetIndex

语法:ListSetIndex (listID, nIndex);

说明:ListSetIndex函数使用一个下标来指定一个字符串列表或数字列表中的一个特定元素为当前元素。你也可以使用使用一个常量来一次检索列表中的一个元素或跳到列表的头或尾。通过使用下标来访问列表中的项,你可以将数字列表或字符串列表处理为队列。

    下标数从0开始。例如,如果你在参数nIndex中输入5,则列表中的第六个物理位置的项成为当前元素。使用ListCurrentItem 和 ListCurrentString来检索当前元素的值。

参数:

listID

指定其下标要被设置的字符串列表或数字列表的名称。

nIndex

指定你要设置为当前元素的元素的数。列表元素从0开始计数。在该参数位置传递一个数值型值或下列预定义常量之一:

LISTFIRST:移动到列表的第一个元素。

LISTLAST:移动到列表的最后一个元素。

LISTNEXT:移动到列表的下一个元素。

LISTPREV:移动到列表的前一个元素。

返回值:

0:表明函数成功更新列表中的当前元素。

< 0:表明函数未能更新列表中的当前元素。

END_OF_LIST (1):表明下标超出有效列表元素的范围。

注解:

·在你设置被索引的元素为当前元素后,你可以在脚本中使用ListCurrentItem 或 ListCurrentString函数来检索被索引(当前)项的值。

·该函数可工作于字符串列表和数字列表。

16.20  ListWriteToFile

语法:ListWriteToFile (listID, szFileName); 

说明:ListWriteToFile函数将一个字符串列表写到一个文本文件。每个字符串显示在文本文件中分隔的行中。

参数:

listID

指定写到一个文本文件中的字符串名。

szFileName

指定要写字符串列表到其中的文件的全限定名。如果文件不存在,则被创建。如果文件已经存在,则它被修改。

返回值:

0:函数成功。

< 0:函数失败。

17  外壳函数

    外壳函数创建新的程序文件夹,删除存在的程序文件夹,添加项目到存在的程序文件夹。在安装的最后,添加应用程序到适当的程序文件夹以允许用户立即访问你的软件。下列函数也支持不同的图标选项。

s AddFolderIcon

添加一个图标到一个文件夹。

s CreateProgramFolder

创建一个程序文件夹。

s CreateShellObjects

创建在资源窗格的外壳对象文件夹中指定文件夹和快捷方式(或组和图标)。

s DeleteFolderIcon

从一个程序文件夹中删除一个图标或项目。

s DeleteProgramFolder

从目标系统中删除一个程序文件夹。

s GetFolderNameList

检索指定文件夹中的所有子文件夹名和快捷方式。

s ProgDefGroupType

在Windows NT环境中将组标识为公用或专用。

s QueryProgItem

返回有关一个指定的程序项目或子文件夹的信息。

s QueryShellMgr

返回当前外壳管理程序的名称。

s ReplaceFolderIcon

置换一个指定文件夹中的一个图标。

s SelectFolder

呈现一个对话框,允许最终用户从一个程序文件夹列表中选择一个文件夹。

s ShowProgramFolder

显示指定的程序文件夹。

17.1  AddFolderIcon 

语法:AddFolderIcon (szProgramFolder, szItemName, szCommandLine, szWorkingDir, 

   szIconPath, nIcon, szShortCutKey, nFlag); 

说明:AddFolderIcon函数插入或置换由szProgramFolder指定的程序文件夹中的一个图标。如果程序文件夹不存在,AddFolderIcon创建它。SzProgramFolder可以在一个多级级联式菜单中指定一个子文件夹。如果子文件夹不存在,AddFolderIcon将创建该子文件夹,并且在必要时创建它的父文件夹。

    当添加图标到Windows NT下的组时,首先调用ProgDefGroupType来确定组为公用还是专用。缺省时,文件夹图标添加为公用。

参数:

szProgramFolder

指定将图标添加至的文件夹的名称。如果该文件夹不存在,InstallShield创建它。

为添加图标到具体的文件夹,指定全限定路径,如:

"C:\\WINDOWS\\STARTMENU\\PROGRAMS\\ACCESSORIES\\GAMES".

为添加一个快捷方式图标到Windows 95及更高版本的开始程序菜单,给该参数传递一个空字符串(“”)。

注意你也可以在该参数位置传递下列InstallShield系统变量之一:

FOLDER_DESKTOP:将图标添加到桌面文件夹。

FOLDER_STARTUP:将图标添加到启动菜单文件夹。

FOLDER_STARTMENU:将图标添加到开始菜单文件夹。

FOLDER_PROGRAMS:将图标添加到开始菜单\程序文件夹。

你也可以指定一个相对于一个由InstallShield系统变量标识的文件夹的路径,例如,

FOLDER_PROGRAMS ^ "ACCESSORIES\\GAMES"

指定要添加到文件夹的图标名。该名将显示在图标下面。在Windows 95及更高版本下,调用AddFolderIcon添加一个图标到一个程序文件夹时,也在由szCommandLine指定的链接目录中创建一个链接文件。注意开发人员外壳不允许在项目名中有下列字符:/, \, :, ?, <, >, 或 |。

szCommandLine

指定下列情况之一:

s 和图标相联系的可执行文件的全限定名,包括任何命令行参数。为添加一个快捷方式图标到Windows 95及更高版本的开始程序菜单,输入一个链接目录的全限定路径,在那儿你的应用程序存放了它的图标链接文件。

s 全限定路径,如果szItemName是一个子文件夹 。(仅对Windows 95及更高版本、Windows NT 4.0)。

如果命令行包含一个长文件名,它必须由引号包围(括起)。更多信息请查看下面的注解部分。

szWorkingDir

指定应用程序文件所在的目录。(如果szItemName是一个子文件夹则不适用)。为使得包含程序文件的目录为工作目录,给该参数传递一个空字符串(“”)。不要调用LongPathToQuote来把该路径包围(括)在引号中。更多信息请查看下面的注解部分。

szIconPath

定要显示的图标的全限定文件名。(如果szItemName是一个子文件夹则不适用)。不要调用LongPathToQuote来把该路径包围(括)在引号中。更多信息请查看下面的注解部分。

nIcon

指定Windows中由szIconPath指定的可执行文件的的图标序号。(如果szItemName是一个子文件夹则不适用)。图标序号数从0开始,因此为显示可执行文件的第一个图标,指定0;为显示第二个,指定1,如此继续。如果你不使用一个Windows图标,给该参数指定0

szShortCutKey

指定快捷键(以字符串形式),允许最终用户迅速启动应用程序。例如,如果你想要能通过按下”Ctrl”,”Alt”然后”1”键来打开应用程序,则给该参数传递”Ctrl+Alt+1”。 如果szItemName是一个子文件夹则不适用)。

nFlag

指定图标表现形式。在该参数位置传递下列预定义常量之一或多个。为给该参数传递两个或更多预定义常量,用按位或操作符(|)将那些常量进行组合:

REPLACE:表明文件夹中的当前图标或项目被置换。

RUN_MAXIMIZED:表明程序被装入时必须被最大化。

RUN_MINIMIZED:表明程序被装入时必须被最小化。

NULL:表明没有选项。

返回值:

0:表明函数成功添加或置换指定文件夹中的图标并使可执行文件和图标相关联。

< 0:表明函数没有能添加或置换指定文件夹中的图标并使可执行文件和图标相关联。

注解:

·如果到你的应用程序可执行文件的路径包含长路径名,你必须把该全限定文件名用单引号或双引号括起来。(如果文件名已经被赋给一个变量,传递该变量给LongPathToQuote来插入引号。)注意命令行参数必须不被引号包围。因此,建议从两个分隔的字符串来建立一个szCommandLine字符串。

·不要调用LongPathToQuote来得到作为参数szWorkingDir 和 szIconPath的表达式。InstallShield自动将这些路径括在引号中。

17.2  CreateProgramFolder

语法:CreateProgramFolder (szFolderName);

说明:CreateProgramFolder函数在目标系统创建一个新文件夹。如果该文件夹已经存在,它被高亮显示。在Windows 95及更高版本,给文件夹被创建在开始程序菜单中。当在Windows NT下创建程序组时,首先调用ProgDefGroupType来确定组为公用还是专用。缺省设置为公用。

参数:

szFolderName

指定要添加到目标系统的文件夹名。

返回值:

0:表明函数成功添加文件夹到目标系统或该文件夹已经存在。

< 0:表明该函数没有能添加指定的程序文件夹。

17.3  CreateShellObjects

语法:CreateShellObjects (szReserved);

说明:CreateShellObjects函数创建已经在当前媒体上被指定的外壳对象(文件夹或快捷方式或组和图标)。当前媒体名被保存在系统变量MEDIA中。外壳对象在资源窗格的外壳对象文件夹中被定义。如果你使用一个基于事件的脚本,任何与一个或多个文件组(使用该外壳对象的文件组属性)相联系的外壳对象在那些文件组被装入时被自动创建。

注意:CreateShellObjects不会在目标系统上创建一个空文件夹(或组)。如果资源窗格中的一个文件夹或组是空的,它将不会由安装程序创建。同样,如果为资源窗格中的一个文件夹指定的快捷方式在运行时没有被创建(因为它们相联系的文件组没有被装入),那么该文件夹不被创建。为创建一个空文件夹(或组),在你的脚本中调用CreateProgramFolder。

参数:

szReserved

给该参数传递一个空字符串(“”)。不允许其它值。

返回值:

0:表明函数成功。

-1:未知错误。

-2:在当前媒体上,调用ComponentTransferData函数前调用该函数。注意,在一个运行基于事件的脚本的安装中,ComponentTransferData被自动调用。

-3:文本替换失败。

-4:创建快捷方式失败。

-5:创建文件夹失败。

-6:创建一个Internet快捷方式失败。

注解:

·安装初始化过程中,系统变量MEDIA的值被设置为‘DATA’。如果你修改该变量的值来指向一个脚本创建组件集,则你在调用CreateShellObjects前必须该值修改回‘DATA’。

This function should be called only after ComponentTransferData has been called. 

该函数只有在已经调用ComponentTransferData后才能被调用。

17.4  DeleteFolderIcon

语法:DeleteFolderIcon (szProgramFolder, szItemName);

说明:DeleteFolderIcon函数从一个文件夹删除一个程序图标。

参数:

szProgramFolder

指定包含要删除图标的文件夹名。

szItemName

指定要被删除的图标名。

返回值:

0:表明函数成功删除指定图标。

< 0:表明函数没有能删除指定图标。

17.5  DeleteProgramFolder

语法:DeleteProgramFolder (szFolderName);

说明:DeleteProgramFolder函数删除一个程序文件夹和它的内容,包括所有位于指定文件夹下的文件夹。它不能删除“程序”文件夹。

参数:

szFolderName

指定要删除的文件夹名。

返回值:

0:表明函数成功删除指定文件夹。

< 0:表明函数没有能删除指定文件夹。

17.6  GetFolderNameList

语法:GetFolderNameList (szFolderName, listItemsID, listSubFoldersID);

说明:GetFolderNameList函数被使用来列举一个指定文件夹的所有程序项快捷方式和子文件夹。该函数也可以被用来列举一个根文件夹的所有程序项快捷方式和子文件夹。

参数:

szFolderName

指定被查询的文件夹名。你可以给szFolderName指定一个全限定路径,如:"C:\\Windows\\Start Menu\\Programs\\Accessories\\Games"。如果szFolderName是空,GetFolderNameList查找缺省程序目录(看下面)。如果你不给szFolderName指定一个绝对路径,GetFolderNameList在缺省程序目录下查找一个子文件夹,按照操作系统:

s Windows 95及更高版本:开始菜单\程序文件夹位于Windows文件夹下。注意即使用户配置文件被激活,该定位不会改变。

s Windows NT 4.0(如果由ProgDefGroupType选定为公用):..\profiles\All Users\Start Menu\Programs文件夹位于Windows文件夹下。

s Windows NT 4.0(如果由ProgDefGroupType选定为专用):. .\profiles\<user name>\Start Menu\Programs位于Windows文件夹下;<user name>是当前用户的用户名。

s 你也可以使用一个InstallShield系统变量:

FOLDER_DESKTOP:查找桌面文件夹。

FOLDER_STARTUP:查找启动菜单文件夹。

FOLDER_STARTMENU:查找开始菜单文件夹。

FOLDER_PROGRAMS:查找开始菜单\程序文件夹。

或你可以使用一个相对路径,如:

FOLDER_PROGRAMS ^ "ACCESSORIES\\GAMES"

listItemsID

在szFolderName返回一个程序项快捷方式名的列表。注意在Windows NT,如果szFolderName包含专用和公用程序项,在该参数返回的列表将包含公用或专用程序项快捷方式,但不是都包含。由listItemsID标识的列表必须已经通过调用ListCreat被初始化。

listSubFoldersID

在szFolderName返回子文件夹名的列表。注意在Windows NT,如果szFolderName包含专用和公用程序项,在该参数返回的列表将包含公用或专用程序项快捷方式,但不是都包含。由listSubFoldersID标识的列表必须已经通过调用ListCreat被初始化。

返回值:

0:GetFolderNameList成功检索所有程序项和子文件夹名。

< 0:GetFolderNameList没有能检索所有程序项和子文件夹名。

注解:

·当该函数被使用在一个运行于Windows NT 4.0下的安装中,应用下列约束条件:

如果你列举一个具体的程序文件夹(也就是,你已经指定到达文件夹的路径),该文件夹必须与当前文件夹类型匹配,公用或专用。如果该文件夹和当前文件夹类型不匹配,它将不会被定位并且函数失败。为改变缺省文件夹类型,调用ProgDefGroupType。

·如果你列举一个支持专用和公用项目和文件夹的文件夹,如FOLDER_PROGRAMS,只有那些适当类型的程序项快捷方式和文件夹将由该函数返回。为改变缺省文件夹类型,调用ProgDefGroupType。

17.7  ProgDefGroupType

语法:ProgDefGroupType (nType);

说明:ProgDefGroupType函数将指定一个程序组在Windows NT下为专用或公用。在你调用AddFolderIcon 或 CreateProgramFolder前调用该函数。缺省程序组类型是公用。

  该函数仅使用在Windows NT环境中。它在其它环境中被忽略。

参数:

nType

指定一个程序组类型。在该参数位置传递下列预定义常量之一:

PERSONAL:指定一个专用程序组。

COMMON:指定一个公用程序组。

返回值:

0:函数通常返回0

注解:

·如果一个运行在Windows NT下的安装中调用SdSelectFolder前调用了ProgDefGroupType,SdSelectFolder将根据传递给ProgDefGroupType的参数显示程序文件夹(公用或专用)。

17.8  QueryProgItem

语法:QueryProgItem (szFolderName, szItemName, svCmdLine, svWrkDir, svIconPath,

nvIconIndex, svShortCutKey, nvMinimizeFlag);

说明:QueryProgItem函数检验一个指定程序项或子文件夹名是否存在。如果InstallShield找到该项目或子文件夹,QueryProgItem返回它的属性。属性包括应用程序的命令行,工作目录,图标路径,快捷键和最小化标志。

    为使用QueryProgItem,在参数szFolderName 和szItemName位置输入信息。InstallShield将用程序项的属性来填充剩余的参数。

当在Windows NT下查询组或文件夹时,首先调用ProgDefGroupType来确定组为公用还是专用。缺省设置为公用。

参数:

szFolderName

指定包含该项目或子文件夹的文件夹名。你可以给szFolderName指定一个全限定路径,如:

"C:\\WINDOWS\\START MENU\\PROGRAMS\\ACCESSORIES\\GAMES"

如果szFolderName是空,QueryProgItem查找缺省程序目录(看下面)。如果你不给szFolderName指定一个绝对路径,QueryProgItem在缺省程序目录下查找一个子文件夹,按照操作系统:

s Windows 95及更高版本:环境变量Windir下的开始菜单\程序。

s Windows NT 4.0(如果由ProgDefGroupType选定为公用):环境变量Windir下的..\profiles\All Users\Start Menu\Programs目录。

s Windows NT 4.0(如果由ProgDefGroupType选定为专用):环境变量Windir下的. .\profiles\<user name>\Start Menu\Programs目录;<user name>是从系统变量USERPROFILE得的当前用户的用户名。

s 你也可以使用一个InstallShield系统变量:

FOLDER_DESKTOP:在桌面文件夹中查询项目。

FOLDER_STARTUP:在启动菜单文件夹中查询项目。

FOLDER_STARTMENU:在开始菜单文件夹中查询项目。

FOLDER_PROGRAMS:在开始菜单\程序文件夹中查询项目。或者你可以使用一个相对路径,例如:

FOLDER_PROGRAMS ^ "ACCESSORIES\\GAMES"

szItemName

指定要找的程序项或子文件夹名。

svCmdLine

返回项目的可执行文件的命令行或子文件夹的完全路径。

svWrkDir

返回程序项工作目录的全路径。(如果szItemName是一个子文件夹则不适用。)

svIconPath

返回.ico文件或.exe文件的全限定文件名。(如果szItemName是一个子文件夹则不适用。)

nvIconIndex

返回作为程序项图标的索引。(如果szItemName是一个子文件夹则不适用。)

svShortCutKey

返回项目的快捷键。(如果szItemName是一个子文件夹则不适用。)

nvMinimizeFlag

(如果szItemName是一个子文件夹则不适用。)返回下列常量之一,指示第一次显示时一个应用程序窗口是否被最小化:

NULL:表明应用程序窗口启动时不被最小化。

RUN_MINIMIZED:表明应用程序窗口启动时被最小化。

返回值:

IS_ITEM (0):表明szItemName是szFolderName的一个程序项或快捷方式。

IS_FOLDER (1):表明szItemName是szFolderName的一个子文件夹。

< 0:表明该函数不能找到程序项或子文件夹名。

注解:

·不同语言下开始菜单位置不同。不管如何,InstallShield能自动选择正确路径。

17.9  QueryShellMgr

语法:QueryShellMgr (svShellMgrName);

说明:QueryShellMgr函数得到Microsoft Windows使用的程序外壳名。如,如果程序外壳是Explorer,则QueryShellMgr在参数svShellMgrName返回字符串"Explorer.exe"。

    如果目标系统的外壳不是Explorer,你可能需要用LaunchApp函数来装入该外壳。创建程序文件夹和程序图标的InstallShield函数与外壳使用一个DDE会话来创建程序文件夹和程序项。大多数可选外壳如Norton Desktop仿真Explorer外壳。因此,它们可以创建程序文件夹和项目。

    在不仿真Explorer外壳的外壳中,InstallShield不能使用程序文件夹和程序项函数来创建或修改程序文件夹和程序项。

参数:

svShellMgrName

返回当前运行的外壳管理程序的非限定名(也就是,没有驱动器标识或路径)。

返回值:

0:表明函数成功检索程序外壳名。

< 0:表明函数没有能检索程序外壳名。

17.10  ReplaceFolderIcon

语法:ReplaceFolderIcon (szProgramFolder, szItemName, szNewItem, szCmdLine, 

  szWorkingDir, szIconPath, nIcon, szShortCutKey, nFlag);

说明:ReplaceFolderIcon函数置换一个指定文件夹中的一个图标。你必须指定一个存在的文件夹,可以是一个你用CreateProgramFolder函数创建也可以是一个已经存在于用户系统上的。

参数:

szProgramFolder

指定包含要被置换的图标的文件夹名。

szItemName

指定要置换的图标名。

szNewItem

指定置换后要显示的图标名。

szCmdLine

指定下列之一:

s 和图标相联系的可执行文件的全限定名,包括任何命令行参数。

s 如果szItemName是一个子文件夹,则是全限定路径。

szWorkingDir

指定应用程序文件所在的目录。(如果szItemName是一个子文件夹则不适用)。为是包含程序文件的目录为工作目录,给该参数传递一个空字符串(“”)。

szIconPath

指定包含该新图标的一个图标文件名或一个有效的Windows可执行文件。

nIcon

如果你指定一个Windows 可执行图标,则指定该图标序号。否则,给该参数传递0

szShortCutKey

指定包含快捷键序列的字符串,用户可以按下它们来启动应用程序。例如,如果你想要能通过按下”Ctrl”,”Alt”然后”1”键来打开应用程序,则给该参数传递”Ctrl+Alt+1”。 如果szItemName是一个子文件夹则不适用)。

nFlag

指定一个或多个选项。在该参数位置传递下列预定义常量。为给该参数传递多个选项,用按位或操作符(|)将那些常量进行组合:

NULL:表明没有选项。

REPLACE:表明存在的图标要被新图标置换。

RUN_MAXIMIZED:表明程序被装入时要最大化。

RUN_MINIMIZED:表明程序被装入时要最小化。

返回值:

0:表明成功置换图标。

< 0:表明函数没有能置换图标。

17.11  SelectFolder

语法:SelectFolder (szTitle, szDefFolder, svResultFolder);

说明:SelectFolder函数显示一个对话框,允许最终用户在一个编辑区输入一个程序文件夹名或从一个列表中选择一个程序文件夹。该函数自动显示系统中的所有程序文件夹。一个传递给svDefFolder的缺省的文件夹名被显示在编辑区。被选定的文件夹名在svResultFolder返回。如果指定文件夹不存在,它不会被创建。

参数:

szTitle

指定对话框标题。为显示缺省标题(“选择程序文件夹”),给该参数传递一个空字符串(“”)。

szDefFolder

指定要显示为缺省文件夹的文件夹名。

svResultFolder

返回有最终用户选定或指定的文件夹名。如果该文件夹不存在,你必须调用CreateProgramFolder来创建它;SelectFolder不会创建该文件夹。

返回值:

NEXT (1):表明最终用户选定Next按钮。

BACK (12):表明最终用户选定Back按钮。

< 0:表明函数成功。

17.12  ShowProgramFolder

语法:ShowProgramFolder (szFolder, nCommand);

说明:ShowProgramFolder函数显示一个程序文件夹。

参数:

szFolder

指定要显示的文件夹名。

nCommand

指定文件夹状态。在该参数位置传递下列预定义常量之一:

SW_SHOW:以标准状态显示文件夹。

SW_MAXIMIZE:最大化文件夹。

SW_MINIMIZE:最小化文件夹。

SW_RESTORE:将文件夹还原到原始大小。

返回值:

该函数没有返回值。

18  扩展函数

  扩展函数允许你调用动态链接库中的函数,调用Windows APIs,或运行另一个应用程序或安装程序脚本。UseDLL 和 UnUseDLL函数允许你装入一个DLL到内存中或卸载它并使用DLLLaunchApp 和 LaunchAppAndWait函数允许你仍在执行脚本时运行另一个Windows 或DOS应用程序。

s CallDLLFx

从一个外部DLL中调用函数。

s Delay

延迟安装程序脚本的执行。

s LaunchApp

运行另一个程序。

s LaunchAppAndWait

运行另一个程序并等待该程序终止。

s UnUseDLL

从内存卸载一个DLL

s UseDLL

把一个DLL装入到内存。

18.1  CallDLLFx

语法:CallDLLFx (szDLL, szFunction, lvValue, svValue);

说明:CallDLLFx函数调用一个指定的DLL中的函数。该函数必须使用下列固定定义,hwnd是InstallShield主窗口的主窗口句柄:

LONG APIENTRY YourFunction (HWND hwnd, LPLONG lpIValue, LPSTR lpszValue);

参数:

szDLL

指定包含要执行的函数的DLL的全限定文件名。

szFunction

指定由szDLL指定的DLL中的函数的名称。

IvValue

指定访问一个DLL函数时传递的长整型变量。

svValue

指定传递给DLL函数的字符串变量。

返回值:

CallDLLFx函数从DLL中的函数返回一个长整型数。

18.2  Delay

语法:Delay (nSeconds);

说明:Delay函数使一个安装程序脚本的执行延迟一个指定的秒数。其它和InstallShield同时运行的任务在InstallShield被延迟时仍正常进行。

参数:

nSeconds

指定程序被延迟的秒数。

返回值:

0:表明函数成功延迟了脚本的执行。

< 0:表明函数未能延迟了脚本的执行。

18.3  LaunchApp

语法:LaunchApp (szCommand, szCmdLine);

说明:LaunchApp函数允许你在脚本内运行另一个应用程序。该应用程序和脚本同时运行。InstallShield对运行的应用程序没有控制权并且不能确定运行的应用程序是否成功运行。运行的应用程序和其它在运行InstallShield时你启动的应用程序一样运行。你可以在InstallShield中运行任何你可以在操作系统中正常运行的应用程序。

参数:

szCommand

指定要运行的应用程序的全限定名。如果你指定一个没有路径的文件名,InstallShield在当前文件夹中,Windows 文件夹中,Windows系统文件夹中和列在环境变量PATH中的文件夹中查找。

如果应用程序的全限定名包括长文件夹名和/或一个长文件名,在把szCommand传递给LaunchAppAndWait之前先把它传递给LongPathToQuote。

szCmdLine

指定传递给szCommand标识的应用程序的命令行参数(如果有)。如果没有参数,则迟到一个空字符串。

返回值:

0:LaunchApp成功运行应用程序。

< 0:LaunchApp未能找到或未能运行应用程序。

注解:

·安装进程在应用程序被运行后继续。应用程序即使在安装脚本终止后仍可以运行。

·你也可以使用FindWindow 和 SendMessage函数来控制或发送消息给运行的应用程序。如果你想要在一个Window中运行一个DOS应用程序,你可以提供一个和DOS应用程序同名的PIFProgram Information File)。在PIF文件中,你指定应用程序运行在其下的一个窗口方式。

·运行一个DOS程序时,你不能确定返回结果DOS_ERRORLEVEL。然而你可以把一个DOS应用程序放进一个批处理文件,让批处理文件来识别错误并创建另一个包含返回错误代码的文件。然后你可以读该文件并确定从DOS应用程序返回的错误代码。

·LaunchApp 使用Windows API 的CreateProcess 来运行应用程序。

18.4  LaunchAppAndWait

语法:LaunchAppAndWait (szProgram, szCmdLine, lWait);

说明:LaunchAppAndWait函数运行由szProgram指定的带有szCmdLine指定的命令行参数的应用程序。第三个参数,lWait指示安装在继续前是否要等待直到运行的应用程序终止。

  一个安装程序只能监控由szProgram指定的应用程序;如果该应用程序要运行其它应用程序或进程,安装程序不能监控它们。因此,安装程序将在第一个应用程序结束后继续,即使那时由第一个应用程序运行的其它应用程序仍在运行。注意如果运行的应用程序终止失败,则安装程序将无限等待运行的应用程序完成。

参数:

szProgram

指定要被运行的应用程序的文件名。建议要指定应用程序的完整路径和文件名。如果你不包括一个路径,InstallShield将使用被Windows API 函数CreateProcess使用的相同的查找次序来定位文件。如果文件未能在这些位置找到,函数将失败。

  如果应用程序的全限定名包括长文件夹名和/或一个长文件名,在把szCommand传递给LaunchAppAndWait之前先把它传递给LongPathToQuote。

szCmdLine

指定传递给运行的应用程序的命令行参数。为运行没有命令行参数的应用程序,传递一个空字符串。

lWait

指定安装程序在继续前是否要等待运行的应用程序终止。在该参数位置传递下列预定义常量之一:

NOWAIT:指定安装程序在运行应用程序后立即继续,应用程序将和安装程序脚本同时运行。注意使用该参数等效于调用函数LaunchApp。

WAIT:指定安装程序必须等待直到由该函数运行的应用程序终止。

返回值:

1:表明应用程序成功运行。

< 0:表明应用程序未能运行。

注解:

·InstallShield 安装程序使用函数CreateProcess。在InstallShield运行应用程序后,它查找装入的应用程序的窗口句柄。如果它找到窗口句柄,则它在继续前等待直到应用程序窗口消失。

·安装程序不能监控一个不创建窗口的应用程序。如果指定的应用程序没有创建一个窗口,安装程序在运行应用程序后立即继续。注意应用程序的窗口不需要可见,但它必须存在,以便让安装程序等待。

·一些应用程序试图装入DLLs并且当那些DLLs不能被定位时不能正确运行。为确保一个应用程序能找到它需要的DLLs,有必要在调用LaunchAppAndWait前改变到包含可执行应用程序的目录。为改变当前目录,调用ChangeDirectory函数。

·如果运行的应用程序终止失败,则安装程序将无限等待运行的应用程序完成。

·LaunchAppAndWait以一个全屏DOS窗口来运行DOS程序。为以一个不同类型的窗口来运行一个DOS程序,你必须直接调用Windows APIs。

18.5  UnUseDLL

语法:UnUseDLL (szDLLName);

说明:UnUseDLL函数从内存卸载一个DLLUnUseDLL将该DLL的锁计数减少一。当锁计数等于0时,InstallShield 卸载该 DLL。每一个对UseDLL的调用都必须有一个对应的对UnUseDLL的调用,因而DLLs在它们不再需要时不会留在内存中而浪费系统资源。一旦你卸载了一个DLL,你不能再调用该DLL中的函数。

    Microsoft Windows系统 DLLs, 如 User.exe, User32.dll, Gdi.exe, Gdi32.dll, Krnl386.exe, Krnl286.exe, 和 Kernel32.dll,自动由Windows 装入和卸载。不要调用UseDLL 和UnUseDLL 来装入和卸载这些DLLs。

参数:

szDLLName

指定DLL的文件名。该参数不要包含路径。

返回值:

0:表明函数成功解锁和从内存卸载DLL

< 0:表明函数未能解锁和卸载DLL

注解:

如果脚本在用UnUseDLL正确卸载DLL前退出或终止,DLL将被锁定在内存。如果你试图再次访问DLL,你的脚本可能失败。你必须通过重启Windows来将DLL从内存中删除。

18.6  UseDLL

语法:UseDLL (szDLLName);

说明:UseDLL函数把一个DLL装入内存。在DLL已经被装入内存后,你的安装程序脚本可以调用该DLL中的函数。注意如果由szDLLName指定的DLL需要其它DLL,那些DLL必须位于某个文件夹中,该DLL试图从这个文件夹装入它们。正常时它是当前目录。为确保那些DLL可以被定位,在调用UseDLL前调用ChangeDirectory来改变当前目录到那些DLL所处的位置。若不能做到这些,则可能DLL不能被正确装入。

  每次你将一个DLL装入到内存,该DLL的锁计数增加。锁计数计算使用该DLL的应用程序的数目。你不再使用DLL时,你必须马上调用UnUseDLL来卸载它。如果你不卸载不再需要的DLL,则该DLL在没有应用程序需要它时仍会留在内存中,因而浪费系统资源。在脚本中每个对UseDLL的调用必须有一个相对应的UnUseDLL调用。

  Microsoft Windows系统 DLLs, 如 User.exe, User32.dll, Gdi.exe, Gdi32.dll, Krnl386.exe, Krnl286.exe, 和 Kernel32.dll,自动由Windows 装入和卸载。不要调用UseDLL 和UnUseDLL 来装入和卸载这些DLLs。

参数:

szDLLName

指定要装入的DLL名。如果你未指定一个扩展名,InstallShield假定文件扩展名为.dll 或.exe。建议该参数包括一个路径,但只是可选。如果该参数没有指定DLL的路径,InstallShield将使用和Windows API 函数LoadLibrary使用的相同的查找次序来查找DLL

有关查找次序的更多信息可查看Windows API函数的说明。

    为在你的安装中包含DLL,把它添加到安装文件窗格中的Language Independent文件夹的合适的子文件夹中。InstallShield将把它压缩到你的安装中。当Setup.exe执行时,它自动解压缩并把你的安装的内容拷贝到由SUPPORTDIR指定的临时目录中。然后你可以添加DLL文件名到SUPPROTDIR以便指向该DLL,如下所示:

    szDLLName = SUPPORTDIR^"MYDLL.DLL";

    UseDLL (szDLLName);

    如果你不放置你的DLL到你的安装中(通过把它插入到安装文件窗格中的合适文件夹中),你可以把文件和你的应用程序文件一起分散,然后从目标系统装入它。然而,如果你这么做,你必须指定你把DLL安装到的位置使得你的安装程序可以指向它。你也必须确保你的安装程序不会试图在DLL被传输到目标系统之前装入它。

返回值:

0:表明函数成功地把DLL装入内存。

< 0:表明函数未能把DLL装入内存。

注解:

·如果UseDLL失败,最大的可能性是DLL没有找到。如果这样,确保参数szDLLName指定了正确的路径。

·另一个通常的使用DLL的错误原因和DLL的依赖性有关:被你装入的DLL所访问的DLLs。如果你的DLL 访问的DLLs没有被装入或没有找到,你的DLL调用可能失败。如果发生这种情况,确保其它DLL存在于系统上并且它们是可访问的。

·如果脚本在用UnUseDLL正确卸载DLL前退出或终止,DLL将被锁定在内存。如果你试图再次访问DLL,脚本可能失败。你必须通过重启Windows来将DLL从内存中删除。

19  批处理函数

19.1  高级批处理文件函数

    高级批处理文件函数和Ez批处理文件函数不同,它们提供更大的灵活性和对批处理文件的更多控制。当需要对一个批处理文件做更多扩充和更复杂的修改,则使用这些函数。

    为用这些高级函数来编辑一个批处理文件,你必须首先通过调用BatchFileLoad把该文件装入到内存。当完成了对该批处理文件的修改,然后必须调用BatchFileSave保存该文件。

    安装初始化时,它选择目标系统的启动批处理文件(Autoexec.bat)作为缺省批处理文件(除非通过调用BatchSetFileName来修改),如果没有指定其它文件名,该文件就是由BatchFileLoad读入内存的文件。为确定缺省批处理文件的全限定名,调用BatchGetFileName。

    不要把Ez配置文件函数和高级配置文件函数混合起来。调用BatchFileLoad之后,直到你调用了BatchFileSave保存你的修改后,你才能使用Ez配置文件函数。

s BatchAdd

添加一个环境变量到一个批处理文件。

s BatchDeleteEx

删除批处理文件中的一行。

s BatchFileLoad

把一个批处理文件装入内存来用高级批处理函数编辑它。

s BatchFileSave

保存一个由BatchFileLoad装入的批处理文件。

s BatchFind

在一个批处理文件中查找项目。

s BatchGetFileName

检索缺省批处理文件的全限定名。

s BatchMoveEx

移动一个批处理文件中的一个项目。

s BatchSetFileName

指定作为缺省批处理文件的一个批处理文件。

相关函数:

s SdShowFileMods

19.1.1  BatchAdd

语法:BatchAdd (szKey, szValue, szRefKey, nOptions);

说明:BatchAdd函数插入一个SET命令或其它DOS命令到一个已经由BatchFileLoad装入内存的批处理文件中。参数nOptions使你可以将新命令添加到文件的第一个或最后一个语句,用新命令取代一个现存语句,或指定将新命令添加到一个现存语句的前面或后面。

    除非你将常量COMMAND和你传递给nOptions的值用或操作符连接,否则BatchAdd自动在你要插入的语句的开始添加DOS关键字SET。如果你没有在nOptions显式指定REPLACE,那么即使在批处理文件中存在重复行,指定的语句也会被添加。

调用BatchAdd前,你必须调用BatchFileLoad来把要修改的文件装入内存。在你修改该文件后,调用BatchFileSave来把它保存到磁盘。

参数:

szKey

指定要添加到批处理文件中的关键字。PATH、 TEMP和 MYENV是该参数有效值的例子。

szValue

指定要添加到该批处理文件中的关键字的值。该字符串必须不长于512个字节;传递一个长于512字节的字符串将会引起一个安装错误。为添加一个更长的字符串,使用FileGrep 和 FileInsertLine函数。

批处理文件完全不支持长路径名。如果你使用该函数来添加包含长路径名的一行,则必需先调用LongPathToShortPath把长路径名转换成它等价的短路径,然后再能把它插入到要添加至批处理文件的字符串中。

szRefKey

指定在批处理文件中与你添加的szKey相关的参考项。

nOptions

指定该行被插入到文件何处。在该参数位置传递下列预定义常量之一:

BEFORE:该语句被添加到包含szRefKey的第一行的前面。如果szRefKey是一个空字符串(“”),该语句被添加到文件首行。

AFTER:该语句被添加到包含szRefKey的最后一行的后面。如果szRefKey是一个空字符串(“”),该语句被添加到文件末行。

REPLACE:该语句将置换文件中已存在的一行。如果存在多行有相同的字,仅最后一行被置换。如果szKey不存在于文件中,新行添加到szRefKey之后。如果szRefKey是一个空字符串(“”),该语句被添加到文件末行。

    当被添加的语句不是一个SET命令,给szKey传递一个空字符串,给szValue传递完整命令,并将常量COMMAND和其它选项之一用或操作符(|)连接,如下所示:

   BatchAdd("", "PAUSE", "", COMMAND | AFTER);

返回值:

0:BatchAdd成功添加一个SET语句或其它命令到批处理文件。

< 0:BatchAdd未能添加一个SET语句或其它命令到批处理文件。

注解:

·一个InstallShield参考项可以是一个环境变量,DOS命令或一个程序文件名。环境变量是关键字,如PATH, COMSPEC, LIB或其它预定义或用户定义的标识符。一个环境变量的值使用DOS SET命令来设置。显示在一个批处理文件中的语句必须是DOS命令,程序名(有或没有命令行参数)或注解。有关命令和环境变量的详细定义请参阅操作系统手册。

19.1.2  BatchDeleteEx

语法:BatchDeleteEx (szKey, nOptions);

说明:BatchDeleteEx函数删除一个批处理文件中包含szKey指定的值的行。调用BatchDeleteEx前,你必须调用BatchFileLoad来把要修改的文件装入内存。在你修改该文件后,调用BatchFileSave来把它保存到磁盘。

参数:

szKey

指定标识要被删除的行的参考关键字。

nOptions

表明szKey是指定一个SET语句中的一个环境变量还是一个命令。在该参数位置传递下列预定义常量之一:

0:指定szKey是一个SET语句中的一个环境变量。一个环境变量是一个预定义的标识符(如PATH, COMSPEC和 LIB),或一个用户定义的标识符。例如,如果szKey的值是"LIBPATH"并且nOptions设置为0,则下面语句将被删除:

SET LIBPATH=C:\Lang\Lib

COMMAND:指定szKey是一个DOS命令或一个程序文件名。

返回值:

0:BatchDeleteEx成功删除包含指定值的行。

< 0:BatchDeleteEx未能删除包含指定值的行。

19.1.3  BatchFileLoad

语法:BatchFileLoad (szBatchFile);

说明:BatchFileLoad函数将指定批处理文件的一份拷贝装入内存以便其它高级批处理文件函数可以被调用来操作该文件。在szBatchFile指定你要编辑的批处理文件名或给szBatchFile传递一个空字符串来编辑缺省批处理文件,它由InstallShield初始化设置为由系统使用的Autoexec.bat。

    注意你可以调用BatchFileLoad来创建一个新批处理文件。为了这么做,你可以给szBatchFile传递一个不存在的文件名。然后调用其它批处理函数来编辑新文件。最后,调用BatchFileSave将新文件保存到磁盘。

使用任何高级批处理文件函数之前,你必须首先调用BatchFileLoad将要修改的文件装入到内存。在你修改文件后,调用BatchFileSave将它保存到磁盘。为得到将安装脚本中使用的缺省批处理文件的全限定名,调用BatchGetFileName。为指定另一个在安装脚本中使用的缺省批处理文件,调用BatchSetFileName。

参数:

szBatchFile

指定装入内存的批处理文件的全限定名。为装入缺省批处理文件,给该参数传递一个空字符串(“”)。如果你在该参数指定一个文件,该文件成为缺省批处理文件。调用该函数后,你可以使用所有高级批处理文件函数来操作该文件。

返回值:

0:BatchFileLoad成功将指定批处理文件装入内存。

< 0:BatchFileLoad未能将指定批处理文件装入内存。

19.1.4  BatchFileSave

语法:BatchFileSave (szBackupFile);

说明:BatchFileSave函数将由BatchFileLoad函数装入内存的批处理文件保存到磁盘。文件保存为它的原始名。如果在szBackupFile指定一个文件名,在被编辑的文件被写到磁盘前原始文件用该文件名更名。如果szBackupFile包含一个空字符串(“”),原始文件被该修改的文件置换。如果你结束用高级批处理文件函数修改一个批处理文件时没有调用BatchFileSave,所有修改将被丢失。

参数:

szBackupFile

指定在编辑被保存前是否要有一个原始文件拷贝的备份。

如果无需创建备份文件,给该参数指定一个空字符串。

如果原始文件必须用一个特定名备份,给该参数传递该文件名。该文件名必须是非限定的(也就是,不限定一个驱动器和/或路径)。注意如果具有指定名称的文件已经存在, BatchFileSave将生成一个唯一的文件扩展名,如接下去布告牌项目中描述。

如果原始文件备份时必须带有一个安装生成文件的扩展名,指定通配符””作为文件扩展名(例如,”Batch.”)。然后安装将赋一个数值型值,从001开始,作为扩展名。如果一个有该扩展名的文件已经存在,扩展名值将增加1直到产生一个唯一的文件名。

一旦创建了备份,InstallShield保存备份文件名到系统变量INFOFILENAME

注意下列重要事实:1)如果上一次对BatchFileLoad的调用指定的批处理文件不存在,备份文件将和由调用BatchFileSave创建的批处理文件相同。2)如果szBakupFile指定原始批处理文件名,那么将不会创建一个备份文件。

返回值:

0:BatchFileSave成功保存内存中的批处理文件到磁盘。

< 0:BatchFileSave未能保存内存中的批处理文件到磁盘。

19.1.5  BatchFind

语法:BatchFind (szRefKey, svResult, nOptions);

说明:BatchFind函数在一个批处理文件中查找出现szRefKey指定的参考关键字的一处或多处。如果你在nOptions指定常量RESTART,返回参考关键字第一次出现之处。为找到出现szRefKey的下一处,将参数nOptions设置为CONTINUE重复调用该函数。

    调用BatchFind前,你必须调用BatchFileLoad来把要修改的文件装入内存。在你修改该文件后,调用BatchFileSave来把它保存到磁盘。

参数:

szRefKey

指定要查找的参考关键字。参考关键字可以是一个环境变量,一个DOS命令或一个程序名。如果参考关键字是一个文件名并且你没有指定一个文件扩展名,函数将返回所有有该基名的关键字。例如,如果你指定Win.com,查找仅对该参考关键字。如果你指定WINWin.exe文件,Win.dll文件,Win.sys文件等等如故存在于批处理文件中,则都将被返回。

svResult

指定在批处理文件中找到的关键字的值。

nOptions

指定从哪儿开始查找;在该参数位置传递下列预定义常量之一:

CONTINUE:从批处理文件当前位置开始查找。

RESTART:从批处理文件开始来开始查找。

当你查找的参考关键字是一个DOS命令或程序名(而不是一个环境变量),将常量COMMANDCONTINUERESTART用或操作符(|)连接,如下所示:

BatchFind ("SCAN.EXE", svResult, COMMAND | RESTART);

返回值:

0:BatchFind成功找到szRefKey的值并在szResult返回它。

< 0:BatchFind未能找到szRefKey的值并在szResult返回它。

19.1.6  BatchGetFileName

语法:BatchGetFileName (svFileName);

说明:BatchGetFileName函数检索缺省批处理文件(由InstallShield初始设置为系统启动时使用的自举Autoexe.bat文件)的全限定名。为指定一个不同的批处理文件为安装脚本中使用的缺省批处理文件,调用BatchSetFileName。

参数:

svFileName

在szFileName返回缺省批处理文件的全限定名。

返回值:

0:BatchGetFileName成功检索缺省批处理文件的全限定名。

< 0:BatchGetFileName未能检索缺省批处理文件的全限定名。

19.1.7  BatchMoveEx

语法:BatchMoveEx (szMove, szRefKey, nOptions, nMoveOption);

说明:BatchMoveEx函数将一个批处理文件中由szMove指定的行从一个位置移动至另一个位置。参数nOptions指定是把该行放置在批处理文件的开始或结尾,还是在szRefKey指定的行的前面或后面。调用BatchMoveEx前,你必须调用BatchFileLoad来把要修改的文件装入内存。在你修改该文件后,调用BatchFileSave来把它保存到磁盘。

参数:

szMove

指定标识要被移动行的参考关键字。

szRefKey

指定关键字,它标识用来定位移动行的参考行。如果szRefKey是一个空字符串,由szMove 指定的行移动到文件的开始或结尾,根据nOptions的值而定。

nOptions

指定将行移动到何处;给该参数传递下列预定义常量之一:

BEFORE:由szMove指定的行被移动到包含szRefKey参考关键字的行的前面。如果szRefKey是一个空字符串,则由szMove指定的行被移动到文件的开始。

AFTER:由szMove指定的行被移动到包含szRefKey参考关键字的行的后面。如果szRefKey是一个空字符串,则由szMove指定的行被移动到文件的结尾。

    当你查找的参考关键字是一个DOS命令或程序名(而不是一个环境变量),将常量COMMANDBEFORE 或AFTER用或操作符(|)连接,如下所示:

BatchMoveEx ("PATH", "SCAN.EXE", BEFORE | COMMAND, 0);

nMoveOption

指定szMove是一个命令还是一个环境变量。给该参数传递下列预定义常量之一:

0:指定szMove是一个环境变量。

COMMAND:指定szMove是一个命令。

返回值:

0:BatchMoveEx成功移动批处理文件中的指定行。

< 0:BatchMoveEx未能移动批处理文件中的指定行。

19.1.8  BatchSetFileName

语法:BatchSetFileName (szBatchFile);

说明:BatchSetFileName函数指定由Ez批处理文件函数及以一个空字符串为其参数调用BatchFileLoad时所使用的批处理文件名。在安装脚本中,该文件被作为缺省批处理文件。安装初始化过程中,缺省批处理文件被设置为系统使用的Autoexec.bat文件。

应重视下列有关BatchSetFileName的事实:

s 它不确认指定文件的存在性。

s 它不把文件装入内存。

参数:

szBatchFile

指定在安装脚本中作为缺省批处理文件使用的文件的全限定名。

返回值:

0:BatchSetFileName成功设置指定文件为缺省批处理文件。

< 0:BatchSetFileName未能设置指定文件为缺省批处理文件。

注解:

BatchSetFileName只简单地指定缺省批处理文件的名称。即使文件名是无效的或指定文件不存在时该函数也会成功。一个无效的文件名将导致随后的Ez批处理文件和高级批处理文件函数失败。

19.2  Ez批处理文件函数

Ez批处理文件函数修改缺省批处理文件。除非通过调用BatchSetFileName来修改,缺省批处理文件是Autoexec.bat。应注意的是每个Ez批处理文件函数打开缺省批处理文件然后在作修改后自动保存它。你使用Ez批处理文件函数时你不用调用函数来打开和保存。

    不要把Ez批处理文件函数和高级批处理文件函数混合起来。调用BatchFileLoad之后,直到你调用了BatchFileSave保存文件后,你才能使用Ez批处理文件函数。

s EzBatchAddPath

修改缺省批处理文件,通过添加一个路径名到一个PATH命令的查找路径或到一个赋给环境变量的值。

s EzBatchAddString

添加一行文本到缺省批处理文件。

s EzBatchReplace

置换缺省批处理文件中的一个语句。

19.2.1  EzBatchAddPath

语法:EzBatchAddPath (szKey, szPath, szRefDir, nPosition);

说明:EzBatchAddPath函数修改缺省批处理文件,通过添加一个路径名到一个PATH命令的查找路径或到一个赋给环境变量的值。除非通过调用BatchSetFileName来修改,缺省批处理文件是Autoexec.bat。

    调用BatchGetFileName来确定缺省批处理文件的全限定名。为改变EzBatchAddPath使用的批处理文件的文件名,调用BatchSetFileName。该函数不支持长文件名。在把它传递到调用EzBatchAddPath 之前调用LongPathToShortPath来转换长路径到它等价短路径。

参数:

szKey

指定要修改的环境变量名。如,为修改PATH语句,在这儿指定”path”。 如果指定的环境变量没有在缺省批处理文件中找到,则为环境变量创建一个完整SET语句并插入到文件中。

szPath

指定添加到环境变量当前值的路径名。在查找路径中插入一个分界分号来把它和其它路径名分隔开。

szRefDir

指定与你添加的szPath新路径名相关的参考关键字(一个路径名)。如果这是一个空字符串,该路径名添加到查找路径的开始或结尾,根据nPosition的值而定。如果由szRegKey指定的路径名没有在查找路径中找到,szKey的值被添加到结尾。

nPosition

指定在查找路径的何处添加新路径名,具体包括以下选项:

BEFORE:新路径名被插入到szRefDir指定的路径名的前面。如果szRefDir 包含一个空字符串,该路径名被添加到查找路径的前面。

AFTER:新路径名被插入到szRefKey指定的路径名之后。如果szRefDir 包含一个空字符串,该路径名被添加到查找路径的结尾。

返回值:

0:EzBatchAddPath成功添加路径名到批处理文件。

< 0:EzBatchAddPath未能添加路径名到批处理文件。

注解:

·缺省批处理文件是隐藏或只读时EzBatchAddPath 可能失败。

·EzBatchAddPath对它修改的文件不做拷贝备分。

19.2.2  EzBatchAddString

语法:EzBatchAddString (szLine, szRefKey, nOptions);

说明:EzBatchAddString函数添加一文本行到缺省批处理文件;除非通过调用BatchSetFileName来修改,缺省批处理文件是Autoexec.bat。为确定缺省批处理文件的全限定名,调用BatchGetFileName。为修改由EzBatchAddPath使用的批处理文件的名称,调用BatchSetFileName。

参数:

szLine

指定添加到文件中的文本行。除非你在nOptions 指定NOSET,该函数假定szLine是一个环境变量;在szLine被写入到缺省批处理文件中前文本”SET”被插入到字符串的前面。

    批处理文件完全不支持长路径名。如果你使用该函数来添加包含长路径名的一行,则必需先调用LongPathToShortPath把长路径名转换成它等价的短路径,然后再能把它插入到要添加至批处理文件的字符串中。

szRefKey

指定和你想要在缺省批处理文件中添加的szLine相关的参考关键字。EzBatchAddString在缺省批处理文件中查找参考关键字和在该行前面或后面放置szLine的内容,根据nOptions 的值。

nOptions

指定使用的选项;在该参数位置传递下列预定义常量之一:

BEFORE:SzLine被添加到包含szRefKey的行之前。如果szRefKey是一个空字符串,szLine被添加到文件的第一行。

AFTER:SzLine被添加到包含szRefKey的行之后。如果szRefKey是一个空字符串,szLine被添加到文件的最后一行。

REPLACE:SzLine置换文件中的一现存行。如果有多行有相同关键字存在,EzBatchAddString仅置换包含该关键字的最后一行。

NOSET:指定文本”SET”不被插入到szLine中的字符串的前面。该常量可以和BEFORE、 AFTER、 和REPLACE用或操作符(|)组合。

当你查找的参考关键字是一个DOS命令或程序名(而不是一个环境变量),将常量COMMAND和其它选项常量用或组合,如下所示:

    EzBatchAddString (szLine, szRefKey, AFTER | COMMAND);

返回值:

0:EzBatchAddString成功添加文本字符串到一个指定批处理文件。

< 0:EzBatchAddString未能添加文本字符串。

注解:

·EzBatchAddString 在参数szRefKey中查找合适的参考关键字。如,一个环境变量的关键字是该环境变量本身的名称。

·如果缺省批处理文件是隐藏或只读时,EzBatchAddString可能失败。

·EzBatchAddString对它修改的文件不做拷贝备分。

19.2.3  EzBatchReplace

语法:EzBatchReplace (szNewString);

说明:EzBatchReplace函数置换缺省批处理文件中的一个现存行;除非通过调用BatchSetFileName来修改,缺省批处理文件是Autoexec.bat。为确定缺省批处理文件的全限定名,调用BatchGetFileName。为修改由EzBatchAddPath使用的批处理文件的名称,调用BatchSetFileName。

参数:

szNewString

指定置换文件中一现存行的新字符串。

    批处理文件完全不支持长路径名。如果你使用该函数来添加包含长路径名的一行,则必需先调用LongPathToShortPath把长路径名转换成它等价的短路径,然后再能把它插入到要添加至批处理文件的字符串中。

返回值:

0:EzBatchReplace成功置换文本行。

< 0:EzBatchReplace未能置换文本行。

注解:

·EzBatchReplace分析szNewString并确定该字符串的关键字。然后它在缺省批处理文件中查找包含相同关键字的一行。该函数置换找到的有相同关键字的最后一行。

·一个批处理文件中的一些常用关键字是PATH、 COMSPEC、TEMP、Smartdrv.exe、Win.com、和Share.exe。

·如果缺省批处理文件是隐藏或只读时,EzBatchReplace函数可能失败。

·EzBatchReplace对它修改的文件不做拷贝备分。

20  卸载函数

    下列函数执行卸载安装和/或维护安装一个已安装应用程序的所需服务。

s ComponentGetTotalCost

请参阅7.9。

s ComponentTransferData

请参阅7.23。

s DeinstallSetReference

请参阅15.3。

s DeinstallStart

请参阅15.4。

s InstallationInfo

请参阅15.5。

s MaintenanceStart

请参阅15.6。

s RegDBGetItem

请参阅15.13。

s RegDBSetItem

请参阅15.19。

21  版本检测函数

    下列函数允许你访问存在于Windows 95及更高版本的文件中的版本信息。为使用这些函数,你需要知道有关版本资源的背景信息。查阅Microsoft Windows Programmer's Reference, Volume 4:资源手册来更好得了解版本资源。函数说明假定你完全熟悉版本资源的概念。

   下列函数获得一个具体文件的版本,找到一个文件并得到它的版本,或查找一个存在的文件和试图安装该文件的一个更新的版本。函数可工作于压缩文件或未压缩文件。

s VerCompare

比较包含版本信息的两个字符串。

s VerFindFileVersion

查找指定文件并检索它的版本和位置。

s VerGetFileVersion

检索一指定文件的版本。

s VerSearchAndUpdateFile

用一个更新的版本置换一个存在的文件。如果指定的文件不存在,则安装更新的版本。

s VerUpdateFile

用一个更新的版本置换一个存在的文件。如果指定的文件不存在,则不安装更新版本。

21.1  VerCompare

语法:VerCompare (szVersionInfo1, szVersionInfo2, nCompareFlag);

说明:VerCompare函数比较两个包含版本信息的字符串。

参数:

szVersionInfo1

以下列格式指定第一个版本字符串:

主版本号.次版本号

如果szVersionInfo1是2.1.2.0,主版本号是2.1,次版本号是2.0。

szVersionInfo2

以相同格式指定第二个版本字符串。

nCompareFlag

传递预定义常量VERSION来指定进行版本号的比较。该参数不允许其它值。

返回值:

EQUALS (2):表明两个字符串有相等值。

GREATER_THAN (0):表明第一个字符串包含的值大于第二个。

LESS_THAN (1):表明第一个字符串包含的值小于第二个。

21.2  VerFindFileVersion

语法:VerFindFileVersion (szFileName, svPath, svVersionNumber);

说明:VerFindFileVersion函数查找一个指定的文件并检索文件版本和位置。VerFindFileVersion使用下列查找算法来找到文件:

1. 首先,它查找Windows 文件夹。

2. 接着,Windows 系统文件夹。

3. 接着,由系统变量TARGETDIR指定的文件夹。

4. 接着,由环境变量PATH指定的文件夹。

5. 最后, Setup.exe运行所在的文件夹。

有关Windows 系统文件夹的信息,请查看InstallShield系统变量WINSYSDIR的文档。

参数:

szFileName

指定要获得其版本的文件的非限定名。不要在该参数位置指定一个驱动器指示符或路径。

svPath

返回文件所在的文件夹的完整路径(包含驱动器指示符)。

svVersionNumber

返回下列格式的文件版本号:

主版本号.次版本号

如果szVersionNumber返回2.1.2.0,则主版本号是2.1,次版本号是2.0。

返回值:

0:表明函数成功返回版本信息。

FILE_NO_VERSION (-8):表明文件被找到但不包含版本信息。

FILE_NOT_FOUND (-2):表明文件未能找到。

注解:

·当使用VerFindFileVersion时,你可能需要为TARGETDIR设置一个值,而不是让InstallShield自动设置它。因为函数在TARGETDIR文件夹中寻找文件,你可能需要临时设置系统变量来确保VerFindFileVersion会找到该文件。如果你要这么做,在将TARGETDIR的值临时设置为另一个文件夹前使用VarSave来保存该值。

21.3  VerGetFileVersion

语法:VerGetFileVersion (szFileName, svVersionNumber);

说明:VerGetFileVersion函数检索指定文件的数值型版本信息。

参数:

szFileName

指定其数值型版本信息要被检索的文件的全限定名。

svVersionNumber

以下列格式的字符串返回文件数值型版本号信息:

主版本号.次版本号

如果szVersionNumber返回2.1.2.0,则主版本号是2.1,次版本号是2.0。

返回值:

0:表明函数成功返回版本信息。

FILE_NOT_FOUND (-2):表明指定文件未能找到。

FILE_NO_VERSION (-8):表明文件被找到但不包含版本信息。

注解:

·值得注意的是,虽然InstallShield 文件版本信息以字符串格式出现,它们所指示的一个文件的版本信息是数值型版本信息。一个文件的字符串版本信息是不能由InstallShield函数检查到和返回的。而且,你必须注意当Windows 资源管理器显示一个文件的属性时,它显示字符串版本信息,可能与文件数值型版本信息不等。因为这个原因,由VerGetFileVersion在参数svVersionNumber返回的值可能与Windows 资源管理器显示的版本信息不匹配。

·有关文件版本信息的更多情况,可查询Windows SDK或Win32 SDK。

21.4  VerSearchAndUpdateFile

语法:VerSearchAndUpdateFile (szFileName, nUpdateFlag, svInstalledFile);

说明:VerSearchAndUpdateFile函数查找指定的文件并在必要时安装该文件的一个更新版本。如果该函数找到该文件,它比较现存文件的版本号和新文件的版本号。如果现存文件是旧的,它被新文件替换。新文件必须在由系统变量SRCDIR指定的目录中。如果函数未找到一个现存文件,它就拷贝新文件到目标系统。Microsoft Windows根据文件类型决定文件安装在哪里。例如,.dlls和系统驱动器被安装在Windows 系统文件夹中。有关Windows 系统文件夹的信息,请查阅InstallShiled 系统变量WINSYSDIR的文档。

VerSearchAndUpdateFile使用下列查找算法来找到现存文件:

请参阅VerFindFileVersion中的查找算法。

参数:

szFileName

指定要安装的文件的未限定名。不要在该参数位置指定一个驱动器指示符或路径。

nUpdateFlag

指示是否该文件要被无条件更新或仅当在目标系统上找到的文件版本比你现有的文件版本旧时才更新。在该参数位置传递下列预定义常量之一:

VER_UPDATE_COND:仅当现存文件是一个旧版本时才更新它。

VER_UPDATE_ALWAYS:即使现存文件是一个更新的版本也要更新它。

svInstalledFile

返回由该函数安装的文件的全限定名。如果你要置换的文件正在使用,则文件以一个轻微差异的名称被安装到相同目录。文件以其扩展名的第一个字符为~字符来更名。例如,如果你安装文件Shell.dll并且文件是锁定的,则该文件被拷贝为Shell.~ll。文件名从该变量返回。

返回值:

FILE_INSTALLED (0):函数成功安装文件。

FILE_IS_LOCKED (-4):表明文件正在被Windows 使用并且不能被置换。新文件以一个新名字被拷贝到相同目录。

FILE_NO_VERSION (-8):表明文件被找到,但它不包含版本信息。文件更新没有执行。

FILE_RD_ONLY (-5):表明现存文件是写保护的。脚本必须在进行安装之前重新设置目标文件的只读标志,然后再尝试安装文件。

FILE_SRC_OLD (-7):表明要安装的文件有相同的日期或比先前存在的文件更早。

OUT_OF_DISK_SPACE (-6):表明函数因为目标驱动器上磁盘空间不足,未能创建文件。文件更新没有执行。

VER_DLL_NOT_FOUND (-3):表明没有找到Ver.dll。文件更新没有执行。

OTHER_FAILURE (-1):表明发生一个不确定错误。文件更新没有执行。

注解:

·使用VerSearchAndUpdateFile时,你可能需要给SRCDIR和/TARGETDIR设置值,而不是让InstallShield自动设置它们。因为函数在SRCDIR和 TARGETDIR文件夹中查找文件,你可能需要临时重新设置这些系统变量的值来确保VerSearchAndUpdateFile会找到文件。如果你需要这么做,则在将SRCDIR 和 TARGETDIR临时设置为其它值之前使用VarSave来保存它们的值。调用VerSearchAndUpdateFile函数后,使用VarRestore来重新设置SRCDIR 和TARGETDIR。

·对于文件传输,VerSearchAndUpdateFile的可能的替换函数是XCopyFile,,它可以做版本检测,标记锁定的.dll和.exe文件待系统重启后更新,并且递增共享的.dll和.exe文件的注册表访问计数器。

21.5  VerUpdateFile

语法:VerUpdateFile (szFileName, nUpdateFlag, svInstalledFilePath);

说明:VerUpdateFile函数使用一个指定文件的版本信息来确定是否要在目标系统上安装该文件。VerUpdateFile在参数szFileName位置得到文件名。如果在szFileName没有指定一个全限定名,VerUpdateFile使用下列查找算法来找到该文件(目标文件):

请参阅VerFindFileVersion的查找算法。

  VerUpdateFile然后将SRCDIR中相同名称的文件的版本和目标文件(如果存在)的版本进行比较。如果源文件的版本号比目标文件的版本号更新,则目标文件被置换为该源文件。如果目标文件不存在,InstallShield拷贝源文件到目标文件。

  当在参数nUpdateFlag位置是SHAREDFILE 或 LOCKEDFILE选项,并且要被更新的.dll或.exe 文件正在被系统使用时,源文件的更名拷贝传输到目标系统并且系统变量BATCH_INSTALL设置为TRUE。然后,当在安装结尾调用RebootDialog或 SdFinishReboot并且系统重启时,锁定文件被更新。有关更新锁定文件的更多信息请查阅RebootDialog 和SdFinishReboot。系统变量BATCH_INSTALL可以被测试来确定是否遇到锁定的.dll或.exe文件。你不能同时使用SHAREDFILE 和 LOCKEDFILE选项,你必须使用一个或另一个。

参数:

szFileName

指定要被更新的文件的全限定名或非限定名。如果该名是非限定的(也就是,如果它不包括一个驱动器指示符或路径),InstallShield查找Windows 或Win95目录,系统目录,由环境变量PATH指定的目录,然后是InstallShield可执行文件的目录来找匹配文件。VerUpdateFile取szFileName的文件名部分,并用它来标识SRCDIR中作为源文件的文件。

nUpdateFlag

指示是否该文件要被无条件更新或仅当在目标系统上找到的文件版本比你的源文件版本早时才更新。在该参数位置传递下列预定义常量之一。你可以用按位或操作符(|)将常量SHAREDFILE和其它常量之一组合。你不可将SHAREDFILE 和 LOCKEDFILE组合。

LOCKEDFILE:使VerUpdateFile标志Windows 或系统重启时要被更新的.dll 和.exe文件。一个锁定文件是一个当InstallShield试图要访问或更新时而正在被一个应用程序或系统使用的文件。LOCKEDFILE选项和 SHAREDFILE一样工作,除了LOCKEDFILE不创建注册表表目或修改注册表访问计数器。你使用SHAREDFILE选项时不能使用LOCKEDFILE选项。有一些非共享文件,对它们脚本作者不要注册表表目和访问计数器。这些文件除非由应用程序本身,否则永不被安装。LOCKEDFILE允许VerUpdateFile处理非共享的锁定文件。

SHAREDFILE:可以通过用VerUpdateFile将所有文件处理为共享,并标志Windows 或系统重启时要被更新的锁定的.dll 和.exe文件,来组合共享和锁定文件的处理。

当文件存在于目标目录并且它有一个大于0的访问计数器时,SHAREDFILE选项使VerUpdateFile处理所有文件为共享文件并将注册表访问计数器加一。如果共享文件不存在于目标目录并且它没有访问计数器时,InstallShield创建该计数器并把它设置为1。如果共享文件已经存在于目标目录但没有访问计数器时,InstallShield创建该计数器并把它初始化为2,作为一个防止安装过程中意外删除的预防措施。

SELFREGISTER

s 当使用“非批处理方法“安装自注册文件时,立即进行自注册处理。

s 当你已经调用Enable(SELFREGISTERBATCH),自注册文件排队等待注册。

s 当使用“批处理方法“安装自注册文件时,一旦调用Do(SELFREGISTRATIONPROCESS),这些文件被注册。

总是将SELFREGISTER和常量SHAREDFILE用按位或操作符组合一起使用。

VER_UPDATE_ALWAYS:更新文件时不考虑版本号。

VER_UPDATE_COND:仅当被替换的文件是旧版本时才更新它。

svInstalledFilePath

返回安装的文件的全限定名。如果你想要置换的文件正在被使用,文件以一个更改名安装到相同目录。InstallShield使用一个~字符来置换文件扩展名的第一个字符。

例如,如果你在更新文件Shell.dll并且目标文件是锁定的,则源文件以Shell.~ll被拷贝到目标目录。文件名从参数svInstalledFilePath返回。

如果SHAREDFILE选项使用到参数nUpdateFlag并且锁定文件当Windows 或系统重启时被正确递交来更新,则发生更新时文件的~更名版本被删除。

返回值:

FILE_INSTALLED (0):表明函数成功安装文件。该常量等于0。所有其它返回值小于0

FILE_IS_LOCKED (-4):表明现存的文件正被Windows使用,不能被置换。新文件以一个新名被拷贝到相同目录,如前面所述。

FILE_NO_VERSION (-8):表明文件被找到,但它不包含版本信息。不执行文件更新。

FILE_RD_ONLY (-5):表明现存文件是写保护的。你必须在进行安装之前重新设置目标文件的只读位,然后再尝试安装文件。

FILE_SRC_EQUAL (-9):表明你要安装的文件和现存文件有相同版本。如果VER_UPDATE_COND标志被设置,则不执行文件更新。

FILE_SRC_OLD (-7):表明你要安装的文件比现存文件要早。如果VER_UPDATE_COND标志被设置,则不执行文件更新。

OUT_OF_DISK_SPACE (-6):表明函数未能创建文件,因为目标驱动器上磁盘空间不足。不执行文件更新。

-51:一个自注册文件未能成功注册。

OTHER_FAILURE (-1):表明发生不确定错误。不执行文件更新。

注解:

·在调用任何使用SHAREDFILE选项的函数前,必须使用InstallationInfo来设置应用程序信息,并且必须使用DeinstallStart函数设置卸载信息。

·当使用VerUpdateFile时,你可能需要为SRCDIR设置一个值,而不是让InstallShield自动设置它。因为函数在SRCDIR文件夹中寻找文件,你可能需要临时设置系统变量来确保VerUpdateFile会找到该文件。如果你要这么做,在将SRCDIR的值临时设置为另一个文件夹前使用VarSave来保存该值。调用VerUpdateFile函数后,使用VarRestore来重新设置SRCDIR。

·对于文件传输,VerSearchAndUpdateFile的可能的替换函数是XCopyFile,,它可以做版本检测,标记锁定的.dll和.exe文件待系统重启后更新,并且递增共享的.dll和.exe文件的注册表访问计数器。

22  杂项函数

    下列函数提供不同的功能,如低层硬件接口,组件创建和操作和用户输出。

s Do

执行当前定义的EXIT 和 HELP处理程序。

s DoInstall

运行另一个InstallShield安装程序。

s Handler

指定一个对退出和帮助事件响应时转移到的标号。

s ISCompareServicePack

比较安装在目标OS上的服务程序包数和指定的服务程序包数。

s MessageBeep

产生一个标准警告蜂鸣。

s SendMessage

发送一个消息到另一个窗口或应用程序。

s Sprintf

返回一个格式化的包含一个或多个字符,数字或字符串值的字符串。

s System

退出到DOS,重启Windows或重启计算机。

s VarRestore

恢复上一次调用VarSave时保存的系统变量SRCDIR和 TARGETDIR 的值。

s 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键时当前定义的HELPEXIT处理程序执行。Do函数也比goto语句(它可以被使用来调用HELPEXIT处理程序标号)提供更大的通用性。Goto语句不能使用在所有的环境中,但Do函数任何时间都可以被虚拟调用。有关缺省和自定义HELPEXIT处理程序的更多信息,参阅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文件位于相同文件夹中。如果不存在这些文件,安装程序不会被正确运行。

因此,建议你将由媒体向导创建的所有文件拷贝到你从中运行第二个安装程序的文件夹中。如果你从第一个安装程序的安装支持文件夹(SUPPORTDIR)中运行第二个安装程序,则建议你把这些文件放置在第一个安装程序的安装文件窗格中的适当的语言和操作系统文件夹中,因而安装初始化时,它们会被自动解压缩在第一个安装程序的支持文件夹中。

22.3  Handler

语法:Handler (nObject, Label);

说明:退出和帮助处理程序只支持向后兼容。在一个基于事件的脚本中,你必须使用OnCanceling 和 OnHelp事件处理程序来代替。

    Handler函数创建事件的自定义处理程序,如Help的加速键(F1),Cancel的加速键和Exit的加速键(F3)。如果用户按下F1键,则当前定义的HELP处理程序被执行。如果用户按下F3键,则当前定义的EXIT处理程序被执行。如果你没有用Handler函数定义自定义的HELPEXIT处理程序,则缺省的处理程序将被执行。缺省的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处理程序。

·在脚本中,EXITHELP处理程序标号和它们的相关代码必须放置在结束程序语句之前。

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在下列情况下产生一个编译错误或运行时失败:

s 指定了多于9个格式说明符和变量:编译错误。

s 变量的数目和格式说明符的数目不匹配。当一个说明符没有一个相应的变量时,结果字符串在该说明符的位置将包含不可预测的字符。当变量多于说明符时,多余的变量将不会被插入到结果字符串中。

s 一个变量和它相应的格式说明符不匹配。结果字符串将在该说明符的位置将包含不可预测的字符。

返回值:

如果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的注解。

 

“相关推荐”对你有帮助么?

  • 非常没帮助
  • 没帮助
  • 一般
  • 有帮助
  • 非常有帮助
提交
©️2022 CSDN 皮肤主题:大白 设计师:CSDN官方博客 返回首页
评论 1

打赏作者

死神在世

你的鼓励将是我创作的最大动力

¥2 ¥4 ¥6 ¥10 ¥20
输入1-500的整数
余额支付 (余额:-- )
扫码支付
扫码支付:¥2
获取中
扫码支付

您的余额不足,请更换扫码支付或充值

打赏作者

实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、C币套餐、付费专栏及课程。

余额充值