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的註解。