libsq3  2007.10.18
Public Member Functions | Protected Member Functions | List of all members
sq3::log_db Class Reference

log_db is a simple logging database for use with arbitrary applications. More...

#include <sq3_log_db.hpp>

Inheritance diagram for sq3::log_db:
sq3::database

Public Member Functions

 log_db (std::string const &filename)
 Opens/creates a db from the given filename. More...
 
 log_db ()
 Creates an unopened database. More...
 
virtual ~log_db ()
 Closes this db.
 
virtual int clear ()
 Empties the log database. More...
 
bool log (std::string const &msg)
 Logs a message to the log database. More...
 
bool log (char const *format,...)
 Logs the given printf-formatted string to the database. More...
 
virtual void show_last (int howMany)
 Shows the last count entries using a subclass-specific method. More...
 
bool trim (int leaveThisMany)
 Deletes all entries in the log except the leaveThisMany most recent. More...
 
- Public Member Functions inherited from sq3::database
sqlite3 * handle () const
 The low-level handle to the sqlite db. More...
 
 database ()
 Creates an unopened database. More...
 
void take_handle (sqlite3 *dbh, std::string const &name="")
 dbh is assumed to be an opened, valid db handle. More...
 
sqlite3 * take_handle ()
 Transfers ownership of this->handle() to the caller. More...
 
 database (std::string const &filename)
 Opens/creates the given db file. More...
 
virtual ~database ()
 Closes this db.
 
bool is_open () const
 Returns true if this db is opened. More...
 
std::string name () const
 Returns the name of the db file.
 
std::string errormsg () const
 Returns the last error message from sqlite, or an empty string if this object is not opened. More...
 
virtual int open (char const *, long flags=0)
 Creates/opens the given db file. More...
 
int open (std::string const &, long flags=0)
 Functionally identical to open(char const*,long). More...
 
int close (bool force=false)
 "Closes" this db. More...
 
int64_t insertid ()
 Returns the rowid of the most recently inserted row on this db.
 
int changes ()
 Returns the number of database rows that were changed (or inserted or deleted) by the most recently completed INSERT, UPDATE, or DELETE statement. More...
 
int setbusytimeout (int ms)
 See sqlite3_busy_timeout().
 
int execute (const std::string &sql)
 Functionally identical to execute(char const *).
 
int execute (char const *sql)
 Executes a statement which is assumed to have a single step and a void result. More...
 
int execute (std::string const &sql, int &tgt)
 Executes a statement which is assumed to have a single result step and an integer result. More...
 
int execute (char const *sql, int &tgt)
 See execute( std::string, int & );.
 
int execute (char const *sql, int64_t &tgt)
 See execute( std::string, int & );.
 
int execute (std::string const &sql, int64_t &tgt)
 See execute( std::string, int & );.
 
int execute (char const *sql, double &tgt)
 See execute( std::string, int & );.
 
int execute (std::string const &sql, double &tgt)
 See execute( std::string, int & );.
 
int execute (char const *sql, std::string &tgt)
 See execute( std::string, int & );.
 
int execute (std::string const &sql, std::string &tgt)
 See execute( std::string, int & );.
 
int execute (char const *sql, sqlite3_text_char_t const **tgt, int &len)
 See execute( std::string, int & );. More...
 
int execute (std::string const &sql, sqlite3_text_char_t const **tgt, int &len)
 See execute( char const *, sqlite3_text_char_t const **, int & ). More...
 
int execute (std::string const &sql, void const **tgt, int &sz)
 See execute( char const *, sqlite3_text_char_t **, int & ). More...
 
int execute (char const *sql, void const **tgt, int &sz)
 See execute( char const *, sqlite3_text_char_t **, int & ). More...
 
int execute (std::string const &sql, sqlite3_callback callback, void *data, std::string &errmsg)
 Executes the given query, calling the given callback function for each row of the result set. More...
 
int execute (char const *sql, sqlite3_callback callback, void *data, std::string &errmsg)
 Identical to the execute(std::string,sqlite3_callback,void*,std::string&).
 
int execute (std::string const &sql, sqlite3_callback callback, void *data=0)
 Convenience overload which has a default data value of 0 and ignores any error string passed back by sqlite3_exec().
 
