Main Page   Namespace List   Class Hierarchy   Alphabetical List   Compound List   File List   Namespace Members   Compound Members   File Members  

pqxx::ConnectionItf Class Reference

ConnectionItf abstract base class; represents a connection to a database. More...

#include <connectionitf.h>

Inheritance diagram for pqxx::ConnectionItf:

pqxx::Connection pqxx::LazyConnection List of all members.

Public Member Functions

 ConnectionItf (const PGSTD::string &ConnInfo)
 Constructor. Sets up connection PostgreSQL connection string.

 ConnectionItf (const char ConnInfo[])
 Constructor. Sets up connection based on PostgreSQL connection string.

virtual ~ConnectionItf ()=0
 Destructor. Implicitly closes the connection.

void Disconnect () const throw ()
 Explicitly close connection.

bool is_open () const
 Is this connection open?

template<typename TRANSACTOR> void Perform (const TRANSACTOR &T, int Attempts=3)
 Perform the transaction defined by a Transactor-based object.

PGSTD::auto_ptr< NoticerSetNoticer (PGSTD::auto_ptr< Noticer > N)
 Set handler for postgresql errors or warning messages.

NoticerGetNoticer () const throw ()
void ProcessNotice (const char[]) throw ()
 Invoke notice processor function. The message should end in newline.

void ProcessNotice (const PGSTD::string &msg) throw ()
 Invoke notice processor function. The message should end in newline.

void Trace (FILE *)
 Enable tracing to a given output stream, or NULL to disable.

void GetNotifs ()
 Check for pending trigger notifications and take appropriate action.

const char * DbName () const throw ()
 Name of database we're connected to, if any.

const char * UserName () const throw ()
 Database user ID we're connected under, if any.

const char * HostName () const throw ()
 Address of server (NULL for local connections).

const char * Port () const throw ()
 Server port number we're connected to.

const char * Options () const throw ()
 Full connection string as used to set up this connection.

int BackendPID () const
 Process ID for backend process.

void Activate () const
 Explicitly activate deferred or deactivated connection.

void Deactivate () const
 Explicitly deactivate connection.

void SetClientEncoding (const char Encoding[])
 Set client-side character encoding.


Protected Member Functions

void Connect () const
 To be used by implementation classes: reall connecto to database.


Friends

class TransactionItf
 Triggers client is listening on.

class LargeObject
class Trigger

Detailed Description

ConnectionItf abstract base class; represents a connection to a database.

This is the first class to look at when you wish to work with a database through libpqxx. Depending on the implementing concrete child class, a connection can be automatically opened when it is constructed, or when it is first used. The connection is automatically closed upon destruction, if it hasn't already been closed manually. To query or manipulate the database once connected, use one of the Transaction classes (see pqxx/transactionitf.h) or preferably the Transactor framework (see pqxx/transactor.h).


Constructor & Destructor Documentation

pqxx::ConnectionItf::ConnectionItf const PGSTD::string &    ConnInfo [explicit]
 

Constructor. Sets up connection PostgreSQL connection string.

Parameters:
ConnInfo a PostgreSQL connection string specifying any required parameters, such as server, port, database, and password.

pqxx::ConnectionItf::ConnectionItf const char    ConnInfo[] [explicit]
 

Constructor. Sets up connection based on PostgreSQL connection string.

Parameters:
ConnInfo a PostgreSQL connection string specifying any required parameters, such as server, port, database, and password. As a special case, a null pointer is taken as the empty string.

pqxx::ConnectionItf::~ConnectionItf   [pure virtual]
 

Destructor. Implicitly closes the connection.


Member Function Documentation

void pqxx::ConnectionItf::Activate   const
 

Explicitly activate deferred or deactivated connection.

Use of this method is entirely optional. Whenever a connection is used while in a deferred or deactivated state, it will transparently try to bring itself into an actiaveted state. This function is best viewed as an explicit hint to the connection that "if you're not in an active state, now would be a good time to get into one." Whether a connection is currently in an active state or not makes no real difference to its functionality. There is also no particular need to match calls to Activate() with calls to Deactivate(). A good time to call Activate() might be just before you first open a transaction on a lazy connection.

