TDE core libraries
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

qconfigDB.h 27KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779
  1. /* -*- C++ -*- */
  2. #ifndef QCONFIGDB_H
  3. #define QCONFIGDB_H
  4. /* the Configuration Database library, Version II
  5. the TDE addressbook
  6. $ Author: Mirko Boehm $
  7. $ Copyright: (C) 1996-2001, Mirko Boehm $
  8. $ Contact: mirko@kde.org
  9. http://www.kde.org $
  10. $ License: GPL with the following explicit clarification:
  11. This code may be linked against any version of the Qt toolkit
  12. from Troll Tech, Norway. $
  13. $Id$
  14. */
  15. namespace std { }
  16. using namespace std;
  17. #include <list>
  18. #include <map>
  19. #include <tqwidget.h>
  20. #include <tqcstring.h>
  21. #include <tqstrlist.h>
  22. class TQTimer;
  23. class TQDate;
  24. class TQString;
  25. class TQDateTime;
  26. extern "C" {
  27. #include <unistd.h>
  28. }
  29. class TQTextStream;
  30. /**
  31. * This is some STL interna, a function object for use with STL
  32. * container classes. Its only element function is the function
  33. * operator that returns a comparison value of the both objects
  34. * it is called with.
  35. */
  36. struct QCStringLess
  37. : public binary_function<const TQCString&, const TQCString&, bool>
  38. {
  39. /**
  40. * The function operator, inline.
  41. */
  42. bool operator()(const TQCString& x, const TQCString& y) const
  43. {
  44. return x < (const char*)y; // make one Qt operator fit exactly
  45. }
  46. };
  47. typedef map<TQCString, TQCString, QCStringLess> StringStringMap;
  48. /**
  49. * The class KeyValueMap is used for managing key-value-pairs
  50. * WITHOUT any hierarchical structure. Objects of it can be
  51. * used as they are or in conjunction with the configuration
  52. * database class.
  53. * While the first version used the string class, this second
  54. * uses the TQCString class.
  55. * The class uses pairs of methods for each datatype, they are
  56. * called ::get and ::insert. Every overloaded version of this
  57. * methods get the key of the settings and a reference to the
  58. * value to set or to store it in. A boolean result reports if
  59. * there where errors or if the key already existed. Keys must
  60. * of course be unique. Please note that the map does NOT store type
  61. * information for the keys. You may retrieve a boolean value for a string,
  62. * it will work if the string is either "true" or "false".
  63. * See the different get- and insert-methods for details.
  64. *
  65. * Capabilities of the class are:
  66. * <OL>
  67. * <LI> storing of any key-value-pair that is storable in
  68. * string values (no binary objects currently), </LI>
  69. * <LI> key-value-pairs are saved in human-readable text files
  70. * when saving to disk, </LI>
  71. * <LI> the values may contain newline and tabulator characters
  72. * which will still be there after saving and rereading, </LI>
  73. * <LI> supports the following datatypes: <OL>
  74. * <LI> strings (of course), </LI>
  75. * <LI> integers, </LI>
  76. * <LI> floating point values and </LI>
  77. * <LI> boolean states </LI> </OL> </LI>
  78. * <LI> supports storing and retrieving of lists of values of the
  79. * following datatypes: <OL>
  80. * <LI> strings, </LI>
  81. * <LI> integers and </LI>
  82. * <LI> floating point values </LI> </OL>
  83. * (boolean lists supported in future when requested) </LI>
  84. * <LI> easy syntax of files, in general it is supposed to be a
  85. * kind of guarantee (you know that free software never
  86. * guarantees anything, don't you?) that every value that
  87. * has been stored by one of the member functions of the
  88. * class like <BR>
  89. * <TT> insert(const TQCString& key, [value&]); </TT> <BR>
  90. * can also be retrieved using <BR>
  91. * <TT> get(const TQCString& key, [value&]);</TT> <BR>
  92. * without being modified. <BR>
  93. * (Please report anything that does not do so!) </LI> </OL>
  94. * The class is used to implement the #QConfigDB class.
  95. */
  96. class KeyValueMap
  97. {
  98. // ############################################################################
  99. protected:
  100. /**
  101. * A map storing the key-value-pairs.
  102. */
  103. StringStringMap* data;
  104. /**
  105. * Transform a complex string into a normal string object.
  106. * The values are not stored as they are, they are coded into
  107. * complex string where control and non-printable characters get a readable
  108. * representation.
  109. * When retrieving, this strings are translated back by this method.
  110. * \a orig contains the string read from the file, \a index the position from
  111. * where to start the translation (need not be the beginning of the string),
  112. * \a result contains the transformed string, \a noOfChars the number of
  113. * characters used to parse the string.
  114. * Returns true if there where no errors while parsing.
  115. * @see makeComplexString
  116. */
  117. bool parseComplexString(const TQCString& orig, int index,
  118. TQCString& result, int& noOfChars) const;
  119. /**
  120. * Codes a normal string into a complex string.
  121. * @see parseComplexString
  122. */
  123. TQCString makeComplexString(const TQCString& orig);
  124. /**
  125. * Inserts a complex string into the map.
  126. * The string must be coded already, no tests are performed.
  127. * \a if force is false, an existing value will not be overridden.
  128. */
  129. bool insertRaw(const TQCString& key, const TQCString& value, bool force=false);
  130. /**
  131. * Retrieves the undecoded value (a complex string) of the given key.
  132. */
  133. bool getRaw(const TQCString& key, TQCString& value) const;
  134. // ----------------------------------------------------------------------------
  135. public:
  136. /**
  137. * The default constructor.
  138. */
  139. KeyValueMap();
  140. /**
  141. * The copy constructor.
  142. */
  143. KeyValueMap(const KeyValueMap&);
  144. /**
  145. * The virtual destructor.
  146. */
  147. virtual ~KeyValueMap();
  148. /**
  149. * The begin iterator. Use it to iterate over the keys in the map.
  150. */
  151. StringStringMap::iterator begin();
  152. /**
  153. * The end iterator.
  154. */
  155. StringStringMap::iterator end();
  156. /**
  157. * Debugging aid: returns true if object is OK.
  158. */
  159. bool invariant();
  160. /**
  161. * Returns the number of key-value-pairs in the map.
  162. */
  163. unsigned int size() const;
  164. /**
  165. * Delete all entries.
  166. */
  167. void clear();
  168. /**
  169. * Fills the map with the files contents.
  170. * If the parameter \a force is true, it overrides keys that are
  171. * already declared in the database and are declared again in the file.
  172. * If \a relax is true, the value of a string may be empty.
  173. */
  174. bool fill(const TQString&, bool force=false, bool relax=false);
  175. /**
  176. * Saves the database to a file.
  177. * Only overrides existing files if force is true.
  178. */
  179. bool save(const TQString&, bool force=false);
  180. /**
  181. * Saves contents to an already open text stream.
  182. * \a count spaces are inserted before each line. This method is
  183. * called when save hierarchical databases.
  184. * @see ::QConfigDB
  185. */
  186. bool save(TQTextStream& file, int count);
  187. /**
  188. * Get the value for the key as a string.
  189. * \a key is the key to search for, \a value is a reference to the object
  190. * the value for the key is assigned to.
  191. */
  192. bool get(const TQCString& key, TQCString& value) const;
  193. /**
  194. * Insert a string value for the given key.
  195. * If force is true, an existing value for this key will be overridden.
  196. * The method returns false if the key exists and \a force is false.
  197. */
  198. bool insert(const TQCString& key, const TQCString& value, bool force=false);
  199. /**
  200. * Insert a character pointer for the given key.
  201. * pgcc treats character pointers as boolean objects, not as strings.
  202. * If force is true, an existing value for this key will be overridden.
  203. * The method returns false if the key exists and \a force is false.
  204. */
  205. inline bool insert(const TQCString& key, const char* value, bool force=false);
  206. /**
  207. * Insert a line like "key_a="Hallo!" into the map as a key-value-pair.
  208. * If force is true existing keys will be overridden.
  209. * If relax is true the value may be empty an empty string.
  210. * If encode is false, the string will not be coded (do not use!).
  211. */
  212. bool insertLine(TQCString, bool force=false, bool relax=false, bool encode=true);
  213. // ---------------
  214. /**
  215. * Get the value for the key as a long integer.
  216. * \a key is the key to search for, \a value is a reference to the object
  217. * the value for the key is assigned to.
  218. */
  219. bool get(const TQCString&, long&) const;
  220. /**
  221. * Insert a long integer value for the given key.
  222. * If force is true, an existing value for this key will be overridden.
  223. * The method returns false if the key exists and \a force is false.
  224. */
  225. bool insert(const TQCString&, const long&, bool force=false);
  226. // ---------------
  227. /**
  228. * For insertion of UNICODE strings, a special method pair is created. The
  229. * data will be translated to utf8 and inserted in the map as a TQCString.
  230. * This will probably be not fast, but this methods are not suited to save
  231. * large amounts of data. For saving anything else than UNICODE strings,
  232. * no such conversion is needed.
  233. * \a key is the key to search for, \a value is a reference to the object
  234. * the value for the key is assigned to.
  235. */
  236. bool get(const TQCString&, TQString&) const;
  237. /**
  238. * Insert a UNICODE string value for the given key.
  239. * If force is true, an existing value for this key will be overridden.
  240. * The method returns false if the key exists and \a force is false.
  241. */
  242. bool insert(const TQCString&, const TQString&, bool force=false);
  243. // ---------------
  244. /**
  245. * Get the value for the key as a double.
  246. * \a key is the key to search for, \a value is a reference to the object
  247. * the value for the key is assigned to.
  248. */
  249. bool get(const TQCString&, double&) const;
  250. /**
  251. * Insert a double value for the given key.
  252. * If force is true, an existing value for this key will be overridden.
  253. * The method returns false if the key exists and \a force is false.
  254. */
  255. bool insert(const TQCString&, const double&, bool force=false);
  256. // ---------------
  257. /**
  258. * Get the value for the key as a boolean value.
  259. * \a key is the key to search for, \a value is a reference to the object
  260. * the value for the key is assigned to.
  261. */
  262. bool get(const TQCString&, bool&) const;
  263. /**
  264. * Insert a boolean value for the given key.
  265. * If force is true, an existing value for this key will be overridden.
  266. * The method returns false if the key exists and \a force is false.
  267. */
  268. bool insert(const TQCString&, const bool&, bool force=false);
  269. // ---------------
  270. /**
  271. * Get the value for the key as a list of strings.
  272. * \a key is the key to search for, \a value is a reference to the object
  273. * the value for the key is assigned to.
  274. */
  275. bool get(const TQCString&, list<TQCString>&) const;
  276. /**
  277. * Insert a list of strings for the given key.
  278. * If force is true, an existing value for this key will be overridden.
  279. * The method returns false if the key exists and \a force is false.
  280. */
  281. bool insert(const TQCString&, const list<TQCString>&, bool force=false);
  282. // --------------
  283. /**
  284. * Get the value for the key as a TQStrList.
  285. * \a key is the key to search for, \a value is a reference to the object
  286. * the value for the key is assigned to.
  287. */
  288. bool get(const TQCString&, TQStrList&) const;
  289. /**
  290. * Insert a TQStrList for the given key.
  291. * If force is true, an existing value for this key will be overridden.
  292. * The method returns false if the key exists and \a force is false.
  293. */
  294. bool insert(const TQCString&, const TQStrList&, bool force=false);
  295. // --------------
  296. /**
  297. * Get the value for the key as a TQStringList. Beware of the difference -
  298. * a TQStringList is a list of TQString objects, while TQStrList handles
  299. * char* like objects.
  300. * \a key is the key to search for, \a value is a reference to the object
  301. * the value for the key is assigned to.
  302. */
  303. bool get(const TQCString&, TQStringList&) const;
  304. /**
  305. * Insert a TQStringList for the given key.
  306. * If force is true, an existing value for this key will be overridden.
  307. * The method returns false if the key exists and \a force is false.
  308. */
  309. bool insert(const TQCString&, const TQStringList&, bool force=false);
  310. // --------------
  311. /**
  312. * Get the value for the key as a list of long integers.
  313. * \a key is the key to search for, \a value is a reference to the object
  314. * the value for the key is assigned to.
  315. */
  316. bool get(const TQCString&, list<long>&) const;
  317. /**
  318. * Insert a list of long integers for the given key.
  319. * If force is true, an existing value for this key will be overridden.
  320. * The method returns false if the key exists and \a force is false.
  321. */
  322. bool insert(const TQCString&, const list<long>&, bool force=false);
  323. // --------------
  324. /**
  325. * Get the value for the key as a list of integers.
  326. * \a key is the key to search for, \a value is a reference to the object
  327. * the value for the key is assigned to.
  328. */
  329. bool get(const TQCString&, list<int>&) const;
  330. /**
  331. * Insert a list of integers for the given key.
  332. * If force is true, an existing value for this key will be overridden.
  333. * The method returns false if the key exists and \a force is false.
  334. */
  335. bool insert(const TQCString&, const list<int>&, bool force=false);
  336. // -------------- some Qt high-level data types:
  337. /**
  338. * Get the value for the key as a TQDate.
  339. * The value will be parsed to a integer list that must be a \e valid
  340. * date (see TQDate documentation). \c false will be returned if the value
  341. * is not valid or a null date. This situation might only happen in
  342. * manually created files, since the insert-method for QDates rejects to
  343. * insert inalid dates, it inserts null dates instead.
  344. * @see get(const TQCString&, TQDate &)
  345. */
  346. bool get(const TQCString&, TQDate &) const;
  347. /**
  348. * Insert a TQDate for the given key.
  349. * If force is true, an existing value for this key will be overridden.
  350. * The method returns false if the key exists and \a force is false.
  351. * \e Attention: If you insert an invalid date a null date will be used.
  352. * A null date will also be returned when retrieving this value.
  353. * You will not be able to store an invalid date and retrieve it using
  354. * ::get!
  355. */
  356. bool insert(const TQCString&, const TQDate&, bool force=false);
  357. // --------------
  358. /**
  359. * Get the value for the key as a list of doubles.
  360. * \a key is the key to search for, \a value is a reference to the object
  361. * the value for the key is assigned to.
  362. */
  363. bool get(const TQCString&, list<double>&) const;
  364. /**
  365. * Insert a list of doubles for the given key.
  366. * If force is true, an existing value for this key will be overridden.
  367. * The method returns false if the key exists and \a force is false.
  368. */
  369. bool insert(const TQCString&, const list<double>&, bool force=false);
  370. // --------------
  371. // end of corresponding get-insert-pairs
  372. /**
  373. * Returns true if there are no keys declared in this map.
  374. */
  375. bool empty();
  376. /**
  377. * Erases all key-value-pairs in the map.
  378. */
  379. bool erase(const TQCString& key);
  380. // ############################################################################
  381. };
  382. /**
  383. * A Section object manages one section of a configuration database.
  384. * A configuration database consists of sections which in turn
  385. * consist of other sections (recursive definition) and
  386. * key-value-pairs. This file declares the Section class. An
  387. * object of Section manages exactly one section during its
  388. * lifetime.
  389. */
  390. class Section
  391. {
  392. // ############################################################################
  393. public:
  394. /**
  395. * The StringSectionMap type is defined to make the code more readable.
  396. */
  397. typedef map<TQCString, Section*, QCStringLess> StringSectionMap;
  398. // ----------------------------------------------------------------------------
  399. protected:
  400. /**
  401. * A map containing the subsections of this section.
  402. */
  403. StringSectionMap sections;
  404. /**
  405. * The key-value-pairs of this section.
  406. */
  407. KeyValueMap keys;
  408. /**
  409. * The number of spaces a subsection is indented in text files.
  410. */
  411. static const int indent_width;
  412. /**
  413. * Insert the spaces for indention the lines of this section when saving.
  414. */
  415. void insertIndentSpace(TQTextStream& file, int level);
  416. /**
  417. * Check whether the string (one line of the file currently read) marks the
  418. * beginning of a new subsection (usually [sectionname]).
  419. */
  420. bool isBeginOfSection(TQCString);
  421. /**
  422. * Check whether the string (one line of the file currently read) marks the
  423. * end of a new subsection (usually [END]).
  424. */
  425. bool isEndOfSection(TQCString);
  426. /**
  427. * Extract the name of the section from the string.
  428. * The string must contain the line that starts the section.
  429. * @see ::isBeginOfSection
  430. */
  431. TQCString nameOfSection(const TQCString&);
  432. // ----------------------------------------------------------------------------
  433. public:
  434. /**
  435. * The default constructor.
  436. */
  437. Section();
  438. /**
  439. * Constructor that fills the keys with the given map entries.
  440. */
  441. Section(const KeyValueMap&);
  442. // handling sections:
  443. /**
  444. * Add an empty new section.
  445. */
  446. bool add(const TQCString&);
  447. /**
  448. * Add the section.
  449. */
  450. bool add(const TQCString&, Section*);
  451. /**
  452. * Search for the section, returning an iterator to it.
  453. */
  454. bool find(const TQCString&, StringSectionMap::iterator&);
  455. /**
  456. * Search for the section, returning a pointer to the section object.
  457. */
  458. bool find(const TQCString&, Section*&);
  459. /**
  460. * Remove this subsection.
  461. */
  462. bool remove(const TQCString&);
  463. /**
  464. * Return the key-value-pairs of this (!) section.
  465. */
  466. KeyValueMap* getKeys();
  467. /**
  468. * Save this section to the given output stream.
  469. * Level is the position in section tree depth (the hierarchy level).
  470. * It is used for indenting.
  471. */
  472. bool save(TQTextStream& stream, int level=0);
  473. /**
  474. * Read one section from the given input stream.
  475. * The method does not expect the line that marks the begin of the
  476. * section. If finish is false, the code does also not except the
  477. * section to be ended with a line like [END].
  478. */
  479. bool readSection(TQTextStream& file, bool finish=true);
  480. /**
  481. * Clears both subsections and keys.
  482. */
  483. bool clear();
  484. /**
  485. * Returns whether this section is empty. A section is empty if it has no
  486. * subsections and no key-value-pairs.
  487. */
  488. bool empty();
  489. // methods to allow iterating through the subsections
  490. /**
  491. * Return an iterator to the beginning of the subsections map.
  492. */
  493. StringSectionMap::iterator sectionsBegin();
  494. /**
  495. * Return an iterator to the end of the subsections map.
  496. */
  497. StringSectionMap::iterator sectionsEnd();
  498. /**
  499. * Return the number of subsections.
  500. */
  501. unsigned int noOfSections();
  502. // ############################################################################
  503. };
  504. /**
  505. * The class QConfigDB is used to manage text-based data files
  506. * with hierarchical structure. <BR>
  507. * It is derived from ::TQWidget, so it may be derived to display
  508. * its contents. The basic implementation here does not display
  509. * anything to make it a lean class. <BR>
  510. * Some notes about the philosophy of the configuration
  511. * database library: <OL>
  512. * <LI> The tasks in managing the structure are shared between the three
  513. * involved classes ::KeyValueMap, ::Section and QConfigDB. </LI>
  514. * <LI> \a QConfigDB
  515. * is used for retrieving sections or key-value-maps from the data
  516. * hierarchy using keys. This keys are either pathes in UNIX style like
  517. * "section_A/section_B/section_C", where C is a subsection of B which
  518. * is in turn a subsection of A, or (STL) lists of strings in equivalent
  519. * style (the first element of the list is treated as the first part of
  520. * the path, and so on). </LI>
  521. * <LI> Section objects are used to manipulate the tree structure below one
  522. * particular section. </LI>
  523. * <LI> KeyValueMap objects are used to retrieve and modify the
  524. * key-value-pairs of one section, but not for its subsections. </LI>
  525. * </OL>
  526. * Thus, to use the keys of a specific section in the database, you first
  527. * retrieve it using the ::get methods, and then manipulate the
  528. * ::KeyValueMap you got. You may also retrieve a pointer to the whole
  529. * section, if you need access to its subsections, for example. Although
  530. * this sounds complex, it is a really easy and comprehensive way to write
  531. * code using tree-structured text files. <BR>
  532. * See the code examples provided with the library for details.
  533. */
  534. class QConfigDB : public TQWidget
  535. {
  536. // ############################################################################
  537. Q_OBJECT
  538. // ----------------------------------------------------------------------------
  539. protected:
  540. /**
  541. * The toplevel section.
  542. */
  543. Section top;
  544. /**
  545. * A timer pointer for watching the file.
  546. */
  547. TQTimer *timer;
  548. // ----------------------------------------------------------------------------
  549. public:
  550. /**
  551. * The Qt standard constructor.
  552. */
  553. QConfigDB(TQWidget* parent=0, const char* name=0);
  554. /**
  555. * The virtual destructor.
  556. */
  557. virtual ~QConfigDB();
  558. /**
  559. * Get the key-value-map for the section referenced by \a key.
  560. */
  561. bool get(const TQCString& key, KeyValueMap*& map);
  562. /**
  563. * Get the key-value-map for the section referenced by \a key as key list.
  564. */
  565. bool get(const list<TQCString>& key, KeyValueMap*& map);
  566. /**
  567. * Get the address of the specified Section object by its path.
  568. * Never delete the section returned to you.
  569. */
  570. bool get(const TQCString& key, Section*&);
  571. /**
  572. * Get the address of the specified Section object by a path list.
  573. * Never delete the section returned to you.
  574. */
  575. bool get(const list<TQCString>& key, Section*&);
  576. /**
  577. * Get the keys of the toplevel section.
  578. */
  579. KeyValueMap* get();
  580. /**
  581. * Create the section with this path.
  582. * All elements of the path that do not exist are created.
  583. */
  584. bool createSection(const TQCString& key);
  585. /**
  586. * Create the section with a path like the path list.
  587. * All elements of the path that do not exist are created.
  588. */
  589. bool createSection(const list<TQCString>& key);
  590. /**
  591. * Load the file.
  592. * @see ::setFileName
  593. */
  594. bool load();
  595. /**
  596. * Save the file.
  597. * \a header will be the comment in the first line of the file.
  598. * If \a force is \c true, a file opened read-only will be switched
  599. * to read and write mode and back after saving.
  600. * @see ::setFileName
  601. */
  602. bool save(const char* header=0, bool force=false);
  603. /**
  604. * Set the current file name to \a name.
  605. * Every QConfigDB object requires a file name to be set using
  606. * this method before the file operations work.
  607. * setFileName performs checks if the current user may use the file
  608. * in the requested way. If \a ro is true, she must have
  609. * permissions to read the file, if it is false, permission must be
  610. * given to read and write the file. If \a mustexist is true, the file
  611. * must have existed before, if not, it might be created.
  612. * If any check failes, false is returned and the objects state is not
  613. * altered. Subsequent calls may be used to check if a file already
  614. * exists.
  615. */
  616. bool setFileName(const TQString& name, bool mustexist=true, bool ro=false);
  617. /**
  618. * Store the modification time of the file for later check of changes.
  619. */
  620. bool storeFileAge();
  621. /**
  622. * Give the current filename.
  623. */
  624. TQString fileName();
  625. /**
  626. * Returns if the current file name is set for read only access.
  627. */
  628. bool isRO();
  629. /**
  630. * Clear the whole database.
  631. */
  632. bool clear();
  633. /**
  634. * Return whether the db is empty (e.g. the toplevel section is).
  635. */
  636. bool empty();
  637. /**
  638. * Return a string describing the version.
  639. */
  640. static const char* version() { return "2.0 $Revision$"; }
  641. /**
  642. * Check wether the given file is locked.
  643. * The method returns zero if not, a number > zero is the pid of the process
  644. * locking the file, a number < zero reports an error and indicates
  645. * that the file is locked.
  646. */
  647. static int IsLocked(const TQString& fn);
  648. /**
  649. * Check an existing lock file for its validity.
  650. * \a fn is the name of the DATA file that is locked.
  651. * As lockfiles often remain when a program crashes, this function
  652. * checks certain conditions that show that a lockfile is not in
  653. * use anymore, these are:
  654. * ° there is no process with the pid in the lockfile,
  655. * ° the systems boot-time is after the creation of the lockfile.
  656. * The problem is that, if there is a process with the pid we have,
  657. * this does not need to be the process that created the lockfile
  658. * the method returns only false if it is shure that no such process
  659. * exists.
  660. * Returns false if the lockfile exists and is definitely stale or there
  661. * is none, returns true if the lockfile seems to be really valid.
  662. */
  663. static bool CheckLockFile(const TQString& filename);
  664. /**
  665. * The static method CleanLockFiles removes all files in the list
  666. * ::LockFiles when called.
  667. * Thus this function should be installed as a handler for SIGINT,
  668. * SIGQUIT, SIGKILL, SIGTERM and other program abortion signals or
  669. * should be called by the respective handlers.
  670. */
  671. static void CleanLockFiles(int);
  672. /**
  673. * Lock the current file.
  674. * Locking is done by creating a file \<filename\> lock.
  675. * QConfigDB-objects will reject opening a file for reading and
  676. * writing if a lockfile for the filename exists.
  677. */
  678. bool lock();
  679. /**
  680. * Unlock the file.
  681. */
  682. bool unlock();
  683. /**
  684. * If \a watch is <TT> true </TT> the object watches its file for changes.
  685. * A timer is started that checks the file age every second and emits
  686. * #fileChanged if it has been overridden meanwhile.
  687. */
  688. void watch(bool state);
  689. // ----------------------------------------------------------------------------
  690. protected:
  691. /**
  692. * Transform a given path into a list of strings.
  693. * All internal path handling is done with lists.
  694. */
  695. list<TQCString> stringToKeylist(const TQCString&);
  696. /**
  697. * The current filename.
  698. */
  699. TQString filename;
  700. /**
  701. * The current file opening mode.
  702. */
  703. bool readonly;
  704. /**
  705. * Whether this object locked the file or not.
  706. */
  707. bool locked;
  708. /**
  709. * The modification time of the last file access.
  710. * Used to recognize file changes, is a null date if the modification time is
  711. * unknown, what usually means that the current file has not been created and
  712. * does not exist by now.
  713. * @see ::storeFileAge
  714. */
  715. TQDateTime *mtime;
  716. /**
  717. * Lock the file.
  718. */
  719. bool lock(const TQString& file);
  720. /**
  721. * Debugging aid, called from REQUIRE and ENSURE macros when the Nana library
  722. * is used.
  723. */
  724. bool invariant();
  725. /**
  726. * All created lockfiles are notified in this list.
  727. * The list contains the names of the lockfiles, not of the files itselfes.
  728. */
  729. static list<TQString> LockFiles;
  730. // ----------------------------------------------------------------------------
  731. public slots:
  732. /**
  733. * Check for file changes.
  734. * This method returns true if the file has been changed on disk
  735. * after the last reading or saving.
  736. */
  737. bool checkFileChanged();
  738. // ----------------------------------------------------------------------------
  739. signals:
  740. /**
  741. * This signal will be send when the database is cleared or reloaded.
  742. * The notification might be needed if pointers or iterators are stored
  743. * outside the database object as they get invalid after reloading.
  744. * The signal hands over its \a this pointer.
  745. */
  746. virtual void changed(QConfigDB*);
  747. /**
  748. * This signal will notify changes of the database <EM> file </EM>. The file
  749. * will be monitored on disk if #watch has been activated.
  750. */
  751. virtual void fileChanged();
  752. // ############################################################################
  753. };
  754. // ----- inline functions:
  755. bool KeyValueMap::insert(const TQCString& key, const char* value, bool force)
  756. {
  757. return insert(key, (TQCString)value, force);
  758. }
  759. // -----
  760. #endif // ! defined QCONFIGDB_H