The Preferences Kit: PrefsSection

Derived from:

Declared in: PrefsSection.h

Library:


Overview

A PrefsSection lets you read and write preferences from your application. This class is providing an access to the PrefsServer.


Initializing

When you construct (or otherwise initialize) a PrefsSection, a connection with the preferences server is automatically opened. The connection is closed when you destroy the object.


Constructor and Destructor


PrefsSection()

      PrefsSection(const PrefsServerType serverType, const char* path)


Creates a PrefsSection object. The available values for serverType are:

PS_User: This section is created at the user level (will inherit from the system level)
PS_System: This section is created at the system level
PS_Temp: This section is created at the temporary level

Sections used in the temporary level will never be saved. the only usage of this level is to share data between application.

The path parameter should contain the path of the section.

ex: "application/Metrowerks/Code Warrior"

If the path doesn't exist, it is created.

Once you created the section you can check is the section is valid using the IsValid() method.


~PrefsSection()

      virtual ~PrefsSection()

Destroys the object.


Status Functions


ReadOnly()

      bool ReadOnly(void)


Returns true if we can not write in the section, this is the case when you boot from a CD for instance. Being read only doesn't mean that you can not modify preferences, it just means that changes won't be saved when you will call the destructor.


IsValid()

     bool IsValid(void)

Returns true if we are well connected to the preferences server. The only caseit should return false is when the prefs_server app is not launched.


Reading and Writing Functions


FindBool()

      bool FindBool(const char* entry, bool defValue = false)

Returns the value found in the entry, if the entry doesn't exist, returnsthe default value.


WriteBool()

      void WriteBool(const char* entry, bool value)

write the value in the entry, if the entry doesn't exist it is created.


FindInt32()

      int32 FindInt32(const char* entry, int32 defValue = 0)

Returns the value found in the entry, if the entry doesn't exist, returns the default value.


WriteInt32()

      void WriteInt32(const char* entry, int32 value)

write the value in the entry, if the entry doesn't exist it is created.


FindFloat()

      float FindFloat(const char* entry, float defValue = 0.0)

Returns the value found in the entry, if the entry doesn't exist, returns the default value.


WriteFloat()

      void WriteFloat(const char* entry, float value)

write the value in the entry, if the entry doesn't exist it is created.


FindRect()

      BRect FindRect(const char* entry, BRect defValue = BRect(0.0,0.0,0.0,0.0))

Returns the value found in the entry, if the entry doesn't exist, returns the default value.


WriteRect()

      void WriteRect(const char* entry, BRect value)

write the value in the entry, if the entry doesn't exist it is created.


FindPoint()

      BPoint FindPoint(const char* entry, BPoint defValue = BPoint(0.0,0.0))

Returns the value found in the entry, if the entry doesn't exist, returns the default value.


WritePoint()

      void WritePoint(const char* entry, BPoint value)

write the value in the entry, if the entry doesn't exist it is created.


FindString()

      void FindString(const char* entry, char* value, const uint32 sizeOfValue, const char* defValue = "")

Copies the value from the entry into the string "value". SizeOfValue should contain the size of the value buffer so the length of the string can be stripped to sizeOfValue -1.

ex:

char result[256];
section->FindString("email", result, sizeof(result));


WriteString()

      void WriteString(const char* entry, const char* value)

write the value in the entry, if the entry doesn't exist it is created.


FindData()

      uint32 FindData(const char* entry, void* buffer, const uint32 bufferSize)

Returns the real length of the data stored in the entry (0 if the entry doesn't exists).
Copies the bufferSize first bytes of the value into buffer.


WriteData()

      void WriteData(const char* entry, const void* data, const uint32 len)

write the value in the entry, if the entry doesn't exist it is created.


Misc Functions



void Flush(void);
void DeleteEntry(const char* entry);
bool EntryExists(const char* entry);
bool DeleteSection(const char* sectionName);
void CreateSection(const char* sectionName);
uint32 IsSectionInUse(const char* sectionName);
char* MallocSectionList(void); // returns a list of sections, has to bedisposed using free()
char* MallocEntryList(void); // returns a list of entries, has to be disposedusing free()
void Reset(bool recursive = true);

<Doc not available yet>