MySQL++ Reference Manual

- Main Page
- Namespaces
- Classes
- Files

- File List
- File Members

dbdriver.h
Go to the documentation of this file.
1
4 /***********************************************************************
5 Copyright (c) 1998 by Kevin Atkinson, (c) 1999-2001 by MySQL AB, and
6 (c) 2004-2009 by Educational Technology Resources, Inc. Others may
7 also hold copyrights on code in this file. See the CREDITS.txt file
8 in the top directory of the distribution for details.
9
10 This file is part of MySQL++.
11
12 MySQL++ is free software; you can redistribute it and/or modify it
13 under the terms of the GNU Lesser General Public License as published
14 by the Free Software Foundation; either version 2.1 of the License, or
15 (at your option) any later version.
16
17 MySQL++ is distributed in the hope that it will be useful, but WITHOUT
18 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
19 FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public
20 License for more details.
21
22 You should have received a copy of the GNU Lesser General Public
23 License along with MySQL++; if not, write to the Free Software
24 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301
25 USA
26 ***********************************************************************/
27
28 #if !defined(MYSQLPP_DBDRIVER_H)
29 #define MYSQLPP_DBDRIVER_H
30
31 #include "common.h"
32
33 #include "options.h"
34
35 #include <typeinfo>
36
37 #include <limits.h>
38
39 namespace mysqlpp {
40
56
57 class MYSQLPP_EXPORT DBDriver
58 {
59 public:
61 enum nr_code {
62 nr_more_results,
63 nr_last_result,
64 nr_error,
65 nr_not_supported
66 };
67
69 DBDriver();
70
77 DBDriver(const DBDriver& other);
78
80 virtual ~DBDriver();
81
85 ulonglong affected_rows()
86 {
87 error_message_.clear();
88 return mysql_affected_rows(&mysql_);
89 }
90
94 std::string client_version() const
95 {
96 error_message_.clear();
97 return mysql_get_client_info();
98 }
99
104 bool connect(const MYSQL& mysql);
105
111 virtual bool connect(const char* host, const char* socket_name,
112 unsigned int port, const char* db, const char* user,
113 const char* password);
114
122 bool connected() const { return is_connected_; }
123
127 void copy(const DBDriver& other);
128
134 bool create_db(const char* db) const;
135
139 void data_seek(MYSQL_RES* res, ulonglong offset) const
140 {
141 error_message_.clear();
142 mysql_data_seek(res, offset);
143 }
144
150 void disconnect();
151
157 bool drop_db(const std::string& db) const;
158
174 bool enable_ssl(const char* key = 0, const char* cert = 0,
175 const char* ca = 0, const char* capath = 0,
176 const char* cipher = 0);
177
183 const char* error()
184 {
185 return error_message_.length() ? error_message_.c_str() : mysql_error(&mysql_);
186 }
187
192 int errnum() { return mysql_errno(&mysql_); }
193
211 size_t escape_string(char* to, const char* from, size_t length)
212 {
213 error_message_.clear();
214 return mysql_real_escape_string(&mysql_, to, from,
215 static_cast<unsigned long>(length));
216 }
217
257 size_t escape_string(std::string* ps, const char* original,
258 size_t length);
259
266 static size_t escape_string_no_conn(char* to, const char* from,
267 size_t length)
268 {
269 return mysql_escape_string(to, from,
270 static_cast<unsigned long>(length));
271 }
272
278 static size_t escape_string_no_conn(std::string* ps,
279 const char* original = 0, size_t length = 0);
280
284 bool execute(const char* qstr, size_t length)
285 {
286 error_message_.clear();
287 return !mysql_real_query(&mysql_, qstr,
288 static_cast<unsigned long>(length));
289 }
290
298 MYSQL_ROW fetch_row(MYSQL_RES* res) const
299 {
300 error_message_.clear();
301 return mysql_fetch_row(res);
302 }
303
308 const unsigned long* fetch_lengths(MYSQL_RES* res) const
309 {
310 error_message_.clear();
311 return mysql_fetch_lengths(res);
312 }
313
327 MYSQL_FIELD* fetch_field(MYSQL_RES* res, size_t i = UINT_MAX) const
328 {
329 error_message_.clear();
330 return i == UINT_MAX ? mysql_fetch_field(res) :
331 mysql_fetch_field_direct(res,
332 static_cast<unsigned int>(i));
333 }
334
338 void field_seek(MYSQL_RES* res, size_t field) const
339 {
340 error_message_.clear();
341 mysql_field_seek(res, MYSQL_FIELD_OFFSET(field));
342 }
343
347 void free_result(MYSQL_RES* res) const
348 {
349 error_message_.clear();
350 mysql_free_result(res);
351 }
352
354 st_mysql_options get_options() const { return mysql_.options; }
355
363 std::string ipc_info()
364 {
365 error_message_.clear();
366 return mysql_get_host_info(&mysql_);
367 }
368
379 ulonglong insert_id()
380 {
381 error_message_.clear();
382 return mysql_insert_id(&mysql_);
383 }
384
392 bool kill(unsigned long tid)
393 {
394 error_message_.clear();
395 return !mysql_kill(&mysql_, tid);
396 }
397
402 bool more_results()
403 {
404 error_message_.clear();
405 #if MYSQL_VERSION_ID > 41000 // only in MySQL v4.1 +
406 return mysql_more_results(&mysql_);
407 #else
408 return false;
409 #endif
410 }
411
421 nr_code next_result()
422 {
423 error_message_.clear();
424 #if MYSQL_VERSION_ID > 41000 // only in MySQL v4.1 +
425 switch (mysql_next_result(&mysql_)) {
426 case 0: return nr_more_results;
427 case -1: return nr_last_result;
428 default: return nr_error;
429 }
430 #else
431 return nr_not_supported;
432 #endif
433 }
434
438 int num_fields(MYSQL_RES* res) const
439 {
440 error_message_.clear();
441 return mysql_num_fields(res);
442 }
443
447 ulonglong num_rows(MYSQL_RES* res) const
448 {
449 error_message_.clear();
450 return mysql_num_rows(res);
451 }
452
463 bool ping()
464 {
465 error_message_.clear();
466 return !mysql_ping(&mysql_);
467 }
468
473 int protocol_version()
474 {
475 error_message_.clear();
476 return mysql_get_proto_info(&mysql_);
477 }
478
482 std::string query_info();
483
492 bool refresh(unsigned options)
493 {
494 error_message_.clear();
495 return !mysql_refresh(&mysql_, options);
496 }
497
502 bool result_empty()
503 {
504 error_message_.clear();
505 return mysql_field_count(&mysql_) == 0;
506 }
507
509 bool select_db(const char* db)
510 {
511 error_message_.clear();
512 return !mysql_select_db(&mysql_, db);
513 }
514
518 std::string server_version()
519 {
520 error_message_.clear();
521 return mysql_get_server_info(&mysql_);
522 }
523
532 bool set_option(Option* o);
533
537 bool set_option(mysql_option moption, const void* arg = 0)
538 {
539 error_message_.clear();
540 return !mysql_options(&mysql_, moption,
541 static_cast<const char*>(arg));
542 }
543
544 #if MYSQL_VERSION_ID >= 40101
545 bool set_option(enum_mysql_set_option msoption)
549 {
550 error_message_.clear();
551 return !mysql_set_server_option(&mysql_, msoption);
552 }
553 #endif
554
560 bool set_option(unsigned int option, bool arg);
561
564 bool set_option_default(Option* o)
565 {
566 const std::type_info& ti = typeid(o);
567 for (OptionList::const_iterator it = applied_options_.begin();
568 it != applied_options_.end();
569 ++it) {
570 if (typeid(*it) == ti) {
571 delete o;
572 return ""; // option of this type already set
573 }
574 }
575
576 return set_option(o);
577 }
578
584 bool shutdown();
585
594 std::string server_status()
595 {
596 error_message_.clear();
597 return mysql_stat(&mysql_);
598 }
599
607 MYSQL_RES* store_result()
608 {
609 error_message_.clear();
610 return mysql_store_result(&mysql_);
611 }
612
623 static bool thread_aware();
624
630 static void thread_end()
631 {
632 #if MYSQL_VERSION_ID > 40000 // only in MySQL v4.0 +
633 mysql_thread_end();
634 #endif
635 }
636
641 unsigned long thread_id()
642 {
643 error_message_.clear();
644 return mysql_thread_id(&mysql_);
645 }
646
665 static bool thread_start()
666 {
667 #if MYSQL_VERSION_ID > 40000 // only in MySQL v4.0 +
668 return !mysql_thread_init();
669 #else
670 return false;
671 #endif
672 }
673
681 MYSQL_RES* use_result()
682 {
683 error_message_.clear();
684 return mysql_use_result(&mysql_);
685 }
686
687 protected:
690 bool connect_prepare();
691
694 bool set_option_impl(Option* o);
695
696 private:
698 typedef std::deque<Option*> OptionList;
699
701 typedef OptionList::iterator OptionListIt;
702
705 DBDriver& operator=(const DBDriver&);
706
707 MYSQL mysql_;
708 bool is_connected_;
709 OptionList applied_options_;
710 OptionList pending_options_;
711 mutable std::string error_message_;
712 };
713
714
715 } // end namespace mysqlpp
716
717 #endif // !defined(MYSQLPP_DBDRIVER_H)
718
mysqlpp::DBDriver::get_options
st_mysql_options get_options() const
Return the connection options object.
Definition: dbdriver.h:354
mysqlpp::DBDriver::insert_id
ulonglong insert_id()
Get ID generated for an AUTO_INCREMENT column in the previous INSERT query.
Definition: dbdriver.h:379
mysqlpp::DBDriver::ping
bool ping()
&quot;Pings&quot; the MySQL database
Definition: dbdriver.h:463
mysqlpp::DBDriver::connected
bool connected() const
Return true if we have an active connection to the database server.
Definition: dbdriver.h:122
mysqlpp::DBDriver::set_option
bool set_option(mysql_option moption, const void *arg=0)
Set MySQL C API connection option.
Definition: dbdriver.h:537
mysqlpp::DBDriver::thread_start
static bool thread_start()
Tells the underlying C API library that the current thread will be using the library&#39;s services...
Definition: dbdriver.h:665
mysqlpp::DBDriver::nr_more_results
success, with more results to come
Definition: dbdriver.h:62
mysqlpp::DBDriver::data_seek
void data_seek(MYSQL_RES *res, ulonglong offset) const
Seeks to a particualr row within the result set.
Definition: dbdriver.h:139
mysqlpp::DBDriver::thread_end
static void thread_end()
Tells the underlying MySQL C API library that this thread is done using the library.
Definition: dbdriver.h:630
mysqlpp::DBDriver::affected_rows
ulonglong affected_rows()
Return the number of rows affected by the last query.
Definition: dbdriver.h:85
mysqlpp::DBDriver::set_option_default
bool set_option_default(Option *o)
Same as set_option(), except that it won&#39;t override a previously-set option.
Definition: dbdriver.h:564
mysqlpp::DBDriver::num_rows
ulonglong num_rows(MYSQL_RES *res) const
Returns the number of rows in the given result set.
Definition: dbdriver.h:447
mysqlpp::DBDriver::protocol_version
int protocol_version()
Returns version number of MySQL protocol this connection is using.
Definition: dbdriver.h:473
mysqlpp::DBDriver::escape_string_no_conn
static size_t escape_string_no_conn(char *to, const char *from, size_t length)
SQL-escapes the given string without reference to the character set of a database server...
Definition: dbdriver.h:266
mysqlpp::DBDriver::error
const char * error()
Return error message for last MySQL error associated with this connection.
Definition: dbdriver.h:183
mysqlpp::DBDriver::nr_code
nr_code
Result code returned by next_result()
Definition: dbdriver.h:61
mysqlpp::DBDriver::next_result
nr_code next_result()
Moves to the next result set from a multi-query.
Definition: dbdriver.h:421
mysqlpp::DBDriver::field_seek
void field_seek(MYSQL_RES *res, size_t field) const
Jumps to the given field within the result set.
Definition: dbdriver.h:338
mysqlpp::Option
Define abstract interface for all *Option subclasses.
Definition: options.h:57
mysqlpp::DBDriver::free_result
void free_result(MYSQL_RES *res) const
Releases memory used by a result set.
Definition: dbdriver.h:347
mysqlpp::DBDriver::fetch_lengths
const unsigned long * fetch_lengths(MYSQL_RES *res) const
Returns the lengths of the fields in the current row from a &quot;use&quot; query.
Definition: dbdriver.h:308
mysqlpp::DBDriver::server_status
std::string server_status()
Returns the database server&#39;s status.
Definition: dbdriver.h:594
mysqlpp::DBDriver::server_version
std::string server_version()
Get the database server&#39;s version number.
Definition: dbdriver.h:518
mysqlpp::DBDriver::client_version
std::string client_version() const
Get database client library version.
Definition: dbdriver.h:94
mysqlpp::DBDriver::store_result
MYSQL_RES * store_result()
Saves the results of the query just execute()d in memory and returns a pointer to the MySQL C API dat...
Definition: dbdriver.h:607
mysqlpp::DBDriver::result_empty
bool result_empty()
Returns true if the most recent result set was empty.
Definition: dbdriver.h:502
mysqlpp::DBDriver::more_results
bool more_results()
Returns true if there are unconsumed results from the most recent query.
Definition: dbdriver.h:402
mysqlpp::DBDriver::nr_error
problem retrieving next result
Definition: dbdriver.h:64
mysqlpp::DBDriver::fetch_row
MYSQL_ROW fetch_row(MYSQL_RES *res) const
Returns the next raw C API row structure from the given result set.
Definition: dbdriver.h:298
mysqlpp::DBDriver::nr_last_result
success, last result received
Definition: dbdriver.h:63
mysqlpp::DBDriver::kill
bool kill(unsigned long tid)
Kill a MySQL server thread.
Definition: dbdriver.h:392
mysqlpp::DBDriver::select_db
bool select_db(const char *db)
Asks the database server to switch to a different database.
Definition: dbdriver.h:509
mysqlpp::DBDriver::ipc_info
std::string ipc_info()
Get information about the IPC connection to the database server.
Definition: dbdriver.h:363
mysqlpp::DBDriver::thread_id
unsigned long thread_id()
Returns the MySQL server thread ID for this connection.
Definition: dbdriver.h:641
mysqlpp::DBDriver::refresh
bool refresh(unsigned options)
Asks the database server to refresh certain internal data structures.
Definition: dbdriver.h:492
common.h
This file includes top-level definitions for use both internal to the library, and outside it...
mysqlpp::DBDriver::num_fields
int num_fields(MYSQL_RES *res) const
Returns the number of fields in the given result set.
Definition: dbdriver.h:438
mysqlpp::DBDriver::errnum
int errnum()
Return last MySQL error number associated with this connection.
Definition: dbdriver.h:192
options.h
Declares the Option class hierarchy, used to implement connection options in Connection and DBDriver ...
mysqlpp::DBDriver::use_result
MYSQL_RES * use_result()
Returns a result set from the last-executed query which we can walk through in linear fashion...
Definition: dbdriver.h:681
mysqlpp::DBDriver::fetch_field
MYSQL_FIELD * fetch_field(MYSQL_RES *res, size_t i=UINT_MAX) const
Returns information about a particular field in a result set.
Definition: dbdriver.h:327
mysqlpp::DBDriver::execute
bool execute(const char *qstr, size_t length)
Executes the given query string.
Definition: dbdriver.h:284
mysqlpp::DBDriver::escape_string
size_t escape_string(char *to, const char *from, size_t length)
Return a SQL-escaped version of the given character buffer.
Definition: dbdriver.h:211
mysqlpp::DBDriver
Provides a thin abstraction layer over the underlying database client library.
Definition: dbdriver.h:57