libgdamm Reference Documentation

Main Page Namespaces Book

# Gnome::Gda::Client Class Reference
[Connections and Commands]

Database client access. More...

Inheritance diagram for Gnome::Gda::Client:

[legend]
List of all members.

## Public Member Functions

bool | begin_transaction (const Glib::ustring& name, TransactionIsolation level)
| Starts a transaction on all connections being managed by the given Gda::Client.
void | close_all_connections ()
| Closes all connections opened by the given Gda::Client object.
bool | commit_transaction (const Glib::ustring& name)
| Commits a running transaction on all connections being managed by the given Gda::Client.
void | declare_connection (const Glib::RefPtr<Connection>& cnc)
| Declares the cnc to client.
Glib::RefPtr<Connection> | find_connection (const Glib::ustring& dsn, const Glib::ustring& username, const Glib::ustring& password)
| Looks for an open connection given a data source name (per libgda configuration), a username and a password.
Glib::ListHandle< Glib::RefPtr< const Connection > > | get_connections () const
| Gets the list of all open connections in the given Gda::Client object.
Glib::ListHandle< Glib::RefPtr< Connection > > | get_connections ()
| Gets the list of all open connections in the given Gda::Client object.
Glib::ustring | get_dsn_specs (const Glib::ustring& provider) const
| Get an XML string representing the parameters which can be present in the DSN string used to open a connection.
const GdaClient* | gobj () const
| Provides access to the underlying C GObject.
GdaClient* | gobj ()
| Provides access to the underlying C GObject.
GdaClient* | gobj_copy ()
| Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.
void | notify_connection_closed_event (const Glib::RefPtr<Connection>& cnc)
| Notifies the given Gda::Client of the Gda::CLIENT_EVENT_CONNECTION_CLOSED event.
void | notify_connection_opened_event (const Glib::RefPtr<Connection>& cnc)
| Notifies the given Gda::Client of the Gda::CLIENT_EVENT_CONNECTION_OPENED event.
void | notify_error_event (const Glib::RefPtr<Connection>& cnc, GdaConnectionEvent* error)
| Notifies the given Gda::Client of the Gda::CLIENT_EVENT_ERROR event.
void | notify_event (const Glib::RefPtr<Connection>& cnc, ClientEvent event, const Glib::RefPtr<ParameterList>& params)
| Notifies an event to the given Gda::Client's listeners.
Glib::RefPtr<Connection> | open_connection (const Glib::ustring& dsn, const Glib::ustring& username, const Glib::ustring& password, ConnectionOptions options=(ConnectionOptions) 0)
| This function is the way of opening database connections with libgda.
Glib::RefPtr<Connection> | open_connection_from_string (const Glib::ustring& provider_id, const Glib::ustring& cnc_string, const Glib::ustring& username, const Glib::ustring& password, ConnectionOptions options=(ConnectionOptions) 0)
| Opens a connection given a provider ID and a connection string.
bool | perform_create_database (const Glib::RefPtr<ServerOperation>& op)
| Creates a new database using the specifications in op, which must have been obtained using prepare_create_database().
bool | perform_drop_database (const Glib::RefPtr<ServerOperation>& op)
| Destroys an existing database using the specifications in op, which must have been obtained using prepare_drop_database().
Glib::RefPtr<ServerOperation> | prepare_create_database (const Glib::ustring& db_name, const Glib::ustring& provider)
| Creates a new Gda::ServerOperation object which contains the specifications required to create a database.
Glib::RefPtr<ServerOperation> | prepare_drop_database (const Glib::ustring& db_name, const Glib::ustring& provider)
| Creates a new Gda::ServerOperation object which contains the specifications required to drop a database.
bool | rollback_transaction (const Glib::ustring& name)
| Cancels a running transaction on all connections being managed by the given Gda::Client.
Glib::SignalProxy3< void, const Glib::RefPtr<Connection>&, ClientEvent, const Glib::RefPtr< ParameterList >& > | signal_event_notification ()

Prototype:
  `void on_my_event_notification(const Glib::RefPtr<Connection>& cnc, ClientEvent event, const Glib::RefPtr<ParameterList>& params)`

