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
- QConfigDB (QWidget* parent=0, const char* name=0)
- The Qt standard constructor.
- virtual ~QConfigDB ()
- The virtual destructor.
- bool get (const QString& key, KeyValueMap*& map)
- Get the key-value-map for the section referenced by key.
- bool get (const list<QString>& key, KeyValueMap*& map)
- Get the key-value-map for the section referenced by key as key list.
- bool get (const QString& key, Section*&)
- Get the address of the specified Section object by its path.
- bool get (const list<QString>& key, Section*&)
- Get the address of the specified Section object by a path list.
- KeyValueMap* get ()
- Get the keys of the toplevel section.
- bool createSection (const QString& key)
- Create the section with this path.
- bool createSection (const list<QString>& key)
- Create the section with a path like the path list.
- bool load ()
- Load the file.
- bool save (const char* header=0, bool force=false)
- Save the file.
- bool setFileName (const QString& name, bool mustexist=true, bool ro=false)
- Set the current file name to name.
- bool storeFileAge ()
- Store the mtime mark of the file for later check of changes.
- QString fileName ()
- Give the current filename.
- bool isRO ()
- Returns if the current file name is set for read only access.
- bool clear ()
- Clear the whole database.
- bool empty ()
- Return whether the db is empty (e.g.
- bool lock ()
- Lock the current file.
- bool unlock ()
- Unlock the file.
- void watch (bool state)
- If watch is
true
the object watches its file for changes.
Public Slots
Signals
- virtual void changed (QConfigDB*)
- This signal will be send when the database is cleared or reloaded.
- virtual void fileChanged ()
- This signal will notify changes of the database file .
Static Public Members
- const char* version ()
- Return a string describing the version.
- int IsLocked (const QString& fn)
- Check wether the given file is locked.
- bool CheckLockFile (const QString& filename)
- Check an existing lock file for its validity.
- void CleanLockFiles (int)
- The static method CleanLockFiles removes all files in the list LockFiles when called.
Protected Members
- list<QString> stringToKeylist (const QString&)
- Transform a given path into a list of strings.
- bool lock (const QString& file)
- Lock the file.
- bool invariant ()
- Debugging aid, called from REQUIRE and ENSURE macros when the Nana library is used.
- Section top
- The toplevel section.
- QTimer* timer
- A timer pointer for watching the file.
- QString filename
- The current filename.
- bool readonly
- The current file opening mode.
- bool locked
- Whether this object locked the file or not.
- time_t mtime
- The modification time of the last file access.
Static Protected Members
- list<QString> LockFiles
- All created lockfiles are notified in this list.
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:
- The tasks in managing the structure are shared between the three
involved classes KeyValueMap, Section and QConfigDB.
- 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).
- Section objects are used to manipulate the tree structure below one
particular section.
- 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]
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.
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()
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()
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]
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]
QTimer* QConfigDB::timer [protected]
A timer pointer for watching the file.
QString QConfigDB::filename [protected]
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
|