What are .INI files? .INI (pronounced dot in-ee or just in-ee) files are plain-text files used to store information that a program wants to "remember" the next time that it's run.  A few examples of the kinds of data that can be kept in .INI files are: user preferences screen size and position most recently used files high scores Officially, Microsoft has claimed that .INI files are obsolete, suggesting that the registry should be used instead. However, .INI files remain a valuable repository. They're easier to inspect, manually edit and remove. Learn all about them in this great tutorial by Brian P. Duckworth. << Main] [Next >>

Besides being called .INI files, these files are also known by the terms initialization files and profile files.  For purposes of this tutorial, I will only refer to them as .INI files.

The most well-known .INI file is the WIN.INI file.  Windows, and certain applications, keep saved settings in this file.  We'll talk more about the WIN.INI file later.

The structure of .INI files

.INI files are divided into sections.  Each section starts with a section header that contains a section name enclosed in square brackets, such as:

[section name]

Within each section are zero or more entries.  Each entry consists of a key name and value, separated by an equal sign, such as:

key name=value

As an example, the WIN.INI file contains a section that holds information about the desktop's properties:

[Desktop]
Wallpaper=(None)
TileWallpaper=1
WallpaperStyle=0
Pattern=(None)

As you can see, I have a really boring desktop! :-)

On Windows NT systems, most sections of the WIN.INI (and other system .INI files) are mapped into the registry.  That is to say, Windows intercepts certain requests to access the WIN.INI and, instead, accesses the registry.  To determine which sections are mapped in this way, refer to the registry key:

HKEY_LOCAL_MACHINE\Software\Microsoft\Windows NT\CurrentVersion\IniFileMapping

Registry access is beyond the scope of this tutorial.  Additional resources on the registry and other topics can be found by following the links on the main page of this site.

Lines that begin with a semicolon (;) are considered to be comments.  However, this is only a standard notation; there is nothing to prevent a key name from having a semicolon as its first character.

Editing .INI files

Because .INI files are plain-text files, any text editor or word processor can be used to modify a .INI file.  However, Microsoft has provided several APIs that can be used to manipulate .INI files programmatically.  It is these APIs that will be the focus of the rest of this tutorial.

Accessing .INI files through the API

There are ten (10) API functions that allow access to .INI files.  Half of these functions allow access exclusively to the WIN.INI file.  The other half allows access to any .INI file (including WIN.INI).  Like all API calls, Visual Basic requires that you use the Declare statement to reference these functions.  The following section describes each of the functions used to access .INI files.

Important terms used in the function descriptions

NULL: A NULL character is equivalent to Chr$(0).  All string values returned by these APIs are terminated by at least one NULL character.

The API is written in the C programming language.  Strings are stored differently in C than in VB.  In C, all strings end with a NULL.

List: A list is the concatenation of zero or more sub-strings.  The sub-strings are delimited by NULLs and the list is terminated by two NULLs.  For example, if a list contained the two substrings "ABC" and "123", the list could be created like:

Dim sNull As String
Dim sList As String

sNull = Chr$(0)
sList = "ABC" & sNull & "123" & sNull & sNull

A lists is the mechanism used by the API to return multiple string values within a single return value.

vbNullString: This is a special built-in Visual Basic constant.  It is similar to, although not to be confused with, a string with a length of zero characters ("").  Because of it's special properties, the API routines can recognize this value and treat it differently than they would a zero-length string.

Strings as return values from API calls

Another unusual aspect of calling APIs is how they return string values.  APIs will not allocate memory for a string; instead, they expect to be provided a pre-sized string buffer.  To insure that an API does not return more characters than the buffer will hold, the size of the string buffer must also be passed to the API.  Additionally, the API will generally return a numeric value indicating how many bytes of the buffer where used as part of the return value.

GetPrivateProfileInt
Description	Retrieves an integer value from any .INI file
Declaration	Declare Function GetPrivateProfileInt Lib "kernel32" _            Alias "GetPrivateProfileIntA" _                  (ByVal sSectionName As String, _                   ByVal sKeyName As String, _                   ByVal lDefault As Long, _                   ByVal sFileName As String) As Long
Parameters	sSectionName	The name of the section to search.
	sKeyName	The name of the key to retrieve.
	lDefault	The value to return if the desired key does not exist.
	sFileName	The filename of the .INI file to search.  If a pathname is not supplied, it will be assumed that the file exists in the Windows directory.