virtual | ~Client ()

## Static Public Member Functions

static Glib::RefPtr<Client> | create ()

## Protected Member Functions

| Client ()
virtual void | on_event_notification (const Glib::RefPtr<Connection>& cnc, ClientEvent event, const Glib::RefPtr<ParameterList>& params)

## Related Functions

(Note that these are not member functions.)
Glib::RefPtr<Gnome::Gda::Client> | wrap (GdaClient* object, bool take_copy=false)
| A Glib::wrap() method for this object.

## Detailed Description

Database client access.

This class is the main entry point for libgda client applications. It provides the way by which client applications open connections. Thus, before using any other database-oriented function in libgda, applications must create a Client object and open the connections from it.

The Client class also provides a way to treat several connections as if they were only one (a connection pool), which allows applications to, for instance, commit/rollback a transaction in all the connections being managed by a unique Client object, or obtain the list of all tables in all opened connections.

Database creation and destruction is done through a Client object using the perform_create_database() and perform_drop_database() methods. Note however that depending on the provider, an opened connection may be required in order to create or destroy a database.

## Constructor & Destructor Documentation

virtual Gnome::Gda::Client::~Client | ( |  | ) | `[virtual]`

Gnome::Gda::Client::Client | ( |  | ) | `[protected]`

## Member Function Documentation

bool Gnome::Gda::Client::begin_transaction | ( | const Glib::ustring & | name,
|  | TransactionIsolation | level |
| ) |  |  |

Starts a transaction on all connections being managed by the given Gda::Client.

It is important to note that this operates on all connections opened within a Gda::Client, which could not be what you're looking for.

To execute a transaction on a unique connection, use gda_connection_begin_transaction, gda_connection_commit_transaction and gda_connection_rollback_transaction.

Parameters:

  | name | The name of the transation to start.

Returns:
  `true` if all transactions could be started successfully, or `false` if one of them fails.

void Gnome::Gda::Client::close_all_connections | ( |  | ) |

Closes all connections opened by the given Gda::Client object.

bool Gnome::Gda::Client::commit_transaction | ( | const Glib::ustring & | name | ) |

Commits a running transaction on all connections being managed by the given Gda::Client.

It is important to note that this operates on all connections opened within a Gda::Client, which could not be what you're looking for.

To execute a transaction on a unique connection, use gda_connection_begin_transaction, gda_connection_commit_transaction and gda_connection_rollback_transaction.

Parameters:

  | name | The name of the transation to commit.

Returns:
  `true` if all transactions could be committed successfully, or `false` if one of them fails.

static Glib::RefPtr<Client> Gnome::Gda::Client::create | ( |  | ) | `[static]`

void Gnome::Gda::Client::declare_connection | ( | const Glib::RefPtr<Connection>& | cnc | ) |

Declares the cnc to client.

This function should not be used directly

Parameters:

  | cnc | A Gda::Connection object.

Glib::RefPtr<Connection> Gnome::Gda::Client::find_connection | ( | const Glib::ustring & | dsn,
|  | const Glib::ustring & | username,
|  | const Glib::ustring & | password |
| ) |  |  |

Looks for an open connection given a data source name (per libgda configuration), a username and a password.

This function iterates over the list of open connections in the given Gda::Client and looks for one that matches the given data source name, username and password.

Parameters:

  | dsn | Data source name.
  | username | User name.
  | password | Password for username.

Returns:
  A pointer to the found connection, or `0` if it could not be found.

Glib::ListHandle<Glib::RefPtr<const Connection>> Gnome::Gda::Client::get_connections | ( |  | ) | const

Gets the list of all open connections in the given Gda::Client object.

The GList returned is an internal pointer, so DON'T TRY TO FREE IT.

Returns:
  A GList of Gda::Connection objects; dont't modify that list.

Glib::ListHandle<Glib::RefPtr<Connection>> Gnome::Gda::Client::get_connections | ( |  | ) |

Gets the list of all open connections in the given Gda::Client object.

The GList returned is an internal pointer, so DON'T TRY TO FREE IT.

Returns:
  A GList of Gda::Connection objects; dont't modify that list.

