connection_base.hxx

#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.hxx"
#include "pqxx/except.hxx"
#include "pqxx/prepared_statement.hxx"
#include "pqxx/strconv.hxx"
#include "pqxx/util.hxx"
#include "pqxx/version.hxx"


/* 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 "//[t01]"
 */

namespace pqxx
{
namespace internal
{
class reactivation_avoidance_exemption;
class sql_cursor;

class reactivation_avoidance_counter
{
public:
  reactivation_avoidance_counter() =default;

  void add(int n) noexcept { m_counter += n; }
  void clear() noexcept { m_counter = 0; }
  int get() const noexcept { return m_counter; }

private:
  int m_counter = 0;
};

}



std::string PQXX_LIBEXPORT encrypt_password(                            //[t00]
        const std::string &user,
        const std::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;
class const_connection_largeobject;
} // namespace pqxx::internal::gate
} // namespace pqxx::internal



class PQXX_LIBEXPORT connection_base
{
public:
  void disconnect() noexcept;                                           //[t02]


  bool PQXX_PURE is_open() const noexcept;                              //[t01]


  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[]) noexcept;                           //[t14]
  void process_notice(const std::string &) noexcept;                    //[t14]

  void trace(std::FILE *) noexcept;                                     //[t03]


  const char *dbname();                                                 //[t01]


  const char *username();                                               //[t01]


  const char *hostname();                                               //[t01]


  const char *port();                                                   //[t01]


  int PQXX_PURE backendpid() const noexcept;                            //[t01]


  int PQXX_PURE sock() const noexcept;                                  //[t87]



  enum capability
  {
    cap_end,
  };



  bool supports(capability c) const noexcept                            //[t88]
        { return m_caps.test(c); }


  int PQXX_PURE protocol_version() const noexcept;                      //[t01]


  int PQXX_PURE server_version() const noexcept;                        //[t01]


  void set_client_encoding(const std::string &Encoding)                 //[t07]
        { set_variable("CLIENT_ENCODING", Encoding); }


  void set_variable(                                                    //[t60]
        const std::string &Var,
        const std::string &Value);


  std::string get_variable(const std::string &);                        //[t60]



  int get_notifs();                                                     //[t04]



  int await_notification();                                             //[t78]


  int await_notification(long seconds, long microseconds);              //[t79]



  void prepare(const std::string &name, const std::string &definition);


  void prepare(const std::string &definition);

  void unprepare(const std::string &name);


  void prepare_now(const std::string &name);


  template<typename TRANSACTOR>
  void perform(const TRANSACTOR &T, int Attempts);                      //[t04]


  template<typename TRANSACTOR>
  void perform(const TRANSACTOR &T) { perform(T, 3); }


  std::string adorn_name(const std::string &);                          //[90]

  std::string esc(const char str[]);

  std::string esc(const char str[], size_t maxlen);

  std::string esc(const std::string &str);

  std::string esc_raw(const unsigned char str[], size_t len);


  std::string unesc_raw(const std::string &text)
                                             { return unesc_raw(text.c_str()); }


  std::string unesc_raw(const char *text);

  std::string quote_raw(const unsigned char str[], size_t len);

  std::string quote_name(const std::string &identifier);


  template<typename T>
  std::string quote(const T &t)
  {
    if (string_traits<T>::is_null(t)) return "NULL";
    return "'" + this->esc(to_string(t)) + "'";
  }

  std::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) noexcept;
  error_verbosity get_verbosity() const noexcept {return m_verbosity;}


  std::vector<errorhandler *> get_errorhandlers() const;

