 |
||||||||||||||||||||||
A
special Focus Section of Visual Basic Explorer
Examples using the API functions.The two sets of API functions provide identical functionality. The only difference being which .INI file is accessed. For this reason, the examples I give will only use the API functions that access "private" .INI files (e.g., GetPrivateProfileString) and not the ones that access the WIN.INI file exclusively (e.g., GetProfileString).When describing strings containing NULL characters, I'll use "ø" to represent a NULL character. For example, the list "AøBøCøø" contains the letters "A", "B" and "C" delimited by NULLs and terminated with two NULLs.
Let's define a few variables and a constant that we'll use throughout the examples: Const sFile As String = "MyINI.ini"As we progress through the examples, the API calls will access and modify the MyINI.ini file. I'll show what MyINI.ini should look like after each example.
This first write will create the .INI file, the section and the entry. lReturn = WritePrivateProfileString("Options", "Path", "C:\Games", sFile) Replace the Options section. sString = "Sound=" & CStr(True) & sNull _ Add a section to hold player #1's statistics. sString = "Name=Brian" & sNull _ Now let's do a few retrievals... Return player #1's high score. lReturn = GetPrivateProfileInt("Player #1", "Score", -1, sFile) Return player #2's high score. Since there isn't a 2nd player, the default value will be returned. lReturn = GetPrivateProfileInt("Player #2", "Score", -1, sFile) Fetch the skill level. sString = String$(10, "*") Fetch all the Options entries. sString = String$(30, "*") Fetch all the section names. sString = String$(25, "*")Notice that lReturn contains the value 19 instead of the expected 18. Normally, lReturn indexes the next-to-last character. However, when retrieving the section names using GetPrivateProfileString or GetProfileString, lReturn indexes the last character. Fetch all the keys in the Options section. sString = String$(20, "*") Lastly, delete the sound option and all of player #1's information. lReturn = WritePrivateProfileString("Options", "Sound", vbNullString, sFile) Case sensitivityFor the most part, section and key names are not case sensitive. That is to say, if a section name is stored in the .INI file as "Options", you could read or write to that section by passing a section name of "OPTIONS" or "options" or even "OpTiOnS" - although I don't know why you'd want to :-)Because of this case insensitivity, you usually can't have two sections or keys with the same name, such as "Options" and "OPTIONS". For example, if you used WriteProfileString to create a key named "Skill", any attempt to add a second key named "SKILL" would only overwrite the value assigned to "Skill". However, when using the WritePrivateProfileSection and WriteProfileSection APIs you could place duplicate key names into the list of entries, which would then get written to the specified section. To retrieve the values for these duplicate keys, you'd have to use the GetPrivateProfileSection and GetProfileSection APIs. For example: sString = "Sound=True" & sNull _results in: Adding duplicate section names is a little trickier. Putting one or more trailing spaces at the end of a section or key name causes the APIs to distinguish between upper and lower case. For example, consider the following API calls: 'No spaces after either "Options" or "Sound".Executing these four API calls results in the .INI file containing the following: In order to distinguish these section and key names when retrieving the values, you'll need to add the extra space to the section and key names when calling GetPrivateProfileString. Even though the API calls exhibit unexpected behaviors, I don't suggest that these (or any other) undocumented "features" be utilized. It would be a mistake to think that all future versions of the API will forever continue to allow such behavior. I only mention these behaviors in case you experience some "weird" results when using these APIs - like I did when testing my code for this tutorial! Accessing .INI files with "class"One of the more unfortunate aspects of these API functions is that they use a special parameter value to yield special results. An example of this is passing vbNullString to GetPrivateProfileString and GetProfileString in order to retrieve a list of section or key names. Besides being a poor programming practice, the use of special parameter values can be confusing.Another problem is the need to pre-size the string that will contain the return value. It's difficult to know how long to make it. There's really only one way to deal with this issue: keep increasing the length until the value fits. To say the least, this situation is a nuisance. A third problem is dealing with lists. The API was written with languages like C++ in mind. As a result, Visual Basic programmers have to deal with the special value of NULL in the return value. If the API had been written for Visual Basic, lists would be returned as an array of strings, instead of a single NULL-delimited string. To avoid these, and other, issues, I created two classes which encapsulate all the details of the API's idiosyncrasies. The CPrivateINI class encapsulates the GetPrivateProfileInt, GetPrivateProfileSection, GetPrivateProfileString, WritePrivateProfileSection and WritePrivateProfileString API functions. The CWinINI class encapsulates the GetProfileInt, GetProfileSection, GetProfileString, WriteProfileSection and WriteProfileString API functions. You can download the classes and an accompanying test project here. Accompanying the project is the file "Class Documentation.html". This file, along with in-line documentation within the class modules, contains a description of the class modules' interfaces (public properties and methods). You can view this documentation file online here. The Test ProjectThere are ten forms in the test project. The first is used to test CPrivateINI, the second (accessed through a menu option) is used to test CWinINI and the third gives a working example of what can happen when you change a key in the WIN.INI file.When testing CPrivateINI, the first thing you must do is assign the name of a .INI file and click "Set INIFile":
When browsing a .INI file, the first thing you may want to do is take a look at all the section names. Simply click the "GetSections" buttons:
To view the keys of a particular section, enter the section's name and press either the "GetKeys" button:
To view all the entries of a particular section, enter the section's name and press either the "GetEntries" or "GetPairs" button:
To view the value of a particular key, enter the section and key names then press either the "GetValue" or "GetLongValue" button:
To test the CWinINI class, we'll have to go to a different screen. Select the menu option shown here:
As you can see, both forms look nearly identical. In the following screen-shot, I've entered the section name "Desktop" and pressed the "GetEntries" button:
The only difference between the two is that the CWinINI test form does not have a place for you to enter the name of the .INI file - it's always WIN.INI. Instead, there's a button labeled "Test Calculator Setting ..." - go ahead, press it:
Conclusion.INI files are very useful for saving user options and other data that your program wants to remember. But accessing .INI files through the API can be difficult and confusing. To help remove some of these hurdles, I created the CPrivateINI and CWinINI classes. Add these files to your own projects or compile them into a .DLL - either way, I think you'll appreciate not having to deal directly with the API for .INI file access. |
||||||||||||||||||||||
