A class representing a configuration for the application. More...

#include <config.h>

Inheritance diagram for PConfig:

Collaboration diagram for PConfig:

Public Member Functions
	~PConfig ()

Section functions
virtual void	SetDefaultSection (const PString &section)
	Set the default section for variable operations. More...

virtual PString	GetDefaultSection () const
	Get the default section for variable operations. More...

virtual PStringArray	GetSections () const
	Get all of the section names currently specified in the file. More...

virtual PStringArray	GetKeys () const
	Get a list of all the keys in the section. More...

virtual PStringArray	GetKeys (const PString &section) const
	Get a list of all the keys in the section. More...

virtual PStringToString	GetAllKeyValues () const
	Get all of the keys in the section and their values. More...

virtual PStringToString	GetAllKeyValues (const PString &section) const
	Get all of the keys in the section and their values. More...

virtual void	DeleteSection ()
	Delete all variables in the specified section. More...

virtual void	DeleteSection (const PString &section)
	Delete all variables in the specified section. More...

virtual void	DeleteKey (const PString &key)
	Delete the particular variable in the specified section. More...

virtual void	DeleteKey (const PString &section, const PString &key)
	Delete the particular variable in the specified section. More...

virtual PBoolean	HasKey (const PString &key) const
	Determine if the particular variable in the section is actually present. More...

virtual PBoolean	HasKey (const PString &section, const PString &key) const
	Determine if the particular variable in the section is actually present. More...

Get/Set variables
virtual PString	GetString (const PString &key) const
	Get a string variable determined by the key in the section. More...

virtual PString	GetString (const PString &key, const PString &dflt) const
	Get a string variable determined by the key in the section. More...

virtual PString	GetString (const PString &section, const PString &key, const PString &dflt) const
	Get a string variable determined by the key in the section. More...

virtual void	SetString (const PString &key, const PString &value)
	Set a string variable determined by the key in the section. More...

virtual void	SetString (const PString &section, const PString &key, const PString &value)
	Set a string variable determined by the key in the section. More...

virtual PBoolean	GetBoolean (const PString &key, PBoolean dflt=false) const
	Get a boolean variable determined by the key in the section. More...

virtual PBoolean	GetBoolean (const PString &section, const PString &key, PBoolean dflt=false) const
	Get a boolean variable determined by the key in the section. More...

virtual void	SetBoolean (const PString &key, PBoolean value)
	Set a boolean variable determined by the key in the section. More...

virtual void	SetBoolean (const PString &section, const PString &key, PBoolean value)
	Set a boolean variable determined by the key in the section. More...

virtual long	GetInteger (const PString &key, long dflt=0) const

virtual long	GetInteger (const PString &section, const PString &key, long dflt=0) const

virtual void	SetInteger (const PString &key, long value)
	Set an integer variable determined by the key in the section. More...

virtual void	SetInteger (const PString &section, const PString &key, long value)
	Set an integer variable determined by the key in the section. More...

template<typename Enumeration >
Enumeration	GetEnum (const PString &key, Enumeration dflt) const

template<typename Enumeration >
Enumeration	GetEnum (const PString &section, const PString &key, Enumeration dflt) const

template<typename Enumeration >
void	SetEnum (const PString &key, Enumeration value)
	Set an enum variable determined by the key in the section. More...

template<typename Enumeration >
void	SetEnum (const PString &section, const PString &key, Enumeration value)
	Set an enum variable determined by the key in the section. More...

virtual PInt64	GetInt64 (const PString &key, PInt64 dflt=0) const
	Get a 64 bit integer variable determined by the key in the section. More...

virtual PInt64	GetInt64 (const PString &section, const PString &key, PInt64 dflt=0) const
	Get a 64 bit integer variable determined by the key in the section. More...

virtual void	SetInt64 (const PString &key, PInt64 value)
	Set a 64 bit integer variable determined by the key in the section. More...

virtual void	SetInt64 (const PString &section, const PString &key, PInt64 value)
	Set a 64 bit integer variable determined by the key in the section. More...

virtual double	GetReal (const PString &key, double dflt=0) const
	Get a floating point variable determined by the key in the section. More...

