CascadeSettings Class Reference

an easy to use settings class More...

#include <cascade/util/CascadeSettings.h>

Inheritance diagram for CascadeSettings:

List of all members.

Public Types
typedef bool()	IntegerValueEnumProc (const CascadeString &variableName, const s32 value, void *pClientData)
typedef bool()	StringValueEnumProc (const CascadeString &variableName, const CascadeString &value, void *pClientData)
Public Member Functions
	CascadeSettings (const CascadeString &sectionName)
virtual	~CascadeSettings ()
	sectionName the section name for the settings
bool	SectionExists ()
bool	CreateSection ()
bool	ReadStringValue (const CascadeString &variableName, CascadeString &valueToSet)
bool	WriteStringValue (const CascadeString &variableName, const CascadeString &value)
bool	ReadIntegerValue (const CascadeString &variableName, s32 &valueToSet)
bool	WriteIntegerValue (const CascadeString &variableName, const s32 &value)
void	Flush ()
void	DeleteIntegerValue (const CascadeString &variableName)
void	DeleteStringValue (const CascadeString &variableName)
	variableName the variable to delete
void	DeleteSection ()
	variableName the variable to delete
bool	EnumerateIntegerValues (IntegerValueEnumProc *pEnumProc, void *pClientData)
bool	EnumerateStringValues (StringValueEnumProc *pEnumProc, void *pClientData)

---

Detailed Description

an easy to use settings class

Skip the description

CascadeSettings provides an easy method for Cascade programs to get and set persistent configuration variables. A CascadeSettings class instance is instantiated with a CascadeString that specifies the section the settings apply to. For example, an application named "DonsCoolApp" written by a developer affiliated with woodward.org might use a section named "org.woodward.DonsCoolApp". All Roku apps use sections of the form "com.roku.XXX".

When a CascadeSettings class instance is instantiated, the persistent backing data for the section may or may not exist. This can be determined by calling SectionExists(). If the section does not exist and the client wants to create the section, then CreateSection() should be called.

Within a section, string variable names are mapped to string or integer values, or both. If a variable does not exist with a string or integer value, the corresponding Read() function will return false. Variable names may be added to the persistent store for the section by calling the appropriate Write() function.

Example:

    CascadeSettings settings(CascadeString("com.roku.deschutes.videosettings"));
    bool bSectionCreated = settings.SectionExists();
    if (! bSectionCreated) bSectionCreated = settings.CreateSection();
    if (! bSectionCreated) { /* bogus! */ return; }

    // I now know that the section "com.roku.deschutes.videosettings" exists!!
    CascadeString outputWidthVariableName("OutputWidth");
    s32 nOutputWidth = 0;
    if (settings.ReadIntegerValue(outputWidthVariableName, nOutputWidth))
    {
   		// the output width was read from the settings
    }
    else
    {
   		// the output width is not in the settings, set it to my default
   		nOutputWidth = 1280;
   		settings.WriteIntegerValue(outputWidthVariableName, nOutputWidth);
    }
    

---

class CascadeSettings

---

Member Typedef Documentation

typedef bool() CascadeSettings::IntegerValueEnumProc(const CascadeString &variableName, const s32 value, void *pClientData)

Callback function for enumerating integer values Clients provide their own IntegerValueEnumProc to the EnumerateIntegerValues() function. Your custom IntegerValueEnumProc will get called back by the EnumerateIntegerValues() function, one for each integer variable contained in the section Parameters: variableName  the name of the integer variable value  the value of the integer variable pClientData  the void * pClientData passed thru from EnumerateIntegerValues() Returns: You should return true to continue enumeration, false to abort it Note: Do not call DeleteIntegerValue() or WriteIntegerValue() from within the callback See also: EnumerateIntegerValues()

typedef bool() CascadeSettings::StringValueEnumProc(const CascadeString &variableName, const CascadeString &value, void *pClientData)

Callback function for enumerating string values Clients provide their own StringValueEnumProc to the EnumerateStringValues() function. Your custom StringValueEnumProc will get called back by the EnumerateStringValues() function, one for each string variable contained in the section Parameters: variableName  the name of the string variable value  the value of the string variable pClientData  the void * pClientData passed thru from EnumerateStringValues() Returns: You should return true to continue enumeration, false to abort it Note: Do not call DeleteStringValue() or WriteStringValue() from within the callback See also: EnumerateStringValues()

---

Constructor & Destructor Documentation

CascadeSettings::CascadeSettings (  const CascadeString &  sectionName  )

constructs a CascadeSettings object for the specified section The CascadeSettings constructor constructs a settings instance for the

virtual CascadeSettings::~CascadeSettings (   )  [virtual]

sectionName the section name for the settings destructor This is the CascadeSettings destructor.

---

Member Function Documentation

bool CascadeSettings::CreateSection (   )

creates the section if it does not already exist CreateSection() creates the section if it doesn't already exist. Returns: true if the section exists or was created succesfully, false if the section could not be created

void CascadeSettings::DeleteIntegerValue (  const CascadeString &  variableName  )

deletes the value associated with an integer variable DeleteIntegerValue() deletes the value associated with an integer variable.

void CascadeSettings::DeleteSection (   )

variableName the variable to delete deletes the section and all values DeleteSection() deletes the section and all of its variables

void CascadeSettings::DeleteStringValue (  const CascadeString &  variableName  )

variableName the variable to delete deletes the value associated with a string variable DeleteIntegerValue() deletes the value associated with a string variable.

bool CascadeSettings::EnumerateIntegerValues (  IntegerValueEnumProc *  pEnumProc, void *  pClientData )

enumerates integer variable values in the section call EnumerateIntegerValues() to enumerate the integer variables within the section. Parameters: pEnumProc  the integer variable enum proc pClientData  the void * pClientData passed straight through to your enum proc Returns: true if enumeration carried through to completion, false if it was aborted

bool CascadeSettings::EnumerateStringValues (  StringValueEnumProc *  pEnumProc, void *  pClientData )

enumerates string variable values in the section call EnumerateStringValues() to enumerate the string variables within the section. Parameters: pEnumProc  the string variable enum proc pClientData  the void * pClientData passed straight through to your enum proc Returns: true if enumeration carried through to completion, false if it was aborted

void CascadeSettings::Flush (   )

flushes settings to persistent store Flush() forces any pending changes in settings to be written to persistent store. This is unnecessary on the HD1000 and is used on SoundBridge to force flush changes to the serial flash prior to a software reboot.

bool CascadeSettings::ReadIntegerValue (  const CascadeString &  variableName, s32 &  valueToSet )

reads the integer value for a variable within the section ReadIntegerValue() reads an integer value for a variable within the section.

bool CascadeSettings::ReadStringValue (  const CascadeString &  variableName, CascadeString &  valueToSet )

reads the string value for a variable within the section ReadStringValue() reads a string value for a variable within the section.

bool CascadeSettings::SectionExists (   )

determines whether or not the section exists SectionExists() determines whether or not the section exists. Returns: whether or not the section exists

bool CascadeSettings::WriteIntegerValue (  const CascadeString &  variableName, const s32 &  value )

writes an integer value for a variable to the section WriteIntegerValue() writes an integer value for a variable to the section.

bool CascadeSettings::WriteStringValue (  const CascadeString &  variableName, const CascadeString &  value )

writes a string value for a variable to the section WriteStringValue() writes a string value for a variable to the section.

---

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

• CascadeSettings.h

---