int pqxx::ConnectionItf::BackendPID   const
 

Process ID for backend process.

Use with care: connections may be lost and automatically re-established without your knowledge, in which case this process ID may no longer be correct. You may, however, assume that this number remains constant and reliable within the span of a successful backend transaction. If the transaction fails, which may be due to a lost connection, then this number will have become invalid at some point within the transaction.

void pqxx::ConnectionItf::Connect   const [protected]
 

To be used by implementation classes: reall connecto to database.

const char* pqxx::ConnectionItf::DbName   const throw ()
 

Name of database we're connected to, if any.

void pqxx::ConnectionItf::Deactivate   const
 

Explicitly deactivate connection.

Like its counterpart Activate(), this method is entirely optional. Calling this function really only makes sense if you won't be using this connection for a while and want to reduce the number of open connections on the database server. There is no particular need to match or pair calls to Deactivate() with calls to Activate(), but calling Deactivate() during a transaction is an error.

void pqxx::ConnectionItf::Disconnect   const throw ()
 

Explicitly close connection.

Noticer* pqxx::ConnectionItf::GetNoticer   const throw ()
 

void pqxx::ConnectionItf::GetNotifs  
 

Check for pending trigger notifications and take appropriate action.

const char* pqxx::ConnectionItf::HostName   const throw ()
 

Address of server (NULL for local connections).

bool pqxx::ConnectionItf::is_open   const
 

Is this connection open?

const char* pqxx::ConnectionItf::Options   const throw ()
 

Full connection string as used to set up this connection.

template<typename TRANSACTOR>
void pqxx::ConnectionItf::Perform const TRANSACTOR &    T,
int    Attempts = 3
 

Perform the transaction defined by a Transactor-based object.

The function may create and execute several copies of the Transactor before it succeeds. If there is any doubt over whether it succeeded (this can happen if the connection is lost just before the backend can confirm success), it is no longer retried and an error message is generated.

Parameters:
T the Transactor to be executed.
Attempts the maximum number of attempts to be made to execute T.

const char* pqxx::ConnectionItf::Port   const throw ()
 

Server port number we're connected to.

void pqxx::ConnectionItf::ProcessNotice const PGSTD::string &    msg throw ()
 

Invoke notice processor function. The message should end in newline.

void pqxx::ConnectionItf::ProcessNotice const    char[] throw ()
 

Invoke notice processor function. The message should end in newline.

void pqxx::ConnectionItf::SetClientEncoding const char    Encoding[]
 

Set client-side character encoding.

Search the PostgreSQL documentation for "multibyte" or "character set encodings" to find out more about the available encodings, how to extend them, and how to use them. Not all server-side encodings are compatible with all client-side encodings or vice versa.

Parameters:
Encoding name of the character set encoding to use

PGSTD::auto_ptr< pqxx::Noticer > pqxx::ConnectionItf::SetNoticer PGSTD::auto_ptr< Noticer   N
 

Set handler for postgresql errors or warning messages.

Return value is the previous handler. Ownership of any previously set Noticer is also passed to the caller, so unless it is stored in another auto_ptr, it will be deleted from the caller's context. This may be important when running under Windows, where a DLL cannot free memory allocated by the main program. If a Noticer is set when the ConnectionItf is destructed, it will also be deleted.

Parameters:
N the new message handler; must not be null or equal to the old one

void pqxx::ConnectionItf::Trace FILE *   
 

Enable tracing to a given output stream, or NULL to disable.

const char* pqxx::ConnectionItf::UserName   const throw ()
 

Database user ID we're connected under, if any.


Friends And Related Function Documentation

friend class LargeObject [friend]
 

friend class TransactionItf [friend]
 

Triggers client is listening on.

friend class Trigger [friend]
 


The documentation for this class was generated from the following files:
Generated on Mon Mar 31 17:57:33 2003 for libpqxx by doxygen1.3-rc3