virtual double	GetReal (const PString &section, const PString &key, double dflt=0) const
	Get a floating point variable determined by the key in the section. More...

virtual void	SetReal (const PString &key, double value)
	Set a floating point variable determined by the key in the section. More...

virtual void	SetReal (const PString &section, const PString &key, double value)
	Set a floating point variable determined by the key in the section. More...

virtual PTime	GetTime (const PString &key) const
	Get a `PTime` variable determined by the key in the section. More...

virtual PTime	GetTime (const PString &key, const PTime &dflt) const
	Get a `PTime` variable determined by the key in the section. More...

virtual PTime	GetTime (const PString &section, const PString &key) const
	Get a `PTime` variable determined by the key in the section. More...

virtual PTime	GetTime (const PString &section, const PString &key, const PTime &dflt) const
	Get a `PTime` variable determined by the key in the section. More...

virtual void	SetTime (const PString &key, const PTime &value)
	Set a `PTime` variable determined by the key in the section. More...

virtual void	SetTime (const PString &section, const PString &key, const PTime &value)
	Set a `PTime` variable determined by the key in the section. More...

Public Member Functions inherited from PObject
unsigned	GetTraceContextIdentifier () const
	Get PTRACE context identifier. More...

void	SetTraceContextIdentifier (unsigned id)

void	GetTraceContextIdentifier (PObject &obj)

void	GetTraceContextIdentifier (PObject *obj)

void	SetTraceContextIdentifier (const PObject &obj)

void	SetTraceContextIdentifier (const PObject *obj)

virtual	~PObject ()

virtual PObject *	Clone () const
	Create a copy of the class on the heap. More...

template<class CLS >
CLS *	CloneAs () const
	As for Clone() but converts to specified type. More...

virtual PINDEX	HashFunction () const
	This function yields a hash value required by the `PDictionary` class. More...

virtual Comparison	Compare (const PObject &obj) const
	Compare the two objects and return their relative rank. More...

virtual Comparison	CompareObjectMemoryDirect (const PObject &obj) const
	Determine the byte wise comparison of two objects. More...

bool	operator== (const PObject &obj) const
	Compare the two objects. More...

bool	operator!= (const PObject &obj) const
	Compare the two objects. More...

bool	operator< (const PObject &obj) const
	Compare the two objects. More...

bool	operator> (const PObject &obj) const
	Compare the two objects. More...

bool	operator<= (const PObject &obj) const
	Compare the two objects. More...

bool	operator>= (const PObject &obj) const
	Compare the two objects. More...

virtual const char *	GetClass (unsigned ancestor=0) const
	Get the current dynamic type of the object instance. More...

PBoolean	IsClass (const char *cls) const

virtual PBoolean	InternalIsDescendant (const char *clsName) const
	Determine if the dynamic type of the current instance is a descendent of the specified class. More...

__inline const PObject *	PTraceObjectInstance () const

virtual void	PrintOn (ostream &strm) const
	Output the contents of the object to the stream. More...

virtual void	ReadFrom (istream &strm)
	Input the contents of the object from the stream. More...

Static Public Member Functions
static const PString &	DefaultSectionName ()

Static Public Member Functions inherited from PObject
static Comparison	InternalCompareObjectMemoryDirect (const PObject obj1, const PObject obj2, PINDEX size)
	Internal function caled from CompareObjectMemoryDirect() More...

static const char *	Class ()
	Get the name of the class as a C string. More...

static __inline const PObject *	PTraceObjectInstance (const char *)

static __inline const PObject *	PTraceObjectInstance (const PObject *obj)

Protected Attributes
PString	defaultSection
	The current section for variable values. More...

Cached *	m_config

Protected Attributes inherited from PObject
unsigned	m_traceContextIdentifier

Construction
enum	Source { Environment, System, Application, NumSources }
	Description of the standard source for configuration information. More...

	PConfig (Source src=Application)
	Create a new configuration object. More...

	PConfig (Source src, const PString &appname)
	Create a new configuration object. More...

	PConfig (Source src, const PString &appname, const PString &manuf)
	Create a new configuration object. More...

	PConfig (const PString &section, Source src=Application)
	Create a new configuration object. More...

	PConfig (const PString &section, Source src, const PString &appname)
	Create a new configuration object. More...

	PConfig (const PString &section, Source src, const PString &appname, const PString &manuf)
	Create a new configuration object. More...

	PConfig (const PFilePath &filename, const PString &section)
	Create a new configuration object. More...

