svn path=/trunk/gtk-sharp/; revision=31100
This commit is contained in:
Miguel de Icaza 2004-07-13 18:56:58 +00:00
parent a7c13bb7c7
commit 17aebcd550
2 changed files with 313 additions and 75 deletions

View File

@ -10,7 +10,14 @@
</AssemblyInfo>
<ThreadSafetyStatement>Gtk# is thread aware, but not thread safe; See the <link location="node:gtk-sharp/programming/threads">Gtk# Thread Programming</link> for details.</ThreadSafetyStatement>
<Docs>
<summary>To be added</summary>
<summary>
<para>
This class is the main entry point for libgda cliente applications. It provides the way by which client applications open connections.
</para>
<para>
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.
</para>
</summary>
<remarks>To be added</remarks>
</Docs>
<Base>
@ -51,7 +58,11 @@
<Parameter Name="options" Type="Gda.ConnectionOptions" />
</Parameters>
<Docs>
<summary>To be added</summary>
<summary>
<para>
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.
</para>
</summary>
<param name="dsn">a <see cref="T:System.String" /></param>
<param name="username">a <see cref="T:System.String" /></param>
<param name="password">a <see cref="T:System.String" /></param>
@ -70,10 +81,18 @@
<Parameter Name="xaction" Type="Gda.Transaction" />
</Parameters>
<Docs>
<summary>To be added</summary>
<summary>
<para>
Starts a transaction on all connections being managed by the given Gda.Client.
</para>
</summary>
<param name="xaction">a <see cref="T:Gda.Transaction" /></param>
<returns>a <see cref="T:System.Boolean" /></returns>
<remarks>To be added</remarks>
<remarks>
<para>
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.
</para>
</remarks>
</Docs>
</Member>
<Member MemberName="NotifyTransactionCommittedEvent">
@ -87,7 +106,10 @@
<Parameter Name="xaction" Type="Gda.Transaction" />
</Parameters>
<Docs>
<summary>To be added</summary>
<summary>
<para>Notifies the given GdaClient of the Gda.Client.EventTransactionCommited event.
</para>
</summary>
<param name="cnc">a <see cref="T:Gda.Connection" /></param>
<param name="xaction">a <see cref="T:Gda.Transaction" /></param>
<remarks>To be added</remarks>
@ -104,7 +126,11 @@
<Parameter Name="xaction" Type="Gda.Transaction" />
</Parameters>
<Docs>
<summary>To be added</summary>
<summary>
<para>
Notifies the given GdaClient of the Gda.Client.EventTransactionCancelled event.
</para>
</summary>
<param name="cnc">a <see cref="T:Gda.Connection" /></param>
<param name="xaction">a <see cref="T:Gda.Transaction" /></param>
<remarks>To be added</remarks>
@ -121,7 +147,11 @@
<Parameter Name="error" Type="Gda.Error" />
</Parameters>
<Docs>
<summary>To be added</summary>
<summary>
<para>
Notifies the given Gda.Client of the Gda.ClientEventError event.
</para>
</summary>
<param name="cnc">a <see cref="T:Gda.Connection" /></param>
<param name="error">a <see cref="T:Gda.Error" /></param>
<remarks>To be added</remarks>
@ -137,10 +167,18 @@
<Parameter Name="xaction" Type="Gda.Transaction" />
</Parameters>
<Docs>
<summary>To be added</summary>
<summary>
<para>
Commits a running transaction on all connections being managed by the given Gda.Client.
</para>
</summary>
<param name="xaction">a <see cref="T:Gda.Transaction" /></param>
<returns>a <see cref="T:System.Boolean" /></returns>
<remarks>To be added</remarks>
<remarks>
<para>
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.
</para>
</remarks>
</Docs>
</Member>
<Member MemberName="FindConnection">
@ -155,12 +193,20 @@
<Parameter Name="password" Type="System.String" />
</Parameters>
<Docs>
<summary>To be added</summary>
<summary>
<para>
Looks for an open connection given a data source name (per libgda configuration), a username and a password.
</para>
</summary>
<param name="dsn">a <see cref="T:System.String" /></param>
<param name="username">a <see cref="T:System.String" /></param>
<param name="password">a <see cref="T:System.String" /></param>
<returns>a <see cref="T:Gda.Connection" /></returns>
<remarks>To be added</remarks>
<remarks>
<para>
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.
</para>
</remarks>
</Docs>
</Member>
<Member MemberName="RollbackTransaction">
@ -173,10 +219,18 @@
<Parameter Name="xaction" Type="Gda.Transaction" />
</Parameters>
<Docs>
<summary>To be added</summary>
<summary>
<para>
Cancels a running transaction on all connections being managed by the given Gda.Client.
</para>
</summary>
<param name="xaction">a <see cref="T:Gda.Transaction" /></param>
<returns>a <see cref="T:System.Boolean" /></returns>
<remarks>To be added</remarks>
<remarks>
<para>
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.
</para>
</remarks>
</Docs>
</Member>
<Member MemberName="NotifyConnectionOpenedEvent">
@ -189,7 +243,7 @@
<Parameter Name="cnc" Type="Gda.Connection" />
</Parameters>
<Docs>
<summary>To be added</summary>
<summary>Notifies the given GdaClient of the Gda.Client.EventConnectionOpened event.</summary>
<param name="cnc">a <see cref="T:Gda.Connection" /></param>
<remarks>To be added</remarks>
</Docs>
@ -206,12 +260,20 @@
<Parameter Name="options" Type="Gda.ConnectionOptions" />
</Parameters>
<Docs>
<summary>To be added</summary>
<summary>
<para>
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.
</para>
</summary>
<param name="provider_id">a <see cref="T:System.String" /></param>
<param name="cnc_string">a <see cref="T:System.String" /></param>
<param name="options">a <see cref="T:Gda.ConnectionOptions" /></param>
<returns>a <see cref="T:Gda.Connection" /></returns>
<remarks>To be added</remarks>
<remarks>
<para>
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
</para>
</remarks>
</Docs>
</Member>
<Member MemberName="NotifyTransactionStartedEvent">
@ -225,7 +287,11 @@
<Parameter Name="xaction" Type="Gda.Transaction" />
</Parameters>
<Docs>
<summary>To be added</summary>
<summary>
<para>
Notifies the given Gda.Client of the Gda.Client.EventTransactionStarted event.
</para>
</summary>
<param name="cnc">a <see cref="T:Gda.Connection" /></param>
<param name="xaction">a <see cref="T:Gda.Transaction" /></param>
<remarks>To be added</remarks>
@ -239,7 +305,11 @@
</ReturnValue>
<Parameters />
<Docs>
<summary>To be added</summary>
<summary>
<para>
Closes all connections opened by the given Gda.Client object.
</para>
</summary>
<remarks>To be added</remarks>
</Docs>
</Member>
@ -255,8 +325,12 @@
<Parameter Name="parms" Type="Gda.ParameterList" />
</Parameters>
<Docs>
<summary>To be added</summary>
<param name="cnc">a <see cref="T:Gda.Connection" /></param>
<summary>
<para>
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.
</para>
</summary>
<param name="cnc">a <see cref="T:Gda.Connection" /> where the event has ocurred.</param>
<param name="evnt">a <see cref="T:Gda.ClientEvent" /></param>
<param name="parms">a <see cref="T:Gda.ParameterList" /></param>
<remarks>To be added</remarks>
@ -282,7 +356,7 @@
<ReturnValue />
<Parameters />
<Docs>
<summary>To be added</summary>
<summary>Default constructor for Gda.Client.</summary>
<returns>a <see cref="T:Gda.Client" /></returns>
<remarks>To be added</remarks>
</Docs>
@ -295,7 +369,11 @@
</ReturnValue>
<Parameters />
<Docs>
<summary>To be added</summary>
<summary>
<para>
Gets the list of all open connections in the given Gda.Client object.
</para>
</summary>
<returns>a <see cref="T:GLib.List" /></returns>
<remarks>To be added</remarks>
</Docs>

