storage/mozIStorageService.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
   8 %{C++
   9
  10 #include "nsLiteralString.h"
  11
  12 %}
  13
  14 interface mozIStorageConnection;
  15 interface nsIFile;
  16 interface nsIFileURL;
  17 interface nsIPropertyBag2;
  18 interface nsIVariant;
  19 interface mozIStorageCompletionCallback;
  20
  21 /**
  22  * PRIVACY WARNING
  23  * ===============
  24  *
  25  * Database file names can be exposed through telemetry and in crash reports on
  26  * the https://crash-stats.mozilla.org site, to allow recognizing the affected
  27  * database.
  28  * if your database name may contain privacy sensitive information, e.g. an
  29  * URL origin, you should use openDatabaseWithFileURL and pass an explicit
  30  * TelemetryFilename to it. That name will be used both for telemetry and for
  31  * thread names in crash reports.
  32  * If you have different needs (e.g. using the javascript module or an async
  33  * connection from the main thread) please coordinate with the mozStorage peers.
  34  */
  35
  36 /**
  37  * The mozIStorageService interface is intended to be implemented by
  38  * a service that can create storage connections (mozIStorageConnection)
  39  * to either a well-known profile database or to a specific database file.
  40  *
  41  * This is the only way to open a database connection.
  42  *
  43  * @note The first reference to mozIStorageService must be made on the main
  44  * thread.
  45  */
  46 [scriptable, uuid(07b6b2f5-6d97-47b4-9584-e65bc467fe9e)]
  47 interface mozIStorageService : nsISupports {
  48   /**
  49    * Open the database with default flags in default mode.
  50    */
  51   const unsigned long OPEN_DEFAULT = 0;
  52
  53   /**
  54    * Open the database with a shared cache. The shared-cache mode
  55    * is more memory-efficient when many connections to the same database
  56    * are expected, though, the connections will contend the cache resource.
  57    * When performance matters, working without a shared-cache will
  58    * improve concurrency.  @see openUnsharedDatabase
  59    */
  60   const unsigned long OPEN_SHARED = 1 << 0;
  61
  62   /**
  63    * Open the underlying database in read-only mode.
  64    */
  65   const unsigned long OPEN_READONLY = 1 << 1;
  66
  67   /**
  68    * Allow simultaneous access to an asynchronous read-only database
  69    * without any file locking.
  70    *
  71    * For synchronous database, the flag has no effect.
  72    *
  73    * Specifying the OPEN_IGNORE_LOCKING_MODE flag will automatically
  74    * turn on the OPEN_READONLY flag.
  75    */
  76   const unsigned long OPEN_IGNORE_LOCKING_MODE = 1 << 2;
  77
  78   /**
  79    * All optional connection object features are off.
  80    */
  81   const unsigned long CONNECTION_DEFAULT = 0;
  82
  83   /**
  84    * Enable Interrupt-method for the synchronous connection object
  85    * returned by openDatabase, openSpecialDatabase, openUnsharedDatabase
  86    * or openDatabaseWithFileURL calls.
  87    *
  88    * When this flag is not set, Interrupt-method of a
  89    * synchronous connection must not be used.
  90    *
  91    * Asynchronous connection is always interruptible and the flag
  92    * does not change anything.
  93    *
  94    * The following are among the potential risks side effects of
  95    * calling the Interrupt-method:
  96    *   - new queries started on a different thread after the
  97    *     interrupt call, but before its completion, are interrupted as if
  98    *     they had been running prior to the interrupt call. Thus thread
  99    *     synchronization is necessary.
 100    *   - calls to close the database will wait until the interruption
 101    *     finishes.
 102    */
 103   const unsigned long CONNECTION_INTERRUPTIBLE = 1 << 0;
 104
 105   /**
 106    * Open an asynchronous connection to a database.
 107    *
 108    * This method MUST be called from the main thread. The connection object
 109    * returned by this function is not threadsafe. You MUST use it only from
 110    * the main thread.
 111    *
 112    * If you have more than one connection to a file, you MUST use the EXACT
 113    * SAME NAME for the file each time, including case. The sqlite code uses
 114    * a simple string compare to see if there is already a connection. Opening
 115    * a connection to "Foo.sqlite" and "foo.sqlite" will CORRUPT YOUR DATABASE.
 116    *
 117    * @param aDatabaseStore Either a nsIFile representing the file that contains
 118    * the database or a special string to open a special database. The special
 119    * string may be:
 120    * - "memory" to open an in-memory database.
 121    *
 122    * @param aOpenFlags
 123    *        A set of flags to open the database with optional features.
 124    *        Currently supports OPEN_SHARED, OPEN_READONLY and
 125    *        OPEN_IGNORE_LOCKING_MODE flags.
 126    *        For full details, please refer to the documentation of the flags.
 127    *
 128    * @param aConnectionFlags
 129    *        A set of flags to enable optional features for the returned
 130    *        asynchronous connection object.
 131    *        Currently supports CONNECTION_INTERRUPTIBLE flag.
 132    *        For full details, please refer to the documentation of the flag.
 133    *
 134    * @param aCallback A callback that will receive the result of the operation.
 135    *  In case of error, it may receive as status:
 136    *  - NS_ERROR_OUT_OF_MEMORY if allocating a new storage object fails.
 137    *  - NS_ERROR_FILE_CORRUPTED if the database file is corrupted.
 138    *  In case of success, it receives as argument the new database
 139    *  connection, as an instance of |mozIStorageAsyncConnection|.
 140    *
 141    * @throws NS_ERROR_INVALID_ARG if |aDatabaseStore| is neither a file nor
 142    *         one of the special strings understood by this method, or if one of
 143    *         the options passed through |aOptions| does not have
 144    *         the right type.
 145    * @throws NS_ERROR_NOT_SAME_THREAD if called from a thread other than the
 146    *         main thread.
 147    */
 148   void openAsyncDatabase(in nsIVariant aDatabaseStore,
 149                          in unsigned long aOpenFlags,
 150                          in unsigned long aConnectionFlags,
 151                          in mozIStorageCompletionCallback aCallback);
 152
 153   /**
 154    * Get a connection to a named special database storage.
 155    *
 156    * @param aStorageKey a string key identifying the type of storage
 157    * requested.  Valid values include: "memory".
 158    *
 159    * @param aName an optional string identifying the name of the database.
 160    * If omitted, a filename of ":memory:" will be used which results in a
 161    * private in-memory database specific to this connection, making it
 162    * impossible to clone the in-memory database. If you want to be able to
 163    * clone the connection (or otherwise connect to the in-memory database from
 164    * a connection), then you must pick a name that's sufficiently unique within
 165    * the process to not collide with other mozStorage users.
 166    *
 167    * @param [optional] aConnectionFlags
 168    *        A set of flags to enable optional features for the returned
 169    *        synchronous connection object.
 170    *        Currently supports CONNECTION_INTERRUPTIBLE flag.
 171    *        For full details, please refer to the documentation of the flag.
 172    *
 173    * @see openDatabase for restrictions on how database connections may be
 174    * used. For the profile database, you should only access it from the main
 175    * thread since other callers may also have connections.
 176    *
 177    * @returns a new mozIStorageConnection for the requested
 178    * storage database.
 179    *
 180    * @throws NS_ERROR_INVALID_ARG if aStorageKey is invalid.
 181    */
 182   mozIStorageConnection openSpecialDatabase(
 183       in ACString aStorageKey,
 184       [optional] in ACString aName,
 185       [optional] in unsigned long aConnectionFlags);
 186
 187   /**
 188    * Open a connection to the specified file.
 189    *
 190    * Consumers should check mozIStorageConnection::connectionReady to ensure
 191    * that they can use the database.  If this value is false, it is strongly
 192    * recommended that the database be backed up with
 193    * mozIStorageConnection::backupDB so user data is not lost.
 194    *
 195    * ==========
 196    *   DANGER
 197    * ==========
 198    *
 199    * If you have more than one connection to a file, you MUST use the EXACT
 200    * SAME NAME for the file each time, including case. The sqlite code uses
 201    * a simple string compare to see if there is already a connection. Opening
 202    * a connection to "Foo.sqlite" and "foo.sqlite" will CORRUPT YOUR DATABASE.
 203    *
 204    * The connection object returned by this function is not threadsafe. You
 205    * must use it only from the thread you created it from.
 206    *
 207    * @param aDatabaseFile
 208    *        A nsIFile that represents the database that is to be opened.
 209    * @param [optional] aConnectionFlags
 210    *        A set of flags to enable optional features for the returned
 211    *        synchronous connection object.
 212    *        Currently supports CONNECTION_INTERRUPTIBLE flag.
 213    *        For full details, please refer to the documentation of the flag.
 214    *
 215    * @returns a mozIStorageConnection for the requested database file.
 216    *
 217    * @throws NS_ERROR_OUT_OF_MEMORY
 218    *         If allocating a new storage object fails.
 219    * @throws NS_ERROR_FILE_CORRUPTED
 220    *         If the database file is corrupted.
 221    */
 222   mozIStorageConnection openDatabase(
 223       in nsIFile aDatabaseFile, [optional] in unsigned long aConnectionFlags);
 224
 225   /**
 226    * Open a connection to the specified file that doesn't share a sqlite cache.
 227    *
 228    * Without a shared-cache, each connection uses its own pages cache, which
 229    * may be memory inefficient with a large number of connections, in such a
 230    * case so you should use openDatabase instead.  On the other side, if cache
 231    * contention may be an issue, for instance when concurrency is important to
 232    * ensure responsiveness, using unshared connections may be a
 233    * performance win.
 234    *
 235    * ==========
 236    *   DANGER
 237    * ==========
 238    *
 239    * If you have more than one connection to a file, you MUST use the EXACT
 240    * SAME NAME for the file each time, including case. The sqlite code uses
 241    * a simple string compare to see if there is already a connection. Opening
 242    * a connection to "Foo.sqlite" and "foo.sqlite" will CORRUPT YOUR DATABASE.
 243    *
 244    * The connection object returned by this function is not threadsafe. You
 245    * must use it only from the thread you created it from.
 246    *
 247    * @param aDatabaseFile
 248    *        A nsIFile that represents the database that is to be opened.
 249    * @param [optional] aConnectionFlags
 250    *        A set of flags to enable optional features for the returned
 251    *        synchronous connection object.
 252    *        Currently supports CONNECTION_INTERRUPTIBLE flag.
 253    *        For full details, please refer to the documentation of the flag.
 254    *
 255    * @returns a mozIStorageConnection for the requested database file.
 256    *
 257    * @throws NS_ERROR_OUT_OF_MEMORY
 258    *         If allocating a new storage object fails.
 259    * @throws NS_ERROR_FILE_CORRUPTED
 260    *         If the database file is corrupted.
 261    */
 262   mozIStorageConnection openUnsharedDatabase(
 263       in nsIFile aDatabaseFile, [optional] in unsigned long aConnectionFlags);
 264
 265   /**
 266    * See openDatabase(). Exactly the same only initialized with a file URL.
 267    * Custom parameters can be passed to SQLite and VFS implementations through
 268    * the query part of the URL.
 269    *
 270    * @param aURL
 271    *        A nsIFileURL that represents the database that is to be opened.
 272    * @param [optional] aTelemetryFilename
 273    *        The name to use for the database in telemetry. Only needed if the
 274    *        actual filename can contain sensitive information.
 275    * @param [optional] aConnectionFlags
 276    *        A set of flags to enable optional features for the returned
 277    *        synchronous connection object.
 278    *        Currently supports CONNECTION_INTERRUPTIBLE flag.
 279    *        For full details, please refer to the documentation of the flag.
 280    */
 281   mozIStorageConnection openDatabaseWithFileURL(
 282       in nsIFileURL aFileURL, [optional] in ACString aTelemetryFilename,
 283       [optional] in unsigned long aConnectionFlags);
 284 };
 285
 286 %{C++
 287
 288 constexpr auto kMozStorageMemoryStorageKey = "memory"_ns;
 289
 290 %}