Additional Inherited Members
Public Types inherited from PObject
enum	Comparison { LessThan = -1, EqualTo = 0, GreaterThan = 1 }
	Result of the comparison operation performed by the `Compare()` function. More...

Protected Member Functions inherited from PObject
	PObject ()
	Constructor for PObject, made protected so cannot ever create one on its own. More...

Friends inherited from PObject

Detailed Description

A class representing a configuration for the application.

There are four sources of configuration information. The system environment, a system wide configuration file, an application specific configuration file or an explicit configuration file.

Configuration information follows a three level hierarchy: file, section and variable. Thus, a configuration file consists of a number of sections each with a number of variables selected by a key. Each variable has an associated value.

Note that the evironment source for configuration information does not have sections. The section is ignored and the same set of keys are available.

The configuration file is a standard text file for the platform with its internals appearing in the form:


     [Section String]
     Key Name=Value String

Member Enumeration Documentation

enum PConfig::Source

Description of the standard source for configuration information.

Enumerator
Environment	The platform specific environment. For Unix, MSDOS, NT etc this is {the} environment current when the program was run. For the MacOS this is a subset of the Gestalt and SysEnviron information.
System	The platform specific system wide configuration file. For MS-Windows this is the WIN.INI file. For Unix, plain MS-DOS, etc this is a configuration file similar to that for applications except there is only a single file that applies to all PWLib applications.
Application	The application specific configuration file. This is the most common source of configuration for an application. The location of this file is platform dependent, but its contents are always the same. For MS-Windows the file should be either in the same directory as the executable or in the Windows directory. For the MacOS this would be either in the System Folder or the Preferences folder within it. For Unix this would be the users home directory.
NumSources

Constructor & Destructor Documentation

PConfig::PConfig ( Source src = Application )

Create a new configuration object.

Once a source is selected for the configuration it cannot be changed. Only at the next level of the hierarchy (sections) are selection able to be made dynamically with an active PConfig object.

Parameters

src	Standard source for the configuration.

PConfig::PConfig	(	Source	src,
		const PString &	appname
	)

Create a new configuration object.

Parameters

src	Standard source for the configuration.
appname	Name of application

PConfig::PConfig	(	Source	src,
		const PString &	appname,
		const PString &	manuf
	)

Create a new configuration object.

Parameters

src	Standard source for the configuration.
appname	Name of application
manuf	Manufacturer

PConfig::PConfig	(	const PString &	section,
		Source	src = `Application`
	)

Create a new configuration object.

Parameters

section	Default section to search for variables.
src	Standard source for the configuration.

PConfig::PConfig	(	const PString &	section,
		Source	src,
		const PString &	appname
	)

Create a new configuration object.

Parameters

section	Default section to search for variables.
src	Standard source for the configuration.
appname	Name of application

PConfig::PConfig	(	const PString &	section,
		Source	src,
		const PString &	appname,
		const PString &	manuf
	)

Create a new configuration object.

Parameters

section	Default section to search for variables.
src	Standard source for the configuration.
appname	Name of application
manuf	Manufacturer

PConfig::PConfig	(	const PFilePath &	filename,
		const PString &	section
	)

Create a new configuration object.

Parameters

filename	Explicit name of the configuration file.
section	Default section to search for variables.

PConfig::~PConfig ( )

Member Function Documentation

static const PString& PConfig::DefaultSectionName ( )

static

virtual void PConfig::DeleteKey ( const PString & key )

virtual

Delete the particular variable in the specified section.

If the section name is not specified then the default section is used.

Note that the variable and key are removed from the file. The key will no longer appear in the GetKeys() function. If you wish to delete the value without deleting the key, use SetString() to set it to the empty string.

Parameters

key	Key of the variable to delete.

virtual void PConfig::DeleteKey	(	const PString &	section,
		const PString &	key
	)

virtual

Delete the particular variable in the specified section.

Parameters

