InstallShield内部库函数全集十七－外壳函数

17  外壳函数
    外壳函数创建新的程序文件夹，删除存在的程序文件夹，添加项目到存在的程序文件夹。在安装的最后，添加应用程序到适当的程序文件夹以允许用户立即访问你的软件。下列函数也支持不同的图标选项。
AddFolderIcon
添加一个图标到一个文件夹。
CreateProgramFolder
创建一个程序文件夹。
CreateShellObjects
创建在资源窗格的外壳对象文件夹中指定文件夹和快捷方式（或组和图标）。
DeleteFolderIcon
从一个程序文件夹中删除一个图标或项目。
DeleteProgramFolder
从目标系统中删除一个程序文件夹。
GetFolderNameList
检索指定文件夹中的所有子文件夹名和快捷方式。
ProgDefGroupType
在Windows NT环境中将组标识为公用或专用。
QueryProgItem
返回有关一个指定的程序项目或子文件夹的信息。
QueryShellMgr
返回当前外壳管理程序的名称。
ReplaceFolderIcon
置换一个指定文件夹中的一个图标。
SelectFolder
呈现一个对话框，允许最终用户从一个程序文件夹列表中选择一个文件夹。
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
指定下列情况之一：
和图标相联系的可执行文件的全限定名，包括任何命令行参数。为添加一个快捷方式图标到Windows 95及更高版本的开始程序菜单，输入一个链接目录的全限定路径，在那儿你的应用程序存放了它的图标链接文件。
全限定路径，如果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在缺省程序目录下查找一个子文件夹，按照操作系统：
Windows 95及更高版本：开始菜单/程序文件夹位于Windows文件夹下。注意即使用户配置文件被激活，该定位不会改变。
Windows NT 4.0（如果由ProgDefGroupType选定为公用）：../profiles/All Users/Start Menu/Programs文件夹位于Windows文件夹下。
Windows NT 4.0（如果由ProgDefGroupType选定为专用）：. ./profiles/ /Start Menu/Programs位于Windows文件夹下； 是当前用户的用户名。
你也可以使用一个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在缺省程序目录下查找一个子文件夹，按照操作系统：
Windows 95及更高版本：环境变量Windir下的开始菜单/程序。
Windows NT 4.0（如果由ProgDefGroupType选定为公用）：环境变量Windir下的../profiles/All Users/Start Menu/Programs目录。
Windows NT 4.0（如果由ProgDefGroupType选定为专用）：环境变量Windir下的. ./profiles/ /Start Menu/Programs目录； 是从系统变量USERPROFILE得的当前用户的用户名。
你也可以使用一个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
指定下列之一：
和图标相联系的可执行文件的全限定名，包括任何命令行参数。
如果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：将文件夹还原到原始大小。
返回值：
该函数没有返回值。