1 库函数综述
InstallShield包含300多个内部库函数,用户可在安装脚本中调用它们来创建程序组,操作文件夹,处理目录,监督安装状态,创建对话框,操作文件及其它更多工作。因为InstallShield脚本编译器已经识别这些库函数名,所以用户在使用它们之前无须说明。
为了成功调用一个内部库函数,用户必须知道库函数名称及使用格式。InstallShield 库函数参阅附录D库函数索引。
组件函数
下列函数允许你控制文件媒体、创建和处理脚本创建的组件组:
ComponentAddItem
增加一个新的组件到脚本创建的组件组中。
ComponentCompareSizeRequired
确定是否有足够的空闲磁盘空间给选定的组件。
ComponentDialog
呈现一个对话框,允许最终用户选择组件和指定一个目标位置。
ComponentError
当一个组件函数失败时,返回附加的错误信息。
ComponentFilterLanguage
激活和禁用基于语言的筛选(程序)。
ComponentFilterOS
激活或禁用基于操作系统的筛选。
ComponentGetData
检索一个组件的有关信息。
ComponentGetItemSize
确定一个指定组件的大小。
ComponentGetTotalCost
确定已经被指定的组件安装和卸载所需的总的空间。
ComponentInitialize
准备供存取的文件媒体库。
ComponentIsItemSelected
确定指定的组件是否已由最终用户选定。
ComponentListItems
创建一个文件媒体库中或一个脚本创建的组件组中的组件列表。
ComponentMoveData
传输和解压缩与文件媒体库中被选组件相关联的文件。
ComponentReinstall
配置安装,使得下一个对ComponentTransferData的调用执行上一次安装运行时指定的文件传输。
ComponentRemoveAll
配置安装,使下一个对ComponentTransferData的调用卸载掉安装。
ComponentSelectItem
选定或撤消选定组件。
ComponentSetData
为指定的组件设置属性和数据。
ComponentSetTarget
指定一个用户定义的变量,放置在一个组件的<TARGETDIR>域。
ComponentTransferData
执行已经被指定的组件安装和卸载。
ComponentSetupTypeEnum
列举与指定的文件媒体库相关联的安装类型。
ComponentSetupTypeGetData
检索和一个指定的已经在InstallShield IDE中创建的安装类型相关联的数据。
ComponentSetupTypeSet
选择与指定的安装类型相关联的所有组件。
ComponentTotalSize
以字节为单位计算选定的组件和子部件的总的大小。
ComponentValidate
确认整个文件媒体库的或在文件库媒体中的一个指定组件的口令。
SdSetupType
显示一个对话框,使最终用户选择三个标准安装类型:典型、简明或自定义中的一个。
SdSetupTypeEx
显示一个对话框,使最终用户选择标准和自定义的安装类型。
7.1 ComponentAddItem
语法:ComponentAddItem (szComponentSet, szComponent, nDataSize, bSelected);
说明:ComponentAddItem函数增加一个组件到一个脚本创建的组件组中。如果一个由szComponentSet指定的脚本创建组件组不存在,它将被创建。每次要增加一个组件到给定的脚本创建组件组中,都要调用ComponentAddItem。你可以创建多个脚本创建组件组,每个都有一个唯一的名称(参数szComponentSet)。
为显示一个供选择的单级组件,使用ComponentDialog, SdComponentDialog, 或SdComponentDialogAdv。使用SdComponentDialog2或r SdComponentMult来显示组件和它们的子部件。
该函数不能使用到文件媒体库。
参数:
szComponentSet
指定要增加一项的脚本创建的组件组的名称。如果脚本创建组件组不存在,ComponentAddItem将创建它。
szComponent
指定要增加的组件名称。不要使用一个空字符串(“”)。
下面是有关指定在函数调用中的组件和子部件的信息:
(指在函数调用中的组件和子部件)
组件是一个涉及一组文件组和/或子部件的通用术语。一个子部件也只是一个组件。它位于其它组件下面,这与和文件夹和子文件夹的关系相似。
“顶层组件”是在分层结构中的最高层组件。顶层组件从不作为子部件被引用。
一些InstallShield组件函数要求你指向一单个组件,而其它的要求你指向多个组件。
为指向一单个组件,使用该组件的名称。为指向一个子部件,使用一个路径形式的表达式,其中分层结构中引向该组件的每个组件的名称由双反斜杠分隔。例如,为指定顶层组件帮助文件下的子部件教学,在你的脚本中使用下列表达式。
szComponent = "Help Files\\Tutorials";
为引用教学下的子部件CBT,使用下列表达式:
szComponent = "Help Files\\Tutorials\\CBT";
一些组件和安装类型对话框函数,如SdComponentMult,显示多个组件和它们的子部件。这些情况下,你可指向多个组件,只要指定在分层结构中就在它们上层的组件即可。如果组件是顶层组件,使用一个空字符串(“”)来引用它们。
例如,如果你传递一个空字符串给SdComponentMult函数,在组件窗口中将显示你的文件媒体库中的所有顶层组件或你的脚本创建的组件组中的所有顶层组件,依赖于系统变量MEDIA的值。所有子部件将显示在Subcomponents窗口中。
另一方面,如果你传递一单个顶层组件(如上例中的帮助文件)给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 = ComponentTransfer