From 17aebcd5506a4306b23194e56c2fc524e70767df Mon Sep 17 00:00:00 2001 From: Miguel de Icaza Date: Tue, 13 Jul 2004 18:56:58 +0000 Subject: [PATCH] Apply patch from wizito@gentelibre.org svn path=/trunk/gtk-sharp/; revision=31100 --- doc/en/Gda/Client.xml | 122 +++++++++++++---- doc/en/Gda/Connection.xml | 266 ++++++++++++++++++++++++++++++-------- 2 files changed, 313 insertions(+), 75 deletions(-) diff --git a/doc/en/Gda/Client.xml b/doc/en/Gda/Client.xml index 111efcc1d..2b4fcf770 100644 --- a/doc/en/Gda/Client.xml +++ b/doc/en/Gda/Client.xml @@ -10,7 +10,14 @@ Gtk# is thread aware, but not thread safe; See the Gtk# Thread Programming for details. - To be added + + +This class is the main entry point for libgda cliente applications. It provides the way by which client applications open connections. + + +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 Gda.Client object, or obtain the list of all tables in all opened connections. + + To be added @@ -51,7 +58,11 @@ - To be added + + +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. + + a a a @@ -70,10 +81,18 @@ - To be added + + +Starts a transaction on all connections being managed by the given Gda.Client. + + a a - To be added + + +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, there are other methods. + + @@ -87,7 +106,10 @@ - To be added + + Notifies the given GdaClient of the Gda.Client.EventTransactionCommited event. + + a a To be added @@ -104,7 +126,11 @@ - To be added + + +Notifies the given GdaClient of the Gda.Client.EventTransactionCancelled event. + + a a To be added @@ -121,7 +147,11 @@ - To be added + + + Notifies the given Gda.Client of the Gda.ClientEventError event. + + a a To be added @@ -137,10 +167,18 @@ - To be added + + +Commits a running transaction on all connections being managed by the given Gda.Client. + + a a - To be added + + +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, there are other methods. + + @@ -155,12 +193,20 @@ - To be added + + +Looks for an open connection given a data source name (per libgda configuration), a username and a password. + + a a a a - To be added + + +This function iterates over the list of open connections in the given Gda.Client object and looks for one that matches the given data source name, username and password. + + @@ -173,10 +219,18 @@ - To be added + + +Cancels a running transaction on all connections being managed by the given Gda.Client. + + a a - To be added + + +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, there are other methods. + + @@ -189,7 +243,7 @@ - To be added + Notifies the given GdaClient of the Gda.Client.EventConnectionOpened event. a To be added @@ -206,12 +260,20 @@ - To be added + + +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. + + a a a a - To be added + + +The format of cnc_string is similar to PostgreSQL and MySQL connection strings. It is a ;-separated series of key=value pairs. Do not add extra whitespace after the ; separator. The possible keys depend on the provider, but these keys should work with all providers: USER, PASSWORD, HOST, DATABASE, PORT + + @@ -225,7 +287,11 @@ - To be added + + +Notifies the given Gda.Client of the Gda.Client.EventTransactionStarted event. + + a a To be added @@ -239,7 +305,11 @@ - To be added + + +Closes all connections opened by the given Gda.Client object. + + To be added @@ -255,8 +325,12 @@ - To be added - a + + +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. + + + a where the event has ocurred. a a To be added @@ -282,7 +356,7 @@ - To be added + Default constructor for Gda.Client. a To be added @@ -295,7 +369,11 @@ - To be added + + +Gets the list of all open connections in the given Gda.Client object. + + a To be added diff --git a/doc/en/Gda/Connection.xml b/doc/en/Gda/Connection.xml index f56e76fe0..4e658cd4a 100644 --- a/doc/en/Gda/Connection.xml +++ b/doc/en/Gda/Connection.xml @@ -10,8 +10,16 @@ Gtk# is thread aware, but not thread safe; See the Gtk# Thread Programming for details. - To be added - To be added + + +The Gda.Connection class offers access to all operations involving an opened connection to a database. Gda.Connection objects are obtained via the Gda.Client class. + + + + +Once obtained, applications can use Gda.Connection to execute commands, run transactions, and get information about all objects stored in the underlying database. + + GLib.Object @@ -48,10 +56,18 @@ - To be added + + +Rollbacks the given transaction. + + a - a - To be added + a true if the operation was successfull, false otherwise + + +This means that all changes made to the underlying data source since the last call to or will be discarded. + + @@ -64,10 +80,18 @@ - To be added + + +Starts a transaction on the data source, identified by the xaction parameter. + + a - a - To be added + a true if the transaction was started successfully, false otherwise + + +Before starting a transaction, you can check whether the underlying provider does support transactions or not by using the method. + + @@ -81,10 +105,14 @@ - To be added + + +Executes a single command on the underlying database, and gets the number of rows affected. + + a a - a + a the numer of affected rows by the executed command, or -1 on error To be added @@ -98,9 +126,13 @@ - To be added + + +Changes the current database for the given connection. This operation is not available in all providers. + + a - a + a true if successful, false otherwise To be added @@ -114,9 +146,13 @@ - To be added + + +Drops a database from the given connection. + + a - a + a true if successful, false otherwise To be added @@ -130,9 +166,17 @@ - To be added + + +This is just another convenience method which lets you add a list of GdaError's to the given connection. + + a - To be added + + +As with , this method makes the connection object emit the "error" signal. The only difference is that, instead of a notification for each error, this function only does one notification for the whole list of errors. + + @@ -145,10 +189,18 @@ - To be added + + +Commits the given transaction to the backend database. + + a - a - To be added + a true if the transaction was finished successfully, false otherwise + + +You need to do first. + + @@ -161,9 +213,17 @@ - To be added + + +Adds an error to the given connection. This function is usually called by providers, to inform clients of errors that happened during some operation. + + a - To be added + + +As soon as a provider (or a client, it does not matter) calls this function, the connection object (and the associated Gda.Client object) emits the "error" signal, to which clients can connect to be informed of errors. + + @@ -176,9 +236,13 @@ - To be added + + +Creates a new database named name on the given connection. + + a - a + a true if successful, false otherwise To be added @@ -192,9 +256,13 @@ - To be added + + +Asks the underlying provider for if a specific feature is supported. + + a - a + a true if the provider supports it, false if not To be added @@ -209,11 +277,18 @@ - To be added + + +Executes a single command on the given connection. + + a a a - To be added + + +This method lets you retrieve a simple data model from the underlying difference, instead of having to retrieve a list of them, as is the case with + @@ -224,8 +299,12 @@ - To be added - a + + +Closes the connection to the underlying data source. After calling this function, you should not use anymore the Gda.Connection object, since it may have been destroyed. + + + a true if succesfull, false otherwise. To be added @@ -240,11 +319,19 @@ - To be added + + +Executes a command on the underlying data source. + + a a - a - To be added + a of + + +This method provides the way to send several commands at once to the data source being accessed by the given object. The specified can contain a list of commands in its "text" property (usually a set of SQL commands separated by ';'). + + @@ -258,11 +345,19 @@ - To be added + + +Asks the underlying data source for a list of database objects. + + a a - a - To be added + a containing the data required + + +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. + + @@ -275,9 +370,13 @@ - To be added + + +Creates a BLOB (Binary Large OBject) with read/write access. + + a - a + a false if database does not support BLOBs, true otherwise and the Gda.Blob is created and ready to be used To be added @@ -308,7 +407,11 @@ - To be added + + +Creates a new Gda.Connection object. + + a a a @@ -316,7 +419,10 @@ a a a - To be added + + +It is not intended to be used directly by applications. Use + @@ -327,9 +433,17 @@ - To be added + + +Gets the connection string used to open this connection. + + a - To be added + + +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. + + @@ -340,9 +454,17 @@ - To be added + + +Retrieves a list of the last errors ocurred in the connection. + + a - To be added + + +You can make a copy of the list using . + + @@ -353,7 +475,11 @@ - To be added + + +Gets the used to open this connection. + + a To be added @@ -366,7 +492,11 @@ - To be added + + +Gets the Data Source Name the connection object is connected to. + + a To be added @@ -379,7 +509,11 @@ - To be added + + +Gets the name of the currently active database in the given Gda.Connection. + + a To be added @@ -392,7 +526,11 @@ - To be added + + +Gets the user name used to open this connection. + + a To be added @@ -405,7 +543,13 @@ - To be added + + +Gets the Gda.Client object associated with a connection. This is always the client that created the connection, as returned by + +Associates a Gda.Client with this connection. This property (setter) is not intended to be called by applications. + + a To be added @@ -418,7 +562,11 @@ - To be added + + +Gets the password used to open this connection. + + a To be added @@ -431,7 +579,11 @@ - To be added + + +Gets the version string of the underlying database server. + + a To be added @@ -444,7 +596,11 @@ - To be added + + +Gets the provider id that this connection is connected to. + + a To be added @@ -469,8 +625,12 @@ - To be added - a + + +Checks whether a connection is open or not. + + + a true if the connection is open, false if it's not To be added