Return Value	The value found or the default value supplied.  For values that are not valid integers, this function will return as much of the value as can be interpreted as a valid integer.  For example, if the entry where "abc=123xyz", the value of 123 would be returned. If the value is prefixed with "x" or "0x" then the value is converted as a hexadecimal number.  For example, if the entry where "abc=0x1a", the value of &H1A, or 26, would be returned.
GetPrivateProfileSection
Description	Retrieves data for an entire section of any .INI file
Declaration	Declare Function GetPrivateProfileSection Lib "kernel32" _            Alias "GetPrivateProfileSectionA" _                  (ByVal sSectionName As String, _                   ByVal sReturnedString As String, _                   ByVal lSize As Long, _                   ByVal sFileName As String) As Long
Parameters	sSectionName	The name of the section to search.
	sReturnedString	The string variable that will contain the list of entries for the specified section.  The string must be pre-sized to at least lSize bytes.
	lSize	The maximum # of characters to load into sReturnedString.
	sFileName	The filename of the .INI file to search.  If a pathname is not supplied, it will be assumed that the file exists in the Windows directory.
Return Value	The # of characters loaded into sReturnedString.  If the return value is lSize-2, sReturnedString is not large enough to hold the entire value.
GetPrivateProfileString
Description	Retrieves a string value from any .INI file
Declaration	Declare Function GetPrivateProfileString Lib "kernel32" _            Alias "GetPrivateProfileStringA" _                  (ByVal sSectionName As String, _                   ByVal sKeyName As String, _                   ByVal sDefault As String, _                   ByVal sReturnedString As String, _                   ByVal lSize As Long, _                   ByVal sFileName As String) As Long
Parameters	sSectionName	The name of the section to search. If vbNullString is passed, a list of all the sections in the .INI file will be returned in sReturnedString.
	sKeyName	The name of the key to retrieve. If vbNullString is passed, a list of all the key names in the section will be returned in sReturnedString.
	sDefault	The value to return if the desired key does not exist.
	sReturnedString	The string variable that will contain the desired value.  The string must be pre-sized to at least lSize bytes.
	lSize	The maximum # of characters to load into sReturnedString.
	sFileName	The filename of the .INI file to search.  If a pathname is not supplied, it will be assumed that the file exists in the Windows directory.
Return Value	The # of characters loaded into sReturnedString, not counting the terminating NULL character.  If the return value is lSize-1, sReturnedString is not large enough to hold the entire value.
GetProfileInt
Description	Retrieves an integer value from the WIN.INI file
Declaration	Declare Function GetProfileInt Lib "kernel32" _            Alias "GetProfileIntA" _                  (ByVal sSectionName As String, _                   ByVal sKeyName As String, _                   ByVal lDefault As Long) As Long
Parameters	sSectionName	The name of the section to search.
	sKeyName	The name of the key to retrieve.
	lDefault	The value to return if the desired key does not exist.
Return Value	The value found or the default value supplied.  For values that are not valid integers, this function will return as much of the value as can be interpreted as a valid integer.  For example, if the entry where "abc=123xyz", the value of 123 would be returned. If the value is prefixed with "x" or "0x" then the value is converted as a hexadecimal number.  For example, if the entry where "abc=0x1a", the value of &H1A, or 26, would be returned.
GetProfileSection
Description	Retrieves data for an entire section of the WIN.INI file
Declaration	Declare Function GetProfileSection Lib "kernel32" _            Alias "GetProfileSectionA" _                  (ByVal sSectionName As String, _                   ByVal sReturnedString As String, _                   ByVal lSize As Long) As Long
Parameters	sSectionName	The name of the section to search.
	sReturnedString	The string variable that will contain the list of entries for the specified section.  The string must be pre-sized to at least lSize bytes.
	lSize	The maximum # of characters to load into sReturnedString.