protected:
  explicit connection_base(connectionpolicy &pol) :
        m_policy(pol)
  {
    // Check library version.  The check_library_version template is declared
    // for any library version, but only actually defined for the version of
    // the libpqxx binary against which the code is linked.
    //
    // If the library binary is a different version than the one declared in
    // these headers, then this call will fail to link: there will be no
    // definition for the function with these exact template parameter values.
    // There will be a definition, but the version in the parameter values will
    // be different.
    //
    // There is no particular reason to do this here in this constructor, except
    // to ensure that every meaningful libpqxx client will execute it.  The call
    // must be in the execution path somewhere or the compiler won't try to link
    // it.  We can't use it to initialise a global or class-static variable,
    // because a smart compiler might resolve it at compile time.
    // 
    // On the other hand, we don't want to make a useless function call too
    // often for performance reasons.  A local static variable is initialised
    // only on the definition's first execution.  Compilers will be well
    // optimised for this behaviour, so there's a minimal one-time cost.
    static const auto version_ok =
      internal::check_library_version<PQXX_VERSION_MAJOR, PQXX_VERSION_MINOR>();
    ignore_unused(version_ok);

    clearcaps();
  }
  void init();

  void close() noexcept;
  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 std::string &query);

  void clearcaps() noexcept;
  void PQXX_PRIVATE set_up_state();
  void PQXX_PRIVATE check_result(const result &);

  void PQXX_PRIVATE internal_set_trace() noexcept;
  int PQXX_PRIVATE PQXX_PURE status() const noexcept;

  friend class internal::gate::const_connection_largeobject;
  const char * PQXX_PURE err_msg() const noexcept;

  void PQXX_PRIVATE reset();
  std::string PQXX_PRIVATE raw_get_var(const std::string &);
  void PQXX_PRIVATE process_notice_raw(const char msg[]) noexcept;

  void read_capabilities();

  prepare::internal::prepared_def &find_prepared(const std::string &);

  prepare::internal::prepared_def &register_prepared(const std::string &);

  friend class internal::gate::connection_prepare_invocation;
  result prepared_exec(
        const std::string &,
        const char *const[],
        const int[],
        const int[],
        int);
  result exec_prepared(const std::string &statement, const internal::params &);
  bool prepared_exists(const std::string &) const;

  internal::pq::PGconn *m_conn = nullptr;

  connectionpolicy &m_policy;

  internal::unique<transaction_base> m_trans;

  std::list<errorhandler *> m_errorhandlers;

  std::FILE *m_trace = nullptr;

  using receiver_list =
        std::multimap<std::string, pqxx::notification_receiver *>;
  receiver_list m_receivers;

  std::map<std::string, std::string> m_vars;

  using PSMap = std::map<std::string, prepare::internal::prepared_def>;
  PSMap m_prepared;

  int m_serverversion = 0;

  internal::reactivation_avoidance_counter m_reactivation_avoidance;

  int m_unique_id = 0;

  bool m_completed = false;

  bool m_inhibit_reactivation = false;

  std::bitset<cap_end> m_caps;

  error_verbosity m_verbosity = normal;

  friend class internal::gate::connection_errorhandler;
  void PQXX_PRIVATE register_errorhandler(errorhandler *);
  void PQXX_PRIVATE unregister_errorhandler(errorhandler *) noexcept;

  friend class internal::gate::connection_transaction;
  result PQXX_PRIVATE exec(const char[], int Retries);
  void PQXX_PRIVATE register_transaction(transaction_base *);
  void PQXX_PRIVATE unregister_transaction(transaction_base *) noexcept;
  bool PQXX_PRIVATE read_copy_line(std::string &);
  void PQXX_PRIVATE write_copy_line(const std::string &);
  void PQXX_PRIVATE end_copy_write();
  void PQXX_PRIVATE raw_set_var(const std::string &, const std::string &);
  void PQXX_PRIVATE add_variables(const std::map<std::string, std::string> &);

  friend class internal::gate::connection_largeobject;
  internal::pq::PGconn *raw_connection() const { return m_conn; }

  friend class internal::gate::connection_notification_receiver;
  void add_receiver(notification_receiver *);
  void remove_receiver(notification_receiver *) noexcept;

  friend class internal::gate::connection_pipeline;
  void PQXX_PRIVATE start_exec(const std::string &);
  bool PQXX_PRIVATE consume_input() noexcept;
  bool PQXX_PRIVATE is_busy() const noexcept;
  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 std::string &query,
        const char *const params[],
        const int paramlengths[],
        const int binaries[],
        int nparams);

  result exec_params(
        const std::string &query,
        const internal::params &args);

  connection_base(const connection_base &) =delete;
  connection_base &operator=(const connection_base &) =delete;
};


namespace internal
{

class PQXX_LIBEXPORT reactivation_avoidance_exemption
{
public:
  explicit reactivation_avoidance_exemption(connection_base &C);
  ~reactivation_avoidance_exemption();

  void close_connection() noexcept { 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