storage/mozIStorageConnection.idl

   1 /* -*- Mode: idl; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 #include "nsISupports.idl"
   7 #include "mozIStorageAsyncConnection.idl"
   8
   9 %{C++
  10 namespace mozilla::dom::quota {
  11 class QuotaObject;
  12 }
  13
  14 namespace mozilla::storage {
  15 class SQLiteMutex;
  16 class SQLiteMutexAutoLock;
  17 }
  18
  19 %}
  20
  21 [ptr] native QuotaObject(mozilla::dom::quota::QuotaObject);
  22 native SQLiteMutex(mozilla::storage::SQLiteMutex&);
  23 native SQLiteMutexAutoLock(const mozilla::storage::SQLiteMutexAutoLock&);
  24
  25 interface mozIStorageAggregateFunction;
  26 interface mozIStorageCompletionCallback;
  27 interface mozIStorageFunction;
  28 interface mozIStorageProgressHandler;
  29 interface mozIStorageBaseStatement;
  30 interface mozIStorageStatement;
  31 interface mozIStorageAsyncStatement;
  32 interface mozIStorageStatementCallback;
  33 interface mozIStoragePendingStatement;
  34 interface nsIFile;
  35
  36 /**
  37  * mozIStorageConnection represents a database connection attached to
  38  * a specific file or to the in-memory data storage.  It is the
  39  * primary interface for interacting with a database, including
  40  * creating prepared statements, executing SQL, and examining database
  41  * errors.
  42  *
  43  * @note From the main thread, you should rather use mozIStorageAsyncConnection.
  44  *
  45  * @threadsafe
  46  */
  47 [scriptable, builtinclass, uuid(4aa2ac47-8d24-4004-9b31-ec0bd85f0cc3)]
  48 interface mozIStorageConnection : mozIStorageAsyncConnection {
  49   /**
  50    * Closes a database connection.  Callers must finalize all statements created
  51    * for this connection prior to calling this method.  It is illegal to use
  52    * call this method if any asynchronous statements have been executed on this
  53    * connection.
  54    *
  55    * @throws NS_ERROR_UNEXPECTED
  56    *         If any statement has been executed asynchronously on this object.
  57    * @throws NS_ERROR_UNEXPECTED
  58    *         If is called on a thread other than the one that opened it.
  59    */
  60   void close();
  61
  62   /**
  63    * Clones a database connection and makes the clone read only if needed.
  64    * SQL Functions and attached on-disk databases are applied to the new clone.
  65    *
  66    * @param aReadOnly
  67    *        If true, the returned database should be put into read-only mode.
  68    *        Defaults to false.
  69    * @return the cloned database connection.
  70    *
  71    * @throws NS_ERROR_UNEXPECTED
  72    *         If this connection is a memory database.
  73    * @note If your connection is already read-only, you will get a read-only
  74    *       clone.
  75    * @note Due to a bug in SQLite, if you use the shared cache (openDatabase),
  76    *       you end up with the same privileges as the first connection opened
  77    *       regardless of what is specified in aReadOnly.
  78    * @note The following pragmas are copied over to a read-only clone:
  79    *        - cache_size
  80    *        - temp_store
  81    *       The following pragmas are copied over to a writeable clone:
  82    *        - cache_size
  83    *        - temp_store
  84    *        - foreign_keys
  85    *        - journal_size_limit
  86    *        - synchronous
  87    *        - wal_autocheckpoint
  88    *       All SQL functions are copied over to read-only and writeable clones.
  89    *       Additionally, all temporary tables, triggers, and views, as well as
  90    *       any indexes on temporary tables, are copied over to writeable clones.
  91    *       For temporary tables, only the schemas are copied, not their
  92    *       contents.
  93    *
  94    */
  95   mozIStorageConnection clone([optional] in boolean aReadOnly);
  96
  97   /**
  98    * The default size for SQLite database pages used by mozStorage for new
  99    * databases.
 100    */
 101   readonly attribute long defaultPageSize;
 102
 103   /**
 104    * Indicates if the connection is open and ready to use.  This will be false
 105    * if the connection failed to open, or it has been closed.
 106    */
 107   readonly attribute boolean connectionReady;
 108
 109   /**
 110    * lastInsertRowID returns the row ID from the last INSERT
 111    * operation.
 112    */
 113   readonly attribute long long lastInsertRowID;
 114
 115   /**
 116    * affectedRows returns the number of database rows that were changed or
 117    * inserted or deleted by last operation.
 118    */
 119   readonly attribute long affectedRows;
 120
 121   /**
 122    * The last error SQLite error code.
 123    */
 124   readonly attribute long lastError;
 125
 126   /**
 127    * The last SQLite error as a string (in english, straight from the
 128    * sqlite library).
 129    */
 130   readonly attribute AUTF8String lastErrorString;
 131
 132   /**
 133    * The schema version of the database.  This should not be used until the
 134    * database is ready.  The schema will be reported as zero if it is not set.
 135    */
 136   attribute long schemaVersion;
 137
 138   //////////////////////////////////////////////////////////////////////////////
 139   //// Statement creation
 140
 141   /**
 142    * Create a mozIStorageStatement for the given SQL expression.  The
 143    * expression may use ? to indicate sequential numbered arguments,
 144    * ?1, ?2 etc. to indicate specific numbered arguments or :name and
 145    * $var to indicate named arguments.
 146    *
 147    * @param aSQLStatement
 148    *        The SQL statement to execute.
 149    * @return a new mozIStorageStatement
 150    */
 151   mozIStorageStatement createStatement(in AUTF8String aSQLStatement);
 152
 153   /**
 154    * Execute a SQL expression, expecting no arguments.
 155    *
 156    * @param aSQLStatement  The SQL statement to execute
 157    */
 158   void executeSimpleSQL(in AUTF8String aSQLStatement);
 159
 160   /**
 161    * Check if the given table exists.
 162    *
 163    * @param aTableName
 164    *        The table to check
 165    * @return TRUE if table exists, FALSE otherwise.
 166    */
 167   boolean tableExists(in AUTF8String aTableName);
 168
 169   /**
 170    * Check if the given index exists.
 171    *
 172    * @param aIndexName   The index to check
 173    * @return TRUE if the index exists, FALSE otherwise.
 174    */
 175   boolean indexExists(in AUTF8String aIndexName);
 176
 177   //////////////////////////////////////////////////////////////////////////////
 178   //// Transactions
 179
 180   /**
 181    * Begin a new transaction. If a transaction is active, throws an error.
 182    */
 183   void beginTransaction();
 184
 185   /**
 186    * Commits the current transaction.  If no transaction is active,
 187    * @throws NS_ERROR_UNEXPECTED.
 188    * @throws NS_ERROR_NOT_INITIALIZED.
 189    */
 190   void commitTransaction();
 191
 192   /**
 193    * Rolls back the current transaction.  If no transaction is active,
 194    * @throws NS_ERROR_UNEXPECTED.
 195    * @throws NS_ERROR_NOT_INITIALIZED.
 196    */
 197   void rollbackTransaction();
 198
 199   //////////////////////////////////////////////////////////////////////////////
 200   //// Tables
 201
 202   /**
 203    * Create the table with the given name and schema.
 204    *
 205    * If the table already exists, NS_ERROR_FAILURE is thrown.
 206    * (XXX at some point in the future it will check if the schema is
 207    * the same as what is specified, but that doesn't happen currently.)
 208    *
 209    * @param aTableName
 210    *        The table name to be created, consisting of [A-Za-z0-9_], and
 211    *        beginning with a letter.
 212    * @param aTableSchema
 213    *        The schema of the table; what would normally go between the parens
 214    *        in a CREATE TABLE statement: e.g., "foo  INTEGER, bar STRING".
 215    *
 216    * @throws NS_ERROR_FAILURE
 217    *         If the table already exists or could not be created for any other
 218    *         reason.
 219    */
 220   void createTable(in string aTableName,
 221                    in string aTableSchema);
 222
 223   /**
 224    * Controls SQLITE_FCNTL_CHUNK_SIZE setting in sqlite. This helps avoid fragmentation
 225    * by growing/shrinking the database file in SQLITE_FCNTL_CHUNK_SIZE increments. To
 226    * conserve memory on systems short on storage space, this function will have no effect
 227    * on mobile devices or if less than 500MiB of space is left available.
 228    *
 229    * @param aIncrement
 230    *        The database file will grow in multiples of chunkSize.
 231    * @param aDatabaseName
 232    *        Sqlite database name. "" means pass NULL for zDbName to sqlite3_file_control.
 233    *        See http://sqlite.org/c3ref/file_control.html for more details.
 234    * @throws NS_ERROR_FILE_TOO_BIG
 235    *         If the system is short on storage space.
 236    */
 237   void setGrowthIncrement(in int32_t aIncrement, in AUTF8String aDatabaseName);
 238
 239   /**
 240    * Enable a predefined virtual table implementation.
 241    *
 242    * @param aModuleName
 243    *        The module to enable. Only "filesystem" is currently supported.
 244    *
 245    * @throws NS_ERROR_FAILURE
 246    *         For unknown module names.
 247    */
 248   [noscript] void enableModule(in ACString aModuleName);
 249
 250   /**
 251    * Get quota objects.
 252    *
 253    * @param[out] aDatabaseQuotaObject
 254    *             The QuotaObject associated with the database file.
 255    * @param[out] aJournalQuotaObject
 256    *             The QuotaObject associated with the journal file.
 257    *
 258    * @throws NS_ERROR_NOT_INITIALIZED.
 259    */
 260   [noscript] void getQuotaObjects(out QuotaObject aDatabaseQuotaObject,
 261                                   out QuotaObject aJournalQuotaObject);
 262
 263   /**
 264    * The mutex used for protection of operations (BEGIN/COMMIT/ROLLBACK) in
 265    * mozStorageTransaction. The lock must be held in a way that spans whole
 266    * operation, not just when accessing the nesting level.
 267    */
 268   [notxpcom, nostdcall] readonly attribute SQLiteMutex sharedDBMutex;
 269
 270   /**
 271    * Helper methods for managing the transaction nesting level. The methods
 272    * must be called with a proof of lock. Currently only used by
 273    * mozStorageTransaction.
 274    */
 275   [notxpcom, nostdcall] unsigned long getTransactionNestingLevel(
 276       in SQLiteMutexAutoLock aProofOfLock);
 277
 278   [notxpcom, nostdcall] unsigned long increaseTransactionNestingLevel(
 279       in SQLiteMutexAutoLock aProofOfLock);
 280
 281   [notxpcom, nostdcall] unsigned long decreaseTransactionNestingLevel(
 282       in SQLiteMutexAutoLock aProofOfLock);
 283 };