WriteProfString

Feedback

Syntax

WriteProfString (szFileName, szSectionName, szKeyName, szValue);

Description

The WriteProfString function writes a profile string to an .ini file. Depending on the values passed to WriteProfString, it can create a section, delete an entire section, create a unique KEY=VALUE entry, delete a KEY=VALUE entry, or update a key's value.

Note the following important points:

• Because of the way in which Windows caches file changes, you should flush the cache buffer after calls to WriteProfString. (See Comments section below.)
   
  
• Changes made to .ini files can be logged for uninstallation. However, there are some important restrictions to be aware of. For more information, see Uninstalling initialization (.ini) file entries.
   
  
• To write an integer value to an .ini file, call WriteProfInt instead.
   
  
• Use the AddProfString and ReplaceProfString functions when you want to modify the System.ini file.

Parameters

szFileName

Specifies the name of the .ini file. If the filename is unqualified (that is, if a drive designation and path are not included), InstallShield searches for the file in the Windows folder. If the file does not exist, it is created in the specified folder; if a path is not included in filename, the file is created in the Windows folder. Note that if the filename is qualified with a path that does not exist, WriteProfString will fail.

szSectionName

Specifies the name of the .ini file section to search for szKeyName. The section name should not be enclosed within delimiting brackets ( [ ] ). The search for this name is not case sensitive.

szKeyName

Specifies the unique key to be updated or deleted. If a key that is to be updated does not exist, it is created. To delete the key specified here, pass a null string ("") in szValue. To delete the entire section specified by szSectionName, including all entries within that, pass a null string ("") in this parameter.

szValue

Specifies the value to assign to the unique key identified by szKeyName. To delete the key, pass a null string ("") in this parameter. To delete the value of the key but retain the key itself , pass a blank space in this parameter.

Return values

0

Indicates that the function successfully wrote the string to the specified .ini file.

< 0

Indicates that the function was unable to write the string to the specified .ini file.

Comments

• The WriteProfString function uses the Windows API WritePrivateProfileString to access the .ini file. Therefore, its functionality is limited by the functionality provided by the Windows API. Consult the Microsoft Windows manual for more information on .ini files.
   
  
• Windows 95 and later cache .ini files, which can cause a delay in writing changes to the specified files. This in turn can interfere with subsequent file operations, such as calls to CopyFile and XCopyFile. Therefore, you should flush the cache buffer after using WriteProfString if you are using file operations shortly afterward. Simply call WriteProfString with null parameters to force Windows 95 or later to write the data to the .ini file immediately:

         WriteProfString ("c:\\test.ini", "Windows", "KeyboardDelay", "100");
         WriteProfString ("","","",""); //null string ("") for all four parameters

         //CopyFile should now have access to updated file.
         CopyFile ("c:\\test.ini", "c:\\temp\\test.ini");