connection_base.hxx

Go to the documentation of this file.

/*-------------------------------------------------------------------------
 *
 *   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-2004, 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.
 *
 *-------------------------------------------------------------------------
 */

#include <map>
#include <memory>

#ifdef _WIN32
#include <winsock2.h>   // for fd_set
#endif  // _WIN32

#include "pqxx/except"
#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 result;
class transaction_base;
class trigger;



struct PQXX_LIBEXPORT noticer : PGSTD::unary_function<const char[], void>
{
  virtual ~noticer() throw () {}  
  virtual void operator()(const char Msg[]) throw () =0;
};



class PQXX_LIBEXPORT connection_base
{
public:

  explicit connection_base(const PGSTD::string &ConnInfo);              //[t2]


  explicit connection_base(const char ConnInfo[]);                      //[t2]

  virtual ~connection_base() =0;                                        //[t1]

  void disconnect() throw ();                                           //[t2]


  bool is_open() const throw ();                                        //[t1]


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

#ifdef PQXX_BROKEN_MEMBER_TEMPLATE_DEFAULT_ARG
  template<typename TRANSACTOR> void perform(TRANSACTOR &T, int Attempts);
  template<typename TRANSACTOR>
  void perform(const TRANSACTOR &T) { perform(T, 3); }
#endif

  // TODO: Define a default noticer (mainly to help out Windows users)

  PGSTD::auto_ptr<noticer> set_noticer(PGSTD::auto_ptr<noticer> N) 
    throw ();                                                           //[t14]
  noticer *get_noticer() const throw () { return m_Noticer.get(); }     //[t14]

  void process_notice(const char[]) throw ();                           //[t14]
  void process_notice(const PGSTD::string &) throw ();                  //[t14]

  void trace(FILE *) throw ();                                          //[t3]


  int get_notifs();                                                     //[t4]

  // Miscellaneous query functions (probably not needed very often)
 
  const char *dbname()                                                  //[t1]
        { halfconnect(); return PQdb(m_Conn); }

  const char *username()                                                //[t1]
        { halfconnect(); return  PQuser(m_Conn); }

  const char *hostname()                                                //[t1]
        { halfconnect(); return PQhost(m_Conn); }

  const char *port()                                                    //[t1]
        { halfconnect(); return PQport(m_Conn); }

  const char *options() const throw ()                                  //[t1]
        { return m_ConnInfo.c_str(); }



  int backendpid() const throw ()                                       //[t1]
        { return m_Conn ? PQbackendPID(m_Conn) : 0; }


  void activate() { Connect(); }                                        //[t12]


  void deactivate();                                                    //[t12]


  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 await_notification();                                             //[t78]


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

#ifdef PQXX_DEPRECATED_HEADERS

  void Disconnect() throw () { disconnect(); }
  template<typename TRANSACTOR> void Perform(const TRANSACTOR &T, int A=3)
        { return perform(T,A); }
  PGSTD::auto_ptr<noticer> SetNoticer(PGSTD::auto_ptr<noticer> N)
        { return set_noticer(N); }
  noticer *GetNoticer() const throw () 
        { return get_noticer(); }
  void ProcessNotice(const char msg[]) throw () { return process_notice(msg); }
  void ProcessNotice(const PGSTD::string &msg) throw () 
        { return process_notice(msg); }
  void Trace(FILE *F) { trace(F); }
  void GetNotifs() { get_notifs(); }
  const char *DbName() { return dbname(); }
  const char *UserName() { return username(); }
  const char *HostName() { return hostname(); }
  const char *Port() { return port(); }
  const char *Options() const throw () { return options(); }
  int BackendPID() const { return backendpid(); }
  void Activate() { activate(); }
  void Deactivate() { deactivate(); }
  void SetClientEncoding(const PGSTD::string &E) { set_client_encoding(E); }
  void SetVariable(const PGSTD::string &Var, const PGSTD::string &Val)
        { set_variable(Var, Val); }
#endif


protected:

  virtual void startconnect() =0;


  virtual void completeconnect() =0;


  virtual void dropconnect() throw () {}

  internal::pq::PGconn *get_conn() const throw () { return m_Conn; }

  void set_conn(internal::pq::PGconn *C) throw () { m_Conn = C; }

  void close() throw ();
  void wait_read() const;
  void wait_read(long seconds, long microseconds) const;
  void wait_write() const;

private:
  void Connect();
  void SetupState();

  void InternalSetTrace() throw ();
  int Status() const throw () { return PQXXPQ::PQstatus(m_Conn); }
  const char *ErrMsg() const throw ();
  void Reset();
  void RestoreVars();
  void halfconnect();
  int set_fdmask() const;
  void clear_fdmask() throw ();
  PGSTD::string RawGetVar(const PGSTD::string &);
  void process_notice_raw(const char msg[]) throw ();


  PGSTD::string m_ConnInfo;

  internal::pq::PGconn *m_Conn;
  internal::unique<transaction_base> m_Trans;

  PGSTD::auto_ptr<noticer> m_Noticer;
  FILE *m_Trace;

  typedef PGSTD::multimap<PGSTD::string, pqxx::trigger *> TriggerList;
  TriggerList m_Triggers;

  PGSTD::map<PGSTD::string, PGSTD::string> m_Vars;

  mutable fd_set m_fdmask;

  friend class transaction_base;
  result Exec(const char[], int Retries);
  result exec_prepared(const char[], 
      int NumParams,
      const char *const *Params,
      int Retries);
  void RegisterTransaction(transaction_base *);
  void UnregisterTransaction(transaction_base *) throw ();
  void MakeEmpty(result &);
  bool ReadCopyLine(PGSTD::string &);
  void WriteCopyLine(const PGSTD::string &);
  void EndCopyWrite();
  void start_exec(const PGSTD::string &);
  internal::pq::PGresult *get_result();

  void RawSetVar(const PGSTD::string &Var, const PGSTD::string &Value);
  void AddVariables(const PGSTD::map<PGSTD::string, PGSTD::string> &);

  friend class largeobject;
  internal::pq::PGconn *RawConnection() const { return m_Conn; }

  friend class trigger;
  void AddTrigger(trigger *);
  void RemoveTrigger(trigger *) throw ();

  friend class pipeline;
  void consume_input() throw () { PQconsumeInput(m_Conn); }
  bool is_busy() const throw () { return PQisBusy(m_Conn); }

  // Not allowed:
  connection_base(const connection_base &);
  connection_base &operator=(const connection_base &);
};


}


// Put this here so on Windows, any noticer will be deleted in caller's context
inline pqxx::connection_base::~connection_base()
{
}

---