int execute (char const *sql, sqlite3_callback callback, void *data=0)
 Convenience overload which has a default data value of 0 and ignores any error string passed back by sqlite3_exec().
 
int pragma (char const *code)
 This is a convenience wrapper for execute( "pragma ..." ). More...
 
int vacuum ()
 Convenience wrapper around execute("vacuum"). More...
 

Protected Member Functions

virtual int on_open ()
 Called when open() succeeds. More...
 

Detailed Description

log_db is a simple logging database for use with arbitrary applications.

It is intended to be a small logger for simple systems, and not a powerful logging system. The main advantages of using an sqlite3 db instead of a conventional log file are:

In the case that you want to query the data, this type creates a table named 'log' with the fields (ts,msg), containing the timestamp and log message, respectively.

Definition at line 28 of file sq3_log_db.hpp.

Constructor & Destructor Documentation

◆ log_db() [1/2]

sq3::log_db::log_db ( std::string const &  filename)
explicit

Opens/creates a db from the given filename.

Note that this function cannot notify the user if the file cannot be created or if the file is not really a DB file (in which case all logging will silently fail)! Use this->is_open() to find out if the open() worked!

Note that it is not legal to have more than one instance with the same filename - the second instance will not be able to open the database! It is also not strictly legal to re-use an existing non-log_db database.

Definition at line 10 of file sq3_log_db.cpp.

References sq3::database::open().

◆ log_db() [2/2]

sq3::log_db::log_db ( )

Creates an unopened database.

Use this->open() to open it.

Member Function Documentation

◆ clear()

int sq3::log_db::clear ( )
virtual

Empties the log database.

Returns SQLITE_OK on success or some other value on error (e.g., db is not open).

Reimplemented from sq3::database.

Definition at line 36 of file sq3_log_db.cpp.

References sq3::database::execute().

◆ log() [1/2]

bool sq3::log_db::log ( std::string const &  msg)

Logs a message to the log database.

Returns true on success, false on error.

If the format string evaluates to an empty string, this function returns true but does not log the entry.

Definition at line 44 of file sq3_log_db.cpp.

References sq3::statement::bind(), sq3::statement::execute(), sq3::database::is_open(), and sq3::rc_is_okay().

◆ log() [2/2]

bool sq3::log_db::log ( char const *  format,
  ... 
)

Logs the given printf-formatted string to the database.

If the resulting string is "too long" then it is internally truncated. "Too long" is rather arbitrarily chosen to be 2k of text.

If the format string evaluates to an empty string, this function returns true but does not log the entry.

In gcc, vsnprintf() is in the std namespace, but in MSVC it is not, so we use 'using' to accomodate both cases.

Definition at line 58 of file sq3_log_db.cpp.

References sq3::statement::bind(), sq3::statement::execute(), and sq3::database::is_open().

◆ on_open()

int sq3::log_db::on_open ( )
protectedvirtual

Called when open() succeeds.

Reimplemented to create the logging table if it's not already in the db.

enable temp_store=MEMORY to speed this up considably on PocketPC devices writing to SD cards.

Reimplemented from sq3::database.

Definition at line 20 of file sq3_log_db.cpp.

References sq3::database::execute(), sq3::database::is_open(), and sq3::database::pragma().

◆ show_last()

void sq3::log_db::show_last ( int  howMany)
virtual

Shows the last count entries using a subclass-specific method.

The default is to send the items to std::cout. A subclass could override this to show a dialog box, for example. A subclass which does so may also want to call the base implementation but certainly doesn't need to.

Subclasses are requested to respect the howMany argument, but may of course format the data to suit their desires.

Definition at line 96 of file sq3_log_db.cpp.

References sq3::cursor::get(), sq3::database::is_open(), and sq3::cursor::step().

◆ trim()

bool sq3::log_db::trim ( int  leaveThisMany)

Deletes all entries in the log except the leaveThisMany most recent.

e.g. Trim( 5 ) leaves only the most recent 5 entries in the database. The intent of this function is to give applications a way of keeping the log size small without having to use Clear() to empty the whole database.

Returns true on success, false on error.

Definition at line 139 of file sq3_log_db.cpp.

References sq3::database::execute(), sq3::database::is_open(), and sq3::database::vacuum().


The documentation for this class was generated from the following files: