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"
5namespace 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 */
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
Encapsulates a connection to an sqlite database.
Definition sq3.hpp:233
log_db is a simple logging database for use with arbitrary applications.
virtual int on_open()
Called when open() succeeds.
log_db()
Creates an unopened database.
bool trim(int leaveThisMany)
Deletes all entries in the log except the leaveThisMany most recent.
bool log(std::string const &msg)
Logs a message to the log database.
virtual ~log_db()
Closes this db.
virtual void show_last(int howMany)
Shows the last count entries using a subclass-specific method.
virtual int clear()
Empties the log database.
The sq3 namespace encapsulates an OO sqlite3 API very similar to the sqlite3x API,...
Definition sq3.hpp:77