libgdamm Reference Documentation
Main Page   Namespaces   Book  

Gnome::Gda::Connection Class Reference
[Connections and Commands]

Manages a connection to a data source. More...

Inheritance diagram for Gnome::Gda::Connection:

Inheritance graph
[legend]
List of all members.

Public Member Functions

void add_event (const Glib::RefPtr<ConnectionEvent>& event)
 Adds an event to the given connection.
Glib::RefPtr<ConnectionEventadd_event_string (const Glib::ustring& str)
 Adds a new error to the given connection object.
bool add_savepoint (const Glib::ustring& name)
 Adds a SAVEPOINT named name .
bool begin_transaction (const Glib::ustring& name, TransactionIsolation level)
 Starts a transaction on the data source, identified by the xaction parameter.
bool change_database (const Glib::ustring& name)
 Changes the current database for the given connection.
void clear_events_list ()
 This function lets you clear the list of Gda::ConnectionEvent's of the given connection.
void close ()
 Closes the connection to the underlying data source, but first emits the "conn_to_close" signal.
bool commit_transaction (const Glib::ustring& name)
 Commits the given transaction to the backend database.
bool delete_savepoint (const Glib::ustring& name)
 Delete the SAVEPOINT named name when not used anymore.
int execute_non_select_command (const Glib::ustring& cmd)
 Executes a non-selection command on the given connection.
int execute_non_select_command (const Command& cmd)
 Executes a non-selection command on the given connection.
int execute_non_select_command (const Command& cmd, const Glib::RefPtr<ParameterList>& params)
 Executes a selection command on the given connection.
Glib::RefPtr<DataModelexecute_select_command (const Glib::ustring& cmd)
 Executes a selection command on the given connection.
Glib::RefPtr<DataModelexecute_select_command (const Command& cmd)
 Executes a selection command on the given connection.
Glib::RefPtr<DataModelexecute_select_command (const Command& cmd, const Glib::RefPtr<ParameterList>& params)
 Executes a selection command on the given connection.
Glib::RefPtr<const Clientget_client () const
 Gets the Gda::Client object associated with a connection.
Glib::RefPtr<Clientget_client ()
 Gets the Gda::Client object associated with a connection.
Glib::ustring get_cnc_string () const
 Gets the connection string used to open this connection.
Glib::ustring get_database () const
 Gets the name of the currently active database in the given GdaConnection .
Glib::ustring get_dsn () const
 
Returns:
The data source name the connection object is connected to.

Glib::ListHandle< Glib::RefPtr<
const ConnectionEvent > > 
get_events () const
 Retrieves a list of the last errors occurred during the connection.
Glib::ListHandle< Glib::RefPtr<
ConnectionEvent > > 
get_events ()
 Retrieves a list of the last errors occurred during the connection.
const ServerProviderInfoget_infos () const
 Get a pointer to a Gda::ServerProviderInfo structure (which must not be modified) to retreive specific information about the provider used by cnc .
Glib::ustring get_last_insert_id (const Glib::RefPtr<DataModel>& recset) const
 Retrieve from the given Gda::Connection the ID of the last inserted row.
ConnectionOptions get_options () const
 Gets the Gda::ConnectionOptions used to open this connection.
Glib::ustring get_password () const
 Gets the password used to open this connection.
Glib::ustring get_provider () const
 Gets the provider id that this connection is connected to.
Glib::RefPtr<const ServerProviderget_provider_obj () const
 Get a pointer to the Gda::ServerProvider object used to access the database.
Glib::RefPtr<ServerProviderget_provider_obj ()
 Get a pointer to the Gda::ServerProvider object used to access the database.
Glib::RefPtr<const DataModelget_schema (ConnectionSchema schema) const
 Asks the underlying data source for a list of database objects.
Glib::RefPtr<DataModelget_schema (ConnectionSchema schema)
 Asks the underlying data source for a list of database objects.
Glib::RefPtr<const DataModelget_schema (ConnectionSchema schema, const Glib::RefPtr<ParameterList>& params) const
 Asks the underlying data source for a list of database objects.
Glib::RefPtr<DataModelget_schema (ConnectionSchema schema, const Glib::RefPtr<ParameterList>& params)
 Asks the underlying data source for a list of database objects.
