summaryrefslogtreecommitdiffstats
path: root/kab/qconfigDB.h
blob: 94a211527df6b0f38f210a2b3e5aaec00ac499d9 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
#ifndef QCONFIGDB_H
#define QCONFIGDB_H

/* the Configuration Database library, Version II
 
   the TDE addressbook

   $ Author: Mirko Boehm $
   $ Copyright: (C) 1996-2001, Mirko Boehm $
   $ Contact: mirko@kde.org
         http://www.kde.org $
   $ License: GPL with the following explicit clarification:
         This code may be linked against any version of the Qt toolkit
         from Troll Tech, Norway. $

   $Id$	 
*/

namespace std { }
using namespace std;

#include <list>
#include <map>
#include <tqwidget.h>
#include <tqcstring.h>
#include <tqstrlist.h>

class TQTimer;
class TQDate;
class TQString;
class TQDateTime;

extern "C" {
#include <unistd.h>
}

class TQTextStream;

/**
 * This is some STL interna, a function object for use with STL
 * container classes. Its only element function is the function
 * operator that returns a comparison value of the both objects
 * it is called with.
 */
struct QCStringLess 
  : public binary_function<const TQCString&, const TQCString&, bool> 
{
  /**
   * The function operator, inline.
   */
  bool operator()(const TQCString& x, const TQCString& y) const 
  { 
    return x < (const char*)y; // make one Qt operator fit exactly
  }
};

typedef map<TQCString, TQCString, QCStringLess> StringStringMap;

/**
 *  The class KeyValueMap is used for managing key-value-pairs
 *  WITHOUT any hierarchical structure.   Objects of it can be
 *  used as they are or in conjunction with the  configuration
 *  database class.
 *  While the first version used the string class, this second
 *  uses the TQCString class.
 *  The class uses pairs of methods for each datatype, they are 
 *  called ::get and ::insert. Every overloaded version of this 
 *  methods get the key of the settings and a reference to the
 *  value to set or to store it in. A boolean result reports if
 *  there where errors or if the key already existed. Keys must
 *  of course be unique. Please note that the map does NOT store type 
 *  information for the keys. You may retrieve a boolean value for a string,
 *  it will work if the string is either "true" or "false".
 *  See the different get- and insert-methods for details.
 *
 *  Capabilities of the class are:
 *  <OL> 
 *  <LI> storing of any key-value-pair that is storable in 
 *    string values (no binary objects currently), </LI>
 *  <LI> key-value-pairs are saved in human-readable text files
 *    when saving to disk, </LI>
 *  <LI> the values may contain newline and tabulator characters
 *    which will still be there after saving and rereading, </LI>
 *  <LI> supports the following datatypes: <OL> 
 *    <LI> strings (of course), </LI>
 *    <LI> integers, </LI>
 *    <LI> floating point values and </LI>
 *    <LI> boolean states </LI> </OL> </LI> 
 *  <LI> supports storing and retrieving of lists of values of the 
 *    following datatypes: <OL> 
 *    <LI> strings, </LI>
 *    <LI> integers and </LI>
 *    <LI> floating point values </LI> </OL> 
 *    (boolean lists supported in future when requested) </LI> 
 *  <LI> easy syntax of files, in general it is supposed to be a 
 *    kind of guarantee  (you know that free software  never 
 *    guarantees anything, don't you?)  that every value that 
 *    has been  stored  by one of the member functions of the 
 *    class like <BR>
 *      <TT> insert(const TQCString& key, [value&]); </TT> <BR>
 *    can also be retrieved using <BR>
 *      <TT> get(const TQCString& key, [value&]);</TT> <BR>
 *    without being modified. <BR>
 *    (Please report anything that does not do so!) </LI> </OL> 
 *  The class is used to implement the #QConfigDB class.
 */

