GtkSharp/doc/en/Gda/Connection.xml
Miguel de Icaza 17aebcd550 Apply patch from wizito@gentelibre.org
svn path=/trunk/gtk-sharp/; revision=31100
2004-07-13 18:56:58 +00:00

680 lines
25 KiB
XML

<Type Name="Connection" FullName="Gda.Connection">
<TypeSignature Language="C#" Value="public class Connection : GLib.Object, IWrapper, IDisposable" Maintainer="auto" />
<AssemblyInfo>
<AssemblyName>gda-sharp</AssemblyName>
<AssemblyPublicKey>
</AssemblyPublicKey>
<AssemblyVersion>0.0.0.0</AssemblyVersion>
<AssemblyCulture>neutral</AssemblyCulture>
<Attributes />
</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>
<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>
</Base>
<Interfaces>
<Interface>
<InterfaceName>GLib.IWrapper</InterfaceName>
</Interface>
<Interface>
<InterfaceName>System.IDisposable</InterfaceName>
</Interface>
</Interfaces>
<Attributes />
<Members>
<Member MemberName="Finalize">
<MemberSignature Language="C#" Value="protected override void Finalize ();" />
<MemberType>Method</MemberType>
<ReturnValue>
<ReturnType>System.Void</ReturnType>
</ReturnValue>
<Parameters />
<Docs>
<summary>To be added</summary>
<remarks>To be added</remarks>
</Docs>
</Member>
<Member MemberName="RollbackTransaction">
<MemberSignature Language="C#" Value="public bool RollbackTransaction (Gda.Transaction xaction);" />
<MemberType>Method</MemberType>
<ReturnValue>
<ReturnType>System.Boolean</ReturnType>
</ReturnValue>
<Parameters>
<Parameter Name="xaction" Type="Gda.Transaction" />
</Parameters>
<Docs>
<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" /> 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">
<MemberSignature Language="C#" Value="public bool BeginTransaction (Gda.Transaction xaction);" />
<MemberType>Method</MemberType>
<ReturnValue>
<ReturnType>System.Boolean</ReturnType>
</ReturnValue>
<Parameters>
<Parameter Name="xaction" Type="Gda.Transaction" />
</Parameters>
<Docs>
<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" /> 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">
<MemberSignature Language="C#" Value="public int ExecuteNonQuery (Gda.Command cmd, Gda.ParameterList parms);" />
<MemberType>Method</MemberType>
<ReturnValue>
<ReturnType>System.Int32</ReturnType>
</ReturnValue>
<Parameters>
<Parameter Name="cmd" Type="Gda.Command" />
<Parameter Name="parms" Type="Gda.ParameterList" />
</Parameters>
<Docs>
<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" /> the numer of affected rows by the executed command, or -1 on error</returns>
<remarks>To be added</remarks>
</Docs>
</Member>
<Member MemberName="ChangeDatabase">
<MemberSignature Language="C#" Value="public bool ChangeDatabase (string name);" />
<MemberType>Method</MemberType>
<ReturnValue>
<ReturnType>System.Boolean</ReturnType>
</ReturnValue>
<Parameters>
<Parameter Name="name" Type="System.String" />
</Parameters>
<Docs>
<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" /> true if successful, false otherwise</returns>
<remarks>To be added</remarks>
</Docs>
</Member>
<Member MemberName="DropDatabase">
<MemberSignature Language="C#" Value="public bool DropDatabase (string name);" />
<MemberType>Method</MemberType>
<ReturnValue>
<ReturnType>System.Boolean</ReturnType>
</ReturnValue>
<Parameters>
<Parameter Name="name" Type="System.String" />
</Parameters>
<Docs>
<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" /> true if successful, false otherwise</returns>
<remarks>To be added</remarks>
</Docs>
</Member>
<Member MemberName="AddErrorList">
<MemberSignature Language="C#" Value="public void AddErrorList (GLib.List error_list);" />
<MemberType>Method</MemberType>
<ReturnValue>
<ReturnType>System.Void</ReturnType>
</ReturnValue>
<Parameters>
<Parameter Name="error_list" Type="GLib.List" />
</Parameters>
<Docs>
<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>
<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">
<MemberSignature Language="C#" Value="public bool CommitTransaction (Gda.Transaction xaction);" />
<MemberType>Method</MemberType>
<ReturnValue>
<ReturnType>System.Boolean</ReturnType>
</ReturnValue>
<Parameters>
<Parameter Name="xaction" Type="Gda.Transaction" />
</Parameters>
<Docs>
<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" /> 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">
<MemberSignature Language="C#" Value="public void AddError (Gda.Error error);" />
<MemberType>Method</MemberType>
<ReturnValue>
<ReturnType>System.Void</ReturnType>
</ReturnValue>
<Parameters>
<Parameter Name="error" Type="Gda.Error" />
</Parameters>
<Docs>
<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>
<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">
<MemberSignature Language="C#" Value="public bool CreateDatabase (string name);" />
<MemberType>Method</MemberType>
<ReturnValue>
<ReturnType>System.Boolean</ReturnType>
</ReturnValue>
<Parameters>
<Parameter Name="name" Type="System.String" />
</Parameters>
<Docs>
<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" /> true if successful, false otherwise</returns>
<remarks>To be added</remarks>
</Docs>
</Member>
<Member MemberName="Supports">
<MemberSignature Language="C#" Value="public bool Supports (Gda.ConnectionFeature feature);" />
<MemberType>Method</MemberType>
<ReturnValue>
<ReturnType>System.Boolean</ReturnType>
</ReturnValue>
<Parameters>
<Parameter Name="feature" Type="Gda.ConnectionFeature" />
</Parameters>
<Docs>
<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" /> true if the provider supports it, false if not</returns>
<remarks>To be added</remarks>
</Docs>
</Member>
<Member MemberName="ExecuteSingleCommand">
<MemberSignature Language="C#" Value="public Gda.DataModel ExecuteSingleCommand (Gda.Command cmd, Gda.ParameterList parms);" />
<MemberType>Method</MemberType>
<ReturnValue>
<ReturnType>Gda.DataModel</ReturnType>
</ReturnValue>
<Parameters>
<Parameter Name="cmd" Type="Gda.Command" />
<Parameter Name="parms" Type="Gda.ParameterList" />
</Parameters>
<Docs>
<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>
<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">
<MemberSignature Language="C#" Value="public bool Close ();" />
<MemberType>Method</MemberType>
<ReturnValue>
<ReturnType>System.Boolean</ReturnType>
</ReturnValue>
<Parameters />
<Docs>
<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>
<Member MemberName="ExecuteCommand">
<MemberSignature Language="C#" Value="public GLib.List ExecuteCommand (Gda.Command cmd, Gda.ParameterList parms);" />
<MemberType>Method</MemberType>
<ReturnValue>
<ReturnType>GLib.List</ReturnType>
</ReturnValue>
<Parameters>
<Parameter Name="cmd" Type="Gda.Command" />
<Parameter Name="parms" Type="Gda.ParameterList" />
</Parameters>
<Docs>
<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" /> 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">
<MemberSignature Language="C#" Value="public Gda.DataModel GetSchema (Gda.ConnectionSchema schema, Gda.ParameterList parms);" />
<MemberType>Method</MemberType>
<ReturnValue>
<ReturnType>Gda.DataModel</ReturnType>
</ReturnValue>
<Parameters>
<Parameter Name="schema" Type="Gda.ConnectionSchema" />
<Parameter Name="parms" Type="Gda.ParameterList" />
</Parameters>
<Docs>
<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" /> 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">
<MemberSignature Language="C#" Value="public bool CreateBlob (Gda.Blob blob);" />
<MemberType>Method</MemberType>
<ReturnValue>
<ReturnType>System.Boolean</ReturnType>
</ReturnValue>
<Parameters>
<Parameter Name="blob" Type="Gda.Blob" />
</Parameters>
<Docs>
<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" /> 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>
<Member MemberName=".ctor">
<MemberSignature Language="C#" Value="public Connection (IntPtr raw);" />
<MemberType>Constructor</MemberType>
<ReturnValue />
<Parameters>
<Parameter Name="raw" Type="System.IntPtr" />
</Parameters>
<Docs>
<summary>To be added</summary>
<param name="raw">a <see cref="T:System.IntPtr" /></param>
<returns>a <see cref="T:Gda.Connection" /></returns>
<remarks>To be added</remarks>
</Docs>
</Member>
<Member MemberName=".ctor">
<MemberSignature Language="C#" Value="public Connection (Gda.Client client, Gda.ServerProvider provider, string dsn, string username, string password, Gda.ConnectionOptions options);" />
<MemberType>Constructor</MemberType>
<ReturnValue />
<Parameters>
<Parameter Name="client" Type="Gda.Client" />
<Parameter Name="provider" Type="Gda.ServerProvider" />
<Parameter Name="dsn" Type="System.String" />
<Parameter Name="username" Type="System.String" />
<Parameter Name="password" Type="System.String" />
<Parameter Name="options" Type="Gda.ConnectionOptions" />
</Parameters>
<Docs>
<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>
<param name="username">a <see cref="T:System.String" /></param>
<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>
<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">
<MemberSignature Language="C#" Value="public string CncString { get; };" />
<MemberType>Property</MemberType>
<ReturnValue>
<ReturnType>System.String</ReturnType>
</ReturnValue>
<Parameters />
<Docs>
<summary>
<para>
Gets the connection string used to open this connection.
</para>
</summary>
<returns>a <see cref="T:System.String" /></returns>
<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">
<MemberSignature Language="C#" Value="public GLib.List Errors { get; };" />
<MemberType>Property</MemberType>
<ReturnValue>
<ReturnType>GLib.List</ReturnType>
</ReturnValue>
<Parameters />
<Docs>
<summary>
<para>
Retrieves a list of the last errors ocurred in the connection.
</para>
</summary>
<returns>a <see cref="T:GLib.List" /></returns>
<remarks>
<para>
You can make a copy of the list using <see cref="M:Gda.Error.ListCopy" />.
</para>
</remarks>
</Docs>
</Member>
<Member MemberName="Options">
<MemberSignature Language="C#" Value="public Gda.ConnectionOptions Options { get; };" />
<MemberType>Property</MemberType>
<ReturnValue>
<ReturnType>Gda.ConnectionOptions</ReturnType>
</ReturnValue>
<Parameters />
<Docs>
<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>
</Member>
<Member MemberName="Dsn">
<MemberSignature Language="C#" Value="public string Dsn { get; };" />
<MemberType>Property</MemberType>
<ReturnValue>
<ReturnType>System.String</ReturnType>
</ReturnValue>
<Parameters />
<Docs>
<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>
</Member>
<Member MemberName="Database">
<MemberSignature Language="C#" Value="public string Database { get; };" />
<MemberType>Property</MemberType>
<ReturnValue>
<ReturnType>System.String</ReturnType>
</ReturnValue>
<Parameters />
<Docs>
<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>
</Member>
<Member MemberName="Username">
<MemberSignature Language="C#" Value="public string Username { get; };" />
<MemberType>Property</MemberType>
<ReturnValue>
<ReturnType>System.String</ReturnType>
</ReturnValue>
<Parameters />
<Docs>
<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>
</Member>
<Member MemberName="Client">
<MemberSignature Language="C#" Value="public Gda.Client Client { set; get; };" />
<MemberType>Property</MemberType>
<ReturnValue>
<ReturnType>Gda.Client</ReturnType>
</ReturnValue>
<Parameters />
<Docs>
<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>
</Member>
<Member MemberName="Password">
<MemberSignature Language="C#" Value="public string Password { get; };" />
<MemberType>Property</MemberType>
<ReturnValue>
<ReturnType>System.String</ReturnType>
</ReturnValue>
<Parameters />
<Docs>
<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>
</Member>
<Member MemberName="ServerVersion">
<MemberSignature Language="C#" Value="public string ServerVersion { get; };" />
<MemberType>Property</MemberType>
<ReturnValue>
<ReturnType>System.String</ReturnType>
</ReturnValue>
<Parameters />
<Docs>
<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>
</Member>
<Member MemberName="Provider">
<MemberSignature Language="C#" Value="public string Provider { get; };" />
<MemberType>Property</MemberType>
<ReturnValue>
<ReturnType>System.String</ReturnType>
</ReturnValue>
<Parameters />
<Docs>
<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>
</Member>
<Member MemberName="Error">
<MemberSignature Language="C#" Value="public event Gda.ErrorHandler Error;" />
<MemberType>Event</MemberType>
<ReturnValue>
<ReturnType>Gda.ErrorHandler</ReturnType>
</ReturnValue>
<Parameters />
<Docs>
<summary>To be added</summary>
<remarks>To be added</remarks>
</Docs>
</Member>
<Member MemberName="IsOpen">
<MemberSignature Language="C#" Value="public bool IsOpen { get; };" />
<MemberType>Property</MemberType>
<ReturnValue>
<ReturnType>System.Boolean</ReturnType>
</ReturnValue>
<Parameters />
<Docs>
<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>
<Member MemberName="GType">
<MemberSignature Language="C#" Value="public static GLib.GType GType { get; };" />
<MemberType>Property</MemberType>
<ReturnValue>
<ReturnType>GLib.GType</ReturnType>
</ReturnValue>
<Parameters />
<Docs>
<summary>GType Property.</summary>
<returns>a <see cref="T:GLib.GType" /></returns>
<remarks>Returns the native <see cref="T:GLib.GType" /> value for <see cref="T:Gda.Connection" />.</remarks>
</Docs>
</Member>
<Member MemberName="OnError">
<MemberSignature Language="C#" Value="protected virtual void OnError (GLib.List error_list);" />
<MemberType>Method</MemberType>
<ReturnValue>
<ReturnType>System.Void</ReturnType>
</ReturnValue>
<Parameters>
<Parameter Name="error_list" Type="GLib.List" />
</Parameters>
<Docs>
<summary>Default handler for the <see cref="M:Gda.Connection.Error" /> event.</summary>
<param name="error_list">a <see cref="T:GLib.List" /></param>
<remarks>Override this method in a subclass to provide a default handler for the <see cref="M:Gda.Connection.Error" /> event.</remarks>
</Docs>
</Member>
<Member MemberName=".ctor">
<MemberSignature Language="C#" Value="protected Connection (GLib.GType gtype);" />
<MemberType>Constructor</MemberType>
<ReturnValue />
<Parameters>
<Parameter Name="gtype" Type="GLib.GType" />
</Parameters>
<Docs>
<summary>Protected Constructor.</summary>
<param name="gtype">a <see cref="T:GLib.GType" /></param>
<returns>a <see cref="T:Gda.Connection" /></returns>
<remarks>Chain to this constructor if you have manually registered a native <see cref="T:GLib.GType" /> value for your subclass.</remarks>
</Docs>
</Member>
</Members>
</Type>