libpqxx  5.0
connection_base.hxx
1 /*-------------------------------------------------------------------------
2  *
3  * FILE
4  * pqxx/connection_base.hxx
5  *
6  * DESCRIPTION
7  * definition of the pqxx::connection_base abstract base class.
8  * pqxx::connection_base encapsulates a frontend to backend connection
9  * DO NOT INCLUDE THIS FILE DIRECTLY; include pqxx/connection_base instead.
10  *
11  * Copyright (c) 2001-2015, Jeroen T. Vermeulen <jtv@xs4all.nl>
12  *
13  * See COPYING for copyright license. If you did not receive a file called
14  * COPYING with this source code, please notify the distributor of this mistake,
15  * or contact the author.
16  *
17  *-------------------------------------------------------------------------
18  */
19 #ifndef PQXX_H_CONNECTION_BASE
20 #define PQXX_H_CONNECTION_BASE
21 
22 #include "pqxx/compiler-public.hxx"
23 #include "pqxx/compiler-internal-pre.hxx"
24 
25 #include <bitset>
26 #include <list>
27 #include <map>
28 #include <memory>
29 
30 #include "pqxx/errorhandler"
31 #include "pqxx/except"
32 #include "pqxx/prepared_statement"
33 #include "pqxx/strconv"
34 #include "pqxx/util"
35 
36 
37 /* Use of the libpqxx library starts here.
38  *
39  * Everything that can be done with a database through libpqxx must go through
40  * a connection object derived from connection_base.
41  */
42 
43 /* Methods tested in eg. self-test program test1 are marked with "//[t1]"
44  */
45 
46 namespace pqxx
47 {
48 class binarystring;
49 class connectionpolicy;
50 class notification_receiver;
51 class result;
52 class transaction_base;
53 
54 namespace internal
55 {
57 class sql_cursor;
58 
60 {
61 public:
62  reactivation_avoidance_counter() : m_counter(0) {}
63 
64  void add(int n) PQXX_NOEXCEPT { m_counter += n; }
65  void clear() PQXX_NOEXCEPT { m_counter = 0; }
66  int get() const PQXX_NOEXCEPT { return m_counter; }
67 
68 private:
69  int m_counter;
70 };
71 
72 }
73 
74 
76 
92 std::string PQXX_LIBEXPORT encrypt_password( //[t0]
93  const std::string &user,
94  const std::string &password);
95 
96 
97 namespace internal
98 {
99 namespace gate
100 {
101 class connection_dbtransaction;
102 class connection_errorhandler;
103 class connection_largeobject;
104 class connection_notification_receiver;
105 class connection_parameterized_invocation;
106 class connection_pipeline;
107 class connection_prepare_invocation;
108 class connection_reactivation_avoidance_exemption;
109 class connection_sql_cursor;
110 class connection_transaction;
111 } // namespace pqxx::internal::gate
112 } // namespace pqxx::internal
113 
114 
116 
149 class PQXX_LIBEXPORT connection_base
150 {
151 public:
153  void disconnect() PQXX_NOEXCEPT; //[t2]
154 
156 
160  bool PQXX_PURE is_open() const PQXX_NOEXCEPT; //[t1]
161 
172 
183  void activate(); //[t12]
184 
186 
194  void deactivate(); //[t12]
195 
197 
241  void inhibit_reactivation(bool inhibit) //[t86]
242  { m_inhibit_reactivation=inhibit; }
243 
245 
250  void simulate_failure(); //[t94]
252 
254  void process_notice(const char[]) PQXX_NOEXCEPT; //[t14]
256  void process_notice(const std::string &) PQXX_NOEXCEPT; //[t14]
257 
259  void trace(std::FILE *) PQXX_NOEXCEPT; //[t3]
260 
269 
273  const char *dbname(); //[t1]
274 
276 
279  const char *username(); //[t1]
280 
282 
285  const char *hostname(); //[t1]
286 
288 
291  const char *port(); //[t1]
292 
294 
303  int PQXX_PURE backendpid() const PQXX_NOEXCEPT; //[t1]
304 
306 
320  int PQXX_PURE sock() const PQXX_NOEXCEPT; //[t87]
321 
330 
333  {
386 
388  cap_end
389  };
390 
391 
393 
409  bool supports(capability c) const PQXX_NOEXCEPT //[t88]
410  { return m_caps.test(c); }
411 
413 
421  int PQXX_PURE protocol_version() const PQXX_NOEXCEPT; //[t1]
422 
424 
436  int PQXX_PURE server_version() const PQXX_NOEXCEPT; //[t1]
438 
440 
446  void set_client_encoding(const std::string &Encoding) //[t7]
447  { set_variable("CLIENT_ENCODING", Encoding); }
448 
450 
466  void set_variable(const std::string &Var,
467  const std::string &Value); //[t60]
468 
470 
477  std::string get_variable(const std::string &); //[t60]
479 
480 
485 
498  int get_notifs(); //[t4]
499 
500 
502 
508  int await_notification(); //[t78]
509 
511 
517  int await_notification(long seconds, long microseconds); //[t79]
519 
520 
557 
591  void prepare(const std::string &name, const std::string &definition);
592 
594 
600  void prepare(const std::string &definition);
601 
603  void unprepare(const std::string &name);
604 
606 
616  void prepare_now(const std::string &name);
617 
647 
656  template<typename TRANSACTOR>
657  void perform(const TRANSACTOR &T, int Attempts); //[t4]
658 
660 
663  template<typename TRANSACTOR>
664  void perform(const TRANSACTOR &T) { perform(T, 3); }
665 
670 
674  std::string adorn_name(const std::string &); //[90]
675 
744  std::string esc(const char str[]);
746 
748  std::string esc(const char str[], size_t maxlen);
749 
751  std::string esc(const std::string &str);
752 
754  std::string esc_raw(const unsigned char str[], size_t len);
755 
757 
760  std::string unesc_raw(const std::string &text)
761  { return unesc_raw(text.c_str()); }
762 
764 
767  std::string unesc_raw(const char *text);
768 
770  std::string quote_raw(const unsigned char str[], size_t len);
771 
773  std::string quote_name(const std::string &identifier);
774 
776 
777  template<typename T>
778  std::string quote(const T &t)
779  {
780  if (string_traits<T>::is_null(t)) return "NULL";
781  return "'" + this->esc(to_string(t)) + "'";
782  }
783 
784  std::string quote(const binarystring &);
786 
788  void cancel_query();
789 
792  {
793  // These values must match those in libpq's PGVerbosity enum.
794  terse=0,
795  normal=1,
796  verbose=2
797  };
798 
800 
808  void set_verbosity(error_verbosity verbosity) PQXX_NOEXCEPT;
810  error_verbosity get_verbosity() const PQXX_NOEXCEPT {return m_verbosity;}
811 
813 
825  std::vector<errorhandler *> get_errorhandlers() const;
826 
827 protected:
828  explicit connection_base(connectionpolicy &);
829  void init();
830 
831  void close() PQXX_NOEXCEPT;
832  void wait_read() const;
833  void wait_read(long seconds, long microseconds) const;
834  void wait_write() const;
835 
836 private:
837 
838  result make_result(internal::pq::PGresult *rhs, const std::string &query);
839 
840  void PQXX_PRIVATE clearcaps() PQXX_NOEXCEPT;
841  void PQXX_PRIVATE SetupState();
842  void PQXX_PRIVATE check_result(const result &);
843 
844  void PQXX_PRIVATE InternalSetTrace() PQXX_NOEXCEPT;
845  int PQXX_PRIVATE PQXX_PURE Status() const PQXX_NOEXCEPT;
846  const char * PQXX_PURE ErrMsg() const PQXX_NOEXCEPT;
847  void PQXX_PRIVATE Reset();
848  void PQXX_PRIVATE RestoreVars();
849  std::string PQXX_PRIVATE RawGetVar(const std::string &);
850  void PQXX_PRIVATE process_notice_raw(const char msg[]) PQXX_NOEXCEPT;
851 
852  void read_capabilities();
853 
854  prepare::internal::prepared_def &find_prepared(const std::string &);
855 
856  prepare::internal::prepared_def &register_prepared(const std::string &);
857 
858  friend class internal::gate::connection_prepare_invocation;
859  result prepared_exec(const std::string &,
860  const char *const[],
861  const int[],
862  const int[],
863  int);
864  bool prepared_exists(const std::string &) const;
865 
867  internal::pq::PGconn *m_Conn;
868 
869  connectionpolicy &m_policy;
870 
872  internal::unique<transaction_base> m_Trans;
873 
874  std::list<errorhandler *> m_errorhandlers;
875 
877  std::FILE *m_Trace;
878 
879  typedef std::multimap<std::string, pqxx::notification_receiver *>
880  receiver_list;
882  receiver_list m_receivers;
883 
885  std::map<std::string, std::string> m_Vars;
886 
887  typedef std::map<std::string, prepare::internal::prepared_def> PSMap;
888 
890  PSMap m_prepared;
891 
893  int m_serverversion;
894 
896  internal::reactivation_avoidance_counter m_reactivation_avoidance;
897 
899  int m_unique_id;
900 
902  bool m_Completed;
903 
905  bool m_inhibit_reactivation;
906 
908  std::bitset<cap_end> m_caps;
909 
911  error_verbosity m_verbosity;
912 
913  friend class internal::gate::connection_errorhandler;
914  void PQXX_PRIVATE register_errorhandler(errorhandler *);
915  void PQXX_PRIVATE unregister_errorhandler(errorhandler *) PQXX_NOEXCEPT;
916 
917  friend class internal::gate::connection_transaction;
918  result PQXX_PRIVATE Exec(const char[], int Retries);
919  void PQXX_PRIVATE RegisterTransaction(transaction_base *);
920  void PQXX_PRIVATE UnregisterTransaction(transaction_base *) PQXX_NOEXCEPT;
921  bool PQXX_PRIVATE ReadCopyLine(std::string &);
922  void PQXX_PRIVATE WriteCopyLine(const std::string &);
923  void PQXX_PRIVATE EndCopyWrite();
924  void PQXX_PRIVATE RawSetVar(const std::string &, const std::string &);
925  void PQXX_PRIVATE AddVariables(const std::map<std::string, std::string> &);
926 
927  friend class internal::gate::connection_largeobject;
928  internal::pq::PGconn *RawConnection() const { return m_Conn; }
929 
930  friend class internal::gate::connection_notification_receiver;
931  void add_receiver(notification_receiver *);
932  void remove_receiver(notification_receiver *) PQXX_NOEXCEPT;
933 
934  friend class internal::gate::connection_pipeline;
935  void PQXX_PRIVATE start_exec(const std::string &);
936  bool PQXX_PRIVATE consume_input() PQXX_NOEXCEPT;
937  bool PQXX_PRIVATE is_busy() const PQXX_NOEXCEPT;
938  int PQXX_PRIVATE encoding_code();
939  internal::pq::PGresult *get_result();
940 
941  friend class internal::gate::connection_dbtransaction;
942 
943  friend class internal::gate::connection_sql_cursor;
944  void add_reactivation_avoidance_count(int);
945 
946  friend class internal::gate::connection_reactivation_avoidance_exemption;
947 
948  friend class internal::gate::connection_parameterized_invocation;
949  result parameterized_exec(
950  const std::string &query,
951  const char *const params[],
952  const int paramlengths[],
953  const int binaries[],
954  int nparams);
955 
956  // Not allowed:
957  connection_base(const connection_base &) PQXX_DELETED_OP;
958  connection_base &operator=(const connection_base &) PQXX_DELETED_OP;
959 };
960 
961 
962 namespace internal
963 {
964 
967 {
968 public:
971 
972  void close_connection() PQXX_NOEXCEPT { m_open = false; }
973 
974 private:
975  connection_base &m_home;
976  int m_count;
977  bool m_open;
978 };
979 
980 
981 void wait_read(const internal::pq::PGconn *);
982 void wait_read(const internal::pq::PGconn *, long seconds, long microseconds);
983 void wait_write(const internal::pq::PGconn *);
984 } // namespace pqxx::internal
985 
986 
987 } // namespace pqxx
988 
989 #include "pqxx/compiler-internal-post.hxx"
990 
991 #endif
connection_base abstract base class; represents a connection to a database.
Definition: connection_base.hxx:149
std::string encrypt_password(const std::string &user, const std::string &password)
Encrypt password for given user.
Definition: connection_base.cxx:116
void perform(const TRANSACTOR &T)
Perform the transaction defined by a transactor-based object.
Definition: connection_base.hxx:664
Definition: connection_base.hxx:345
std::string unesc_raw(const std::string &text)
Unescape binary data, e.g. from a table field or notification payload.
Definition: connection_base.hxx:760
Definition: connection_base.hxx:349
capability
Session capabilities.
Definition: connection_base.hxx:332
Definition: connection_base.hxx:341
Definition: connection_base.hxx:377
Definition: connection_base.hxx:353
Definition: connection_base.hxx:59
error_verbosity
Error verbosity levels.
Definition: connection_base.hxx:791
void inhibit_reactivation(bool inhibit)
Disallow (or permit) connection recovery.
Definition: connection_base.hxx:241
Definition: connection_base.hxx:369
error_verbosity get_verbosity() const PQXX_NOEXCEPT
Retrieve current error verbosity.
Definition: connection_base.hxx:810
void add(int n) PQXX_NOEXCEPT
Definition: connection_base.hxx:64
Definition: notification.hxx:59
Definition: connection_base.hxx:365
Definition: connection_base.hxx:373
Cursor with SQL positioning semantics.
Definition: cursor.hxx:183
Definition: binarystring.hxx:59
Base class for error-handler callbacks.
Definition: errorhandler.hxx:57
Definition: connectionpolicy.hxx:39
Definition: connection_base.hxx:337
Definition: connection_base.hxx:381
Definition: connection_base.hxx:357
reactivation_avoidance_counter()
Definition: connection_base.hxx:62
Traits class for use in string conversions.
Definition: strconv.hxx:46
bool supports(capability c) const PQXX_NOEXCEPT
Does this connection seem to support the given capability?
Definition: connection_base.hxx:409
Definition: connection_base.hxx:361
void close_connection() PQXX_NOEXCEPT
Definition: connection_base.hxx:972
Scoped exemption to reactivation avoidance.
Definition: connection_base.hxx:966
std::string quote(const T &t)
Represent object as SQL string, including quoting &amp; escaping.
Definition: connection_base.hxx:778
Result set containing data returned by a query or command.
Definition: result.hxx:78
Definition: transaction_base.hxx:133
Definition: connection_base.hxx:385
void clear() PQXX_NOEXCEPT
Definition: connection_base.hxx:65
std::string to_string(const field &Obj)
Convert a field to a string.
Definition: result.hxx:464