Main Page   Namespace List   Class Hierarchy   Compound List   File List   Namespace Members   Compound Members   File Members  

mysqlpp::Connection Class Reference

Manages the connection to the MySQL database. More...

#include <connection.h>

Inheritance diagram for mysqlpp::Connection:

Inheritance graph
[legend]
Collaboration diagram for mysqlpp::Connection:

Collaboration graph
[legend]
List of all members.

Public Types

enum  OptionArgType
 Legal types of option arguments.

enum  Option
 Per-connection options you can set with set_option(). More...


Public Methods

MYSQLPP_EXPORT Connection (bool te=true)
 Create object without connecting it to the MySQL server.

MYSQLPP_EXPORT Connection (const char *db, const char *host="", const char *user="", const char *passwd="", uint port=0, my_bool compress=0, unsigned int connect_timeout=60, cchar *socket_name=0, unsigned int client_flag=0)
 Create object and connect to database server in one step.

MYSQLPP_EXPORT ~Connection ()
 Destroy connection object.

MYSQLPP_EXPORT bool connect (cchar *db="", cchar *host="", cchar *user="", cchar *passwd="", uint port=0, my_bool compress=0, unsigned int connect_timeout=60, cchar *socket_name=0, unsigned int client_flag=0)
 Connect to database after object is created.

void close ()
 Close connection to MySQL server.

MYSQLPP_EXPORT std::string info ()
 Calls MySQL C API function mysql_info() and returns result as a C++ string.

bool connected () const
 return true if connection was established successfully

bool success () const
 Return true if the last query was successful.

void purge ()
 Alias for close().

MYSQLPP_EXPORT Query query ()
 Return a new query object.

 operator bool ()
 Alias for success().

const char * error ()
 Return error message for last MySQL error associated with this connection.

int errnum ()
 Return last MySQL error number associated with this connection.

int refresh (unsigned int refresh_options)
 Wraps MySQL C API function mysql_refresh().

int ping ()
 "Pings" the MySQL database

int kill (unsigned long pid)
 Kill a MySQL server thread.

std::string client_info ()
 Get MySQL client library version.

std::string host_info ()
 Get information about the network connection.

int proto_info ()
 Returns version number of MySQL protocol this connection is using.

std::string server_info ()
 Get the MySQL server's version number.

std::string stat ()
 Returns information about MySQL server status.

MYSQLPP_EXPORT bool create_db (const std::string &db)
 Create a database.

MYSQLPP_EXPORT bool drop_db (const std::string &db)
 Drop a database.

bool select_db (const std::string &db)
 Change to a different database.

MYSQLPP_EXPORT bool select_db (const char *db)
 Change to a different database.

MYSQLPP_EXPORT bool reload ()
 Ask MySQL server to reload the grant tables.

MYSQLPP_EXPORT bool shutdown ()
 Ask MySQL server to shut down.

st_mysql_options get_options () const
 Return the connection options object.

MYSQLPP_EXPORT bool set_option (Option option)
 Sets a connection option, with no argument.

MYSQLPP_EXPORT bool set_option (Option option, const char *arg)
 Sets a connection option, with string argument.

MYSQLPP_EXPORT bool set_option (Option option, unsigned int arg)
 Sets a connection option, with integer argument.

MYSQLPP_EXPORT bool set_option (Option option, bool arg)
 Sets a connection option, with Boolean argument.

MYSQLPP_EXPORT void enable_ssl (const char *key=0, const char *cert=0, const char *ca=0, const char *capath=0, const char *cipher=0)
 Enable SSL-encrypted connection.

my_ulonglong affected_rows ()
 Return the number of rows affected by the last query.

my_ulonglong insert_id ()
 Get ID generated for an AUTO_INCREMENT column in the previous INSERT query.

std::ostream & api_version (std::ostream &os)
 Insert C API version we're linked against into C++ stream.


Protected Methods

MYSQLPP_EXPORT void disconnect ()
 Drop the connection to the database server.

bool option_pending (Option option, bool arg) const
 Returns true if the given option is to be set once connection comes up.

void apply_pending_options ()
 For each option in pending option queue, call set_option().

bool bad_option (Option option, OptionArgType type)
 Generic wrapper for bad_option_*().

bool bad_option_type (Option option)
 Handles call of incorrect set_option() overload.

bool bad_option_value (Option option)
 Handles bad option values sent to set_option().

OptionArgType option_arg_type (Option option)
 Given option value, return its proper argument type.

bool set_option_impl (mysql_option moption, const void *arg=0)
 Set MySQL C API connection option.


Detailed Description

