Bommels05/Mozilla
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Fix for bug 196575. Add comments to IDL interfaces

Browse Source 
r/moa=varga, patch by Neil Deakin <enndeakin@sympatico.ca>


git-svn-id: svn://10.0.0.236/trunk@147362 18797224-902f-48f8-a5cc-f745e15eee43
This commit is contained in:
varga%utcru.sk
2003-09-27 14:42:26 +00:00
parent 8dd5a08649
commit 84058c65d6
8 changed files with 515 additions and 33 deletions
Download Patch File Download Diff File Expand all files Collapse all files

68
mozilla/extensions/sql/base/public/mozISqlConnection.idl
View File

@@ -20,6 +20,7 @@
*
* Contributor(s):
* Jan Varga <varga@utcru.sk>
* Neil Deakin <enndeakin@sympatico.ca>
*
* Alternatively, the contents of this file may be used under the terms of
* either the GNU General Public License Version 2 or later (the "GPL"), or
@@ -42,13 +43,20 @@ interface mozISqlRequest;
interface mozISqlRequestObserver;
/**
* A connection to a SQL database. This interface may be further extended
* by a particular database implementation. The SQL service is responsible
* for creating and maintaining connections, so there isn't a means to create
* one directly via this interface.
*
* @status UNDER_REVIEW
*/
[scriptable, uuid(f16397a4-1ecb-4e08-84f8-27750c04b779)]
interface mozISqlConnection : nsISupports
{
/**
* A string holding the name and/or version info of the database.
*/
readonly attribute AString serverVersion;
/**
@@ -62,13 +70,14 @@ interface mozISqlConnection : nsISupports
readonly attribute long lastID;
/**
* Set up the connection.
* Set up the connection. This is called by the SQL service. There is no
* need to call this method directly.
*
* @param aHost The host name.
* @param aPort The port at which the host is listening.
* @param aDatabase The real database name to connect to.
* @param aUsername The username to connect as.
* @param aPassword The password to use in authentification phase.
* @param aHost the host name.
* @param aPort the port at which the host is listening.
* @param aDatabase the real database name to connect to.
* @param aUsername the username to connect as.
* @param aPassword the password to use in authentification phase.
*/
void init(in AString aHost,
in long aPort,
@@ -77,47 +86,70 @@ interface mozISqlConnection : nsISupports
in AString aPassword);
/**
* Execute the query synchronously and return database result.
* Execute an SQL query synchronously and return the query result.
*
* @param aQuery The query to execute.
* @param aQuery the SQL string of the query to execute
* @return the result of the query
*/
mozISqlResult executeQuery(in AString aQuery);
/**
* Execute the update synchronously and return number of updated rows.
* Execute an SQL update synchronously and return the number of updated
* rows.
*
* @param aUpdate The update to execute.
* @param aUpdate the update to execute
* @return the result of the query
*/
long executeUpdate(in AString aUpdate);
/**
* Execute an SQL query asynchronously and return a request. An observer
* may be used to track when the query has completed.
*
* @param aQuery the SQL string of the query to execute
* @param aContext extra argument that will be passed to the observer
* @param aObserver observer that will be notified when the query is done
* @return a request object
*/
mozISqlRequest asyncExecuteQuery(in AString aQuery,
in nsISupports aContext,
in mozISqlRequestObserver aObserver);
/**
* Execute an SQL update asynchronously and return a request. An observer
* may be used to track when the query has completed.
*
* @param aQuery the SQL string of the update to execute
* @param aContext extra argument that will be passed to the observer
* @param aObserver observer that will be notified when the update is done
* @return a request object
*/
mozISqlRequest asyncExecuteUpdate(in AString aQuery,
in nsISUpports aContext,
in nsISupports aContext,
in mozISqlRequestObserver aObserver);
/**
* Begin transaction.
* Begin a transaction. Updates made during the transaction will not be
* made permanent until it is committed using commitTransaction.
*/
void beginTransaction();
/**
* Commit transaction.
* Commit the current transaction
*/
void commitTransaction();
/**
* Rollback transaction.
* Rollback (cancel) the current transaction
*/
void rollbackTransaction();
/**
* Get primary keys.
* Return the primary keys of a given table.
*
* @param aSchema The schema.
* @param aTable The table name.
* @param aSchema the schema
* @param aTable the table name of the keys to retrieve
* @return the result which holds the keys
*/
mozISqlResult getPrimaryKeys(in AString aSchema, in AString aTable);

2
mozilla/extensions/sql/base/public/mozISqlDataSource.idl
View File

@@ -20,6 +20,7 @@
*
* Contributor(s):
* Jan Varga <varga@utcru.sk>
* Neil Deakin <enndeakin@sympatico.ca>
*
* Alternatively, the contents of this file may be used under the terms of
* either the GNU General Public License Version 2 or later (the "GPL"), or
@@ -52,7 +53,6 @@ interface mozISqlDataSource : nsISupports
*
* @param aRowIndex The row index.
*/
nsIRDFResource getResourceAtIndex(in long aRowIndex);
/**

16
mozilla/extensions/sql/base/public/mozISqlInputStream.idl
View File

@@ -20,6 +20,7 @@
*
* Contributor(s):
* Jan Varga <varga@utcru.sk>
* Neil Deakin <enndeakin@sympatico.ca>
*
* Alternatively, the contents of this file may be used under the terms of
* either the GNU General Public License Version 2 or later (the "GPL"), or
@@ -38,15 +39,28 @@
#include "nsISupports.idl"
/**
* This interface is a utility for reading SQL result contents as a stream.
*
* @status UNDER_DEVELOPMENT
*/
[scriptable, uuid(555f2485-ba82-4c5c-9dd2-d801104dc09e)]
interface mozISqlInputStream : nsISupports
{
/**
* Retrieves the name of a column given its index. Indicies start at zero.
*
* @param aColumnIndex the index of the column to return
* @return the column name
*/
AString getColumnHeader(in long aColumnIndex);
/**
* Sets the name of a column given its index. Indicies start at zero.
*
* @param aColumnIndex the index of the column to change
* @param aLabel the column name
*/
void setColumnHeader(in long aColumnIndex, in AString aLabel);
};

37
mozilla/extensions/sql/base/public/mozISqlRequest.idl
View File

@@ -20,6 +20,7 @@
*
* Contributor(s):
* Jan Varga <varga@utcru.sk>
* Neil Deakin <enndeakin@sympatico.ca>
*
* Alternatively, the contents of this file may be used under the terms of
* either the GNU General Public License Version 2 or later (the "GPL"), or
@@ -42,36 +43,68 @@ interface mozISqlRequestObserver;
interface mozISqlResult;
/**
* A request interface used during an asynchronous SQL query or update operation.
*
* @status UNDER_REVIEW
*/
[scriptable, uuid(f67cb817-5e07-49ff-aacc-5c80585c5031)]
interface mozISqlRequest : nsISupports
{
/**
* The most recent error message.
*/
readonly attribute AString errorMessage;
/**
* The result of the operation.
*/
readonly attribute mozISqlResult result;
/**
* The number of rows that were affected during an update.
*/
readonly attribute long affectedRows;
/**
* The ID of the most recently added record.
*/
readonly attribute long lastID;
/**
* The SQL query
*/
readonly attribute AString query;
/**
* The context passed to the connection's asyncExecuteQuery or
* asyncExecuteUpdate method.
*/
readonly attribute nsISupports ctxt;
/**
* The observer that listens for when the request is finished.
* Methods of the observer should be called by the request.
*/
readonly attribute mozISqlRequestObserver observer;
/**
* Status codes
*/
const long STATUS_NONE = 0;
const long STATUS_EXECUTED = 1;
const long STATUS_COMPLETE = 2;
const long STATUS_ERROR = 3;
const long STATUS_CANCELLED = 4;
/**
* The status of the request.
*/
readonly attribute long status;
/**
* Cancels the operation.
*/
void cancel();
};

18
mozilla/extensions/sql/base/public/mozISqlRequestObserver.idl
View File

@@ -20,6 +20,7 @@
*
* Contributor(s):
* Jan Varga <varga@utcru.sk>
* Neil Deakin <enndeakin@sympatico.ca>
*
* Alternatively, the contents of this file may be used under the terms of
* either the GNU General Public License Version 2 or later (the "GPL"), or
@@ -40,16 +41,31 @@
interface mozISqlRequest;
/**
* This observer interface is used to listen to asynchronous SQL query or
* update requests.
*
* @status UNDER_REVIEW
*/
[scriptable, uuid(9e950bc0-e252-41ef-ac6f-3e3c4acd9dd8)]
interface mozISqlRequestObserver : nsISupports
{
/**
* This method will be called when the request is started.
*
* @param aRequest the request that has started
* @param aContext a context that was supplied in the query/update call
*/
void onStartRequest(in mozISqlRequest aRequest,
in nsISupports aContext);
/**
* This method will be called when the request has finished. This function
* will be called in both success and error cases.
*
* @param aRequest the request that has started
* @param aContext a context that was supplied in the query/update call
*/
void onStopRequest(in mozISqlRequest aRequest,
in nsISupports aContext);

73
mozilla/extensions/sql/base/public/mozISqlResult.idl
View File

@@ -20,6 +20,7 @@
*
* Contributor(s):
* Jan Varga <varga@utcru.sk>
* Neil Deakin <enndeakin@sympatico.ca>
*
* Alternatively, the contents of this file may be used under the terms of
* either the GNU General Public License Version 2 or later (the "GPL"), or
@@ -42,27 +43,61 @@ interface mozISqlResultEnumerator;
interface mozISqlInputStream;
/**
* The result of an SQL query. Use the enumerate method to retrieve each
* row.
*
* @status UNDER_DEVELOPMENT
*/
[scriptable, uuid(08c220b0-7140-456a-89e9-c94609a7392d)]
interface mozISqlResult : nsISupports
{
/**
* The connection used to execute the query
*/
readonly attribute mozISqlConnection connection;
/**
* The SQL query
*/
readonly attribute AString query;
/**
* The table that was used in the query. If more than one table was used,
* only the first is returned.
*/
readonly attribute AString tableName;
/**
* The number of rows in the result
*/
readonly attribute long rowCount;
/**
* The number of columns in the result
*/
readonly attribute long columnCount;
/**
* Retrieves the name of a column given its index. Indicies start at zero.
*
* @param aColumnIndex the index of the column to return
* @return the column name
*/
AString getColumnName(in long aColumnIndex);
/**
* Retrieves the index of a column given its name. If the column does not
* exist, -1 is returned.
*
* @param aColumnName the column name to return
* @return the column index
*/
long getColumnIndex(in AString aColumnName);
/**
* column type constants used by |getColumnType|.
*/
const long TYPE_STRING = 1;
const long TYPE_INT = 2;
const long TYPE_FLOAT = 3;
@@ -71,17 +106,51 @@ interface mozISqlResult : nsISupports
const long TYPE_TIME = 6;
const long TYPE_DATETIME = 7;
const long TYPE_BOOL = 8;
/**
* Returns the type of the data in a given column.
*
* @param aColumnIndex the index of the column to return the type of
* @return the column type
*/
long getColumnType(in long aColumnIndex);
/**
* Returns the type of the data in a given column as a string. This is used
* as an alternative to using the constants and will return either
* string, int, float, decimal, date, time, datetime or bool.
*
* @param aColumnIndex the index of the column to return the type of
* @return the column type
*/
AString getColumnTypeAsString(in long aColumnIndex);
/**
* Returns the maximum number of bytes that are needed to hold a value in a
* particular column.
*
* @param aColumnIndex the index of the column to return the size of
* @return the column size
*/
long getColumnDisplaySize(in long aColumnIndex);
/**
* Returns an enumerator to enumerator over the returned rows.
*
* @return the row enumerator
*/
mozISqlResultEnumerator enumerate();
/**
* Returns a stream which may be used to return the rows as HTML.
*
* @return the input stream
*/
mozISqlInputStream open();
/**
* Re-executes the query.
*/
void reload();
};

241
mozilla/extensions/sql/base/public/mozISqlResultEnumerator.idl
View File

@@ -20,6 +20,7 @@
*
* Contributor(s):
* Jan Varga <varga@utcru.sk>
* Neil Deakin <enndeakin@sympatico.ca>
*
* Alternatively, the contents of this file may be used under the terms of
* either the GNU General Public License Version 2 or later (the "GPL"), or
@@ -40,87 +41,325 @@
interface nsIVariant;
/**
* This interface is used to get the results from an SQL query.
* The enumerator uses a row pointer which can be adjusted with
* the next and previous methods. Other methods operate only on
* the row selected by the pointer.
*
* The row pointer starts just before the first row, so you should
* always call the next method once before attempting to read row
* data.
*
* @status UNDER_DEVELOPMENT
*/
[scriptable, uuid(dcc0d29e-2b44-460e-b39f-89121ff8b963)]
interface mozISqlResultEnumerator : nsISupports
{
/**
* The most recent error message.
*/
readonly attribute AString errorMessage;
/**
* Moves the row pointer to the next row in the results.
* Returns true if there is a next row and false if there are
* no more rows.
*
* @return false if there are no more rows
*/
boolean next();
/**
* Moves the row pointer to the previous row in the results.
* Returns true if there is a previous row.
*
* @return false if there are no previous rows
*/
boolean previous();
/**
* Moves the row pointer to just before the first row.
*/
void beforeFirst();
/**
* Moves the row pointer to the first row.
*/
void first();
/**
* Moves the row pointer to the last row.
*/
void last();
/**
* Moves the row pointer by a number relative to the current row.
* An error occurs if this causes the row pointer to extend past
* the last row. This method may also be used to move the row pointer
* back by using a negative value.
*
* @param aRowIndex aRowIndex the number of rows to move by
*/
void relative(in long aRows);
/**
* Moves the row pointer to a specific row. An error occurs if the index
* is after the last row.
*
* @param aRowIndex the index of the row to move to
*/
void absolute(in long aRowIndex);
/**
* Returns true if the value at the specified column in the current row
* is null.
*
* @param aColumnIndex the column to retrieve
* @return true if the value is null
*/
boolean isNull(in long aColumnIndex);
/**
* Returns the value at the specified column in the current row as a variant.
*
* @param aColumnIndex the column to retrieve
* @return the value as a variant
*/
nsIVariant getVariant(in long aColumnIndex);
/**
* Returns the value at the specified column in the current row as a string.
* An error occurs if the value is not a string type.
*
* @param aColumnIndex the column to retrieve
* @return the string value
*/
AString getString(in long aColumnIndex);
/**
* Returns the value at the specified column in the current row as an
* integer. An error occurs if the value is not a integer type.
*
* @param aColumnIndex the column to retrieve
* @return the integer value
*/
long getInt(in long aColumnIndex);
/**
* Returns the value at the specified column in the current row as a
* float. An error occurs if the value is not a float type.
*
* @param aColumnIndex the column to retrieve
* @return the float value
*/
float getFloat(in long aColumnIndex);
/**
* Returns the value at the specified column in the current row as a
* decimal. An error occurs if the value is not a decimal type.
*
* @param aColumnIndex the column to retrieve
* @return the decimal value
*/
float getDecimal(in long aColumnIndex);
/**
* Returns the value at the specified column in the current row as a date.
* An error occurs if the value is not a date type.
*
* @param aColumnIndex the column to retrieve
* @return the date value
*/
long long getDate(in long aColumnIndex);
/**
* Returns the value at the specified column in the current row as a
* boolean. An error occurs if the value is not a boolean type.
*
* @param aColumnIndex the column to retrieve
* @return the boolean value
*/
boolean getBool(in long aColumnIndex);
/**
* Sets the value at the specified column in the current row to null.
* Changes are not committed until either the insertRow or updateRow method
* is called.
*
* @param aColumnIndex the column to modify
*/
void setNull(in long aColumnIndex);
/**
* Sets the value at the specified column in the current row to the
* default value for that column. Changes are not committed until either the
* insertRow or updateRow method is called.
*
* @param aColumnIndex the column to modify
*/
void setDefault(in long aColumnIndex);
/**
* Sets the value at the specified column in the current row to its original
* value. The row may be changed with the various setX methods and then
* commited with updateRow.
*
* @param aColumnIndex the column to modify
*/
void copy(in long aColumnIndex);
/**
* Sets the value at the specified column in the current row to a variant.
* Changes are not committed until either the insertRow or updateRow method
* is called.
*
* @param aColumnIndex the column to modify
* @param aValue the value to assign
*/
void setVariant(in long aColumnIndex, in nsIVariant aValue);
/**
* Sets the value at the specified column in the current row to a string.
* Changes are not committed until either the insertRow or updateRow method
* is called.
*
* @param aColumnIndex the column to modify
* @param aValue the value to assign
*/
void setString(in long aColumnIndex, in AString aValue);
/**
* Sets the value at the specified column in the current row to an integer.
* Changes are not committed until either the insertRow or updateRow method
* is called.
*
* @param aColumnIndex the column to modify
* @param aValue the value to assign
*/
void setInt(in long aColumnIndex, in long aValue);
/**
* Sets the value at the specified column in the current row to a float.
* Changes are not committed until either the insertRow or updateRow method
* is called.
*
* @param aColumnIndex the column to modify
* @param aValue the value to assign
*/
void setFloat(in long aColumnIndex, in float aValue);
/**
* Sets the value at the specified column in the current row to a decimal.
* Changes are not committed until either the insertRow or updateRow method
* is called.
*
* @param aColumnIndex the column to modify
* @param aValue the value to assign
*/
void setDecimal(in long aColumnIndex, in float aValue);
/**
* Sets the value at the specified column in the current row to a date.
* Changes are not committed until either the insertRow or updateRow method
* is called.
*
* @param aColumnIndex the column to modify
* @param aValue the value to assign
*/
void setDate(in long aColumnIndex, in long long aValue);
/**
* Sets the value at the specified column in the current row to a boolean.
* Changes are not committed until either the insertRow or updateRow method
* is called.
*
* @param aColumnIndex the column to modify
* @param aValue the value to assign
*/
void setBool(in long aColumnIndex, in boolean aValue);
/**
* Sets the value of the cells in all columns in the current row to null.
* This is equivalent to calling setNullValue for every column.
*/
void setNullValues();
/**
* Sets the value of the cells in all columns in the current row to the
* default values for the columns. This is equivalent to calling
* setDefaultValue for every column.
*/
void setDefaultValues();
/**
* Sets the values of all of the cells in the current row to their original
* values. The row may be changed with the various set methods and then
* commited with updateRow. This method is equivalent to calling the copy
* method for each column.
*/
void copyValues();
/**
* Returns true if inserts are allowed.
*
* @return true if inserts are allowed
*/
boolean canInsert();
/**
* Returns true if updates are allowed.
*
* @return true if updates are allowed
*/
boolean canUpdate();
/**
* Returns true if deletes are allowed.
*
* @return true if deletes are allowed
*/
boolean canDelete();
/**
* Inserts a row using the data assigned using the various setX methods.
* The row was inserted successfully if 0 or 1 is returned, however if 0
* is returned, the row does not satisfy the where condition of the result
* (that is, it doesn't belong in the result enumerator) and does not need
* to be displayed.
*
* @return 1 if the row was inserted, 0 if the row was
* inserted but does not fit the condition, or -1
* if an error occured.
*/
long insertRow();
/**
* Updates the current row using the data assigned using the various setX
* methods. The row was inserted successfully if 0 or 1 is returned, however
* if 0 is returned, the row does not satisfy the where condition of the
* result and does not need to be displayed.
*
* @return 1 if the row was updated, 0 if the row was updated
* but does not fit the condition, or -1 if an error
* occured.
*/
long updateRow();
/**
* Deletes the current row.
*
* @return 1 if the row was deleted or -1 if an error occured.
*/
long deleteRow();
/**
* Holds the SQL condition clause.
*/
readonly attribute AString currentCondition;
};

93
mozilla/extensions/sql/base/public/mozISqlService.idl
View File

@@ -20,6 +20,7 @@
*
* Contributor(s):
* Jan Varga <varga@utcru.sk>
* Neil Deakin <enndeakin@sympatico.ca>
*
* Alternatively, the contents of this file may be used under the terms of
* either the GNU General Public License Version 2 or later (the "GPL"), or
@@ -41,21 +42,62 @@ interface nsIRDFResource;
interface mozISqlConnection;
/**
* The SQL service is used to construct direct connections to SQL-based
* databases. The service maintains a set of aliases, one for each database
* to connect to. Methods are provided for adding, retrieving and removing
* aliases. Once an alias has been added, it is persistent, so it does not need
* to be added again. The aliases are stored in user preferences.
* Aliases are identfied using an RDF resource.
*
* Once an alias has been added, a connection may be opened to a database using
* the RDF resource.
*
* @status UNDER_DEVELOPMENT
*/
[scriptable, uuid(1ceb35b7-daa8-4ce4-ac67-125fb17cb019)]
interface mozISqlService : nsISupports
{
/**
* Holds the string message of the last error that occured when a connection
* was opened.
*/
readonly attribute AString errorMessage;
nsIRDFResource addAlias(in AString aName,
in AString aType,
in AString aHostname,
in long aPort,
in AString aDatabase);
/**
* Add an alias for a database connection. An alias must be added before a
* connection can be made.
*
* Different types of databases may be connected to using the |aType|
* argument. For instance 'pgsql' or 'mysql'. When a connection is made, a
* component of the form '@mozilla.org/sql/connection;1?type=<type>' will be
* looked up using the component manager. This allows additional database
* implementations to be provided separately of mozSQL.
*
* @param aName human-readable name of the alias
* @param aType database type (such as pgsql)
* @param aHostname hostname for the database
* @param aPort port for the database
* @param aDatabase database name
* @return an RDF resource representing the alias
*/
nsIRDFResource addAlias(in AString aName,
in AString aType,
in AString aHostname,
in long aPort,
in AString aDatabase);
/**
* Retrieves alias information. The out parameters are filled in with
* the corresponding information.
*
* @param aAlias the alias to retrieve
* @param aName human-readable name of the alias
* @param aType database type
* @param aHostname hostname of the database
* @param aPort port of the database
* @param aDatabase database name
*/
void fetchAlias(in nsIRDFResource aAlias,
out AString aName,
out AString aType,
@@ -63,6 +105,18 @@ interface mozISqlService : nsISupports
out long aPort,
out AString aDatabase);
/**
* Update the information of an alias that has already been added. The new
* information replaces the old information.
*
*
* @param aAlias the alias to update
* @param aName human-readable name of the alias
* @param aType database type (such as pgsql)
* @param aHostname hostname for the database
* @param aPort port for the database
* @param aDatabase database name
*/
void updateAlias(in nsIRDFResource aAlias,
in AString aName,
in AString aType,
@@ -70,12 +124,37 @@ interface mozISqlService : nsISupports
in long aPort,
in AString aDatabase);
/**
* Removes an alias that already exists.
*
* @param aAlias the alias to remove
*/
void removeAlias(in nsIRDFResource aAlias);
/**
* Get the alias resource with the given name.
*
* @param aName the name of the alias to retrieve
* @return the RDF resource for the alias, or null if it doesn't exist.
*/
nsIRDFResource getAlias(in AString aName);
/**
* Retrieves an SQL connection to a database given its alias. If a
* connection is already open, that connection is returned. Otherwise,
* a new connection is opened and returned.
*
* @param aAlias the alias to use to open a connection
* @return a connection
*/
mozISqlConnection getConnection(in nsIRDFResource aAlias);
/**
* Opens and returns a new connection to a database. The user will be
* prompted for a username and password.
*
* @param aAlias the alias to use to open a connection
* @return a newly opened connection
*/
mozISqlConnection getNewConnection(in nsIRDFResource aAlias);
};