11 INI file function of the INSTALLSHIELD internal library function
The INI file function obtains information or copy information from the initialization and configuration file to these files. One initialization file is a special ASCII file containing keyword-value. Keyword name - Value Options for the application when the runtime is run. You can also access and modify dedicated initialization files and system initialization files. The following list briefly describes each INI file function.
Modifications made by AddProfstring, ReplaceProfstring, or WriteProfstring pair. In-unloaded records can be deposited. However, some important limits must be known. For more information, you can view an entry for uninstall .ini files.
AddProfstring
Add a non-unique key to a .ini file.
GetProfint
Returns an integer from one .ini file.
Getprofstring
Returns a string from one .ini file.
Getprofstringlist
Returns a list of key names and string values from one .ini file.
Replaceprofstring
Replace a string in a configuration file (.ini file).
Writeprofint
Write an integer string to a .ini file.
Writeprofstring
Write a string into a .ini file.
related functions
SDShowFileMods
Create a dialog, propose to modify the file and how to provide options.
11.1 addprofstring
Syntax: Addprofstring (SzFileName, SzsectionName, SzkeyName, Szvalue);
Description: addprofstring function Add a configuration string to a .ini file unconditionally. Using AddProfstring only adds non-unique keys, such as those found in the System.ini file [386ENH] segment (Device = ...). AddProfstring Add Key = Value to the end of the segment of the specified .ini file. It does not replace or updates an existing key. To update an existing non-unique key, call ReplaceProfString. To add a unique key or update a unique key to the value of a unique key, call WriteProfstring.
The modifications made to the .ini file can be stored in the uninstall record. However, some important limits must be known. For more information, you can view an entry for uninstall .ini files.
parameter:
SZFileName
Specifies the name of the .ini file to add a configuration string. If SZFileName is an unlimited name (that is, does not include a drive indicator and path), INSTALLSHIELD finds the file in the Windows folder. If the file does not exist, it is created in the specified folder if the file is not included in the file name, which is created in the Windows folder. Note If the file name is defined in a path that does not exist, addprofstring will fail.
SzsectionName
Specify a paragraph in the .ini file. The configuration string is inserted at the end of this segment. If this paragraph does not exist, INSTALLSHIELD creates it. Segment names must not be enclosed in the boundaries ([]). Note that the configuration string is still inserted even if the keys specified by SzkeyName are already inserted.
SzkeyName
Specifies the key name to be inserted. The value of this parameter will be displayed on the left side of the configuration string.
SzValue
Specifies the value assigned to this key. The value of this parameter will be displayed on the right side of the configuration string.
return value:
0: AddprofString Successfully Adds the specified configuration string to .ini file.
<0: addprofstring Fails to add the specified configuration string to .ini file.
annotation:
AddProfstring does not use the Windows API to modify the .ini file. Windows APIs cannot handle the type of modification that addprming might implementation. 11.2 getProfint
Syntax: getprofint (SZFileName, SzsectionName, SzkeyName, NVValue);
Note: The getprofint function retrieves an integer from one .ini file. When the parameter nDefault is specified as 0, GetProfint is working like Windows API GetPrivateProfileint.
parameter:
SZFileName
Specify a .INI file name, get the current integer value of a key. If SZFileName is an unlimited name (that is, does not include a drive indicator and path), INSTALLSHIELD finds the file in the Windows folder.
SzsectionName
Specify a paragraph name in the .ini file, look for SzkeyName. Segment names must not be enclosed in the boundaries ([]).
Find this name when you don't care.
SzkeyName
Specify a key whose integer value is returned to NVValue. Find this button is not case sensitive.
NVValue
Returns a full value currently assigned to SZKEYNAME. Due to the limit of the getPrivateProfileint function, this function can only return a 16-bit value from the configuration file.
Therefore, the maximum value that can be returned is 65, 535; a larger value may not be returned correctly. If you need to return a larger value, use the usual file handler, such as FileGrep and FileInsertline, and then convert the returned string into a integer value by calling strand.
return value:
GetProfint always returns 0.
annotation:
· If you use the Windows API function GetPrivateProfileint, if the error that can't find files, segments, or key names is not returned; but NVValue contains 0. Therefore, it is impossible to distinguish an error and a return value of 0. To identify 0 and one error, call GetPrivateProfileint directly and specify a candidate default.
· Under Windows NT (not Windows 95 and later), some calls to the getPrivateProfileint function (so also getprofint functions) are automatically imaged to the Windows registry instead of the configuration file.
11.3 getprofstring
Grammar: getProfstring (SzFileName, SzsectionName, SzkeyName, SvResult);
Description: The getProfstring function retrieves a configuration string from a specified .ini file. GetProfstring is working like Windows API getPrivateProfileString.
parameter:
SZFileName
Specify a .INI file name, get the current value of a key. If SZFileName is an unlimited name (that is, does not include a drive indicator and path), INSTALLSHIELD finds the file in the Windows folder.
SzsectionName
Specify a paragraph name in the .ini file, look for SzkeyName. Segment names must not be enclosed in the boundaries ([]).
Find this segment name is not case sensitive. To get a list of all segment names in an INI file, pass an empty string to this parameter. For more information, please see the annotations below.
SzkeyName
Specify a key, its value is returned to SvResult. Find this button is not case sensitive. To get a list of all key names in a segment, pass an empty string to this parameter. For more information, please see the annotations below. SvResult
If SZSECTIONNAME specifies a segment name, szkeyName specifies a key name, the value of the key is returned to this parameter. If SzsectionName specifies an empty string, all segments return to SVRESULT. If SzkeyName specifies an empty string, all key names in this segment returns to SvResult.
return value:
0: getProfString successfully returns the value of the configuration string.
<0: getprofstring failed to return the value of the configuration string.
-2: The value of the key is more than 2048 characters (can be returned by getprofstring to the maximum number of characters).
annotation:
· To get a list of all paragraphs in an INI file, this parameter szsectionName passes an empty string. The parameter SvResult is returned to the parameter svresult of the parameter svresult. Svresult must be long enough to accept all paragraphs. Use the strGetToKens function to give a single segment name from the string.
· Pass an empty string to the parameter szkeyname for all the key names in the segments specified by SzsectionName. Returns to the parameter SVRESULT by the key name of the empty characterization. SvResult must have a long enough to accept all key names. Use the strGetToKens function to give a single key name from the string.
GetProfString uses functions provided by your operating environment to access .ini files. Therefore, INSTALLSHIELD functionality may be limited by the operating environment.
11.4 getprofstringlist
Grammar: getProfstringList (SzfileName, SzsectionName, ListKeyNames, ListValues);
Note: The getProfStringList function retrieves the key name and string value list from the specified INI file.
parameter:
SZFileName
Specify a .INI file name, get the key name and string value from it. If SZFileName is an unlimited name (that is, does not include a drive indicator and path), INSTALLSHIELD finds the file in the Windows folder.
SzsectionName
Specify a parameter in the .ini file, find the key name and string value from it. Segment names must not be enclosed in the boundaries ([]). Find this segment name is not case sensitive.
ListKeynames
Returns a key name list. A list of strings identified by the listKeynames must have been initialized by calling ListCreate.
Listvalues
Returns a list of string values. A list of strings identified by the listValues must have been initialized by calling ListCreate.
return value:
0: Indicates that the function successfully reads the segment and inserts the key name and string value into the specified list.
-2: Indicates that one or all of the lists are invalid. Other negative values indicate that the function has not read or unable to insert the key name and string value into the specified list.
11.5 ReplaceProfstring
Syntax: ReplaceProfstring (SzFileName, SzsectionName, SzkeyName, SzorigValue,
szreplaceValue;
Description: ReplaceProfstring function Replacement. Init Configuration string in the II file. This function can replace the value of the repetition key (non-unique key), as found in the system.ini file [386enh] segment (device = ...). This function looks for a szkeyName = SzorigValue, and is discontinued. If it is not found, it starts to add zkeyName = szreplaceValue in the SzsectionName segment. If you add a unique key (that is, the WriteProfstring function is used if you have a given segment, all keys are different). Use this function to replace only non-unique key names, such as Device = line in the System.ini file.
The modifications made to the .ini file can be stored in the uninstall record. However, some important limits must be known. For more information, you can view an entry for uninstall .ini files.
parameter:
SZFileName
Specifies the name of the .ini file to replace the configuration string. If SZFileName is an unlimited name (that is, does not include a drive indicator and path), INSTALLSHIELD finds the file in the Windows folder. If the file does not exist, it is created in the specified folder if the file is not included in the file name, which is created in the Windows folder. Note If the file name is limited to a path that does not exist, ReplaceProfString will fail.
SzsectionName
Specify a paragraph name in the .ini file, look for SzkeyName. Segment names must not be enclosed in the boundaries ([]). Find this segment name is not case sensitive.
SzkeyName
Specifies the key name to be replaced. If the key does not exist, it is created.
SzorigValue
Identifies the current value of the key specified by SzkeyName.
SzreplaceValue
Specifies the new value assigned to SZKEYNAME. The value of this parameter will be displayed on the right of the configuration string (szkeyname = szvalue).
return value:
0: Indicates that the function is successfully replaced or adds a configuration string.
<0: Indicates that the function failed to replace or add a configuration string.
annotation:
· Windows .ini is a text file. You must use the appropriate version of InstallShield in each operating system.
11.6 WriteProfint
Syntax: WriteProfint (SZFileName, SzsectionName, SzkeyName, Ivalue);
Note: The WriteProfint function modifies a .ini file by inserting or updating a configuration string (integer value). Note the following points:
Because the WINDOWS cache save file changes, you must refresh the cache after calling WriteProfstring. (Look at the following annotation section.)
The modifications made to the .ini file can be stored in the uninstall record. However, some important limits must be known. For more information, you can view an entry for uninstall .ini files.
To write a string value to a .ini file, call WriteProfstring.
Use addprming and replaceprofstring functions when you want to modify the System.ini file.
parameter:
SZFileName
Specifies the name of the .ini file to replace the configuration string. If SZFileName is an unlimited name (that is, does not include a drive indicator and path), INSTALLSHIELD finds the file in the Windows folder. If the file does not exist, it is created in the specified folder if the file is not included in the file name, which is created in the Windows folder. Note If the file name is limited to a path that does not exist, Write Profint will fail. SzsectionName
Specify a paragraph name in the .ini file, szkeyName will be inserted or will be modified. Segment names must not be enclosed in the boundaries ([]). Find this segment name is not case sensitive.
SzkeyName
Specifies the unique keys to update. If the key to be updated does not exist in the specified segment, it is created.
To remove a single segment from one .ini file, pass an empty string to the parameter szkeyname. To remove one or more keys from one segment of a .ini file, use WriteProfString.
iValue
Specifies the integer value to assign the unique key identified by the szkeyName.
return value:
0: Indicates that the function successfully updates the specified .ini file.
<0: Indicates that the function failed to update the specified .ini file.
annotation:
The WriteProfint function uses Windows API WritePrivateProfileString to access .ini files. Therefore, its function functionality is limited by the function functions provided by the Windows API. More information for .ini files You can query Microsoft Windows Manual.
· .Ini files are placed in a cache under Windows 95 and later, which may cause delays to write to the specified file. This can then prevent subsequent file operations such as calling CopyFile and XcopyFile. So if you then use the file operation, you must refresh the cache after using WriteProfint. Simply call WRITEPROFINT with empty parameters to enforce Windows 95 and later to write data to .ini files, as shown below:
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
Syntax: WriteProfstring (Szfilename, SzsectionName, SzkeyName, Szvalue);
Description: The WriteProfString function writes a configuration string to one .ini file. Based on the value passed to WriteProfString, it can create a segment, delete a single paragraph, create a unique key = value entry, delete a key = value entry, or update the value of a key.
Note that points are the point of attention in WriteProfint.
parameter:
SZFileName
Specify the name of the .ini file. If SZFileName is an unlimited name (that is, does not include a drive indicator and path), INSTALLSHIELD finds the file in the Windows folder. If the file does not exist, it is created in the specified folder if the file is not included in the file name, which is created in the Windows folder. Note If the file name is defined in a path that does not exist, Write profString will fail. SzsectionName
Specify a paragraph name in the .ini file, szkeyName will be inserted or will be modified. Segment names must not be enclosed in the boundaries ([]). Find this segment name is not case sensitive.
SzkeyName
Specifies the unique key to update or delete. If the key to be updated does not exist in the specified segment, it is created. To delete the key, pass an empty string to the parameter szvalue. To delete the entire segment specified by szsectionName (including all entries inside), pass an empty string to the parameter szkeyname.
SzValue
Specifies the value that is assigned to the unique key identified by the SZKeynamW. To delete this button, pass an empty string for this parameter. In order to delete the value of the key, the key itself is reserved, the key is sent to the key.
return value:
0: Indicates that the function successfully writes string to the specified .ini file.
<0: Indicates that the function is not written to the specified .ini file.
annotation:
See WriteProfint's annotation.