Glib::ustring get_server_version () const
 Gets the version string of the underlying database server.
Glib::RefPtr<const TransactionStatusget_transaction_status () const
 Get the status of cnc regarding transactions.
Glib::ustring get_username () const
 Gets the user name used to open this connection.
const GdaConnection* gobj () const
 Provides access to the underlying C GObject.
GdaConnection* gobj ()
 Provides access to the underlying C GObject.
GdaConnection* gobj_copy ()
 Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.
bool is_opened () const
 Checks whether a connection is open or not.
bool open ()
 Tries to open the connection.
bool rollback_savepoint (const Glib::ustring& name)
 Rollback all the modifications made after the SAVEPOINT named name .
bool rollback_transaction (const Glib::ustring& name)
 Rollbacks the given transaction.
bool set_dsn (const Glib::ustring& datasource)
 Sets the data source of the connection.
bool set_password (const Glib::ustring& password)
 Sets the user password for the connection to the server.
bool set_username (const Glib::ustring& username)
 Sets the user name for the connection.
Glib::SignalProxy0<void> signal_conn_closed ()
 
Prototype:
void conn_closed()

Glib::SignalProxy0<void> signal_conn_opened ()
 
Prototype:
void conn_opened()

Glib::SignalProxy0<void> signal_conn_to_close ()
 
Prototype:
void conn_to_close()

Glib::SignalProxy0<void> signal_dsn_changed ()
 
Prototype:
void dsn_changed()

Glib::SignalProxy1< void,
const Glib::RefPtr<ConnectionEvent >&> 
signal_error ()
 
Prototype:
void error(const Glib::RefPtr<ConnectionEvent>& error)

Glib::SignalProxy0<void> signal_transaction_status_changed ()
 
Prototype:
void transaction_status_changed()

bool supports_feature (ConnectionFeature feature) const
 Asks the underlying provider for if a specific feature is supported.
Glib::ustring value_to_sql_string (const Value& from) const
 Produces a fully quoted and escaped string from a GValue.
virtual ~Connection ()

Static Public Member Functions

static Glib::RefPtr<Connectioncreate ()

Protected Member Functions

 Connection ()
virtual void on_conn_closed ()
virtual void on_conn_opened ()
virtual void on_conn_to_close ()
virtual void on_dsn_changed ()
virtual void on_error (const Glib::RefPtr<ConnectionEvent>& error)
virtual void on_transaction_status_changed ()

Related Functions

(Note that these are not member functions.)

Glib::RefPtr<Gnome::Gda::Connectionwrap (GdaConnection* object, bool take_copy=false)
 
Parameters:
object The C instance


Detailed Description

Manages a connection to a data source.

This class offers access to all operations involving an opened connection to a database. Connection objects are obtained via the Client class.

Once obtained, applications can use a Connection to execute commands, run transactions, and get information about all objects stored in the underlying database.


Constructor & Destructor Documentation

virtual Gnome::Gda::Connection::~Connection (  )  [virtual]

Gnome::Gda::Connection::Connection (  )  [protected]


Member Function Documentation

void Gnome::Gda::Connection::add_event ( const Glib::RefPtr<ConnectionEvent>&  event  ) 

Adds an event to the given connection.

This function is usually called by providers, to inform clients of events that happened during some operation.

As soon as a provider (or a client, it does not matter) calls this function with an event object which is an error, the connection object (and the associated Gda::Client object) emits the "error" signal, to which clients can connect to be informed of events.

WARNING: the reference to the event object is stolen by this function!

Parameters:
event Is stored internally, so you don't need to unref it.

Glib::RefPtr<ConnectionEvent> Gnome::Gda::Connection::add_event_string ( const Glib::ustring str  ) 

Adds a new error to the given connection object.

This is just a convenience function that simply creates a Gda::ConnectionEvent and then calls gda_server_connection_add_error.

Parameters:
str A format string (see the printf(3) documentation).
Varargs The arguments to insert in the error message.
Returns:
A new Gda::ConnectionEvent object, however the caller does not hold a reference to the returned object, and if need be the caller must call Glib::object_ref() on it.

bool Gnome::Gda::Connection::add_savepoint ( const Glib::ustring name  ) 

Adds a SAVEPOINT named name .