section	Section to use instead of the default.
key	Key of the variable to delete.

virtual void PConfig::DeleteSection ( )

virtual

Delete all variables in the specified section.

If the section name is not specified then the default section is deleted.

Note that the section header is also removed so the section will not appear in the GetSections() function.

virtual void PConfig::DeleteSection ( const PString & section )

virtual

Delete all variables in the specified section.

Parameters

section Name of section to delete.

virtual PStringToString PConfig::GetAllKeyValues ( ) const

virtual

Get all of the keys in the section and their values.

If the section name is not specified then use the default section.

Returns: Dictionary of all key names and their values.

virtual PStringToString PConfig::GetAllKeyValues ( const PString & section ) const

virtual

Get all of the keys in the section and their values.

Parameters

section Section to use instead of the default.

virtual PBoolean PConfig::GetBoolean	(	const PString &	key,
		PBoolean	dflt = `false`
	)		const

virtual

Get a boolean variable determined by the key in the section.

If the section name is not specified then the default section is used.

The boolean value can be specified in a number of ways. The true value is returned if the string value for the variable begins with either the 'T' character or the 'Y' character. Alternatively if the string can be converted to a numeric value, a non-zero value will also return true. Thus the values can be Key=True, Key=Yes or Key=1 for true and Key=False, Key=No, or Key=0 for false.

If the key is not present the value returned is the that provided by the dlft parameter. Note that this is different from the key being present but having no value, in which case false is returned.

Returns: boolean value of the variable.

Parameters

key	The key name for the variable.
dflt	Default value for the variable.

virtual PBoolean PConfig::GetBoolean	(	const PString &	section,
		const PString &	key,
		PBoolean	dflt = `false`
	)		const

virtual

Get a boolean variable determined by the key in the section.

Parameters

section	Section to use instead of the default.
key	The key name for the variable.
dflt	Default value for the variable.

virtual PString PConfig::GetDefaultSection ( ) const

virtual

Get the default section for variable operations.

All functions that deal with keys and get or set configuration values will use this section unless an explicit section name is specified.

Note when the Environment source is being used the default section may be retrieved but it is ignored.

Returns: default section name string.

template<typename Enumeration >

Enumeration PConfig::GetEnum	(	const PString &	key,
		Enumeration	dflt
	)		const

inline

Parameters

key	The key name for the variable.
dflt	Default value for the variable.

References GetInteger().

template<typename Enumeration >

Enumeration PConfig::GetEnum	(	const PString &	section,
		const PString &	key,
		Enumeration	dflt
	)		const

inline

Parameters

section	Section to use instead of the default.
key	The key name for the variable.
dflt	Default value for the variable.

References GetInteger().

virtual PInt64 PConfig::GetInt64	(	const PString &	key,
		PInt64	dflt = `0`
	)		const

virtual

Get a 64 bit integer variable determined by the key in the section.

If the section name is not specified then the default section is used.

If the key is not present the value returned is the that provided by the dlft parameter. Note that this is different from the key being present but having no value, in which case zero is returned.

Returns: integer value of the variable.

Parameters

key	The key name for the variable.
dflt	Default value for the variable.

virtual PInt64 PConfig::GetInt64	(	const PString &	section,
		const PString &	key,
		PInt64	dflt = `0`
	)		const

virtual

Get a 64 bit integer variable determined by the key in the section.

Parameters

section	Section to use instead of the default.
key	The key name for the variable.
dflt	Default value for the variable.

virtual long PConfig::GetInteger	(	const PString &	key,
		long	dflt = `0`
	)		const

virtual

Parameters

key	The key name for the variable.
dflt	Default value for the variable.

Referenced by GetEnum().

virtual long PConfig::GetInteger	(	const PString &	section,
		const PString &	key,
		long	dflt = `0`
	)		const

virtual

Parameters

section	Section to use instead of the default.
key	The key name for the variable.
dflt	Default value for the variable.

virtual PStringArray PConfig::GetKeys ( ) const

virtual

Get a list of all the keys in the section.

If the section name is not specified then use the default section.

Returns: list of all key names.

virtual PStringArray PConfig::GetKeys ( const PString & section ) const

virtual