Manages the connection to the MySQL database.


Member Enumeration Documentation

enum mysqlpp::Connection::Option
 

Per-connection options you can set with set_option().

This is currently a combination of the MySQL C API mysql_option and enum_mysql_set_option enums. It may be extended in the future.


Constructor & Destructor Documentation

mysqlpp::Connection::Connection bool    te = true
 

Create object without connecting it to the MySQL server.

Parameters:
te  if true, exceptions are thrown on errors

mysqlpp::Connection::Connection const char *    db,
const char *    host = "",
const char *    user = "",
const char *    passwd = "",
uint    port = 0,
my_bool    compress = 0,
unsigned int    connect_timeout = 60,
cchar   socket_name = 0,
unsigned int    client_flag = 0
 

Create object and connect to database server in one step.

This constructor allows you to most fully specify the options used when connecting to the MySQL database. It is the thinnest layer in MySQL++ over the MySQL C API function mysql_real_connect(). The correspondence isn't exact as we have some additional parameters you'd have to set with mysql_option() when using the C API.

Parameters:
db  name of database to use
host  host name or IP address of MySQL server, or 0 if server is running on the same host as your program
user  user name to log in under, or 0 to use the user name this program is running under
passwd  password to use when logging in
port  TCP port number MySQL server is listening on, or 0 to use default value
compress  if true, compress data passing through connection, to save bandwidth at the expense of CPU time
connect_timeout  max seconds to wait for server to respond to our connection attempt
socket_name  Unix domain socket server is using, if connecting to MySQL server on the same host as this program running on, or 0 to use default name
client_flag  special connection flags. See MySQL C API documentation for mysql_real_connect() for details.


Member Function Documentation

my_ulonglong mysqlpp::Connection::affected_rows   [inline]
 

Return the number of rows affected by the last query.

Simply wraps mysql_affected_rows() in the C API.

ostream & mysqlpp::Connection::api_version std::ostream &    os
 

Insert C API version we're linked against into C++ stream.

Version will be of the form X.Y.Z, where X is the major version number, Y the minor version, and Z the bug fix number.

void mysqlpp::Connection::apply_pending_options   [protected]
 

For each option in pending option queue, call set_option().

Called within connect() method after connection is established. Despools options in the order given to set_option().

std::string mysqlpp::Connection::client_info   [inline]
 

Get MySQL client library version.

Simply wraps mysql_get_client_info() in the C API.

void mysqlpp::Connection::close   [inline]
 

Close connection to MySQL server.

Closes the connection to the MySQL server.

bool mysqlpp::Connection::connect cchar   db = "",
cchar   host = "",
cchar   user = "",
cchar   passwd = "",
uint    port = 0,
my_bool    compress = 0,
unsigned int    connect_timeout = 60,
cchar   socket_name = 0,
unsigned int    client_flag = 0
 

Connect to database after object is created.

It's better to use the connect-on-create constructor if you can. See its documentation for the meaning of these parameters.

If you call this method on an object that is already connected to a database server, the previous connection is dropped and a new connection is established.

bool mysqlpp::Connection::connected   const [inline]
 

return true if connection was established successfully

Returns:
true if connection was established successfully

bool mysqlpp::Connection::create_db const std::string &    db
 

Create a database.

Parameters:
db  name of database to create
Returns:
true if database was created successfully

void mysqlpp::Connection::disconnect   [protected]
 

Drop the connection to the database server.

This method is protected because it should only be used within the library. Unless you use the default constructor, this object should always be connected.

bool mysqlpp::Connection::drop_db const std::string &    db
 

Drop a database.

Parameters:
db  name of database to destroy
Returns:
true if database was created successfully

void mysqlpp::Connection::enable_ssl const char *    key = 0,
const char *    cert = 0,
const char *    ca = 0,
const char *    capath = 0,
const char *    cipher = 0
 

Enable SSL-encrypted connection.

Parameters:
key  the pathname to the key file
cert  the pathname to the certificate file
ca  the pathname to the certificate authority file
capath  directory that contains trusted SSL CA certificates in pem format.
cipher  list of allowable ciphers to use
Must be called before connection is established.

Wraps mysql_ssl_set() in MySQL C API.

int mysqlpp::Connection::errnum   [inline]
 

Return last MySQL error number associated with this connection.

Simply wraps mysql_errno() in the C API.

const char* mysqlpp::Connection::error   [inline]
 

Return error message for last MySQL error associated with this connection.

Simply wraps mysql_error() in the C API.

std::string mysqlpp::Connection::host_info   [inline]
 

Get information about the network connection.

