mysql_cli::Conn Class Reference

MySQL connection class. More...

#include <conn.h>

List of all members.

Public Member Functions

 Conn ()
 Default constructor.
 Conn (char const *host, char const *user, char const *password, char const *db, unsigned int port, char const *us)
 Constructor with the same parameters as mysql_connect().
 Conn (Conn const &c)
 Copy constructor.
Connoperator= (Conn const &right)
 Assignment operator.
 ~Conn ()
 Destructor.
bool connect ()
 Connects to the MySQL server.
bool change_user (char const *user, char const *password, char const *db)
 Changes the current MySQL user.
bool select_db (char const *db)
 Changes the current MySQL database.
bool reconnect ()
 Reconnects to the MySQL server.
bool ping ()
 "Pings" the MySQL server.
void close (bool clear_queue)
 Closes the connection to the MySQL server.
unsigned long escape_string (misc::cstring &dest, char const *src, long len=-1)
 Escapes a string.
char const * escape_string (char const *str, long len=-1)
 Escapes a string.
bool query (char const *query, unsigned long length, Result *result, bool use=false)
 Executes a query.
bool query (char const *query, Result *result, bool use=false)
 Same as query(query, strlen(query), result, use);.
bool queryf (Result *result, char const *fmt,...) FORMAT(printf
 printf()-like interface to query() -- limited to queries with 16384 characters.
bool bool query_cache (std::string const &query, bool cache)
 Executes a query, with queuing facility.
bool connected () const
 Returns whether the MySQL connection is established.
bool gone () const
 Returns whether the server is gone or lost.
unsigned int queries () const
 Returns the number of queries that have been issued since connection.
time_t since () const
 Returns when the connection was established.
double exectime () const
 Returns the execution time for the last query.
unsigned long thread_id ()
 Returns the MySQL connection thread ID.
unsigned int errnum ()
 Returns the last error number that happened on the mysql connection.
char const * error ()
 Returns a string describing the last error that happened on the mysql connection.
char const * host_info ()
 Returns a string describing the connection, including server hostname.
unsigned int proto_info ()
 Returns the protocol version used by the connection.
char const * server_info ()
 Returns a string that represents the server version number.
unsigned long server_version ()
 Returns the version number of the server.
char const * stat ()
 Returns server status string.
my_ulonglong insert_id ()
 Returns the last insert ID.
my_ulonglong affected_rows ()
 Returns the number of rows affected by the last query.
unsigned int warning_count ()
 Returns the number of warnings for the last query.
char const * info ()
 Returns information about the last query.
unsigned int field_count ()
 Returns the number of fields for the last query.
unsigned int connect_timeout () const
 Returns the connection timeout (in seconds).
unsigned int connect_timeout (unsigned int timeout)
 Sets the connection timeout (in seconds).
my_bool reconnect () const
 Returns whether the connection is reestablished automatically.
my_bool reconnect (my_bool reco)
 Sets whether the connection is reestablished automatically.
char const * host () const
 Returns the MySQL hostname.
char const * host (char const *host)
 Sets the MySQL hostname.
unsigned int port () const
 Returns the MySQL port.
unsigned int port (unsigned int port)
 Sets the MySQL port.
char const * unix_socket () const
 Returns the MySQL hostname.
char const * unix_socket (char const *us)
 Sets the MySQL hostname.
char const * user () const
 Returns the MySQL username.
char const * user (char const *user)
 Sets the MySQL username.
char const * password () const
 Returns the MySQL password.
char const * password (char const *password)
 Sets the MySQL username.
char const * db () const
 Returns the MySQL database.
char const * db (char const *db)
 Sets the MySQL database.
char const * charset ()
 Returns the connection character set.
char const * charset (char const *charset)
 Sets the connection character set.
Events const * events () const
 Returns the event notifier object.
Eventsevents (Events *events)
 Sets the event notifier object.
bool log_queries () const
 Returns whether queries are logged.
bool log_queries (bool value)
 Sets whether queries are logged.
bool log_warnings () const
 Returns whether warnings are logged.
bool log_warnings (bool value)
 Sets whether warnings are logged.

Static Public Member Functions

static char const * client_info ()
 Returns the MySQL client library version string.
static unsigned long client_version ()
 Returns the MySQL client library version.

Protected Types

typedef std::deque
< std::string > 
queue_type
 Type of the query queue.

Protected Attributes

MYSQL * m_handle
 The MySQL connection handle.
bool m_connected
 Is it currently connected?
bool m_gone
 Is the server lost or gone away?
std::deque< std::string > m_queue
 Query queue.
unsigned int m_queries
 How much queries have been done?
time_t m_since
 Since when are we connected?
double m_exectime
 Last query execution time.
unsigned int m_ctimeout
 Connect timeout (in seconds).
my_bool m_reconnect
 Reconnect automatically ?
misc::cstring m_host
 Server's hostname.
unsigned int m_port
 Server's port.
misc::cstring m_unixsocket
 Server's unix socket.
misc::cstring m_user
 MySQL username.
misc::cstring m_password
 MySQL password.
misc::cstring m_db
 MySQL database.
misc::cstring m_charset
 Connection character set.
misc::cstring m_es
 A shared buffer for escape_string().
size_t m_essize
 Maximum size of the escape_string buffer.
Eventsm_e
 Events notifier.
bool m_logqueries
 Log queries?
bool m_logwarnings
 Log warnings?


Detailed Description

This class encapsulates a MySQL connection.

See the MySQL C API for more detailed information on some of the functions.


Constructor & Destructor Documentation

mysql_cli::Conn::Conn ( Conn const &  c  )  [inline]

Copy constructor. It copies the various data fields of the connection (like host, username, password...) but does not reestablish a connection.

Parameters:
[in] c The connection to copy.


Member Function Documentation

Conn& mysql_cli::Conn::operator= ( Conn const &  right  ) 

Assignment operator. Like the copy constructor, a new connection is not established.

Parameters:
[in] right The connection that is assigned.
Returns:
The connection object.
See also:
Conn(Conn const &)

bool mysql_cli::Conn::connect (  ) 

Connects to the MySQL server.

Returns:
true if successful, false otherwise. An evConnected event is logged if successful; an evError event is logged otherwise.

bool mysql_cli::Conn::change_user ( char const *  user,
char const *  password,
char const *  db 
)

Changes the current MySQL user. If the user, password or database is invalid, then no change is made and the connection is still valid. Else, the user(), password() and db() fields are updated automatically.

Parameters:
[in] user The user to change to.
[in] password The user's password.
[in] db The database to use.
Returns:
true if successful, false otherwise.

bool mysql_cli::Conn::select_db ( char const *  db  ) 

Changes the current MySQL database. If the database can't be changed, then no change is made and the connection is still valid. Else, the db() field is updated automatically.

Parameters:
[in] db The database to use.
Returns:
true if successful, false otherwise.

bool mysql_cli::Conn::reconnect (  )  [inline]

Reconnects to the MySQL server. This is equivalent to calling close(false) and connect(). It is generally used after a change of one of the connection credentials.

Returns:
The return value of connect().

bool mysql_cli::Conn::ping (  ) 

"Pings" the MySQL server, i.e. checks whether the connection is working. If the connection has gone down, a reconnection is attempted.

Returns:
true if the connection works, false otherwise.

void mysql_cli::Conn::close ( bool  clear_queue  ) 

Closes the connection to the MySQL server, if a connection is established.

Parameters:
[in] clear_queue true if the queue needs to be cleared, false otherwise.
An evClosed event is logged.

unsigned long mysql_cli::Conn::escape_string ( misc::cstring dest,
char const *  src,
long  len = -1 
)

Escapes a string in a way that is suitable to use in a query.

Parameters:
[in] dest The destination string, a misc::cstring object that will automatically be sized accordingly.
[in] src The string to escape.
[in] len The length of the string to escape. If this is -1, then the length is computed automatically.
Returns:
The length of the destination string.

char const* mysql_cli::Conn::escape_string ( char const *  str,
long  len = -1 
)

Escapes a string in a way that is suitable to use in a query. The returned string is stored in the object instance for which the method is called; therefore, further calls to this method for the same object will overwrite the contents of the returned string.

Parameters:
[in] str The string to escape.
[in] len The length of the string to escape. If this is -1, then the length is computed automatically.
Returns:
The escaped string.

bool mysql_cli::Conn::query ( char const *  query,
unsigned long  length,
Result result,
bool  use = false 
)

Executes a SQL query.

Parameters:
[in] query The query to execute.
[in] length The length of the query, in bytes.
[in] result If different than NULL, the result of the query will be assigned to this result object. If it is NULL, and the query returned a result, the function will automatically retrieve and free it, so that another query can take place afterwards.
[in] use If true, mysql_use_result() is used to get the result set instead of mysql_store_result().
Returns:
true if the query was successful and the retrieval of the result set succeeded, false otherwise.

bool bool mysql_cli::Conn::query_cache ( std::string const &  query,
bool  cache 
)

Executes a SQL query. By setting the appropriate parameter to true, the query is put in a queue when the server is gone and will be executed once the server comes back, in the connect() or ping() functions.

This function should be used only for queries that don't return a result set (there would be no way to retrieve them anyway).

Parameters:
[in] query The query to execute.
[in] cache Whether this query is allowed to be cached.
Returns:
true if the query was successful, false otherwise.

bool mysql_cli::Conn::gone (  )  const [inline]

Returns whether the server is gone or lost (i.e. if one of the MySQL functions returned CR_SERVER_GONE_ERROR or CR_SERVER_LOST), if the connection has not been reestablished.

Returns:
true if it is gone or lost, false otherwise.

char const* mysql_cli::Conn::info (  ) 

Returns information about the last query, but only for a few statements, including INSERT, ALTER TABLE and UPDATE.

Returns:
Information about the last query.

unsigned int mysql_cli::Conn::connect_timeout (  )  const [inline]

Returns the connection timeout (in seconds).

Returns:
The connection timeout, which may be zero if the default value must be used.

unsigned int mysql_cli::Conn::connect_timeout ( unsigned int  timeout  )  [inline]

Sets the connection timeout (in seconds).

Parameters:
[in] timeout The connection timeout. If it is zero, then the default value is used.
Returns:
The new connection timeout.

my_bool mysql_cli::Conn::reconnect (  )  const [inline]

Returns whether the connection is reestablished automatically if it was dropped and a query is made.

Returns:
true if the connection is reestablished automatically, false otherwise. By default, it is true.

my_bool mysql_cli::Conn::reconnect ( my_bool  reco  )  [inline]

Sets whether the connection is reestablished automatically if it was dropped and a query is made.

Parameters:
[in] reco true if the connection must be reestablished, false otherwise.
Returns:
The option's new value.

Events* mysql_cli::Conn::events ( Events events  ) 

Sets the event notifier object.

Parameters:
[in] events A pointer to the event notifier object. Conn will automatically free it when it's no longer needed.
Returns:
The new event notifier object.

bool mysql_cli::Conn::log_warnings ( bool  value  )  [inline]

Sets whether warnings are logged. Warnings may only be logged after a call to the execute() method.

Parameters:
[in] value true if the warnings need to be logged, false otherwise.


The documentation for this class was generated from the following file:
Generated on Fri Apr 18 22:03:29 2008 for Epona API by  doxygen 1.5.3