RetroZilla/extensions/sql/base/public/mozISqlService.idl

174 lines
6.3 KiB
Plaintext
Raw Normal View History

2015-10-21 05:03:22 +02:00
/* ***** BEGIN LICENSE BLOCK *****
* Version: MPL 1.1/GPL 2.0/LGPL 2.1
*
* The contents of this file are subject to the Mozilla Public License Version
* 1.1 (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
* http://www.mozilla.org/MPL/
*
* Software distributed under the License is distributed on an "AS IS" basis,
* WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
* for the specific language governing rights and limitations under the
* License.
*
* The Original Code is mozilla.org code.
*
* The Initial Developer of the Original Code is Jan Varga
* Portions created by the Initial Developer are Copyright (C) 2003
* the Initial Developer. All Rights Reserved.
*
* Contributor(s):
* 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
* the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
* in which case the provisions of the GPL or the LGPL are applicable instead
* of those above. If you wish to allow use of your version of this file only
* under the terms of either the GPL or the LGPL, and not to allow others to
* use your version of this file under the terms of the MPL, indicate your
* decision by deleting the provisions above and replace them with the notice
* and other provisions required by the GPL or the LGPL. If you do not delete
* the provisions above, a recipient may use your version of this file under
* the terms of any one of the MPL, the GPL or the LGPL.
*
* ***** END LICENSE BLOCK ***** */
#include "nsISupports.idl"
interface nsIRDFResource;
interface nsISimpleEnumerator;
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;
/**
* 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
* @param aPriority priority
* @return an RDF resource representing the alias
*/
nsIRDFResource addAlias(in AString aName,
in AString aType,
in AString aHostname,
in long aPort,
in AString aDatabase,
in long aPriority);
/**
* 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
* @param aPriority priority
*/
void fetchAlias(in nsIRDFResource aAlias,
out AString aName,
out AString aType,
out AString aHostname,
out long aPort,
out AString aDatabase,
out long aPriority);
/**
* 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
* @param aPriority priority
*/
void updateAlias(in nsIRDFResource aAlias,
in AString aName,
in AString aType,
in AString aHostname,
in long aPort,
in AString aDatabase,
in long aPriority);
/**
* 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);
/**
* Get the aliases with the given name.
*
* @param aName the name of the aliases to retrieve
* @return an enumerator for the aliases
*/
nsISimpleEnumerator getAliases(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);
};