String contains info about type of connection and the server hostname.

Simply wraps mysql_get_host_info() in the C API.

my_ulonglong mysqlpp::Connection::insert_id   [inline]
 

Get ID generated for an AUTO_INCREMENT column in the previous INSERT query.

Return values:
0  if the previous query did not generate an ID. Use the SQL function LAST_INSERT_ID() if you need the last ID generated by any query, not just the previous one.

int mysqlpp::Connection::kill unsigned long    pid [inline]
 

Kill a MySQL server thread.

Parameters:
pid  ID of thread to kill
Simply wraps mysql_kill() in the C API.

mysqlpp::Connection::operator bool   [inline]
 

Alias for success().

Alias for success() member function. Allows you to have code constructs like this:

                    Connection conn;
                    .... use conn
                    if (conn) {
                        ... last SQL query was successful
                    }
                    else {
                        ... error occurred in SQL query
                    }

bool mysqlpp::Connection::option_pending Option    option,
bool    arg
const [protected]
 

Returns true if the given option is to be set once connection comes up.

Parameters:
option  option to check for in queue
arg  argument to match against

int mysqlpp::Connection::ping   [inline]
 

"Pings" the MySQL database

If server doesn't respond, this function tries to reconnect.

Return values:
0  if server is responding, regardless of whether we had to reconnect or not
nonzero  if server did not respond to ping and we could not re-establish the connection
Simply wraps mysql_ping() in the C API.

int mysqlpp::Connection::proto_info   [inline]
 

Returns version number of MySQL protocol this connection is using.

Simply wraps mysql_get_proto_info() in the C API.

Query mysqlpp::Connection::query  
 

Return a new query object.

The returned query object is tied to this MySQL connection, so when you call a method like execute() on that object, the query is sent to the server this object is connected to.

int mysqlpp::Connection::refresh unsigned int    refresh_options [inline]
 

Wraps MySQL C API function mysql_refresh().

The corresponding C API function is undocumented. All I know is that it's used by mysqldump and mysqladmin, according to MySQL bug database entry http://bugs.mysql.com/bug.php?id=9816 If that entry changes to say that the function is now documented, reevaluate whether we need to wrap it. It may be that it's not supposed to be used by regular end-user programs.

bool mysqlpp::Connection::reload  
 

Ask MySQL server to reload the grant tables.

User must have the "reload" privilege.

Simply wraps mysql_reload() in the C API. Since that function is deprecated, this one is, too. The MySQL++ replacement is execute("FLUSH PRIVILEGES").

std::string mysqlpp::Connection::server_info   [inline]
 

Get the MySQL server's version number.

Simply wraps mysql_get_server_info() in the C API.

bool mysqlpp::Connection::set_option Option    option
 

Sets a connection option, with no argument.

Parameters:
option  any of the Option enum constants
Based on the option you give, this function calls either mysql_options() or mysql_set_server_option() in the C API.

There are several overloaded versions of this function. The others take an additional argument for the option and differ only by the type of the option. Unlike with the underlying C API, it does matter which of these overloads you call: if you use the wrong argument type or pass an argument where one is not expected (or vice versa), the call will either throw an exception or return false, depending on the object's "throw exceptions" flag.

This mechanism parallels the underlying C API structure fairly closely, but do not expect this to continue in the future. Its very purpose is to 'paper over' the differences among the C API's option setting mechanisms, so it may become further abstracted from these mechanisms.

Return values:
true  if option was successfully set
If exceptions are enabled, a false return means the C API rejected the option, or the connection is not established and so the option was queued for later processing. If exceptions are disabled, false can also mean that the argument was of the wrong type (wrong overload was called), the option value was out of range, or the option is not supported by the C API, most because it isn't a high enough version. These latter cases will cause BadOption exceptions otherwise.

bool mysqlpp::Connection::set_option_impl mysql_option    moption,
const void *    arg = 0
[protected]
 

Set MySQL C API connection option.

Wraps mysql_options() in C API. This is an internal implementation detail, to be used only by the public overloads above.

bool mysqlpp::Connection::shutdown  
 

Ask MySQL server to shut down.

User must have the "shutdown" privilege.

Simply wraps mysql_shutdown() in the C API.

std::string mysqlpp::Connection::stat   [inline]
 

Returns information about MySQL server status.

String is similar to that returned by the mysqladmin status command. Among other things, it contains uptime in seconds, and the number of running threads, questions and open tables.


The documentation for this class was generated from the following files:
Generated on Thu Aug 25 02:55:54 2005 for MySQL++ by doxygen1.2.18