InstallShield内部库函数之INI文件函数

INI文件函数
    INI文件函数从初始化和配置文件中获得信息或拷贝信息到这些文件。一个初始化文件是一个特殊的包含关键字名-值对的ASCII文件。关键字名-值对代表运行时对应用程序的选项。你也可以访问和修改专用的初始化文件和系统初始化文件。下面的列表简要描述了每个INI文件函数。
    由AddProfString, ReplaceProfString, 或 WriteProfString对.ini文件所做的修改可以存入卸载记录中。然而，必须知道一些重要的限制。更多信息，可查看卸载.ini文件的条目。
AddProfString
在.ini文件的一段中添加一个非唯一键。
GetProfInt
从一个.ini文件中返回一个整数。
GetProfString
从一个.ini文件中返回一个字符串。
GetProfStringList
从一个.ini文件中返回键名和字符串值的列表。
ReplaceProfString
置换一个配置文件（.ini文件）中一个字符串。
WriteProfInt
将一个有整数的字符串写到一个.ini文件中。
WriteProfString
将一个字符串写到一个.ini文件中。
相关函数
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文件。
注解：
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文件。注意下列要点：
因为Windows 高速缓存保存文件的方法改变，你必须在调用WriteProfString后刷新高速缓存。（看下面的注解部分。）
对.ini文件所做的修改可以存入到卸载记录中。然而，必须知道一些重要的限制。更多信息，可查看卸载.ini文件的条目。
为写一个字符串值到一个.ini文件，则调用WriteProfString。
当你想修改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); file://null string ("") in first three parameters
   file://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的注解。