connection.hxx

/* Definition of the connection class.
 *
 * pqxx::connection encapsulates a connection to a database.
 *
 * DO NOT INCLUDE THIS FILE DIRECTLY; include pqxx/connection instead.
 *
 * Copyright (c) 2000-2020, Jeroen T. Vermeulen.
 *
 * 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
#define PQXX_H_CONNECTION

#include "pqxx/compiler-public.hxx"
#include "pqxx/internal/compiler-internal-pre.hxx"

#include <functional>
#include <list>
#include <map>
#include <memory>
#include <string_view>

#include "pqxx/errorhandler.hxx"
#include "pqxx/except.hxx"
#include "pqxx/prepared_statement.hxx"
#include "pqxx/strconv.hxx"
#include "pqxx/util.hxx"
#include "pqxx/zview.hxx"


namespace pqxx::internal
{
class sql_cursor;
} // namespace pqxx::internal


namespace pqxx::internal::gate
{
class connection_dbtransaction;
class connection_errorhandler;
class connection_largeobject;
class connection_notification_receiver;
class connection_pipeline;
class connection_sql_cursor;
class connection_stream_from;
class connection_stream_to;
class connection_transaction;
class const_connection_largeobject;
} // namespace pqxx::internal::gate


namespace pqxx
{
[[nodiscard]] std::string PQXX_LIBEXPORT
encrypt_password(char const user[], char const password[]);

[[nodiscard]] inline std::string
encrypt_password(std::string const &user, std::string const &password)
{
  return encrypt_password(user.c_str(), password.c_str());
}


enum class error_verbosity : int
{
  // These values must match those in libpq's PGVerbosity enum.
  terse = 0,
  normal = 1,
  verbose = 2
};



class PQXX_LIBEXPORT connection
{
public:
  connection() : connection{""} {}

  explicit connection(std::string const &options) : connection{options.c_str()}
  {}

  explicit connection(char const options[])
  {
    check_version();
    init(options);
  }

  explicit connection(zview options) : connection{options.c_str()} {}


  connection(connection &&rhs);

  ~connection()
  {
    try
    {
      close();
    }
    catch (std::exception const &)
    {}
  }


  connection &operator=(connection &&rhs);

  connection(connection const &) = delete;
  connection &operator=(connection const &) = delete;


  [[nodiscard]] bool PQXX_PURE is_open() const noexcept;

  void process_notice(char const[]) noexcept;
  void process_notice(std::string const &msg) noexcept
  {
    process_notice(zview{msg});
  }

  void process_notice(zview) noexcept;

  void trace(std::FILE *) noexcept;

  [[nodiscard]] char const *dbname() const;

  [[nodiscard]] char const *username() const;

  [[nodiscard]] char const *hostname() const;

  [[nodiscard]] char const *port() const;

  [[nodiscard]] int PQXX_PURE backendpid() const noexcept;


  [[nodiscard]] int PQXX_PURE sock() const noexcept;


  [[nodiscard]] int PQXX_PURE protocol_version() const noexcept;


  [[nodiscard]] int PQXX_PURE server_version() const noexcept;


  [[nodiscard]] std::string get_client_encoding() const;


  void set_client_encoding(std::string const &encoding)
  {
    set_client_encoding(encoding.c_str());
  }


  void set_client_encoding(char const encoding[]);

  [[nodiscard]] int PQXX_PRIVATE encoding_id() const;



  void set_variable(std::string_view var, std::string_view value);


  std::string get_variable(std::string_view);



  int get_notifs();



  int await_notification();

  // TODO: Use time_t instead of long?  See #339.

  int await_notification(long seconds, long microseconds);


  [[nodiscard]] std::string encrypt_password(
    char const user[], char const password[], char const *algorithm = nullptr);
  [[nodiscard]] std::string
  encrypt_password(zview user, zview password, zview algorithm)
  {
    return encrypt_password(user.c_str(), password.c_str(), algorithm.c_str());
  }


  void prepare(char const name[], char const definition[]);

  void prepare(std::string const &name, std::string const &definition)
  {
    prepare(name.c_str(), definition.c_str());
  }

  void prepare(zview name, zview definition)
  {
    prepare(name.c_str(), definition.c_str());
  }


  void prepare(char const definition[]);
  void prepare(zview definition) { return prepare(definition.c_str()); }

  void unprepare(std::string_view name);


  [[nodiscard]] std::string adorn_name(std::string_view);



  [[nodiscard]] std::string esc(char const text[], std::size_t maxlen) const
  {
    return esc(std::string_view(text, maxlen));
  }

  [[nodiscard]] std::string esc(char const text[]) const
  {
    return esc(std::string_view(text));
  }


  [[nodiscard]] std::string esc(std::string_view text) const;

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


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


  [[nodiscard]] std::string unesc_raw(zview text) const
  {
    return unesc_raw(text.c_str());
  }


  [[nodiscard]] std::string unesc_raw(char const text[]) const;

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

  [[nodiscard]] std::string quote_name(std::string_view identifier) const;


  template<typename T>[[nodiscard]] inline std::string quote(T const &t) const;

  [[nodiscard]] std::string quote(binarystring const &) const;


  [[nodiscard]] std::string
  esc_like(std::string_view text, char escape_char = '\\') const;


  void cancel_query();


  void set_verbosity(error_verbosity verbosity) noexcept;


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


  [[nodiscard]] std::string connection_string() const;


  void close();

private:
  void init(char const options[]);

  void wait_read() const;
  // TODO: Use time_t instead of long?  See #339.
  void wait_read(long seconds, long microseconds) const;

  result make_result(
    internal::pq::PGresult *pgr, std::shared_ptr<std::string> const &query);

  void PQXX_PRIVATE set_up_state();

  int PQXX_PRIVATE PQXX_PURE status() const noexcept;


  std::size_t esc_to_buf(std::string_view text, char *buf) const;

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

  void PQXX_PRIVATE process_notice_raw(char const msg[]) noexcept;

  result exec_prepared(std::string_view statement, internal::params const &);

  void check_movable() const;
  void check_overwritable() const;

  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(std::string_view);
  result PQXX_PRIVATE exec(std::shared_ptr<std::string>);
  void PQXX_PRIVATE register_transaction(transaction_base *);
  void PQXX_PRIVATE unregister_transaction(transaction_base *) noexcept;

  friend class internal::gate::connection_stream_from;
  std::pair<std::unique_ptr<char, std::function<void(char *)>>, std::size_t>
    PQXX_PRIVATE read_copy_line();

  friend class internal::gate::connection_stream_to;
  void PQXX_PRIVATE write_copy_line(std::string_view);
  void PQXX_PRIVATE end_copy_write();

  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(char const query[]);
  bool PQXX_PRIVATE consume_input() noexcept;
  bool PQXX_PRIVATE is_busy() const noexcept;
  internal::pq::PGresult *get_result();

  friend class internal::gate::connection_dbtransaction;
  friend class internal::gate::connection_sql_cursor;

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

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

  internal::unique<transaction_base> m_trans;

  std::list<errorhandler *> m_errorhandlers;

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

  int m_unique_id = 0;
};


using connection_base = connection;


template<typename T> inline std::string connection::quote(T const &t) const
{
  if (is_null(t))
    return "NULL";
  auto const text{to_string(t)};

  // Okay, there's an easy way to do this and there's a hard way.  The easy
  // way was "quote, esc(to_string(t)), quote".  I'm going with the hard way
  // because it's going to save some string manipulation that will probably
  // incur some unnecessary memory allocations and deallocations.
  std::string buf{'\''};
  buf.resize(2 + 2 * text.size() + 1);
  auto const content_bytes{esc_to_buf(text, buf.data() + 1)};
  auto const closing_quote{1 + content_bytes};
  buf[closing_quote] = '\'';
  auto const end{closing_quote + 1};
  buf.resize(end);
  return buf;
}
} // namespace pqxx


namespace pqxx::internal
{
PQXX_LIBEXPORT void wait_read(internal::pq::PGconn const *);
PQXX_LIBEXPORT void
wait_read(internal::pq::PGconn const *, long seconds, long microseconds);
PQXX_LIBEXPORT void wait_write(internal::pq::PGconn const *);
} // namespace pqxx::internal

#include "pqxx/internal/compiler-internal-post.hxx"
#endif