Get a list of all the keys in the section.

Parameters

section Section to use instead of the default.

virtual double PConfig::GetReal	(	const PString &	key,
		double	dflt = `0`
	)		const

virtual

Get a floating point variable determined by the key in the section.

If the section name is not specified then the default section is used.

If the key is not present the value returned is the that provided by the dlft parameter. Note that this is different from the key being present but having no value, in which case zero is returned.

Returns: floating point value of the variable.

Parameters

key	The key name for the variable.
dflt	Default value for the variable.

virtual double PConfig::GetReal	(	const PString &	section,
		const PString &	key,
		double	dflt = `0`
	)		const

virtual

Get a floating point variable determined by the key in the section.

Parameters

section	Section to use instead of the default.
key	The key name for the variable.
dflt	Default value for the variable.

virtual PStringArray PConfig::GetSections ( ) const

virtual

Get all of the section names currently specified in the file.

A section is the part specified by the [ and ] characters.

Note when the Environment source is being used this will return an empty list as there are no section present.

Returns: list of all section names.

virtual PString PConfig::GetString ( const PString & key ) const

virtual

Get a string variable determined by the key in the section.

If the section name is not specified then the default section is used.

If the key is not present the value returned is the that provided by the dlft parameter. Note that this is different from the key being present but having no value, in which case an empty string is returned.

Returns: string value of the variable.

Parameters

key	The key name for the variable.

virtual PString PConfig::GetString	(	const PString &	key,
		const PString &	dflt
	)		const

virtual

Get a string variable determined by the key in the section.

Parameters

key	The key name for the variable.
dflt	Default value for the variable.

virtual PString PConfig::GetString	(	const PString &	section,
		const PString &	key,
		const PString &	dflt
	)		const

virtual

Get a string variable determined by the key in the section.

Parameters

section	Section to use instead of the default.
key	The key name for the variable.
dflt	Default value for the variable.

virtual PTime PConfig::GetTime ( const PString & key ) const

virtual

Get a PTime variable determined by the key in the section.

If the section name is not specified then the default section is used.

If the key is not present the value returned is the that provided by the dlft parameter. Note that this is different from the key being present but having no value, in which case zero is returned.

Returns: time/date value of the variable.

Parameters

key	The key name for the variable.

virtual PTime PConfig::GetTime	(	const PString &	key,
		const PTime &	dflt
	)		const

virtual

Get a PTime variable determined by the key in the section.

Parameters

key	The key name for the variable.
dflt	Default value for the variable.

virtual PTime PConfig::GetTime	(	const PString &	section,
		const PString &	key
	)		const

virtual

Get a PTime variable determined by the key in the section.

Parameters

section	Section to use instead of the default.
key	The key name for the variable.

virtual PTime PConfig::GetTime	(	const PString &	section,
		const PString &	key,
		const PTime &	dflt
	)		const

virtual

Get a PTime variable determined by the key in the section.

Parameters

section	Section to use instead of the default.
key	The key name for the variable.
dflt	Default value for the variable.

virtual PBoolean PConfig::HasKey ( const PString & key ) const

virtual

Determine if the particular variable in the section is actually present.

This function allows a caller to distinguish between getting a saved value or using the default value. For example if you called GetString("MyKey", "DefVal") there is no way to distinguish between the default "DefVal" being used, or the user had explicitly saved the value "DefVal" into the PConfig.

Parameters

key	Key of the variable.

virtual PBoolean PConfig::HasKey	(	const PString &	section,
		const PString &	key
	)		const

virtual

Determine if the particular variable in the section is actually present.

Parameters

section	Section to use instead of the default.
key	Key of the variable.

virtual void PConfig::SetBoolean	(	const PString &	key,
		PBoolean	value
	)

virtual

Set a boolean variable determined by the key in the section.

If the section name is not specified then the default section is used.

If value is true then the string "True" is written to the variable otherwise the string "False" is set.

Parameters

key	The key name for the variable.
value	New value to set for the variable.

virtual void PConfig::SetBoolean	(	const PString &	section,
		const PString &	key,
		PBoolean	value
	)

virtual

Set a boolean variable determined by the key in the section.

Parameters