View File

@ -10,8 +10,16 @@
</AssemblyInfo>
<ThreadSafetyStatement>Gtk# is thread aware, but not thread safe; See the <link location="node:gtk-sharp/programming/threads">Gtk# Thread Programming</link> for details.</ThreadSafetyStatement>
<Docs>
<summary>To be added</summary>
<remarks>To be added</remarks>
<summary>
<para>
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.
</para>
</summary>
<remarks>
<para>
Once obtained, applications can use Gda.Connection to execute commands, run transactions, and get information about all objects stored in the underlying database.
</para>
</remarks>
</Docs>
<Base>
<BaseTypeName>GLib.Object</BaseTypeName>
@ -48,10 +56,18 @@
<Parameter Name="xaction" Type="Gda.Transaction" />
</Parameters>
<Docs>
<summary>To be added</summary>
<summary>
<para>
Rollbacks the given transaction.
</para>
</summary>
<param name="xaction">a <see cref="T:Gda.Transaction" /></param>
<returns>a <see cref="T:System.Boolean" /></returns>
<remarks>To be added</remarks>
<returns>a <see cref="T:System.Boolean" /> true if the operation was successfull, false otherwise</returns>
<remarks>
<para>
This means that all changes made to the underlying data source since the last call to <see cref="M:Gda.Connection.BeginTransaction" /> or <see cref="M:Gda.Connection.CommitTransaction" /> will be discarded.
</para>
</remarks>
</Docs>
</Member>
<Member MemberName="BeginTransaction">
@ -64,10 +80,18 @@
<Parameter Name="xaction" Type="Gda.Transaction" />
</Parameters>
<Docs>
<summary>To be added</summary>
<summary>
<para>
Starts a transaction on the data source, identified by the xaction parameter.
</para>
</summary>
<param name="xaction">a <see cref="T:Gda.Transaction" /></param>
<returns>a <see cref="T:System.Boolean" /></returns>
<remarks>To be added</remarks>
<returns>a <see cref="T:System.Boolean" /> true if the transaction was started successfully, false otherwise</returns>
<remarks>
<para>
Before starting a transaction, you can check whether the underlying provider does support transactions or not by using the <see cref="M:Gda.Connection.Supports" /> method.
</para>
</remarks>
</Docs>
</Member>
<Member MemberName="ExecuteNonQuery">
@ -81,10 +105,14 @@
<Parameter Name="parms" Type="Gda.ParameterList" />
</Parameters>
<Docs>
<summary>To be added</summary>
<summary>
<para>
Executes a single command on the underlying database, and gets the number of rows affected.
</para>
</summary>
<param name="cmd">a <see cref="T:Gda.Command" /></param>
<param name="parms">a <see cref="T:Gda.ParameterList" /></param>
<returns>a <see cref="T:System.Int32" /></returns>
<returns>a <see cref="T:System.Int32" /> the numer of affected rows by the executed command, or -1 on error</returns>
<remarks>To be added</remarks>
</Docs>
</Member>
@ -98,9 +126,13 @@
<Parameter Name="name" Type="System.String" />
</Parameters>
<Docs>
<summary>To be added</summary>
<summary>
<para>
Changes the current database for the given connection. This operation is not available in all providers.
</para>
</summary>
<param name="name">a <see cref="T:System.String" /></param>
<returns>a <see cref="T:System.Boolean" /></returns>
<returns>a <see cref="T:System.Boolean" /> true if successful, false otherwise</returns>
<remarks>To be added</remarks>
</Docs>
</Member>
@ -114,9 +146,13 @@
<Parameter Name="name" Type="System.String" />
</Parameters>
<Docs>
<summary>To be added</summary>
<summary>
<para>
Drops a database from the given connection.
</para>
</summary>
<param name="name">a <see cref="T:System.String" /></param>
<returns>a <see cref="T:System.Boolean" /></returns>
<returns>a <see cref="T:System.Boolean" /> true if successful, false otherwise</returns>
<remarks>To be added</remarks>
</Docs>
</Member>
@ -130,9 +166,17 @@
<Parameter Name="error_list" Type="GLib.List" />
</Parameters>
<Docs>
<summary>To be added</summary>
<summary>
<para>
This is just another convenience method which lets you add a list of GdaError's to the given connection.
</para>
</summary>
<param name="error_list">a <see cref="T:GLib.List" /></param>
<remarks>To be added</remarks>
<remarks>
<para>
As with <see cref="M:Gda.Connection.AddError" /> , 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.
</para>
</remarks>
</Docs>
</Member>
<Member MemberName="CommitTransaction">
@ -145,10 +189,18 @@
<Parameter Name="xaction" Type="Gda.Transaction" />
</Parameters>
<Docs>
<summary>To be added</summary>
<summary>
<para>
Commits the given transaction to the backend database.
</para>
</summary>
<param name="xaction">a <see cref="T:Gda.Transaction" /></param>
<returns>a <see cref="T:System.Boolean" /></returns>
<remarks>To be added</remarks>
<returns>a <see cref="T:System.Boolean" /> true if the transaction was finished successfully, false otherwise</returns>
<remarks>
<para>
You need to do <see cref="M:Gda.Connection.BeginTransaction" /> first.
</para>
</remarks>
</Docs>
</Member>
<Member MemberName="AddError">
@ -161,9 +213,17 @@
<Parameter Name="error" Type="Gda.Error" />
</Parameters>
<Docs>
<summary>To be added</summary>
<summary>
<para>
Adds an error to the given connection. This function is usually called by providers, to inform clients of errors that happened during some operation.
</para>
</summary>
<param name="error">a <see cref="T:Gda.Error" /></param>
<remarks>To be added</remarks>
<remarks>
<para>
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.
</para>
</remarks>
</Docs>
</Member>
<Member MemberName="CreateDatabase">
@ -176,9 +236,13 @@
<Parameter Name="name" Type="System.String" />
</Parameters>
<Docs>
<summary>To be added</summary>
<summary>
<para>
Creates a new database named name on the given connection.
</para>
</summary>
<param name="name">a <see cref="T:System.String" /></param>
<returns>a <see cref="T:System.Boolean" /></returns>
<returns>a <see cref="T:System.Boolean" /> true if successful, false otherwise</returns>
<remarks>To be added</remarks>
</Docs>
</Member>
@ -192,9 +256,13 @@
<Parameter Name="feature" Type="Gda.ConnectionFeature" />
</Parameters>
<Docs>
<summary>To be added</summary>
<summary>
<para>
Asks the underlying provider for if a specific feature is supported.
</para>
</summary>
<param name="feature">a <see cref="T:Gda.ConnectionFeature" /></param>
<returns>a <see cref="T:System.Boolean" /></returns>
<returns>a <see cref="T:System.Boolean" /> true if the provider supports it, false if not</returns>
<remarks>To be added</remarks>
</Docs>
</Member>
@ -209,11 +277,18 @@
<Parameter Name="parms" Type="Gda.ParameterList" />
</Parameters>
<Docs>
<summary>To be added</summary>
<summary>
<para>
Executes a single command on the given connection.
</para>
</summary>
<param name="cmd">a <see cref="T:Gda.Command" /></param>
<param name="parms">a <see cref="T:Gda.ParameterList" /></param>
<returns>a <see cref="T:Gda.DataModel" /></returns>
<remarks>To be added</remarks>
<remarks>
<para>
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 <see cref="M:Gda.Connection.ExecuteCommand" /></para>
</remarks>
</Docs>
</Member>
<Member MemberName="Close">
@ -224,8 +299,12 @@
</ReturnValue>
<Parameters />
<Docs>
<summary>To be added</summary>
<returns>a <see cref="T:System.Boolean" /></returns>
<summary>
<para>
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.
</para>
</summary>
<returns>a <see cref="T:System.Boolean" /> true if succesfull, false otherwise.</returns>
<remarks>To be added</remarks>
</Docs>
</Member>
@ -240,11 +319,19 @@
<Parameter Name="parms" Type="Gda.ParameterList" />
</Parameters>
<Docs>
<summary>To be added</summary>
<summary>
<para>
Executes a command on the underlying data source.
</para>
</summary>
<param name="cmd">a <see cref="T:Gda.Command" /></param>
<param name="parms">a <see cref="T:Gda.ParameterList" /></param>
<returns>a <see cref="T:GLib.List" /></returns>
<remarks>To be added</remarks>
<returns>a <see cref="T:GLib.List" /> of <see cref="T:Gda.DataModel" /></returns>
<remarks>
<para>
This method provides the way to send several commands at once to the data source being accessed by the given <see cref="T:Gda.Command" /> object. The <see cref="T:Gda.Command" /> specified can contain a list of commands in its "text" property (usually a set of SQL commands separated by ';').
</para>
</remarks>
</Docs>
</Member>
<Member MemberName="GetSchema">
@ -258,11 +345,19 @@
<Parameter Name="parms" Type="Gda.ParameterList" />
</Parameters>
<Docs>
<summary>To be added</summary>
<summary>
<para>
Asks the underlying data source for a list of database objects.
</para>
</summary>
<param name="schema">a <see cref="T:Gda.ConnectionSchema" /></param>
<param name="parms">a <see cref="T:Gda.ParameterList" /></param>
<returns>a <see cref="T:Gda.DataModel" /></returns>
<remarks>To be added</remarks>
<returns>a <see cref="T:Gda.DataModel" /> containing the data required</returns>
<remarks>
<para>
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.
</para>
</remarks>
</Docs>
</Member>
<Member MemberName="CreateBlob">
@ -275,9 +370,13 @@
<Parameter Name="blob" Type="Gda.Blob" />
</Parameters>
<Docs>
<summary>To be added</summary>
<summary>
<para>
Creates a BLOB (Binary Large OBject) with read/write access.
</para>
</summary>
<param name="blob">a <see cref="T:Gda.Blob" /></param>
<returns>a <see cref="T:System.Boolean" /></returns>
<returns>a <see cref="T:System.Boolean" /> false if database does not support BLOBs, true otherwise and the Gda.Blob is created and ready to be used</returns>
<remarks>To be added</remarks>
</Docs>
</Member>
@ -308,7 +407,11 @@
<Parameter Name="options" Type="Gda.ConnectionOptions" />
</Parameters>
<Docs>
<summary>To be added</summary>
<summary>
<para>
Creates a new Gda.Connection object.
</para>
</summary>
<param name="client">a <see cref="T:Gda.Client" /></param>
<param name="provider">a <see cref="T:Gda.ServerProvider" /></param>
<param name="dsn">a <see cref="T:System.String" /></param>
@ -316,7 +419,10 @@
<param name="password">a <see cref="T:System.String" /></param>
<param name="options">a <see cref="T:Gda.ConnectionOptions" /></param>
<returns>a <see cref="T:Gda.Connection" /></returns>
<remarks>To be added</remarks>
<remarks>
<para>
It is not intended to be used directly by applications. Use <see cref="M:Gda.Client.OpenConnection" /></para>
</remarks>
</Docs>
</Member>
<Member MemberName="CncString">
@ -327,9 +433,17 @@
</ReturnValue>
<Parameters />
<Docs>
<summary>To be added</summary>
<summary>
<para>
Gets the connection string used to open this connection.
</para>
</summary>
<returns>a <see cref="T:System.String" /></returns>
<remarks>To be added</remarks>
<remarks>
<para>
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.
</para>
</remarks>
</Docs>
</Member>
<Member MemberName="Errors">
@ -340,9 +454,17 @@
</ReturnValue>
<Parameters />
<Docs>
<summary>To be added</summary>
<summary>
<para>
Retrieves a list of the last errors ocurred in the connection.
</para>
</summary>
<returns>a <see cref="T:GLib.List" /></returns>
<remarks>To be added</remarks>
<remarks>
<para>
You can make a copy of the list using <see cref="M:Gda.Error.ListCopy" />.
</para>
</remarks>
</Docs>
</Member>
<Member MemberName="Options">
@ -353,7 +475,11 @@
</ReturnValue>
<Parameters />
<Docs>
<summary>To be added</summary>
<summary>
<para>
Gets the <see cref="T:Gda.ConnectionOptions" /> used to open this connection.
</para>
</summary>
<returns>a <see cref="T:Gda.ConnectionOptions" /></returns>
<remarks>To be added</remarks>
</Docs>
@ -366,7 +492,11 @@
</ReturnValue>
<Parameters />
<Docs>
<summary>To be added</summary>
<summary>
<para>
Gets the Data Source Name the connection object is connected to.
</para>
</summary>
<returns>a <see cref="T:System.String" /></returns>
<remarks>To be added</remarks>
</Docs>
@ -379,7 +509,11 @@
</ReturnValue>
<Parameters />
<Docs>
<summary>To be added</summary>
<summary>
<para>
Gets the name of the currently active database in the given Gda.Connection.
</para>
</summary>
<returns>a <see cref="T:System.String" /></returns>
<remarks>To be added</remarks>
</Docs>
@ -392,7 +526,11 @@
</ReturnValue>
<Parameters />
<Docs>
<summary>To be added</summary>
<summary>
<para>
Gets the user name used to open this connection.
</para>
</summary>
<returns>a <see cref="T:System.String" /></returns>
<remarks>To be added</remarks>
</Docs>
@ -405,7 +543,13 @@
</ReturnValue>
<Parameters />
<Docs>
<summary>To be added</summary>
<summary>
<para>
Gets the Gda.Client object associated with a connection. This is always the client that created the connection, as returned by <see cref="M:Gda.Client.OpenConnection" /></para>
<para>
Associates a Gda.Client with this connection. This property (setter) is not intended to be called by applications.
</para>
</summary>
<returns>a <see cref="T:Gda.Client" /></returns>
<remarks>To be added</remarks>
</Docs>
@ -418,7 +562,11 @@
</ReturnValue>
<Parameters />
<Docs>
<summary>To be added</summary>
<summary>
<para>
Gets the password used to open this connection.
</para>
</summary>
<returns>a <see cref="T:System.String" /></returns>
<remarks>To be added</remarks>
</Docs>
@ -431,7 +579,11 @@
</ReturnValue>
<Parameters />
<Docs>
<summary>To be added</summary>
<summary>
<para>
Gets the version string of the underlying database server.
</para>
</summary>
<returns>a <see cref="T:System.String" /></returns>
<remarks>To be added</remarks>
</Docs>
@ -444,7 +596,11 @@
</ReturnValue>
<Parameters />
<Docs>
<summary>To be added</summary>
<summary>
<para>
Gets the provider id that this connection is connected to.
</para>
</summary>
<returns>a <see cref="T:System.String" /></returns>
<remarks>To be added</remarks>
</Docs>
@ -469,8 +625,12 @@
</ReturnValue>
<Parameters />
<Docs>
<summary>To be added</summary>
<returns>a <see cref="T:System.Boolean" /></returns>
<summary>
<para>
Checks whether a connection is open or not.
</para>
</summary>
<returns>a <see cref="T:System.Boolean" /> true if the connection is open, false if it's not</returns>
<remarks>To be added</remarks>
</Docs>
</Member>