00001 #ifndef sq3_LOG_DB_HPP_INCLUDED 00002 #define sq3_LOG_DB_HPP_INCLUDED 1 00003 00004 #include "sq3.hpp" 00005 namespace sq3 { 00006 00007 /** 00008 log_db is a simple logging database for use with arbitrary 00009 applications. It is intended to be a small logger for 00010 simple systems, and not a powerful logging system. The main 00011 advantages of using an sqlite3 db instead of a conventional 00012 log file are: 00013 00014 - We get log parsing for free by using compatible sqlite3 tools. 00015 00016 - Since each log entry is its own database record, the log 00017 can contain arbitrarily-formatted messages without causing 00018 any problems should we want to re-parse the log file later 00019 on. 00020 00021 - The actual i/o is handled by sqlite3, so we don't need to 00022 deal with any of that tedium. 00023 00024 In the case that you want to query the data, this type creates 00025 a table named 'log' with the fields (ts,msg), containing the timestamp 00026 and log message, respectively. 00027 */ 00028 class log_db : public database 00029 { 00030 public: 00031 /** 00032 Opens/creates a db from the given filename. 00033 Note that this function cannot notify the user 00034 if the file cannot be created or if the file 00035 is not really a DB file (in which case all logging 00036 will silently fail)! Use this->is_open() to find out 00037 if the open() worked! 00038 00039 Note that it is not legal to have more than one instance 00040 with the same filename - the second instance will not 00041 be able to open the database! It is also not strictly 00042 legal to re-use an existing non-log_db database. 00043 */ 00044 explicit log_db( std::string const & filename ); 00045 00046 /** 00047 Creates an unopened database. Use this->open() to 00048 open it. 00049 */ 00050 log_db(); 00051 00052 /** 00053 Closes this db. 00054 */ 00055 virtual ~log_db(); 00056 00057 /** 00058 Empties the log database. Returns SQLITE_OK on 00059 success or some other value on error (e.g., db is 00060 not open). 00061 */ 00062 virtual int clear(); 00063 /** 00064 Logs a message to the log database. Returns true 00065 on success, false on error. 00066 00067 If the format string evaluates to an empty string, 00068 this function returns true but does not log the 00069 entry. 00070 */ 00071 bool log( std::string const & msg ); 00072 00073 /** 00074 Logs the given printf-formatted string to the 00075 database. If the resulting string is "too long" 00076 then it is internally truncated. "Too long" is 00077 rather arbitrarily chosen to be 2k of text. 00078 00079 If the format string evaluates to an empty string, 00080 this function returns true but does not log the 00081 entry. 00082 */ 00083 bool log( char const * format, ... ); 00084 00085 /** 00086 Shows the last count entries using a subclass-specific 00087 method. The default is to send the items to std::cout. 00088 A subclass could override this to show a dialog box, 00089 for example. A subclass which does so may also want 00090 to call the base implementation but certainly doesn't 00091 need to. 00092 00093 Subclasses are requested to respect the howMany 00094 argument, but may of course format the data to suit 00095 their desires. 00096 */ 00097 virtual void show_last( int howMany ); 00098 00099 /** 00100 Deletes all entries in the log except the leaveThisMany 00101 most recent. e.g. Trim( 5 ) leaves only the most recent 00102 5 entries in the database. The intent of this function 00103 is to give applications a way of keeping the log size small 00104 without having to use Clear() to empty the whole database. 00105 00106 Returns true on success, false on error. 00107 */ 00108 bool trim( int leaveThisMany ); 00109 00110 protected: 00111 /** 00112 Called when open() succeeds. Reimplemented 00113 to create the logging table if it's not already 00114 in the db. 00115 */ 00116 virtual int on_open(); 00117 private: 00118 log_db( log_db const & ); // not implemented 00119 log_db & operator=( log_db const & ); // not implemented 00120 }; 00121 00122 00123 } // namespace sq3 00124 00125 00126 #endif // sq3_LOG_DB_HPP_INCLUDED