Parameters:
name Name of the savepoint to add.
error A place to store errors or 0.
Returns:
true if no error occurred.

bool Gnome::Gda::Connection::begin_transaction ( const Glib::ustring name,
TransactionIsolation  level 
)

Starts a transaction on the data source, identified by the xaction parameter.

Before starting a transaction, you can check whether the underlying provider does support transactions or not by using the supports_feature() function.

Parameters:
name The name of the transation to start.
error A place to store errors, or 0.
Returns:
true if the transaction was started successfully, false otherwise.

bool Gnome::Gda::Connection::change_database ( const Glib::ustring name  ) 

Changes the current database for the given connection.

This operation is not available in all providers.

Parameters:
name Name of database to switch to.
Returns:
true if successful, false otherwise.

void Gnome::Gda::Connection::clear_events_list (  ) 

This function lets you clear the list of Gda::ConnectionEvent's of the given connection.

void Gnome::Gda::Connection::close (  ) 

Closes the connection to the underlying data source, but first emits the "conn_to_close" signal.

bool Gnome::Gda::Connection::commit_transaction ( const Glib::ustring name  ) 

Commits the given transaction to the backend database.

You need to call begin_transaction() first.

Parameters:
name The name of the transation to commit.
error A place to store errors, or 0.
Returns:
true if the transaction was finished successfully, false otherwise.

static Glib::RefPtr<Connection> Gnome::Gda::Connection::create (  )  [static]

bool Gnome::Gda::Connection::delete_savepoint ( const Glib::ustring name  ) 

Delete the SAVEPOINT named name when not used anymore.

Parameters:
name Name of the savepoint to delete.
error A place to store errors or 0.
Returns:
true if no error occurred.

int Gnome::Gda::Connection::execute_non_select_command ( const Glib::ustring cmd  ) 

Executes a non-selection command on the given connection.

This function returns the number of rows impacted by the execution of cmd, or -1 if an error occurred, or -2 if the provider does not return the number of rows impacted.

Note that no check is made regarding the actual number of statements in cmd or if it really contains a non SELECT statement. This function is just a convenience function around the execute_command() function. If cmd contains several statements, the last ParameterList is returned.

Parameters:
cmd A Command.
Returns:
the number of rows affected (>=0) or -1 or -2
Exceptions:
ConnectionError 

int Gnome::Gda::Connection::execute_non_select_command ( const Command cmd  ) 

Executes a non-selection command on the given connection.

This function returns the number of rows impacted by the execution of cmd, or -1 if an error occurred, or -2 if the provider does not return the number of rows impacted.

Note that no check is made regarding the actual number of statements in cmd or if it really contains a non SELECT statement. This function is just a convenience function around the execute_command() function. If cmd contains several statements, the last ParameterList is returned.

Parameters:
cmd A Command.
Returns:
the number of rows affected (>=0) or -1 or -2
Exceptions:
ConnectionError 

int Gnome::Gda::Connection::execute_non_select_command ( const Command cmd,
const Glib::RefPtr<ParameterList>&  params 
)

Executes a selection command on the given connection.

This function returns the number of rows impacted by the execution of cmd , or -1 if an error occurred, or -2 if the provider does not return the number of rows impacted.

Note that no check is made regarding the actual number of statements in cmd or if it really contains a non SELECT statement. This function is just a convenience function around the execute_command() function. If cmd contains several statements, the last Gda::ParameterList is returned.

See the documentation of the execute_command() for information about the params list of parameters.

Parameters:
cmd A Gda::Command.
params Parameter list for the command.
error A place to store an error, or 0.
Returns:
The number of rows impacted (>=0) or -1 or -2.

Glib::RefPtr<DataModel> Gnome::Gda::Connection::execute_select_command ( const Glib::ustring cmd  ) 

Executes a selection command on the given connection.

Note that no check is made regarding the actual number of statements in cmd or if it really contains a SELECT statement. This function is just a convenience function around the execute_command() method. If cmd contains several statements, only the last DataModel is returned.

Parameters:
cmd A SQL command string.
Returns:
A DataModel containing the data returned by the data source, or a null DataModel if an error occurred.
Exceptions:
ConnectionError 

