libsq3  2007.10.18
sq3_log_db.hpp
1 #ifndef sq3_LOG_DB_HPP_INCLUDED
2 #define sq3_LOG_DB_HPP_INCLUDED 1
3 
4 #include "sq3.hpp"
5 namespace sq3 {
6 
7  /**
8  log_db is a simple logging database for use with arbitrary
9  applications. It is intended to be a small logger for
10  simple systems, and not a powerful logging system. The main
11  advantages of using an sqlite3 db instead of a conventional
12  log file are:
13 
14  - We get log parsing for free by using compatible sqlite3 tools.
15 
16  - Since each log entry is its own database record, the log
17  can contain arbitrarily-formatted messages without causing
18  any problems should we want to re-parse the log file later
19  on.
20 
21  - The actual i/o is handled by sqlite3, so we don't need to
22  deal with any of that tedium.
23 
24  In the case that you want to query the data, this type creates
25  a table named 'log' with the fields (ts,msg), containing the timestamp
26  and log message, respectively.
27  */
28  class log_db : public database
29  {
30  public:
31  /**
32  Opens/creates a db from the given filename.
33  Note that this function cannot notify the user
34  if the file cannot be created or if the file
35  is not really a DB file (in which case all logging
36  will silently fail)! Use this->is_open() to find out
37  if the open() worked!
38 
39  Note that it is not legal to have more than one instance
40  with the same filename - the second instance will not
41  be able to open the database! It is also not strictly
42  legal to re-use an existing non-log_db database.
43  */
44  explicit log_db( std::string const & filename );
45 
46  /**
47  Creates an unopened database. Use this->open() to
48  open it.
49  */
50  log_db();
51 
52  /**
53  Closes this db.
54  */
55  virtual ~log_db();
56 
57  /**
58  Empties the log database. Returns SQLITE_OK on
59  success or some other value on error (e.g., db is
60  not open).
61  */
62  virtual int clear();
63  /**
64  Logs a message to the log database. Returns true
65  on success, false on error.
66 
67  If the format string evaluates to an empty string,
68  this function returns true but does not log the
69  entry.
70  */
71  bool log( std::string const & msg );
72 
73  /**
74  Logs the given printf-formatted string to the
75  database. If the resulting string is "too long"
76  then it is internally truncated. "Too long" is
77  rather arbitrarily chosen to be 2k of text.
78 
79  If the format string evaluates to an empty string,
80  this function returns true but does not log the
81  entry.
82  */
83  bool log( char const * format, ... );
84 
85  /**
86  Shows the last count entries using a subclass-specific
87  method. The default is to send the items to std::cout.
88  A subclass could override this to show a dialog box,
89  for example. A subclass which does so may also want
90  to call the base implementation but certainly doesn't
91  need to.
92 
93  Subclasses are requested to respect the howMany
94  argument, but may of course format the data to suit
95  their desires.
96  */
97  virtual void show_last( int howMany );
98 
99  /**
100  Deletes all entries in the log except the leaveThisMany
101  most recent. e.g. Trim( 5 ) leaves only the most recent
102  5 entries in the database. The intent of this function
103  is to give applications a way of keeping the log size small
104  without having to use Clear() to empty the whole database.
105 
106  Returns true on success, false on error.
107  */
108  bool trim( int leaveThisMany );
109 
110  protected:
111  /**
112  Called when open() succeeds. Reimplemented
113  to create the logging table if it's not already
114  in the db.
115  */
116  virtual int on_open();
117  private:
118  log_db( log_db const & ); // not implemented
119  log_db & operator=( log_db const & ); // not implemented
120  };
121 
122 
123 } // namespace sq3
124 
125 
126 #endif // sq3_LOG_DB_HPP_INCLUDED