Return Value	The # of characters loaded into sReturnedString.  If the return value is lSize-2, sReturnedString is not large enough to hold the entire value.
GetProfileString
Description	Retrieves a string value from the WIN.INI file
Declaration	Declare Function GetProfileString Lib "kernel32" _            Alias "GetProfileStringA" _                  (ByVal sSectionName As String, _                   ByVal sKeyName As String, _                   ByVal sDefault As String, _                   ByVal sReturnedString As String, _                   ByVal lSize As Long) As Long
Parameters	sSectionName	The name of the section to search. If vbNullString is passed, a list of all the sections in the WIN.INI file will be returned in sReturnedString.
	sKeyName	The name of the key to retrieve. If vbNullString is passed, a list of all the key names in the section will be returned in sReturnedString.
	sReturnedString	The string variable that will contain the desired value.  The string must be pre-sized to at least lSize bytes.
	lSize	The maximum # of characters to load into sReturnedString.
Return Value	The # of characters loaded into sReturnedString, not counting the terminating NULL character.  If the return value is lSize-1, sReturnedString is not large enough to hold the entire value.
WritePrivateProfileSection
Description	Writes data to an entire section of any .INI file
Declaration	Declare Function WritePrivateProfileSection Lib "kernel32" _            Alias "WritePrivateProfileSectionA" _                  (ByVal sSectionName As String, _                   ByVal sString As String, _                   ByVal sFileName As String) As Long
Parameters	sSectionName	The name of the section to be replaced.  Any existing entries in the section will be replaced.  If the section does not exist, a new one will be appended to the file.
	sString	The list of entries to write.  The entries in the list must be delimited by a NULL character; the list must be terminated by two NULL characters.
	sFileName	The name of the .INI file to be written.  If a pathname is not supplied, it will be assumed that the file is located in the Windows directory.  If the file does not exist, a new one will be created.
Return Value	Returns non-zero on success; zero on failure.
WritePrivateProfileString
Description	Writes a string value to any .INI file
Declaration	Declare Function WritePrivateProfileString Lib "kernel32" _            Alias "WritePrivateProfileStringA" _                  (ByVal sSectionName As String, _                   ByVal sKeyName As String, _                   ByVal sString As String, _                   ByVal sFileName As String) As Long
Parameters	sSectionName	The name of the section to be written.  If the section does not exist, a new one will be appended to the file.
	sKeyName	The name of the key to be replaced.  Any existing value for this key will be replaced.  If the key does not exist, a new entry will be appended to the section. If vbNullString is passed, the entire section, including the section header, will be deleted from the .INI file.
	sString	The new value to be assigned. If vbNullString is passed, the key will be deleted from the section.
	sFileName	The name of the .INI file to be written.  If a pathname is not supplied, it will be assumed that the file is located in the Windows directory.  If the file does not exist, a new one will be created.
Return Value	Returns non-zero on success; zero on failure.
WriteProfileSection
Description	Writes data to an entire section of the WIN.INI file
Declaration	Declare Function WriteProfileSection Lib "kernel32" _            Alias "WriteProfileSectionA" _                  (ByVal sSectionName As String, _                   ByVal sString As String) As Long
Parameters	sSectionName	The name of the section to be replaced.  Any existing entries in the section will be replaced.  If the section does not exist, a new one will be appended to the file.
	sString	The list of entries to write.  The entries in the list must be delimited by a NULL character; the list must be terminated by two NULL characters.
Return Value	Returns non-zero on success; zero on failure.
WriteProfileString
Description	Writes a string value to the WIN.INI file
Declaration	Declare Function WriteProfileString Lib "kernel32" _            Alias "WriteProfileStringA" _                  (ByVal sSectionName As String, _                   ByVal sKeyName As String, _                   ByVal sString As String) As Long
Parameters	sSectionName	The name of the section to be written.  If the section does not exist, a new one will be appended to the file.
	sKeyName	The name of the key to be replaced.  Any existing value for this key will be replaced.  If the key does not exist, a new entry will be appended to the section. If vbNullString is passed, the entire section, including the section header, will be deleted from the WIN.INI file.
	sString	The new value to be assigned. If vbNullString is passed, the key will be deleted from the section.
Return Value	Returns non-zero on success; zero on failure.

Brian P. Duckworth

<< Main] [Next >>