libsq3 2007.10.18
sq3_log_db.hpp
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