storage/public/mozIStorageConnection.idl

   1 /* -*- Mode: idl; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* ***** BEGIN LICENSE BLOCK *****
   3  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   4  *
   5  * The contents of this file are subject to the Mozilla Public License Version
   6  * 1.1 (the "License"); you may not use this file except in compliance with
   7  * the License. You may obtain a copy of the License at
   8  * http://www.mozilla.org/MPL/
   9  *
  10  * Software distributed under the License is distributed on an "AS IS" basis,
  11  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  12  * for the specific language governing rights and limitations under the
  13  * License.
  14  *
  15  * The Original Code is Oracle Corporation code.
  16  *
  17  * The Initial Developer of the Original Code is
  18  *  Oracle Corporation
  19  * Portions created by the Initial Developer are Copyright (C) 2004
  20  * the Initial Developer. All Rights Reserved.
  21  *
  22  * Contributor(s):
  23  *   Vladimir Vukicevic <vladimir.vukicevic@oracle.com>
  24  *   Brett Wilson <brettw@gmail.com>
  25  *   Shawn Wilsher <me@shawnwilsher.com>
  26  *   Lev Serebryakov <lev@serebryakov.spb.ru>
  27  *
  28  * Alternatively, the contents of this file may be used under the terms of
  29  * either the GNU General Public License Version 2 or later (the "GPL"), or
  30  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  31  * in which case the provisions of the GPL or the LGPL are applicable instead
  32  * of those above. If you wish to allow use of your version of this file only
  33  * under the terms of either the GPL or the LGPL, and not to allow others to
  34  * use your version of this file under the terms of the MPL, indicate your
  35  * decision by deleting the provisions above and replace them with the notice
  36  * and other provisions required by the GPL or the LGPL. If you do not delete
  37  * the provisions above, a recipient may use your version of this file under
  38  * the terms of any one of the MPL, the GPL or the LGPL.
  39  *
  40  * ***** END LICENSE BLOCK ***** */
  41
  42 #include "nsISupports.idl"
  43
  44 interface mozIStorageAggregateFunction;
  45 interface mozIStorageFunction;
  46 interface mozIStorageProgressHandler;
  47 interface mozIStorageStatement;
  48 interface nsIFile;
  49
  50 /**
  51  * mozIStorageConnection represents a database connection attached to
  52  * a specific file or to the in-memory data storage.  It is the
  53  * primary interface for interacting with a database, including
  54  * creating prepared statements, executing SQL, and examining database
  55  * errors.
  56  */
  57 [scriptable, uuid(623f9ddb-434b-4d39-bc2d-1c617da241d0)]
  58 interface mozIStorageConnection : nsISupports {
  59   /*
  60    * Initialization and status
  61    */
  62
  63   /**
  64    * Closes a database connection.  C++ callers should simply set the database
  65    * variable to NULL.
  66    */
  67    void close();
  68
  69   /**
  70    * Indicates if the connection is open and ready to use.  This will be false
  71    * if the connection failed to open, or it has been closed.
  72    */
  73   readonly attribute boolean connectionReady;
  74
  75   /**
  76    * The current database nsIFile.  Null if the database
  77    * connection refers to an in-memory database.
  78    */
  79   readonly attribute nsIFile databaseFile;
  80
  81   /**
  82    * lastInsertRowID returns the row ID from the last INSERT
  83    * operation.
  84    */
  85   readonly attribute long long lastInsertRowID;
  86
  87   /**
  88    * The last error SQLite error code.
  89    */
  90   readonly attribute long lastError;
  91
  92   /**
  93    * The last SQLite error as a string (in english, straight from the
  94    * sqlite library).
  95    */
  96   readonly attribute AUTF8String lastErrorString;
  97
  98   /**
  99    * The schema version of the database.  This should not be used until the
 100    * database is ready.  The schema will be reported as zero if it is not set.
 101    */
 102   attribute long schemaVersion;
 103
 104   /*
 105    * Statement creation
 106    */
 107
 108   /**
 109    * Create a mozIStorageStatement for the given SQL expression.  The
 110    * expression may use ? to indicate sequential numbered arguments,
 111    * ?1, ?2 etc. to indicate specific numbered arguments or :name and
 112    * $var to indicate named arguments.
 113    *
 114    * @param aSQLStatement  The SQL statement to execute
 115    *
 116    * @returns a new mozIStorageStatement
 117    */
 118   mozIStorageStatement createStatement(in AUTF8String aSQLStatement);
 119
 120   /**
 121    * Execute a SQL expression, expecting no arguments.
 122    *
 123    * @param aSQLStatement  The SQL statement to execute
 124    */
 125   void executeSimpleSQL(in AUTF8String aSQLStatement);
 126
 127   /**
 128    * Check if the given table exists.
 129    *
 130    * @param aTableName   The table to check
 131    * @returns TRUE if table exists, FALSE otherwise.
 132    */
 133   boolean tableExists(in AUTF8String aTableName);
 134
 135   /**
 136    * Check if the given index exists.
 137    *
 138    * @param aIndexName   The index to check
 139    * @returns TRUE if the index exists, FALSE otherwise.
 140    */
 141   boolean indexExists(in AUTF8String aIndexName);
 142
 143
 144   /*
 145    * Transactions
 146    */
 147
 148   /**
 149    * Returns true if a transaction is active on this connection.
 150    */
 151   readonly attribute boolean transactionInProgress;
 152
 153   /**
 154    * Begin a new transaction.  sqlite default transactions are deferred.
 155    * If a transaction is active, throws an error.
 156    */
 157   void beginTransaction();
 158
 159   /**
 160    * Begins a new transaction with the given type.
 161    */
 162   const PRInt32 TRANSACTION_DEFERRED = 0;
 163   const PRInt32 TRANSACTION_IMMEDIATE = 1;
 164   const PRInt32 TRANSACTION_EXCLUSIVE = 2;
 165   void beginTransactionAs(in PRInt32 transactionType);
 166
 167   /**
 168    * Commits the current transaction.  If no transaction is active,
 169    * @throws NS_ERROR_STORAGE_NO_TRANSACTION.
 170    */
 171   void commitTransaction();
 172
 173   /**
 174    * Rolls back the current transaction.  If no transaction is active,
 175    * @throws NS_ERROR_STORAGE_NO_TRANSACTION.
 176    */
 177   void rollbackTransaction();
 178
 179   /*
 180    * Tables
 181    */
 182
 183   /**
 184    * Create the table with the given name and schema.
 185    *
 186    * If the table already exists, NS_ERROR_FAILURE is thrown.
 187    * (XXX at some point in the future it will check if the schema is
 188    * the same as what is specified, but that doesn't happen currently.)
 189    *
 190    * @param aTableName the table name to be created, consisting of
 191    * [A-Za-z0-9_], and beginning with a letter.
 192    *
 193    * @param aTableSchema the schema of the table; what would normally
 194    * go between the parens in a CREATE TABLE statement: e.g., "foo
 195    * INTEGER, bar STRING".
 196    *
 197    * @throws NS_ERROR_FAILURE if the table already exists or could not
 198    * be created for any other reason.
 199    *
 200    */
 201   void createTable(in string aTableName,
 202                    in string aTableSchema);
 203
 204   /*
 205    * Functions
 206    */
 207
 208   /**
 209    * Create a new SQLite function
 210    *
 211    * @param aFunctionName  The name of function to create, as seen in SQL.
 212    * @param aNumArguments  The number of arguments the function takes. Pass
 213    *                       -1 for variable-argument functions.
 214    * @param aFunction      The instance of mozIStorageFunction, which implements
 215    *                       the function in question.
 216    */
 217   void createFunction(in AUTF8String aFunctionName,
 218                       in long aNumArguments,
 219                       in mozIStorageFunction aFunction);
 220
 221   /**
 222    * Create a new SQLite aggregate function
 223    *
 224    * @param aFunctionName  The name of aggregate function to create, as seen
 225    *                       in SQL.
 226    * @param aNumArguments  The number of arguments the function takes. Pass
 227    *                       -1 for variable-argument functions.
 228    * @param aFunction      The instance of mozIStorageAggreagteFunction,
 229    *                       which implements the function in question.
 230    */
 231   void createAggregateFunction(in AUTF8String aFunctionName,
 232                                in long aNumArguments,
 233                                in mozIStorageAggregateFunction aFunction);
 234   /**
 235    * Delete custom SQLite function (simple or aggregate one)
 236    *
 237    * @param aFunctionName  The name of function to remove.
 238    */
 239   void removeFunction(in AUTF8String aFunctionName);
 240
 241   /**
 242    * Sets a progress handler. Only one handler can be registered at a time.
 243    * If you need more than one, you need to chain them yourself.
 244    *
 245    * @param aGranularity   The number of SQL virtual machine steps between
 246    *                       progress handler callbacks.
 247    * @param aHandler       The instance of mozIStorageProgressHandler.
 248    *
 249    * @return previous registered handler.
 250    */
 251   mozIStorageProgressHandler setProgressHandler(in PRInt32 aGranularity,
 252                                                 in mozIStorageProgressHandler aHandler);
 253
 254   /**
 255    * Remove a progress handler.
 256    *
 257    * @return previous registered handler.
 258    */
 259   mozIStorageProgressHandler removeProgressHandler();
 260 };