class KeyValueMap 
{
  // ############################################################################
protected:
  /**
   * A map storing the key-value-pairs.
   */
  StringStringMap* data;
  /**
   * Transform a complex string into a normal string object.
   * The values are not stored  as they are, they are coded into 
   * complex string where control and non-printable characters get a readable
   * representation.
   * When retrieving, this strings are translated back by this method.
   * \a orig contains the string read from the file, \a index the position from 
   * where to start the translation (need not be the beginning of the string), 
   * \a result contains the transformed string, \a noOfChars the number of 
   * characters used to parse the string. 
   * Returns true if there where no errors while parsing.
   * @see makeComplexString
   */
  bool parseComplexString(const TQCString& orig, int index,
			  TQCString& result, int& noOfChars) const; 
  /**
   * Codes a normal string into a complex string. 
   * @see parseComplexString
   */
  TQCString makeComplexString(const TQCString& orig); 
  /**
   * Inserts a complex string into the map.
   * The string must be coded already, no tests are performed. 
   * \a if force is false, an existing value will not be overridden.
   */
  bool insertRaw(const TQCString& key, const TQCString& value, bool force=false);
  /**
   * Retrieves the undecoded value (a complex string) of the given key.
   */
  bool getRaw(const TQCString& key, TQCString& value) const; 
  // ----------------------------------------------------------------------------
public:
  /**
   * The default constructor.
   */
  KeyValueMap(); 
  /**
   * The copy constructor.
   */
  KeyValueMap(const KeyValueMap&); 
  /**
   * The virtual destructor.
   */
  virtual ~KeyValueMap(); 
  /**
   * The begin iterator. Use it to iterate over the keys in the map.
   */
  StringStringMap::iterator begin();
  /**
   * The end iterator.
   */
  StringStringMap::iterator end();
  /**
   * Debugging aid: returns true if object is OK.
   */
  bool invariant();
  /**
   * Returns the number of key-value-pairs in the map.
   */
  unsigned int size() const; 
  /**
   * Delete all entries.
   */
  void clear(); 
  /**
   * Fills the map with the files contents.
   * If the parameter \a force is true, it overrides keys that are
   * already declared in the database and are declared again in the file.
   * If \a relax is true, the value of a string may be empty.
   */
  bool fill(const TQString&, bool force=false, bool relax=false); 
  /**
   * Saves the database to a file. 
   * Only overrides existing files if force is true.
   */
  bool save(const TQString&, bool force=false); 
  /**
   * Saves contents to an already open text stream.
   * \a count spaces are inserted before each line. This method is 
   * called when save hierarchical databases.
   * @see ::QConfigDB
   */
  bool save(TQTextStream& file, int count); 
  /**
   * Get the value for the key as a string. 
   * \a key is the key to search for, \a value is a reference to the object
   * the value for the key is assigned to.
   */
  bool get(const TQCString& key, TQCString& value) const;
  /**
   * Insert a string value for the given key. 
   * If force is true, an existing value for this key will be overridden.
   * The method returns false if the key exists and \a force is false.
   */
  bool insert(const TQCString& key, const TQCString& value, bool force=false);
  /**
   * Insert a character pointer  for the given key. 
   * pgcc treats character pointers as boolean objects, not as strings.
   * If force is true, an existing value for this key will be overridden.
   * The method returns false if the key exists and \a force is false.
   */
  inline bool insert(const TQCString& key, const char* value, bool force=false);
  /**
   * Insert a line like "key_a="Hallo!" into the map as a key-value-pair. 
   * If force is true existing keys will be overridden.
   * If relax is true the value may be empty an empty string.
   * If encode is false, the string will not be coded (do not use!).
   */
  bool insertLine(TQCString, bool force=false, bool relax=false, bool encode=true);
  // ---------------
  /**
   * Get the value for the key as a long integer. 
   * \a key is the key to search for, \a value is a reference to the object
   * the value for the key is assigned to.
   */
  bool get(const TQCString&, long&) const;
  /**
   * Insert a long integer value for the given key. 
   * If force is true, an existing value for this key will be overridden.
   * The method returns false if the key exists and \a force is false.
   */
  bool insert(const TQCString&, const long&, bool force=false);
  // ---------------
  /**
   * For insertion of UNICODE strings, a special method pair is created. The 
   * data will be translated to utf8 and inserted in the map as a TQCString. 
   * This will probably be not fast, but this methods are not suited to save 
   * large amounts of data. For saving anything else than UNICODE strings,
   * no such conversion is needed.
   * \a key is the key to search for, \a value is a reference to the object
   * the value for the key is assigned to.
   */
  bool get(const TQCString&, TQString&) const;
  /**
   * Insert a UNICODE string value for the given key. 
   * If force is true, an existing value for this key will be overridden.
   * The method returns false if the key exists and \a force is false.
   */
  bool insert(const TQCString&, const TQString&, bool force=false);
  // ---------------
  /**
   * Get the value for the key as a double. 
   * \a key is the key to search for, \a value is a reference to the object
   * the value for the key is assigned to.
   */
  bool get(const TQCString&, double&) const;
  /**
   * Insert a double value for the given key. 
   * If force is true, an existing value for this key will be overridden.
   * The method returns false if the key exists and \a force is false.
   */
  bool insert(const TQCString&, const double&, bool force=false);
  // ---------------
  /**
   * Get the value for the key as a boolean value. 
   * \a key is the key to search for, \a value is a reference to the object
   * the value for the key is assigned to.
   */
  bool get(const TQCString&, bool&) const;
  /**
   * Insert a boolean value for the given key. 
   * If force is true, an existing value for this key will be overridden.
   * The method returns false if the key exists and \a force is false.
   */
  bool insert(const TQCString&, const bool&, bool force=false);
  // ---------------
  /**
   * Get the value for the key as a list of strings. 
   * \a key is the key to search for, \a value is a reference to the object
   * the value for the key is assigned to.
   */
  bool get(const TQCString&, list<TQCString>&) const;
  /**
   * Insert a list of strings for the given key. 
   * If force is true, an existing value for this key will be overridden.
   * The method returns false if the key exists and \a force is false.
   */
  bool insert(const TQCString&, const list<TQCString>&, bool force=false);
  // --------------
  /**
   * Get the value for the key as a TQStrList. 
   * \a key is the key to search for, \a value is a reference to the object
   * the value for the key is assigned to.
   */
  bool get(const TQCString&, TQStrList&) const;
  /**
   * Insert a TQStrList for the given key. 
   * If force is true, an existing value for this key will be overridden.
   * The method returns false if the key exists and \a force is false.
   */
  bool insert(const TQCString&, const TQStrList&, bool force=false);
  // --------------
  /**
   * Get the value for the key as a TQStringList. Beware of the difference -
   * a TQStringList is a list of TQString objects, while TQStrList handles
   * char* like objects.
   * \a key is the key to search for, \a value is a reference to the object
   * the value for the key is assigned to.
   */
  bool get(const TQCString&, TQStringList&) const;
  /**
   * Insert a TQStringList for the given key. 
   * If force is true, an existing value for this key will be overridden.
   * The method returns false if the key exists and \a force is false.
   */
  bool insert(const TQCString&, const TQStringList&, bool force=false);
  // --------------
  /**
   * Get the value for the key as a list of long integers. 
   * \a key is the key to search for, \a value is a reference to the object
   * the value for the key is assigned to.
   */
  bool get(const TQCString&, list<long>&) const;
  /**
   * Insert a list of long integers for the given key. 
   * If force is true, an existing value for this key will be overridden.
   * The method returns false if the key exists and \a force is false.
   */
  bool insert(const TQCString&, const list<long>&, bool force=false);
  // --------------
  /**
   * Get the value for the key as a list of integers. 
   * \a key is the key to search for, \a value is a reference to the object
   * the value for the key is assigned to.
   */
  bool get(const TQCString&, list<int>&) const;
  /**
   * Insert a list of integers for the given key. 
   * If force is true, an existing value for this key will be overridden.
   * The method returns false if the key exists and \a force is false.
   */
  bool insert(const TQCString&, const list<int>&, bool force=false);
  // -------------- some Qt high-level data types:
  /**
   * Get the value for the key as a TQDate.
   * The value will be parsed to a integer list that must be a \e valid
   * date (see TQDate documentation). \c false will be returned if the value
   * is not valid or a null date. This situation might only happen in
   * manually created files, since the insert-method for QDates rejects to
   * insert inalid dates, it inserts null dates instead.
   * @see get(const TQCString&, TQDate &)
   */
  bool get(const TQCString&, TQDate &) const;
  /**
   * Insert a TQDate for the given key.
   * If force is true, an existing value for this key will be overridden.
   * The method returns false if the key exists and \a force is false.
   * \e Attention: If you insert an invalid date a null date will be used.
   * A null date will also be returned when retrieving this value.
   * You will not be able to store an invalid date and retrieve it using
   * ::get!
   */
  bool insert(const TQCString&, const TQDate&, bool force=false);
  // --------------
  /**
   * Get the value for the key as a list of doubles. 
   * \a key is the key to search for, \a value is a reference to the object
   * the value for the key is assigned to.
   */
  bool get(const TQCString&, list<double>&) const;
  /**
   * Insert a list of doubles for the given key. 
   * If force is true, an existing value for this key will be overridden.
   * The method returns false if the key exists and \a force is false.
   */
  bool insert(const TQCString&, const list<double>&, bool force=false);
  // --------------
  // end of corresponding get-insert-pairs
  /**
   * Returns true if there are no keys declared in this map.
   */
  bool empty(); 
  /**
   * Erases all key-value-pairs in the map.
   */ 
  bool erase(const TQCString& key); 
  // ############################################################################
};