Glib::ustring Gnome::Gda::Client::get_dsn_specs | ( | const Glib::ustring & | provider | ) | const

Get an XML string representing the parameters which can be present in the DSN string used to open a connection.

Parameters:

  | provider | A provider.

Returns:
  A string (free it after usage), or `0` if an error occurred.

const GdaClient* Gnome::Gda::Client::gobj | ( |  | ) | const`[inline]`

Provides access to the underlying C GObject.

Reimplemented from Glib::ObjectBase.

GdaClient* Gnome::Gda::Client::gobj | ( |  | ) | `[inline]`

Provides access to the underlying C GObject.

Reimplemented from Glib::ObjectBase.

GdaClient* Gnome::Gda::Client::gobj_copy | ( |  | ) |

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

void Gnome::Gda::Client::notify_connection_closed_event | ( | const Glib::RefPtr<Connection>& | cnc | ) |

Notifies the given Gda::Client of the Gda::CLIENT_EVENT_CONNECTION_CLOSED event.

Parameters:

  | cnc | A Gda::Connection object.

void Gnome::Gda::Client::notify_connection_opened_event | ( | const Glib::RefPtr<Connection>& | cnc | ) |

Notifies the given Gda::Client of the Gda::CLIENT_EVENT_CONNECTION_OPENED event.

Parameters:

  | cnc | A Gda::Connection object.

void Gnome::Gda::Client::notify_error_event | ( | const Glib::RefPtr<Connection>& | cnc,
|  | GdaConnectionEvent * | error |
| ) |  |  |

Notifies the given Gda::Client of the Gda::CLIENT_EVENT_ERROR event.

Parameters:

  | cnc | A Gda::Connection object.

void Gnome::Gda::Client::notify_event | ( | const Glib::RefPtr<Connection>& | cnc,
|  | ClientEvent | event,
|  | const Glib::RefPtr<ParameterList>& | params |
| ) |  |  |

Notifies an event to the given Gda::Client's listeners.

The event can be anything (see Gda::ClientEvent) ranging from a connection opening operation, to changes made to a table in an underlying database.

Parameters:

  | cnc | A Gda::Connection object where the event has occurred.
  | event | Event ID.
  | params | Parameters associated with the event.

virtual void Gnome::Gda::Client::on_event_notification | ( | const Glib::RefPtr<Connection>& | cnc,
|  | ClientEvent | event,
|  | const Glib::RefPtr<ParameterList>& | params |
| ) |  |  | `[protected, virtual]`

Glib::RefPtr<Connection> Gnome::Gda::Client::open_connection | ( | const Glib::ustring & | dsn,
|  | const Glib::ustring & | username,
|  | const Glib::ustring & | password,
|  | ConnectionOptions | options = `(ConnectionOptions) 0` |
| ) |  |  |

This function is the way of opening database connections with libgda.

Establishes a connection to a data source. The connection will be opened if no identical connection is available in the Gda::Client connection pool, and re-used if available. If you dont want to share the connection, specify Gda::CONNECTION_OPTIONS_DONT_SHARE as one of the flags in the options parameter.

The username and password used to actually open the connection are the first non-`0` string being chosen by order from <itemizedlist> <listitem>the username or password</listitem> <listitem>the username or password sprcified in the DSN definition</listitem> <listitem>the USERNAME= and PASSWORD= parts of the connection string in the DSN definition</listitem> </itemizedlist>

Parameters:

  | dsn | Data source name.
  | username | User name or `0`.
  | password | Password for username, or `0`.
  | options | Options for the connection (see Gda::ConnectionOptions).

Returns:
  The opened connection if successful, `0` if there is an error.

Glib::RefPtr<Connection> Gnome::Gda::Client::open_connection_from_string | ( | const Glib::ustring & | provider_id,
|  | const Glib::ustring & | cnc_string,
|  | const Glib::ustring & | username,
|  | const Glib::ustring & | password,
|  | ConnectionOptions | options = `(ConnectionOptions) 0` |
| ) |  |  |

Opens a connection given a provider ID and a connection string.