section	Section to use instead of the default.
key	The key name for the variable.
value	New value to set for the variable.

virtual void PConfig::SetDefaultSection ( const PString & section )

virtual

Set the default section for variable operations.

All functions that deal with keys and get or set configuration values will use this section unless an explicit section name is specified.

Note when the Environment source is being used the default section may be set but it is ignored.

Parameters

section New default section name.

template<typename Enumeration >

void PConfig::SetEnum	(	const PString &	key,
		Enumeration	value
	)

inline

Set an enum variable determined by the key in the section.

If the section name is not specified then the default section is used.

The value is always formatted as a signed number with no leading or trailing blanks.

Parameters

key	The key name for the variable.
value	New value to set for the variable.

References SetInteger().

template<typename Enumeration >

void PConfig::SetEnum	(	const PString &	section,
		const PString &	key,
		Enumeration	value
	)

inline

Set an enum variable determined by the key in the section.

Parameters

section	Section to use instead of the default.
key	The key name for the variable.
value	New value to set for the variable.

References SetInteger().

virtual void PConfig::SetInt64	(	const PString &	key,
		PInt64	value
	)

virtual

Set a 64 bit integer variable determined by the key in the section.

If the section name is not specified then the default section is used.

The value is always formatted as a signed number with no leading or trailing blanks.

Parameters

key	The key name for the variable.
value	New value to set for the variable.

virtual void PConfig::SetInt64	(	const PString &	section,
		const PString &	key,
		PInt64	value
	)

virtual

Set a 64 bit integer variable determined by the key in the section.

Parameters

section	Section to use instead of the default.
key	The key name for the variable.
value	New value to set for the variable.

virtual void PConfig::SetInteger	(	const PString &	key,
		long	value
	)

virtual

Set an integer variable determined by the key in the section.

If the section name is not specified then the default section is used.

The value is always formatted as a signed number with no leading or trailing blanks.

Parameters

key	The key name for the variable.
value	New value to set for the variable.

Referenced by SetEnum().

virtual void PConfig::SetInteger	(	const PString &	section,
		const PString &	key,
		long	value
	)

virtual

Set an integer variable determined by the key in the section.

Parameters

section	Section to use instead of the default.
key	The key name for the variable.
value	New value to set for the variable.

virtual void PConfig::SetReal	(	const PString &	key,
		double	value
	)

virtual

Set a floating point variable determined by the key in the section.

If the section name is not specified then the default section is used.

The value is always formatted as a signed decimal or exponential form number with no leading or trailing blanks, ie it uses the g formatter from the printf() function.

Parameters

key	The key name for the variable.
value	New value to set for the variable.

virtual void PConfig::SetReal	(	const PString &	section,
		const PString &	key,
		double	value
	)

virtual

Set a floating point variable determined by the key in the section.

Parameters

section	Section to use instead of the default.
key	The key name for the variable.
value	New value to set for the variable.

virtual void PConfig::SetString	(	const PString &	key,
		const PString &	value
	)

virtual

Set a string variable determined by the key in the section.

If the section name is not specified then the default section is used.

Parameters

key	The key name for the variable.
value	New value to set for the variable.

virtual void PConfig::SetString	(	const PString &	section,
		const PString &	key,
		const PString &	value
	)

virtual

Set a string variable determined by the key in the section.

Parameters

section	Section to use instead of the default.
key	The key name for the variable.
value	New value to set for the variable.

virtual void PConfig::SetTime	(	const PString &	key,
		const PTime &	value
	)

virtual

Set a PTime variable determined by the key in the section.

If the section name is not specified then the default section is used.

Parameters

key	The key name for the variable.
value	New value to set for the variable.

virtual void PConfig::SetTime	(	const PString &	section,
		const PString &	key,
		const PTime &	value
	)

virtual

Set a PTime variable determined by the key in the section.

Parameters

section	Section to use instead of the default.
key	The key name for the variable.
value	New value to set for the variable.

Member Data Documentation

PString PConfig::defaultSection

protected

The current section for variable values.

Cached* PConfig::m_config

protected

The documentation for this class was generated from the following files:

config.h

Public Member Functions

Static Public Member Functions

Protected Attributes

Construction

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation