Compound list   Compound Members  

QConfigDB Class Reference

The class QConfigDB is used to manage text-based data files with hierarchical structure. More...

List of all members.

Public Members

Public Slots

Signals

Static Public Members

Protected Members

Static Protected Members


Detailed Description

The class QConfigDB is used to manage text-based data files with hierarchical structure.


It is derived from QWidget, so it may be derived to display its contents. The basic implementation here does not display anything to make it a lean class.
Some notes about the philosophy of the configuration database library:

  1. The tasks in managing the structure are shared between the three involved classes KeyValueMap, Section and QConfigDB.
  2. QConfigDB is used for retrieving sections or key-value-maps from the data hierarchy using keys. This keys are either pathes in UNIX style like "section_A/section_B/section_C", where C is a subsection of B which is in turn a subsection of A, or (STL) lists of strings in equivalent style (the first element of the list is treated as the first part of the path, and so on).
  3. Section objects are used to manipulate the tree structure below one particular section.
  4. KeyValueMap objects are used to retrieve and modify the key-value-pairs of one section, but not for its subsections.
Thus, to use the keys of a specific section in the database, you first retrieve it using the get() methods, and then manipulate the KeyValueMap you got. You may also retrieve a pointer to the whole section, if you need access to its subsections, for example. Although this sounds complex, it is a really easy and comprehensive way to write code using tree-structured text files.
See the code examples provided with the library for details.


Member Function Documentation

QConfigDB::QConfigDB(QWidget* parent=0, const char* name=0)

The Qt standard constructor.

virtual QConfigDB::~QConfigDB() [virtual]

The virtual destructor.

bool QConfigDB::get(const QString& key, KeyValueMap*& map)

Get the key-value-map for the section referenced by key.

bool QConfigDB::get(const list<QString>& key, KeyValueMap*& map)

Get the key-value-map for the section referenced by key as key list.

bool QConfigDB::get(const QString& key, Section*&)

Get the address of the specified Section object by its path.

Never delete the section returned to you.

bool QConfigDB::get(const list<QString>& key, Section*&)

Get the address of the specified Section object by a path list.

Never delete the section returned to you.

KeyValueMap* QConfigDB::get()

Get the keys of the toplevel section.

bool QConfigDB::createSection(const QString& key)

Create the section with this path.

All elements of the path that do not exist are created.

bool QConfigDB::createSection(const list<QString>& key)

Create the section with a path like the path list.

All elements of the path that do not exist are created.

bool QConfigDB::load()

Load the file.

See also:
setFileName()

bool QConfigDB::save(const char* header=0, bool force=false)

Save the file.

header will be the comment in the first line of the file. If force is \tt true, a file opened read-only will be switched to read and write mode and back after saving.

See also:
setFileName()

bool QConfigDB::setFileName(const QString& name, bool mustexist=true, bool ro=false)

Set the current file name to name.

Every QConfigDB object requires a file name to be set using this method before the file operations work. setFileName performs checks if the current user may use the file in the requested way. If ro is true, she must have permissions to read the file, if it is false, permission must be given to read and write the file. If mustexist is true, the file must have existed before, if not, it might be created. If any check failes, false is returned and the objects state is not altered. Subsequent calls may be used to check if a file already exists.

bool QConfigDB::storeFileAge()

Store the mtime mark of the file for later check of changes.

QString QConfigDB::fileName()

Give the current filename.

bool QConfigDB::isRO()

Returns if the current file name is set for read only access.

bool QConfigDB::clear()

Clear the whole database.

bool QConfigDB::empty()

Return whether the db is empty (e.g.

the toplevel section is).

bool QConfigDB::lock()

Lock the current file.

Locking is done by creating a file <filename>.lock. QConfigDB-objects will reject opening a file for reading and writing if a lockfile for the filename exists.

bool QConfigDB::unlock()

Unlock the file.

void QConfigDB::watch(bool state)

If watch is true the object watches its file for changes.

A timer is started that checks the file age every second and emits fileChanged() if it has been overridden meanwhile.

bool QConfigDB::checkFileChanged() [slot]

Check for file changes.

This method returns true if the file has been changed on disk after the last reading or saving.

virtual void QConfigDB::changed(QConfigDB*) [virtual, signal]

This signal will be send when the database is cleared or reloaded.

The notification might be needed if pointers or iterators are stored outside the database object as they get invalid after reloading. The signal hands over its this pointer.

virtual void QConfigDB::fileChanged() [virtual, signal]

This signal will notify changes of the database file .

The file will be monitored on disk if watch() has been activated.

const char* QConfigDB::version() [static]

Return a string describing the version.

int QConfigDB::IsLocked(const QString& fn) [static]

Check wether the given file is locked.

The method returns zero if not, a number > zero is the pid of the process locking the file, a number < zero reports an error and indicates that the file is locked.

bool QConfigDB::CheckLockFile(const QString& filename) [static]

Check an existing lock file for its validity.

fn is the name of the DATA file that is locked. As lockfiles often remain when a program crashes, this function checks certain conditions that show that a lockfile is not in use anymore, these are: ° there is no process with the pid in the lockfile, ° the systems boot-time is after the creation of the lockfile. The problem is that, if there is a process with the pid we have, this does not need to be the process that created the lockfile the method returns only false if it is shure that no such process exists. Returns false if the lockfile exists and is definitely stale or there is none, returns true if the lockfile seems to be really valid.

void QConfigDB::CleanLockFiles(int) [static]

The static method CleanLockFiles removes all files in the list LockFiles when called.

Thus this function should be installed as a handler for SIGINT, SIGQUIT, SIGKILL, SIGTERM and other program abortion signals or should be called by the respective handlers.

list<QString> QConfigDB::stringToKeylist(const QString&) [protected]

Transform a given path into a list of strings.

All internal path handling is done with lists.

bool QConfigDB::lock(const QString& file) [protected]

Lock the file.

bool QConfigDB::invariant() [protected]

Debugging aid, called from REQUIRE and ENSURE macros when the Nana library is used.


Member Data Documentation

Section QConfigDB::top [protected]

The toplevel section.

QTimer* QConfigDB::timer [protected]

A timer pointer for watching the file.

QString QConfigDB::filename [protected]

The current filename.

bool QConfigDB::readonly [protected]

The current file opening mode.

bool QConfigDB::locked [protected]

Whether this object locked the file or not.

time_t QConfigDB::mtime [protected]

The modification time of the last file access.

Used to recognize file changes, is zero if the modification time is unknown, what usually means that the current file has not been created and does not exist by now.

See also:
storeFileAge()

list<QString> QConfigDB::LockFiles [static, protected]

All created lockfiles are notified in this list.

The list contains the names of the lockfiles, not of the files itselfes.


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

The KDE Addressbook Developers Reference 
Mirko Sucker, 1999