Glib::RefPtr<DataModel> Gnome::Gda::Connection::execute_select_command ( const Command cmd  ) 

Executes a selection command on the given connection.

Note that no check is made regarding the actual number of statements in cmd or if it really contains a SELECT statement. This function is just a convenience function around the execute_command() method. If cmd contains several statements, only the last DataModel is returned.

Parameters:
cmd A Command.
Returns:
A DataModel containing the data returned by the data source, or a null DataModel if an error occurred.
Exceptions:
ConnectionError 

Glib::RefPtr<DataModel> Gnome::Gda::Connection::execute_select_command ( const Command cmd,
const Glib::RefPtr<ParameterList>&  params 
)

Executes a selection command on the given connection.

This function returns a Gda::DataModel resulting from the SELECT statement, or 0 if an error occurred.

Note that no check is made regarding the actual number of statements in cmd or if it really contains a SELECT statement. This function is just a convenience function around the execute_command() function. If cmd contains several statements, the last Gda::DataModel is returned.

See the documentation of the execute_command() for information about the params list of parameters.

Parameters:
cmd A Gda::Command.
params Parameter list for the command.
error A place to store an error, or 0.
Returns:
A Gda::DataModel containing the data returned by the data source, or 0 if an error occurred.

Glib::RefPtr<const Client> Gnome::Gda::Connection::get_client (  )  const

Gets the Gda::Client object associated with a connection.

This is always the client that created the connection, as returned by gda_client_open_connection.

Returns:
The client to which the connection belongs to.

Glib::RefPtr<Client> Gnome::Gda::Connection::get_client (  ) 

Gets the Gda::Client object associated with a connection.

This is always the client that created the connection, as returned by gda_client_open_connection.

Returns:
The client to which the connection belongs to.

Glib::ustring Gnome::Gda::Connection::get_cnc_string (  )  const

Gets the connection string used to open this connection.

The connection string is the string sent over to the underlying database provider, which describes the parameters to be used to open a connection on the underlying data source.

Returns:
The connection string used when opening the connection.

Glib::ustring Gnome::Gda::Connection::get_database (  )  const

Gets the name of the currently active database in the given GdaConnection .

Returns:
The name of the current database.

Glib::ustring Gnome::Gda::Connection::get_dsn (  )  const

Returns:
The data source name the connection object is connected to.

Glib::ListHandle<Glib::RefPtr<const ConnectionEvent>> Gnome::Gda::Connection::get_events (  )  const

Retrieves a list of the last errors occurred during the connection.

You can make a copy of the list using gda_connection_event_list_copy.

Returns:
A GList of Gda::ConnectionEvent.

Glib::ListHandle<Glib::RefPtr<ConnectionEvent>> Gnome::Gda::Connection::get_events (  ) 

Retrieves a list of the last errors occurred during the connection.

You can make a copy of the list using gda_connection_event_list_copy.

Returns:
A GList of Gda::ConnectionEvent.

const ServerProviderInfo* Gnome::Gda::Connection::get_infos (  )  const

Get a pointer to a Gda::ServerProviderInfo structure (which must not be modified) to retreive specific information about the provider used by cnc .

Glib::ustring Gnome::Gda::Connection::get_last_insert_id ( const Glib::RefPtr<DataModel>&  recset  )  const

Retrieve from the given Gda::Connection the ID of the last inserted row.

A connection must be specified, and, optionally, a result set. If not 0, the underlying provider should try to get the last insert ID for the given result set.

Parameters:
recset Recordset.
Returns:
A string representing the ID of the last inserted row, or 0 if an error occurred or no row has been inserted. It is the caller's reponsibility to free the returned string.

ConnectionOptions Gnome::Gda::Connection::get_options (  )  const

Gets the Gda::ConnectionOptions used to open this connection.

Returns:
The connection options.

Glib::ustring Gnome::Gda::Connection::get_password (  )  const

Gets the password used to open this connection.

Returns:
The password.

Glib::ustring Gnome::Gda::Connection::get_provider (  )  const

Gets the provider id that this connection is connected to.

Returns:
The provider ID used to open this connection.

Glib::RefPtr<const ServerProvider> Gnome::Gda::Connection::get_provider_obj (  )  const

Get a pointer to the Gda::ServerProvider object used to access the database.