/**
 * A Section object manages one section of a configuration database.
 * A configuration database consists of sections which in turn 
 * consist of other sections (recursive definition) and 
 * key-value-pairs. This file declares the Section class. An 
 * object of Section manages exactly one section during its 
 * lifetime.
 */

class Section
{
  // ############################################################################
public:
  /**
   * The StringSectionMap type is defined to make the code more readable.
   */
  typedef map<TQCString, Section*, QCStringLess> StringSectionMap;
  // ----------------------------------------------------------------------------
protected:
  /**
   * A map containing the subsections of this section.
   */
  StringSectionMap sections;
  /**
   * The key-value-pairs of this section.
   */
  KeyValueMap keys;
  /**
   * The number of spaces a subsection is indented in text files.
   */
  static const int indent_width;
  /**
   * Insert the spaces for indention the lines of this section when saving.
   */
  void insertIndentSpace(TQTextStream& file, int level);
  /**
   * Check whether the string (one line of the file currently read) marks the
   *  beginning of a new subsection (usually [sectionname]).
   */
  bool isBeginOfSection(TQCString);
  /**
   * Check whether the string (one line of the file currently read) marks the
   *  end of a new subsection (usually [END]).
   */
  bool isEndOfSection(TQCString);
  /**
   * Extract the name of the section from the string.
   * The string must contain the line that starts the section.
   * @see ::isBeginOfSection
   */
  TQCString nameOfSection(const TQCString&);
  // ----------------------------------------------------------------------------
public:
  /**
   * The default constructor.
   */
  Section();
  /**
   * Constructor that fills the keys with the given map entries.
   */
  Section(const KeyValueMap&);
  // handling sections:
  /**
   * Add an empty new section.
   */
  bool add(const TQCString&);
  /**
   * Add the section.
   */
  bool add(const TQCString&, Section*);
  /**
   * Search for the section, returning an iterator to it.
   */
  bool find(const TQCString&, StringSectionMap::iterator&);
  /**
   * Search for the section, returning a pointer to the section object.
   */
  bool find(const TQCString&, Section*&);
  /**
   * Remove this subsection.
   */
  bool remove(const TQCString&);
  /**
   * Return the key-value-pairs of this (!) section.
   */
  KeyValueMap* getKeys();
  /**
   * Save this section to the given output stream.
   * Level is the position in section tree depth (the hierarchy level). 
   * It is used for indenting.
   */
  bool save(TQTextStream& stream, int level=0);
  /**
   * Read one section from the given input stream.
   * The method does not expect the line that marks the begin of the 
   * section. If finish is false, the code does also not except the 
   * section to be ended with a line like [END].
   */
  bool readSection(TQTextStream& file, bool finish=true);
  /**
   * Clears both subsections and keys.
   */
  bool clear();
  /**
   * Returns whether this section is empty. A section is empty if it has no
   * subsections and no key-value-pairs.
   */
  bool empty();
  // methods to allow iterating through the subsections
  /**
   * Return an iterator to the beginning of the subsections map.
   */
  StringSectionMap::iterator sectionsBegin();
  /**
   * Return an iterator to the end of the subsections map.
   */
  StringSectionMap::iterator sectionsEnd();
  /**
   * Return the number of subsections.
   */
  unsigned int noOfSections();
  // ############################################################################
};

