![Demo app screenshot](/KB/winsdk/reg_settings/reg_settings01.jpg)
Introduction
CRegSettings
is a simple class that can be used for storing settings inside registry, with as much trouble as with calling AfxMessageBox
. Well, anyways, it is now 3 A.M. and I have to get up in a few short hours, so I'll try to make this quick and easy..
CRegSettings
is a lightweight wrapper for system registry. Storing and reading data from registry with this class is a matter of a single line of code - a call to Read
/Write
members of the class.
One could say that all this is for nothing, since we have WritePrivateProfileString
and its companions, but let me remind you what Platform SDK says: "This function is provided only for compatibility with 16-bit versions of Windows. Applications should store initialization information in the registry."
On the other hand, there is CWinApp::WriteProfileString
and its friends, but as you will see soon, CRegSettings
offers a bit better and more complex structuring of your settings, by allowing you to have subkey of a subkey of subkey of a...you get it.
Using the code
To begin using CRegSettings
, #include
its header and off you go!:-) After creating an object of CRegSettings
type, you need to set its company and/or application name. Because the class opens HKEY_CURRENT_USER\Software
, it will need company and/or application name to use as subkeys of KHCU\Software
. For example:
CRegSettings settings;
settings.SetCompanyName( "SprdSoft Inc." );
settings.SetAppName( "SomeVeryImportantApplication" );
The code above will cause all your settings to be stored in this key:
HKEY_CURRENT_USER\Software\SprdSoft Inc.\SomeVeryImportantApplication
Here is the API:
void SetUseFlushing( BOOL bUseFlushing = TRUE )
void SetAppName( LPCTSTR szAppName )
void SetCompanyName( LPCTSTR szCompanyName )
CString GetAppName() const
CString GetCompanyName() const
BOOL GetUseFlushing() const
static CString GetLastErrorText();
BOOL DeleteAll( BOOL bDeleteCompany = FALSE );
BOOL Write( LPCTSTR szKey, LPCTSTR szName, DATA_TYPE value );
BOOL Read( LPCTSTR szKey, LPCTSTR szName, DATA_TYPE& value );
Where DATA_TYPE
can be one of the following: UCHAR
, char
, USHORT
, short
, UINT
, int
, ULONG
, long
, float
, double
, CString
, or LPVOID
data. Any function returning BOOL
returns TRUE
on success and FALSE
on failure (now, that's a surprise..).
Special care should be taken when working with LPVOID
data and reading string values. Check out the demo app and browse the source code for info.
Here is a small example:
CRegSettings settings;
settings.SetCompanyName( "SprdSoft Inc." );
settings.SetAppName( "Some Stupid App" );
BOOL result = FALSE;
float number = 5.1f;
result = settings.Write( "SomeSubkey\\SomeOtherSubkey/SubkeysSubkey",
"tha_value", float );
if ( result == FALSE )
{
CString sz = settings.GetLastErrorText();
AfxMessageBox( sz );
}
Notice the ability to use slash and/or backslash as you want to. Reading is pretty much the same.
Points of Interest
Flushing - to find out why (not to) use flushing for registry keys, refer to MSDN / Platform SDK on topic RegFlushKey
under remarks. (In short: it needs much system resources, so it's not recommended..)
GetLastErrorText()
- if any of the functions inside CRegSettings
class fails and returns false, this is how you get the text to (eventually) display to user. This function just wraps up GetLastError()
and FormatMessage()
- info available in MSDN.
bDeleteCompany
flag - very important! If you want to delete all of your app's settings, you call DeleteAll()
. If bDeleteCompany
flag is FALSE
then only the app's subkey will be deleted. If you set bDeleteCompany
to TRUE
, your entire company's key and all its subkeys are removed. Do not use this unless you're really sure you want (like in the demo app)! You can read some more in the source file.
You will notice that SHDeleteKey
is used in DeleteAll()
, and that is only because RegDeleteKey
under NT (and I presume XP too) does not delete unless the key is completely empty.
Important information that everyone on CP already knows, but - just in case, I give you a copy/paste text from MSDN:
"Value lengths are limited by available memory. Long values (more than 2048 bytes) should be stored as files with the filenames stored in the registry. This helps the registry perform efficiently. Application elements such as icons, bitmaps, and executable files should be stored as files and not be placed in the registry."
In other words, don't store too big pieces of data in registry. (-:
Conclusion
Well, that's all. I haven't found any bugs (yet..), so feel free to explore and crash your PC. (-: Since everything is pretty much straightforward, there is not much to say here. If you find it useful, use it, modify it, launch nuclear missiles with it (but do let me know about this one), and of course, print it and use it as toilet paper. Feedback is, of course, always appreciated. Everything is Copylefted by me (T1TAN) and SprdSoft Inc. But free for use of any kind except selling the source code. Right, like anyone would try to sell this... (-:
History
- 31.10.2004 - initial release.