Returns:
The Gda::ServerProvider (NEVER 0).

Glib::RefPtr<ServerProvider> Gnome::Gda::Connection::get_provider_obj (  ) 

Get a pointer to the Gda::ServerProvider object used to access the database.

Returns:
The Gda::ServerProvider (NEVER 0).

Glib::RefPtr<const DataModel> Gnome::Gda::Connection::get_schema ( ConnectionSchema  schema  )  const

Asks the underlying data source for a list of database objects.

This is the function that lets applications ask the different providers about all their database objects (tables, views, procedures, etc). The set of database objects that are retrieved are given by the 2 parameters of this function: schema, which specifies the specific schema required, and params, which is a list of parameters that can be used to give more detail about the objects to be returned.

The list of parameters is specific to each schema type, see the get_schema() virtual method for providers for more details.

Parameters:
schema Database schema to get.
Returns:
A DataModel containing the data required.
Exceptions:
Gda::ConnectionError 

Glib::RefPtr<DataModel> Gnome::Gda::Connection::get_schema ( ConnectionSchema  schema  ) 

Asks the underlying data source for a list of database objects.

This is the function that lets applications ask the different providers about all their database objects (tables, views, procedures, etc). The set of database objects that are retrieved are given by the 2 parameters of this function: schema, which specifies the specific schema required, and params, which is a list of parameters that can be used to give more detail about the objects to be returned.

The list of parameters is specific to each schema type, see the get_schema() virtual method for providers for more details.

Parameters:
schema Database schema to get.
Returns:
A DataModel containing the data required.
Exceptions:
Gda::ConnectionError 

Glib::RefPtr<const DataModel> Gnome::Gda::Connection::get_schema ( ConnectionSchema  schema,
const Glib::RefPtr<ParameterList>&  params 
) const

Asks the underlying data source for a list of database objects.

This is the function that lets applications ask the different providers about all their database objects (tables, views, procedures, etc). The set of database objects that are retrieved are given by the 2 parameters of this function: schema , which specifies the specific schema required, and params , which is a list of parameters that can be used to give more detail about the objects to be returned.

The list of parameters is specific to each schema type, see the get_schema() virtual method for providers for more details.

Parameters:
schema Database schema to get.
params Parameter list.
error A place to store errors, or 0.
Returns:
A Gda::DataModel containing the data required. The caller is responsible of freeing the returned model using Glib::object_unref().

Glib::RefPtr<DataModel> Gnome::Gda::Connection::get_schema ( ConnectionSchema  schema,
const Glib::RefPtr<ParameterList>&  params 
)

Asks the underlying data source for a list of database objects.

This is the function that lets applications ask the different providers about all their database objects (tables, views, procedures, etc). The set of database objects that are retrieved are given by the 2 parameters of this function: schema , which specifies the specific schema required, and params , which is a list of parameters that can be used to give more detail about the objects to be returned.

The list of parameters is specific to each schema type, see the get_schema() virtual method for providers for more details.

Parameters:
schema Database schema to get.
params Parameter list.
error A place to store errors, or 0.
Returns:
A Gda::DataModel containing the data required. The caller is responsible of freeing the returned model using Glib::object_unref().

Glib::ustring Gnome::Gda::Connection::get_server_version (  )  const

Gets the version string of the underlying database server.

Returns:
The server version string.

Glib::RefPtr<const TransactionStatus> Gnome::Gda::Connection::get_transaction_status (  )  const

Get the status of cnc regarding transactions.

The returned object should not be modified or destroyed; however it may be modified or destroyed by the connection itself.

If 0 is returned, then no transaction has been associated with cnc

Returns:
A Gda::TransactionStatus object, or 0.

Glib::ustring Gnome::Gda::Connection::get_username (  )  const

Gets the user name used to open this connection.

Returns:
The user name.

const GdaConnection* Gnome::Gda::Connection::gobj (  )  const [inline]

Provides access to the underlying C GObject.

Reimplemented from Glib::ObjectBase.

GdaConnection* Gnome::Gda::Connection::gobj (  )  [inline]

Provides access to the underlying C GObject.

Reimplemented from Glib::ObjectBase.

GdaConnection* Gnome::Gda::Connection::gobj_copy (  ) 

Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.

