/usr/include/mysql++/connection.h is in libmysql++-dev 3.2.1+pristine-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 | /// \file connection.h
/// \brief Declares the Connection class.
///
/// Every program using MySQL++ must create a Connection object, which
/// manages information about the connection to the database server, and
/// performs connection-related operations once the connection is up.
/// Subordinate classes, such as Query and Row take their defaults as
/// to whether exceptions are thrown when errors are encountered from
/// the Connection object that created them, directly or indirectly.
/***********************************************************************
Copyright (c) 1998 by Kevin Atkinson, (c) 1999-2001 by MySQL AB, and
(c) 2004-2007 by Educational Technology Resources, Inc. Others may
also hold copyrights on code in this file. See the CREDITS.txt file
in the top directory of the distribution for details.
This file is part of MySQL++.
MySQL++ is free software; you can redistribute it and/or modify it
under the terms of the GNU Lesser General Public License as published
by the Free Software Foundation; either version 2.1 of the License, or
(at your option) any later version.
MySQL++ is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public
License for more details.
You should have received a copy of the GNU Lesser General Public
License along with MySQL++; if not, write to the Free Software
Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301
USA
***********************************************************************/
#if !defined(MYSQLPP_CONNECTION_H)
#define MYSQLPP_CONNECTION_H
#include "common.h"
#include "noexceptions.h"
#include "options.h"
#include <string>
namespace mysqlpp {
#if !defined(DOXYGEN_IGNORE)
// Make Doxygen ignore this
class MYSQLPP_EXPORT Query;
class DBDriver;
#endif
/// \brief Manages the connection to the database server.
///
/// This class is a thick wrapper around DBDriver, adding high-level
/// error handling, utility functions, and abstraction away from
/// underlying C API details.
class MYSQLPP_EXPORT Connection : public OptionalExceptions
{
private:
/// \brief Pointer to bool data member, for use by safe bool
/// conversion operator.
///
/// \see http://www.artima.com/cppsource/safebool.html
typedef bool Connection::*private_bool_type;
public:
/// \brief Create object without connecting to the database server.
///
/// \param te if true, exceptions are thrown on errors
Connection(bool te = true);
/// \brief 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 database server.
///
/// \param db name of database to select upon connection
/// \param server specifies the IPC method and parameters for
/// contacting the server; see below for details
/// \param user user name to log in under, or 0 to use the user
/// name this program is running under
/// \param password password to use when logging in
/// \param port TCP port number database server is listening on, or
/// 0 to use default value; note that you may also give this as
/// part of the \c server parameter
///
/// The server parameter can be any of several different forms:
///
/// - \b 0: Let the database driver decide how to connect; usually
/// some sort of localhost IPC method.
/// - \b ".": On Windows, this means named pipes, if the server
/// supports it
/// - \b "/some/domain/socket/path": If the passed string doesn't
/// match one of the previous alternatives and we're on a system
/// that supports Unix domain sockets, MySQL++ will test it to see
/// if it names one, and use it if we have permission.
/// - \b "host.name.or.ip:port": If the previous test fails, or if
/// the system doesn't support Unix domain sockets at all, it
/// assumes the string is some kind of network address, optionally
/// followed by a colon and port. The name can be in dotted quad
/// form, a host name, or a domain name. The port can either be a
/// TCP/IP port number or a symbolic service name. If a port or
/// service name is given here and a nonzero value is passed for
/// the \c port parameter, the latter takes precedence.
Connection(const char* db, const char* server = 0, const char* user = 0,
const char* password = 0, unsigned int port = 0);
/// \brief Establish a new connection using the same parameters as
/// an existing connection.
///
/// \param other existing Connection object
Connection(const Connection& other);
/// \brief Destroy object
virtual ~Connection();
/// \brief Get version of library underpinning the current database
/// driver.
std::string client_version() const;
/// \brief 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.
virtual bool connect(const char* db = 0, const char* server = 0,
const char* user = 0, const char* password = 0,
unsigned int port = 0);
/// \brief Returns true if connection was established successfully
///
/// \return true if connection was established successfully
bool connected() const;
/// \brief Returns the number of rows in a table
///
/// \param table name of table whose rows you want counted
///
/// This is syntactic sugar for a \c SELECT \c COUNT(*)
/// \c FROM \c table SQL query.
ulonglong count_rows(const std::string& table);
/// \brief Ask the database server to create a database
///
/// \param db name of database to create
///
/// \return true if database was created successfully
bool create_db(const std::string& db);
/// \brief Drop the connection to the database server
void disconnect();
/// \brief Returns a reference to the current database driver
///
/// \internal This exists mostly for the benefit of Query, Result
/// and ResUse. If there is something you want to use in the
/// DBDriver interface, look for something similar in one of these
/// classes instead. If you still can't find it, send a message to
/// the mailing list asking about it. Unless you're doing something
/// very low-level, there should never be a reason to use the
/// driver directly.
DBDriver* driver() { return driver_; }
/// \brief Asks the database server to drop (destroy) a database
///
/// \param db name of database to destroy
///
/// \return true if database was dropped successfully
bool drop_db(const std::string& db);
/// \brief Return last error number associated with this
/// connection
int errnum();
/// \brief Return error message for last error associated with
/// this connection.
///
/// Returns either a MySQL++-specific error message if one exists,
/// or one from the current database driver otherwise.
const char* error() const;
/// \brief Get information about the IPC connection to the
/// database server
///
/// String contains info about type of connection (e.g. TCP/IP,
/// named pipe, Unix socket...) and the server hostname.
std::string ipc_info() const;
/// \brief Kill a database server thread
///
/// \param tid ID of thread to kill
///
/// \see thread_id()
bool kill(unsigned long tid) const;
/// \brief Test whether any error has occurred within the object.
///
/// Allows the object to be used in bool context, like this:
///
/// \code
/// Connection conn;
/// .... use conn
/// if (conn) {
/// ... nothing bad has happened since last successful use
/// }
/// else {
/// ... some error has occurred
/// }
/// \endcode
///
/// Prior to MySQL++ v3, the object was always falsy when we
/// weren't connected. Now a true return simply indicates a lack of
/// errors. If you've been using this to test for whether the
/// connection is still up, you need to call connected() instead.
operator private_bool_type() const
{
return copacetic_ ? &Connection::copacetic_ : 0;
}
/// \brief Copy an existing Connection object's state into this
/// object.
Connection& operator=(const Connection& rhs);
/// \brief "Pings" the database server
///
/// \retval true if server is responding
/// \retval false if either we already know the connection is down
/// and cannot re-establish it, or if the server did not respond to
/// the ping and we could not re-establish the connection.
bool ping();
/// \brief Returns version number of the protocol the database
/// driver uses to communicate with the server.
int protocol_version() const;
/// \brief Return a new query object.
///
/// The returned query object is tied to this connection object,
/// so when you call a method like
/// \link Query::execute() execute() \endlink
/// on that object, the query is sent to the server this object
/// is connected to.
///
/// \param qstr an optional query string for populating the
/// new Query object
Query query(const char* qstr = 0);
/// \brief Return a new query object
///
/// \param qstr initial query string
Query query(const std::string& qstr);
/// \brief Change to a different database managed by the
/// database server we are connected to.
///
/// \param db database to switch to
///
/// \retval true if we changed databases successfully
bool select_db(const std::string& db);
/// \brief Get the database server's version string
std::string server_version() const;
/// \brief Sets a connection option
///
/// \param o pointer to any derivative of Option allocated on
/// the heap
///
/// Objects passed to this method and successfully set will be
/// released when this Connection object is destroyed. If an error
/// occurs while setting the option the object will be deleted
/// immediately.
///
/// Because there are so many Option subclasses, the actual effect
/// of this function has a wide range. This mechanism abstracts
/// away many things that are unrelated down at the database driver
/// level, hiding them behind a coherent, type-safe interface.
///
/// The rules about which options can be set, when, are up to the
/// underlying database driver. Some must be set before the
/// connection is established because they can only be used during
/// that connection setup process. Others can be set at any time
/// after the connection comes up. If you get it wrong, you'll get
/// a BadOption exception.
///
/// \retval true if option was successfully set
bool set_option(Option* o);
/// \brief Ask database server to shut down.
bool shutdown();
/// \brief Returns information about database server's status
std::string server_status() const;
/// \brief Returns true if both MySQL++ and database driver we're
/// using were compiled with thread awareness.
static bool thread_aware();
/// \brief Tells the underlying database driver that this thread
/// is done using the library.
static void thread_end();
/// \brief Returns the database server's thread ID for this connection
///
/// This has nothing to do with threading on the client side. The
/// only thing you can do with this value is pass it to kill().
unsigned long thread_id();
/// \brief Tells the underlying database driver that the current
/// thread is now using its services.
///
/// It's not necessary to call this from the thread that creates
/// the connection as it's done automatically. This method exists
/// for times when multiple threads may use this object; it allows
/// the underlying database driver to set up any per-thread data
/// structures it needs.
///
/// The MySQL++ user manual's <a href="../userman/threads.html">chapter
/// on threads</a> details two major strategies for dealing with
/// connections in the face of threads. The Connection-per-thread
/// option frees you from ever having to call this method. The
/// other documented strategy is to use ConnectionPool, which opens
/// the possibility for one thread to create a connection that
/// another uses, so you do need to call this method in that case,
/// or with any other similar strategy.
///
/// \retval True if there was no problem
static bool thread_start();
protected:
/// \brief Build an error message in the standard form used whenever
/// one of the methods can't succeed because we're not connected to
/// the database server.
void build_error_message(const char* core);
/// \brief Establish a new connection as a copy of an existing one
///
/// \param other the connection to copy
void copy(const Connection& other);
/// \brief Extract elements from the server parameter in formats
/// suitable for passing to DBDriver::connect().
bool parse_ipc_method(const char* server, std::string& host,
unsigned int& port, std::string& socket_name);
//// Subclass data
mutable std::string error_message_; ///< MySQL++ specific error, if any
private:
DBDriver* driver_;
bool copacetic_;
};
} // end namespace mysqlpp
// Not strictly required, but bring in our specialization subclasses
#include "tcp_connection.h"
#include "uds_connection.h"
#include "wnp_connection.h"
#endif // !defined(MYSQLPP_CONNECTION_H)
|