connection_base.hxx
/*-------------------------------------------------------------------------
*
* FILE
* pqxx/connection_base.hxx
*
* DESCRIPTION
* definition of the pqxx::connection_base abstract base class.
* pqxx::connection_base encapsulates a frontend to backend connection
* DO NOT INCLUDE THIS FILE DIRECTLY; include pqxx/connection_base instead.
*
* Copyright (c) 2001-2011, Jeroen T. Vermeulen <jtv@xs4all.nl>
*
* See COPYING for copyright license. If you did not receive a file called
* COPYING with this source code, please notify the distributor of this mistake,
* or contact the author.
*
*-------------------------------------------------------------------------
*/
#ifndef PQXX_H_CONNECTION_BASE
#define PQXX_H_CONNECTION_BASE
#include "pqxx/compiler-public.hxx"
#include "pqxx/compiler-internal-pre.hxx"
#include <bitset>
#include <list>
#include <map>
#include <memory>
#include "pqxx/errorhandler"
#include "pqxx/except"
#include "pqxx/prepared_statement"
#include "pqxx/strconv"
#include "pqxx/util"
/* Use of the libpqxx library starts here.
*
* Everything that can be done with a database through libpqxx must go through
* a connection object derived from connection_base.
*/
/* Methods tested in eg. self-test program test1 are marked with "//[t1]"
*/
namespace pqxx
{
class binarystring;
class connectionpolicy;
class notification_receiver;
class result;
class transaction_base;
namespace internal
{
class reactivation_avoidance_exemption;
class sql_cursor;
class reactivation_avoidance_counter
{
public:
reactivation_avoidance_counter() : m_counter(0) {}
void add(int n) throw () { m_counter += n; }
void clear() throw () { m_counter = 0; }
int get() const throw () { return m_counter; }
private:
int m_counter;
};
}
PGSTD::string PQXX_LIBEXPORT encrypt_password( //[t0]
const PGSTD::string &user,
const PGSTD::string &password);
namespace internal
{
namespace gate
{
class connection_dbtransaction;
class connection_errorhandler;
class connection_largeobject;
class connection_notification_receiver;
class connection_parameterized_invocation;
class connection_pipeline;
class connection_prepare_invocation;
class connection_reactivation_avoidance_exemption;
class connection_sql_cursor;
class connection_transaction;
} // namespace pqxx::internal::gate
} // namespace pqxx::internal
class PQXX_LIBEXPORT connection_base
{
public:
void disconnect() throw (); //[t2]
bool PQXX_PURE is_open() const throw (); //[t1]
void activate(); //[t12]
void deactivate(); //[t12]
void inhibit_reactivation(bool inhibit) //[t86]
{ m_inhibit_reactivation=inhibit; }
void simulate_failure(); //[t94]
void process_notice(const char[]) throw (); //[t14]
void process_notice(const PGSTD::string &) throw (); //[t14]
void trace(PGSTD::FILE *) throw (); //[t3]
const char *dbname(); //[t1]
const char *username(); //[t1]
const char *hostname(); //[t1]
const char *port(); //[t1]
int PQXX_PURE backendpid() const throw (); //[t1]
int PQXX_PURE sock() const throw (); //[t87]
enum capability
{
cap_prepared_statements,
cap_create_table_with_oids,
cap_nested_transactions,
cap_cursor_scroll,
cap_cursor_with_hold,
cap_cursor_update,
cap_cursor_fetch_0,
cap_table_column,
cap_read_only_transactions,
cap_statement_varargs,
cap_prepare_unnamed_statement,
cap_parameterized_statements,
cap_notify_payload,
cap_end
};
bool supports(capability c) const throw () { return m_caps.test(c); } //[t88]
int PQXX_PURE protocol_version() const throw (); //[t1]
int PQXX_PURE server_version() const throw (); //[t1]
void set_client_encoding(const PGSTD::string &Encoding) //[t7]
{ set_variable("CLIENT_ENCODING", Encoding); }
void set_variable(const PGSTD::string &Var,
const PGSTD::string &Value); //[t60]
PGSTD::string get_variable(const PGSTD::string &); //[t60]
int get_notifs(); //[t4]
int await_notification(); //[t78]
int await_notification(long seconds, long microseconds); //[t79]
void prepare(const PGSTD::string &name, const PGSTD::string &definition);
void prepare(const PGSTD::string &definition);
void unprepare(const PGSTD::string &name);
void prepare_now(const PGSTD::string &name);
template<typename TRANSACTOR>
void perform(const TRANSACTOR &T, int Attempts); //[t4]
template<typename TRANSACTOR>
void perform(const TRANSACTOR &T) { perform(T, 3); }
PGSTD::string adorn_name(const PGSTD::string &); //[90]
PGSTD::string esc(const char str[]);
PGSTD::string esc(const char str[], size_t maxlen);
PGSTD::string esc(const PGSTD::string &str);
PGSTD::string esc_raw(const unsigned char str[], size_t len);
PGSTD::string quote_raw(const unsigned char str[], size_t len);
PGSTD::string quote_name(const PGSTD::string &identifier);
template<typename T>
PGSTD::string quote(const T &t)
{
if (string_traits<T>::is_null(t)) return "NULL";
return "'" + this->esc(to_string(t)) + "'";
}
PGSTD::string quote(const binarystring &);
void cancel_query();
enum error_verbosity
{
// These values must match those in libpq's PGVerbosity enum.
terse=0,
normal=1,
verbose=2
};
void set_verbosity(error_verbosity verbosity) throw();
error_verbosity get_verbosity() const throw() {return m_verbosity;}
PGSTD::vector<errorhandler *> get_errorhandlers() const;
protected:
explicit connection_base(connectionpolicy &);
void init();
void close() throw ();
void wait_read() const;
void wait_read(long seconds, long microseconds) const;
void wait_write() const;
private:
result make_result(internal::pq::PGresult *rhs, const PGSTD::string &query);
void PQXX_PRIVATE clearcaps() throw ();
void PQXX_PRIVATE SetupState();
void PQXX_PRIVATE check_result(const result &);
void PQXX_PRIVATE InternalSetTrace() throw ();
int PQXX_PRIVATE PQXX_PURE Status() const throw ();
const char * PQXX_PURE ErrMsg() const throw ();
void PQXX_PRIVATE Reset();
void PQXX_PRIVATE RestoreVars();
PGSTD::string PQXX_PRIVATE RawGetVar(const PGSTD::string &);
void PQXX_PRIVATE process_notice_raw(const char msg[]) throw ();
void read_capabilities() throw ();
prepare::internal::prepared_def &find_prepared(const PGSTD::string &);
prepare::internal::prepared_def &register_prepared(const PGSTD::string &);
friend class internal::gate::connection_prepare_invocation;
result prepared_exec(const PGSTD::string &,
const char *const[],
const int[],
const int[],
int);
bool prepared_exists(const PGSTD::string &) const;
internal::pq::PGconn *m_Conn;
connectionpolicy &m_policy;
internal::unique<transaction_base> m_Trans;
PGSTD::list<errorhandler *> m_errorhandlers;
PGSTD::FILE *m_Trace;
typedef PGSTD::multimap<PGSTD::string, pqxx::notification_receiver *>
receiver_list;
receiver_list m_receivers;
PGSTD::map<PGSTD::string, PGSTD::string> m_Vars;
typedef PGSTD::map<PGSTD::string, prepare::internal::prepared_def> PSMap;
PSMap m_prepared;
int m_serverversion;
internal::reactivation_avoidance_counter m_reactivation_avoidance;
int m_unique_id;
bool m_Completed;
bool m_inhibit_reactivation;
PGSTD::bitset<cap_end> m_caps;
error_verbosity m_verbosity;
friend class internal::gate::connection_errorhandler;
void PQXX_PRIVATE register_errorhandler(errorhandler *);
void PQXX_PRIVATE unregister_errorhandler(errorhandler *) throw ();
friend class internal::gate::connection_transaction;
result PQXX_PRIVATE Exec(const char[], int Retries);
void PQXX_PRIVATE RegisterTransaction(transaction_base *);
void PQXX_PRIVATE UnregisterTransaction(transaction_base *) throw ();
bool PQXX_PRIVATE ReadCopyLine(PGSTD::string &);
void PQXX_PRIVATE WriteCopyLine(const PGSTD::string &);
void PQXX_PRIVATE EndCopyWrite();
void PQXX_PRIVATE RawSetVar(const PGSTD::string &, const PGSTD::string &);
void PQXX_PRIVATE AddVariables(const PGSTD::map<PGSTD::string,
PGSTD::string> &);
friend class internal::gate::connection_largeobject;
internal::pq::PGconn *RawConnection() const { return m_Conn; }
friend class internal::gate::connection_notification_receiver;
void add_receiver(notification_receiver *);
void remove_receiver(notification_receiver *) throw ();
friend class internal::gate::connection_pipeline;
void PQXX_PRIVATE start_exec(const PGSTD::string &);
bool PQXX_PRIVATE consume_input() throw ();
bool PQXX_PRIVATE is_busy() const throw ();
int PQXX_PRIVATE encoding_code();
internal::pq::PGresult *get_result();
friend class internal::gate::connection_dbtransaction;
friend class internal::gate::connection_sql_cursor;
void add_reactivation_avoidance_count(int);
friend class internal::gate::connection_reactivation_avoidance_exemption;
friend class internal::gate::connection_parameterized_invocation;
result parameterized_exec(
const PGSTD::string &query,
const char *const params[],
const int paramlengths[],
const int binaries[],
int nparams);
// Not allowed:
connection_base(const connection_base &);
connection_base &operator=(const connection_base &);
};
#ifdef PQXX_HAVE_AUTO_PTR
struct PQXX_LIBEXPORT PQXX_NOVTABLE noticer :
PGSTD::unary_function<const char[], void>
{
virtual ~noticer() throw () {}
virtual void operator()(const char[]) throw () =0;
};
struct PQXX_LIBEXPORT nonnoticer : noticer
{
virtual void operator()(const char[]) throw () {}
};
class PQXX_LIBEXPORT scoped_noticer : errorhandler
{
public:
scoped_noticer(connection_base &c, PGSTD::auto_ptr<noticer> t) throw () :
errorhandler(c), m_noticer(t.release()) {}
protected:
scoped_noticer(connection_base &c, noticer *t) throw () :
errorhandler(c), m_noticer(t) {}
virtual bool operator()(const char msg[]) throw ()
{
(*m_noticer)(msg);
return false;
}
private:
PGSTD::auto_ptr<noticer> m_noticer;
};
class PQXX_LIBEXPORT disable_noticer : scoped_noticer
{
public:
explicit disable_noticer(connection_base &c) :
scoped_noticer(c, new nonnoticer) {}
};
#endif
namespace internal
{
class PQXX_LIBEXPORT reactivation_avoidance_exemption
{
public:
explicit reactivation_avoidance_exemption(connection_base &C);
~reactivation_avoidance_exemption();
void close_connection() throw () { m_open = false; }
private:
connection_base &m_home;
int m_count;
bool m_open;
};
void wait_read(const internal::pq::PGconn *);
void wait_read(const internal::pq::PGconn *, long seconds, long microseconds);
void wait_write(const internal::pq::PGconn *);
} // namespace pqxx::internal
} // namespace pqxx
#include "pqxx/compiler-internal-post.hxx"
#endif
pqxx::result
Result set containing data returned by a query or command.
Definition: result.hxx:81
pqxx::connection_base
connection_base abstract base class; represents a connection to a database.
Definition: connection_base.hxx:151
pqxx::connection_base::supports
bool supports(capability c) const
Does this connection seem to support the given capability?
Definition: connection_base.hxx:396
pqxx::notification_receiver
Definition: notification.hxx:59
pqxx::internal::reactivation_avoidance_counter::clear
void clear()
Definition: connection_base.hxx:65
pqxx::internal::unique
Ensure proper opening/closing of GUEST objects related to a "host" object.
Definition: util.hxx:699
pqxx::connection_base::set_client_encoding
void set_client_encoding(const std::string &Encoding)
Set client-side character encoding.
Definition: connection_base.hxx:436
pqxx::connection_base::cap_nested_transactions
Can transactions be nested in other transactions?
Definition: connection_base.hxx:345
pqxx::connection_base::cap_statement_varargs
Do prepared statements support varargs?
Definition: connection_base.hxx:363
pqxx::encrypt_password
std::string encrypt_password(const std::string &user, const std::string &password)
Encrypt password for given user. Requires libpq 8.2 or better.
pqxx::internal::reactivation_avoidance_exemption::close_connection
void close_connection()
Definition: connection_base.hxx:991
pqxx::prepare::internal::prepared_def
Internal representation of a prepared statement definition.
Definition: prepared_statement.hxx:214
pqxx::binarystring
Definition: binarystring.hxx:59
pqxx::connection_base::cap_create_table_with_oids
Can we specify WITH OIDS with CREATE TABLE?
Definition: connection_base.hxx:342
pqxx::internal::reactivation_avoidance_counter::reactivation_avoidance_counter
reactivation_avoidance_counter()
Definition: connection_base.hxx:62
pqxx::connection_base::cap_cursor_with_hold
Can cursors be declared WITH HOLD?
Definition: connection_base.hxx:350
pqxx::connection_base::cap_read_only_transactions
Can transactions be READ ONLY?
Definition: connection_base.hxx:360
pqxx::connection_base::inhibit_reactivation
void inhibit_reactivation(bool inhibit)
Disallow (or permit) connection recovery.
Definition: connection_base.hxx:243
pqxx::internal::reactivation_avoidance_counter::add
void add(int n)
Definition: connection_base.hxx:64
pqxx::connectionpolicy
Definition: connectionpolicy.hxx:39
pqxx::connection_base::cap_cursor_fetch_0
Can cursors fetch zero elements? (Used to trigger a "fetch all")
Definition: connection_base.hxx:354
pqxx::internal::reactivation_avoidance_counter
Definition: connection_base.hxx:59
pqxx::connection_base::cap_table_column
Can we ask what table column a result column came from?
Definition: connection_base.hxx:357
pqxx::string_traits
Traits class for use in string conversions.
Definition: strconv.hxx:46
pqxx::to_string
std::string to_string(const field &Obj)
Convert a field to a string.
Definition: result.hxx:467
pqxx::internal::sql_cursor
Cursor with SQL positioning semantics.
Definition: cursor.hxx:194
pqxx::connection_base::cap_notify_payload
Can notifications carry payloads?
Definition: connection_base.hxx:372
pqxx::internal::wait_read
void wait_read(const internal::pq::PGconn *)
pqxx::connection_base::perform
void perform(const TRANSACTOR &T)
Perform the transaction defined by a transactor-based object.
Definition: connection_base.hxx:654
pqxx::connection_base::get_verbosity
error_verbosity get_verbosity() const
Retrieve current error verbosity.
Definition: connection_base.hxx:787
pqxx::errorhandler
Base class for error-handler callbacks.
Definition: errorhandler.hxx:57
pqxx::connection_base::capability
capability
Session capabilities.
Definition: connection_base.hxx:336
pqxx::connection_base::quote
std::string quote(const T &t)
Represent object as SQL string, including quoting & escaping.
Definition: connection_base.hxx:755
pqxx::connection_base::cap_cursor_scroll
Can cursors be declared SCROLL?
Definition: connection_base.hxx:348
pqxx::connection_base::cap_prepared_statements
Does the backend support prepared statements? (If not, we emulate them)
Definition: connection_base.hxx:339
pqxx::internal::wait_write
void wait_write(const internal::pq::PGconn *)
pqxx::internal::reactivation_avoidance_exemption
Scoped exemption to reactivation avoidance.
Definition: connection_base.hxx:985
pqxx::connection_base::cap_parameterized_statements
Can this connection execute parameterized statements?
Definition: connection_base.hxx:369
pqxx::connection_base::cap_cursor_update
Can cursors be updateable?
Definition: connection_base.hxx:352
pqxx
The home of all libpqxx classes, functions, templates, etc.
Definition: basic_connection.hxx:35
pqxx::transaction_base
Definition: transaction_base.hxx:133
pqxx::connection_base::error_verbosity
error_verbosity
Error verbosity levels.
Definition: connection_base.hxx:768
pqxx::connection_base::cap_prepare_unnamed_statement
Is the unnamed prepared statement supported?
Definition: connection_base.hxx:366