bool Gnome::Gda::Connection::is_opened (  )  const

Checks whether a connection is open or not.

Returns:
true if the connection is open, false if it's not.

virtual void Gnome::Gda::Connection::on_conn_closed (  )  [protected, virtual]

virtual void Gnome::Gda::Connection::on_conn_opened (  )  [protected, virtual]

virtual void Gnome::Gda::Connection::on_conn_to_close (  )  [protected, virtual]

virtual void Gnome::Gda::Connection::on_dsn_changed (  )  [protected, virtual]

virtual void Gnome::Gda::Connection::on_error ( const Glib::RefPtr<ConnectionEvent>&  error  )  [protected, virtual]

virtual void Gnome::Gda::Connection::on_transaction_status_changed (  )  [protected, virtual]

bool Gnome::Gda::Connection::open (  ) 

Tries to open the connection.

Parameters:
error A place to store errors, or 0.
Returns:
true if the connection is opened, and false otherwise.

bool Gnome::Gda::Connection::rollback_savepoint ( const Glib::ustring name  ) 

Rollback all the modifications made after the SAVEPOINT named name .

Parameters:
name Name of the savepoint to rollback to.
error A place to store errors or 0.
Returns:
true if no error occurred.

bool Gnome::Gda::Connection::rollback_transaction ( const Glib::ustring name  ) 

Rollbacks the given transaction.

This means that all changes made to the underlying data source since the last call to begin_transaction() or commit_transaction() will be discarded.

Parameters:
name The name of the transation to commit.
error A place to store errors, or 0.
Returns:
true if the operation was successful, false otherwise.

bool Gnome::Gda::Connection::set_dsn ( const Glib::ustring datasource  ) 

Sets the data source of the connection.

If the connection is already opened, then no action is performed at all and false is returned.

If the requested datasource does not exist, then nothing is done and false is returned.

Parameters:
datasource A gda datasource.
Returns:
true on success.

bool Gnome::Gda::Connection::set_password ( const Glib::ustring password  ) 

Sets the user password for the connection to the server.

If the connection is already opened, then no action is performed at all and false is returned.

Returns:
true on success.

bool Gnome::Gda::Connection::set_username ( const Glib::ustring username  ) 

Sets the user name for the connection.

If the connection is already opened, then no action is performed at all and false is returned.

Returns:
true on success.

Glib::SignalProxy0< void > Gnome::Gda::Connection::signal_conn_closed (  ) 

Prototype:
void conn_closed()

Glib::SignalProxy0< void > Gnome::Gda::Connection::signal_conn_opened (  ) 

Prototype:
void conn_opened()

Glib::SignalProxy0< void > Gnome::Gda::Connection::signal_conn_to_close (  ) 

Prototype:
void conn_to_close()

Glib::SignalProxy0< void > Gnome::Gda::Connection::signal_dsn_changed (  ) 

Prototype:
void dsn_changed()

Glib::SignalProxy1<void,const Glib::RefPtr<ConnectionEvent>&> Gnome::Gda::Connection::signal_error (  ) 

Prototype:
void error(const Glib::RefPtr<ConnectionEvent>& error)

Glib::SignalProxy0< void > Gnome::Gda::Connection::signal_transaction_status_changed (  ) 

Prototype:
void transaction_status_changed()

bool Gnome::Gda::Connection::supports_feature ( ConnectionFeature  feature  )  const

Asks the underlying provider for if a specific feature is supported.

Parameters:
feature Feature to ask for.
Returns:
true if the provider supports it, false if not.

Glib::ustring Gnome::Gda::Connection::value_to_sql_string ( const Value from  )  const

Produces a fully quoted and escaped string from a GValue.

Parameters:
from G::Value to convert from.
Returns:
Escaped and quoted value or 0 if not supported.


Friends And Related Function Documentation

Glib::RefPtr<Gnome::Gda::Connection> wrap ( GdaConnection *  object,
bool  take_copy = false 
) [related]

Parameters:
object The C instance

Parameters:
take_copy False if the result should take ownership of the C instance. True if it should take a new copy or ref.
Returns:
A C++ instance that wraps this C instance.


The documentation for this class was generated from the following file:
Generated for libgdamm by Doxygen 1.5.1 © 1997-2001