/**
 *  The class QConfigDB is used to manage text-based data files 
 *  with hierarchical structure. <BR>
 *  It is derived from ::TQWidget, so it may be derived to display 
 *  its contents. The basic implementation here does not display 
 *  anything to make it a lean class.  <BR>
 *  Some notes about the philosophy of the configuration 
 *  database library: <OL>
 *  <LI> The tasks in managing the structure are shared between the three
 *       involved classes ::KeyValueMap, ::Section and QConfigDB. </LI>
 *  <LI> \a 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). </LI>
 *  <LI> Section objects are used to manipulate the tree structure below one
 *       particular section. </LI>
 *  <LI> KeyValueMap objects are used to retrieve and modify the 
 *       key-value-pairs of one section, but not for its subsections. </LI> 
 *  </OL>
 *  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. <BR>
 *  See the code examples provided with the library for details.
 */

class QConfigDB : public TQWidget
{
  // ############################################################################
  TQ_OBJECT
  // ----------------------------------------------------------------------------
protected:
  /**
   * The toplevel section.
   */
  Section top;
  /**
   * A timer pointer for watching the file.
   */
  TQTimer *timer;
  // ----------------------------------------------------------------------------
public:
  /**
   * The Qt standard constructor.
   */
  QConfigDB(TQWidget* parent=0, const char* name=0);
  /**
   * The virtual destructor.
   */
  virtual ~QConfigDB();
  /**
   * Get the key-value-map for the section referenced by \a key.
   */
  bool get(const TQCString& key, KeyValueMap*& map);
  /**
   * Get the key-value-map for the section referenced by \a key as key list.
   */
  bool get(const list<TQCString>& key, KeyValueMap*& map);
  /**
   * Get the address of the specified Section object by its path. 
   * Never delete the section returned to you.
   */
  bool get(const TQCString& key, Section*&);
  /**
   * Get the address of the specified Section object by a path list. 
   * Never delete the section returned to you.
   */  
  bool get(const list<TQCString>& key, Section*&);
  /**
   * Get the keys of the toplevel section.
   */
  KeyValueMap* get();
  /**
   * Create the section with this path. 
   * All elements of the path that do not exist are created.
   */
  bool createSection(const TQCString& key);
  /**
   * Create the section with a path like the path list. 
   * All elements of the path that do not exist are created.
   */
  bool createSection(const list<TQCString>& key);
  /**
   * Load the file.
   * @see ::setFileName
   */
  bool load();
  /**
   * Save the file. 
   * \a header will be the comment in the first line of the file.
   * If \a force is \c true, a file opened read-only will be switched
   * to read and write mode and back after saving. 
   * @see ::setFileName
   */
  bool save(const char* header=0, bool force=false); 
  /**
   * Set the current file name to \a 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 \a 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 \a 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 setFileName(const TQString& name, bool mustexist=true, bool ro=false);
  /**
   * Store the modification time of the file for later check of changes.
   */
  bool storeFileAge();
  /**
   * Give the current filename.
   */
  TQString fileName(); 
  /**
   * Returns if the current file name is set for read only access.
   */
  bool isRO(); 
  /**
   * Clear the whole database.
   */
  bool clear();
  /**
   * Return whether the db is empty (e.g. the toplevel section is).
   */
  bool empty();
  /**
   * Return a string describing the version.
   */
  static const char* version() { return "2.0 $Revision$"; }
  /**
   * 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.
   */
  static int IsLocked(const TQString& fn);
  /**
   * Check an existing lock file for its validity.
   * \a 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.
   */
  static bool CheckLockFile(const TQString& filename);
  /**
   * 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.
   */
  static void CleanLockFiles(int);
  /**
   * 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 lock();
  /**
   * Unlock the file.
   */
  bool unlock();
  /**
   * If \a watch is <TT> true </TT> 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.
   */ 
  void watch(bool state);
  // ----------------------------------------------------------------------------
protected:
  /**
   * Transform a given path into a list of strings. 
   * All internal path handling is done with lists.
   */
  list<TQCString> stringToKeylist(const TQCString&);
  /**
   * The current filename.
   */
  TQString filename; 
  /**
   * The current file opening mode.
   */
  bool readonly; 
  /**
   * Whether this object locked the file or not.
   */
  bool locked;
  /**
   * The modification time of the last file access.
   * Used to recognize file changes, is a null date if the modification time is 
   * unknown, what usually means that the current file has not been created and
   * does not exist by now. 
   * @see ::storeFileAge
   */
  TQDateTime *mtime;
  /**
   * Lock the file.
   */
  bool lock(const TQString& file);
  /**
   * Debugging aid, called from REQUIRE and ENSURE macros when the Nana library 
   * is used.
   */
  bool invariant();
  /**
   * All created lockfiles are notified in this list. 
   * The list contains the names of the lockfiles, not of the files itselfes.
   */
  static list<TQString> LockFiles;
  // ----------------------------------------------------------------------------
public slots:
  /**
   * Check for file changes. 
   * This method returns true if the file has been changed on disk
   * after the last reading or saving.
   */
  bool checkFileChanged();
  // ----------------------------------------------------------------------------
signals:
  /**
   * 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 \a this pointer.
   */
  virtual void changed(QConfigDB*);
  /**
   * This signal will notify changes of the database <EM> file </EM>. The file
   * will be monitored on disk if #watch has been activated.
   */
  virtual void fileChanged();
  // ############################################################################
};

// ----- inline functions:
bool KeyValueMap::insert(const TQCString& key, const char* value, bool force)
{ 
  return insert(key, (TQCString)value, force); 
}
// -----

#endif // ! defined QCONFIGDB_H