AppSettings v1.27 A set
of C++ classes to encapsulate Application Settings
Welcome to
AppSettings, a collection of freeware C++ classes to encapsulate
reading and writing application configuration settings. The supported output
formats are:
- Per user in the Registry (HKEY_CURRENT_USER\Software\"Company Name"\"Product
Name"\"Product Version") via the class CHKCUAppSettings
- Per machine in the Registry (HKEY_LOCAL_MACHINE\Software\"Company Name"\"Product
Name"\"Product Version") via the class CHKLMAppSettings
- Service parameters in the registry (HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\"Service
Name"\Parameters) via the class CServicesAppSettings. This means that you
can use this class in conjunction with the author's own
CNTService class framework in
preference to the functions for configuration settings provided by that framework.
- A standard windows ini file via the class CIniAppSettings
- An XML file via the class CXMLAppSettings. Internally this class uses the
MSXML parser to create and parse the XML.
- A JSON file via the class CJSONAppSettings. Internally this class uses the
JSON++ library of the author to create and parse the
JSON.
The ini, xml and json file locations can be:
- A per user roaming file stored in "c:\users\<User Name>\Application
Data\"Company Name"\"Product Name"\"Product Version"
via the method CIniAppSettings::GetRoamingDataFileLocation.
- A per user non-roaming file normally stored in "c:\users\<User Name>\Local
Settings\Application Data\"Company Name"\"Product Name"\"Product
Version" via the method CIniAppSettings::GetNonRoamingDataFileLocation.
- A per computer (non-user specific and non-roaming) file stored in "c:\users\All
Users\Application Data\"Company Name"\"Product Name"\"Product
Version" via the method CIniAppSettings::GetPerComputerDataFileLocation.
- A file in the same directory as the current process via the method CIniAppSettings::GetCurrentProcessIniFileLocation.
Note, that using this location for an ini or xml file is not a good idea for
security reasons.
- Any other location via a call to CIniAppSettings::SetIniFile, CXMLAppSettings::SetXMLFile
or CJSONAppSettings::SetJSONFile.
Features
- 6 different output formats are supported as mentioned above.
- To keep the API's as consistent as possible between each of the 5 main classes,
they all implement a COM like interface called "IAppSettings". This
concept is similar to a COM or .NET interface and allows you to easily swap
the output formats without having to rewrite your Get... / Write... code. The
API consists of the functions defined in the IAppSettings virtual base class
in AppSettings.h"
- The API's are loosely based on the persistence functions built into MFC's
CWinApp class which support the HKCU registry and simple ini files. Changing
your code to support AppSettings should be relatively simply. You then quickly
gain output format independence and easy access to the locations which MS considers
best practice for application settings.
- The classes hides the low level details of manipulating an XML DOM if all
you want in your XML file is some simple application settings.
- Works equally well in Unicode as well as ASCII builds.
- The classes make use of exceptions to report errors to help client code
which is developed to be as robust as possible.
- The registry and xml output format can also be optionally flushed upon a
write or left to be lazy written.
- The xml output format can be optionally "pretty printed".
- Unlike the MFC CWinApp persistence functions, these classes throw exceptions
when a value is not located. This allows you to easily distinguish from when
a configuration setting is present and is the default value and when it is not
present. Your client code should expect these unexpected conditions and handle
them by catching the "CAppSettingsException*\CAppSettingsException&"
exceptions which are throw in these cases.
The enclosed zip file contains the AppSettings
source code and a simple VC2017 console based test app to exercise all the classes.
Copyright
- You are allowed to include the source code in any product (commercial, shareware,
freeware or otherwise) when your product is released in binary form.
- You are allowed to modify the source code in any way you want except you
cannot modify the copyright details at the top of each module.
- If you want to distribute source code with your application, then you are
only allowed to distribute versions released by the author. This is to maintain
a single distribution point for the source code.
Updates
v1.27 (5 February 2025)
- Updated copyright details.
- Updated GetModuleFileName calls to handle path length > _MAX_PATH.
- Reworked CIniAppSettings::GetCurrentProcessIniFileLocation to use
std::filesystem::path.
v1.26 (3 October 2023)
- Optimized construction of various std::vector and std::[w]string
instances throughout the codebase.
v1.25 (14 May 2023)
- Updated copyright details
- Updated module to indicate that it needs to be compiled using
/std:c++17. Thanks to Martin Richter for reporting this issue.
v1.24 (30 January 2022)
- Updated copyright details.
- Fixed more static code analysis warnings in Visual Studio 2022.
- Updated the code to use C++ uniform initialization for all variable
declarations.
v1.23 (17 March 2020)
- Updated copyright details.
- Fixed more Clang-Tidy static code analysis warnings in the code.
v1.22 (27 November 2019)
- Changed the default parameter lpszDefault in
IAppSettings::GetProfileString from nullptr to _T(""). This avoids problems
where the default value is actually returned from this method. Thanks to
Rene M. Laviolette for reporting this bug.
v1.21 (26 May 2019)
- Removed the String CAppSettingsException::GetErrorMessage method. This
avoids compile problems when the code is compiled in a project which is not
using C++ 17.
- Fixed up other compile problems in the module when the code is
compiled in a project which is not using C++ 17.
v1.20 (22 April 2019)
- Updated copyright details
- Updated the code to clean compile on VC 2019
v1.19 (2 September 2018)
- Fixed a number of compiler warnings when using VS 2017 15.8.2
- Updated the code to work with the latest version of JSON++
v1.18 (29 July 2018)
- Updated copyright details.
- Fixed a number of C++ core guidelines compiler warnings. These
changes mean that the code will now only compile on VC 2017 or later.
- Removed code path which supported CAPPSETTINGS_MFC_EXTENSIONS define
- Reworked the various GetBinary methods to use a std::vector<BYTE>
parameter or return value.
- Reworked the various GetSections methods to return a std::vector<String>
- Reworked the various GetSection methods to return a std::vector<String>
- Reworked all usage of ATL::CHeapPtr to now use std::vector<BYTE>
- Replaced BOOL throughout the codebase with bool.
v1.17 (21 December 2017)
- Added code to CJSONAppSettings::GetInt to validate the JSON data type.
- Added code to CJSONAppSettings::GetString to validate the JSON data
type.
- Added code to CJSONAppSettings::GetDocumentNode to validate the JSON
data type.
- Added code to CJSONAppSettings::GetSectionNode to validate the JSON data
type.
- CJSONAppSettings::WriteInt now writes the integer value out as a JSON
number.
v1.16 (20 December 2017)
- Added support for JSON output via the author's JSON++ classes.
v1.15 (25 November 2017)
- Updated the code to compile cleanly when
_ATL_NO_AUTOMATIC_NAMESPACE is defined.
v1.14 (21 September 2017)
- Replaced CString::operator LPC*STR() calls throughout the codebase with
CString::GetString calls
- Replaced NULL throughout the codebase with nullptr. This means
that the minimum requirement for the framework is now VC 2010.
- Replaced LONG with LSTATUS for all registry return values
throughout the codebase.
v1.13 (21 March 2017)
- Updated copyright details.
- Updated the code to compile cleanly on VC 2017
v1.12 (2 January 2016)
- Updated copyright details.
- The code now uses wostringstream and ostringstream instead of wstringstream
and stringstream.
v1.11 (13 December 2015)
- Optimized usage of ATL::CW2T calls in Unicode builds
v1.10 (12 December 2015)
- Verified code compiles cleanly in VC 2015.
- Added SAL annotations to all the code.
- CRegistryAppSettings::GetInt now throws an exception if the returned data
type from the registry is not REG_DWORD.
- CRegistryAppSettings::GetString now throws an exception if the returned
data type from the registry is not REG_SZ.
- CRegistryAppSettings::GetBinary now throws an exception if the returned
data type from the registry is not REG_BINARY.
- CRegistryAppSettings::GetStringArrayFromRegistry now throws an exception
if the returned data type from the registry is not REG_MULTI_SZ.
- CIniAppSettings::GetBinary now throws an exception if the returned data
length is not even (a requirement because of how the data is written to the
ini files by WriteBinary).
- Fixed an issue in CIniAppSettings::GetStringArray when a empty BLOB was
returned from GetBinary.
- CXMLAppSettings::GetBinary now throws an exception if the returned data
length is not even (a requirement because of how the data is written to the
ini files by WriteBinary).
- Reworked the pretty print support for MSXML to use SAX writer instead of
writing text nodes directly.
- CRegistryAppSettings::GetString now handles non null terminated data as
returned from the registry.
- Updated CRegistryAppSettings::GetSection to handle value name lengths >
4096.
- Updated CRegistryAppSettings::GetStringArrayFromRegistry now handles non
doubly null terminated data as returned from the registry.
- Fixed a bug in CRegistryAppSettings::SetStringArrayIntoRegistry where the
code would not correctly set the cbData parameter when calling the RegSetValueEx
API when compiled in UNICODE mode.
- Reworked the classes to optionally compile without MFC. By default the classes
now use STL classes and idioms but if you define CAPPSETTINGS_MFC_EXTENSIONS
the classes will revert back to the MFC behaviour.
v1.09 (4 January 2015)
- Updated copyright details.
- Updated the code to clean compile in VC 2010 - VC 2013.
v1.08 (19 March 2009)
- Updated copyright details.
- Updated the sample app solution settings to use more reasonable defaults
- The IAppSettings interface now supports a new GetSections method. This returns
all the root sections which a configuration file has. Thanks to Rolf Kristensen
for prompting this nice addition to the classes.
- Updated the IAppSettings::GetSection method to support a boolean "bWithValues"
parameter which determines if the returned string array should or should name
include the values. This allows client code to easily get all the sections names.
Thanks to Rolf Kristensen for providing this nice addition to the classes.
- Reworked most of the internal code which does heap allocations using "new"
to instead now use ATL::CHeapPtr.
v1.07 (6 June 2008)
- Updated copyright details.
- Updated sample app to clean compile on VC 2008
- The code has now been updated to support VC 2005 or later only.
- Code now compiles cleanly using Code Analysis (/analyze)
v1.06 (28 December 2007)
- CAppSettingsException::GetErrorMessage now uses Checked::tcsncpy_s if compiled
using VC 2005 or later.
v1.05 (24 December 2007)
v1.04 (5 July 2007)
- Added support for "Pretty Printing" to the CXMLAppSettings class.
This is achieved through an additional parameter to the constructor.
v1.03 (6 January 2007)
- Updated copyright details.
- Fixed a bug in CRegistryAppSettings::SetStringArrayIntoRegistry related
to use of _tcscpy_s
- Fixed a bug in CIniAppSettings::WriteStringArray related to use of _tcscpy_s
- Fixed a bug in CXMLAppSettings::WriteStringArray related to use of _tcscpy_s
v1.02 (19 August 2006)
- Fixed compile problems when code is compiled in a mixed MFC / ATL project.
- Addition of "WriteProfile..." functions to IAppSettings which
provides similar functionality to the MFC CWinApp functions of the same name.
These new functions allow you to ignore errors reading a value and instead return
a default value.
- Removed the MFC C++ runtime macros from CAppSettingsException as they were
not really required.
v1.01 (29 July 2006)
- All AppSettings classes now support "GetSection" and "WriteSection"
methods. These new functions are modelled on the "GetPrivateProfileSection"
and "WritePrivateProfileSection" Win32 API calls. Thanks to Brad Bruce
for suggesting these updates.
- Made the AfxThrowWin32AppSettingsException function a member of IAppSettings
and renamed it to ThrowWin32AppSettingsException
- Made the AfxThrowCOMAppSettingsException function a member of IAppSettings
and renamed it to ThrowCOMAppSettingsException
- Code now uses newer C++ style casts instead of C style casts.
- Made all the WriteBinary methods now accept a const BYTE* parameter instead
of LPBYTE
- Updated the code to clean compile on VC 2005
- Fixed a bug in CXMLAppSettings::GetBinary where returned binary data was
being returned incorrectly.
v1.0 (11 June 2006)