This allows applications to open connections without having to create a data source in the configuration. The format of cnc_string is similar to PostgreSQL and MySQL connection strings. It is a semicolumn-separated series of key=value pairs. Do not add extra whitespace after the semicolumn separator. The possible keys depend on the provider, but these keys should work with all providers: USER, PASSWORD, HOST, DATABASE, PORT

The username and password used to actually open the connection are the first non-`0` string being chosen by order from <itemizedlist> <listitem>the username or password</listitem> <listitem>the USERNAME= and PASSWORD= parts of the cnc_string</listitem> </itemizedlist>

Parameters:

  | provider_id | Provider ID to connect to.
  | cnc_string | Connection string.
  | username | User name.
  | password | Password for username.
  | options | Options for the connection (see Gda::ConnectionOptions).

Returns:
  The opened connection if successful, `0` if there is an error.

bool Gnome::Gda::Client::perform_create_database | ( | const Glib::RefPtr<ServerOperation>& | op | ) |

Creates a new database using the specifications in op, which must have been obtained using prepare_create_database().

Parameters:

  | op | A Gda::ServerOperation object obtained using prepare_create_database().

Returns:
  `true` if no error occurred and the database has been created.

bool Gnome::Gda::Client::perform_drop_database | ( | const Glib::RefPtr<ServerOperation>& | op | ) |

Destroys an existing database using the specifications in op, which must have been obtained using prepare_drop_database().

Parameters:

  | op | A Gda::ServerOperation object obtained using prepare_drop_database().

Returns:
  `true` if no error occurred and the database has been destroyed.

Glib::RefPtr<ServerOperation> Gnome::Gda::Client::prepare_create_database | ( | const Glib::ustring & | db_name,
|  | const Glib::ustring & | provider |
| ) |  |  |

Creates a new Gda::ServerOperation object which contains the specifications required to create a database.

Once these specifications provided, use perform_create_database() to perform the database creation.

If db_name is left `0`, then the name of the database to create will have to be set in the returned Gda::ServerOperation using Gda::ServerOperation::set_value_at().

Parameters:

  | db_name | The name of the database to create, or `0`.
  | provider | A provider.

Returns:
  New Gda::ServerOperation object, or `0` if the provider does not support database creation.

Glib::RefPtr<ServerOperation> Gnome::Gda::Client::prepare_drop_database | ( | const Glib::ustring & | db_name,
|  | const Glib::ustring & | provider |
| ) |  |  |

Creates a new Gda::ServerOperation object which contains the specifications required to drop a database.

Once these specifications provided, use perform_drop_database() to perform the database creation.

If db_name is left `0`, then the name of the database to drop will have to be set in the returned Gda::ServerOperation using Gda::ServerOperation::set_value_at().

Parameters:

  | db_name | The name of the database to drop, or `0`.
  | provider | A provider.

Returns:
  New Gda::ServerOperation object, or `0` if the provider does not support database destruction.

bool Gnome::Gda::Client::rollback_transaction | ( | const Glib::ustring & | name | ) |

Cancels a running transaction on all connections being managed by the given Gda::Client.

It is important to note that this operates on all connections opened within a Gda::Client, which could not be what you're looking for.

To execute a transaction on a unique connection, use gda_connection_begin_transaction, gda_connection_commit_transaction and gda_connection_rollback_transaction.

Parameters:

  | name | The name of the transation to rollback.

Returns:
  `true` if all transactions could be cancelled successfully, or `false` if one of them fails.

Glib::SignalProxy3<void,const Glib::RefPtr<Connection>&,ClientEvent,const Glib::RefPtr<ParameterList>&> Gnome::Gda::Client::signal_event_notification | ( |  | ) |

Prototype:
  `void on_my_event_notification(const Glib::RefPtr<Connection>& cnc, ClientEvent event, const Glib::RefPtr<ParameterList>& params)`

## Friends And Related Function Documentation

Glib::RefPtr<Gnome::Gda::Client> wrap | ( | GdaClient * | object,
|  | bool | take_copy = `false` |
| ) |  |  | `[related]`

A Glib::wrap() method for this object.

Parameters:

  | object | The C instance.
  | 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:

- client.h