diff options
Diffstat (limited to 'storage/mozIStorageService.idl')
| -rw-r--r-- | storage/mozIStorageService.idl | 290 |
1 files changed, 290 insertions, 0 deletions
diff --git a/storage/mozIStorageService.idl b/storage/mozIStorageService.idl new file mode 100644 index 0000000000..22c1dc0565 --- /dev/null +++ b/storage/mozIStorageService.idl @@ -0,0 +1,290 @@ +/* -*- Mode: idl; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ +/* This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ + +#include "nsISupports.idl" + +%{C++ + +#include "nsLiteralString.h" + +%} + +interface mozIStorageConnection; +interface nsIFile; +interface nsIFileURL; +interface nsIPropertyBag2; +interface nsIVariant; +interface mozIStorageCompletionCallback; + +/** + * PRIVACY WARNING + * =============== + * + * Database file names can be exposed through telemetry and in crash reports on + * the https://crash-stats.mozilla.org site, to allow recognizing the affected + * database. + * if your database name may contain privacy sensitive information, e.g. an + * URL origin, you should use openDatabaseWithFileURL and pass an explicit + * TelemetryFilename to it. That name will be used both for telemetry and for + * thread names in crash reports. + * If you have different needs (e.g. using the javascript module or an async + * connection from the main thread) please coordinate with the mozStorage peers. + */ + +/** + * The mozIStorageService interface is intended to be implemented by + * a service that can create storage connections (mozIStorageConnection) + * to either a well-known profile database or to a specific database file. + * + * This is the only way to open a database connection. + * + * @note The first reference to mozIStorageService must be made on the main + * thread. + */ +[scriptable, uuid(07b6b2f5-6d97-47b4-9584-e65bc467fe9e)] +interface mozIStorageService : nsISupports { + /** + * Open the database with default flags in default mode. + */ + const unsigned long OPEN_DEFAULT = 0; + + /** + * Open the database with a shared cache. The shared-cache mode + * is more memory-efficient when many connections to the same database + * are expected, though, the connections will contend the cache resource. + * When performance matters, working without a shared-cache will + * improve concurrency. @see openUnsharedDatabase + */ + const unsigned long OPEN_SHARED = 1 << 0; + + /** + * Open the underlying database in read-only mode. + */ + const unsigned long OPEN_READONLY = 1 << 1; + + /** + * Allow simultaneous access to an asynchronous read-only database + * without any file locking. + * + * For synchronous database, the flag has no effect. + * + * Specifying the OPEN_IGNORE_LOCKING_MODE flag will automatically + * turn on the OPEN_READONLY flag. + */ + const unsigned long OPEN_IGNORE_LOCKING_MODE = 1 << 2; + + /** + * All optional connection object features are off. + */ + const unsigned long CONNECTION_DEFAULT = 0; + + /** + * Enable Interrupt-method for the synchronous connection object + * returned by openDatabase, openSpecialDatabase, openUnsharedDatabase + * or openDatabaseWithFileURL calls. + * + * When this flag is not set, Interrupt-method of a + * synchronous connection must not be used. + * + * Asynchronous connection is always interruptible and the flag + * does not change anything. + * + * The following are among the potential risks side effects of + * calling the Interrupt-method: + * - new queries started on a different thread after the + * interrupt call, but before its completion, are interrupted as if + * they had been running prior to the interrupt call. Thus thread + * synchronization is necessary. + * - calls to close the database will wait until the interruption + * finishes. + */ + const unsigned long CONNECTION_INTERRUPTIBLE = 1 << 0; + + /** + * Open an asynchronous connection to a database. + * + * This method MUST be called from the main thread. The connection object + * returned by this function is not threadsafe. You MUST use it only from + * the main thread. + * + * If you have more than one connection to a file, you MUST use the EXACT + * SAME NAME for the file each time, including case. The sqlite code uses + * a simple string compare to see if there is already a connection. Opening + * a connection to "Foo.sqlite" and "foo.sqlite" will CORRUPT YOUR DATABASE. + * + * @param aDatabaseStore Either a nsIFile representing the file that contains + * the database or a special string to open a special database. The special + * string may be: + * - "memory" to open an in-memory database. + * + * @param aOpenFlags + * A set of flags to open the database with optional features. + * Currently supports OPEN_SHARED, OPEN_READONLY and + * OPEN_IGNORE_LOCKING_MODE flags. + * For full details, please refer to the documentation of the flags. + * + * @param aConnectionFlags + * A set of flags to enable optional features for the returned + * asynchronous connection object. + * Currently supports CONNECTION_INTERRUPTIBLE flag. + * For full details, please refer to the documentation of the flag. + * + * @param aCallback A callback that will receive the result of the operation. + * In case of error, it may receive as status: + * - NS_ERROR_OUT_OF_MEMORY if allocating a new storage object fails. + * - NS_ERROR_FILE_CORRUPTED if the database file is corrupted. + * In case of success, it receives as argument the new database + * connection, as an instance of |mozIStorageAsyncConnection|. + * + * @throws NS_ERROR_INVALID_ARG if |aDatabaseStore| is neither a file nor + * one of the special strings understood by this method, or if one of + * the options passed through |aOptions| does not have + * the right type. + * @throws NS_ERROR_NOT_SAME_THREAD if called from a thread other than the + * main thread. + */ + void openAsyncDatabase(in nsIVariant aDatabaseStore, + in unsigned long aOpenFlags, + in unsigned long aConnectionFlags, + in mozIStorageCompletionCallback aCallback); + + /** + * Get a connection to a named special database storage. + * + * @param aStorageKey a string key identifying the type of storage + * requested. Valid values include: "memory". + * + * @param aName an optional string identifying the name of the database. + * If omitted, a filename of ":memory:" will be used which results in a + * private in-memory database specific to this connection, making it + * impossible to clone the in-memory database. If you want to be able to + * clone the connection (or otherwise connect to the in-memory database from + * a connection), then you must pick a name that's sufficiently unique within + * the process to not collide with other mozStorage users. + * + * @param [optional] aConnectionFlags + * A set of flags to enable optional features for the returned + * synchronous connection object. + * Currently supports CONNECTION_INTERRUPTIBLE flag. + * For full details, please refer to the documentation of the flag. + * + * @see openDatabase for restrictions on how database connections may be + * used. For the profile database, you should only access it from the main + * thread since other callers may also have connections. + * + * @returns a new mozIStorageConnection for the requested + * storage database. + * + * @throws NS_ERROR_INVALID_ARG if aStorageKey is invalid. + */ + mozIStorageConnection openSpecialDatabase( + in ACString aStorageKey, + [optional] in ACString aName, + [optional] in unsigned long aConnectionFlags); + + /** + * Open a connection to the specified file. + * + * Consumers should check mozIStorageConnection::connectionReady to ensure + * that they can use the database. If this value is false, it is strongly + * recommended that the database be backed up with + * mozIStorageConnection::backupDB so user data is not lost. + * + * ========== + * DANGER + * ========== + * + * If you have more than one connection to a file, you MUST use the EXACT + * SAME NAME for the file each time, including case. The sqlite code uses + * a simple string compare to see if there is already a connection. Opening + * a connection to "Foo.sqlite" and "foo.sqlite" will CORRUPT YOUR DATABASE. + * + * The connection object returned by this function is not threadsafe. You + * must use it only from the thread you created it from. + * + * @param aDatabaseFile + * A nsIFile that represents the database that is to be opened. + * @param [optional] aConnectionFlags + * A set of flags to enable optional features for the returned + * synchronous connection object. + * Currently supports CONNECTION_INTERRUPTIBLE flag. + * For full details, please refer to the documentation of the flag. + * + * @returns a mozIStorageConnection for the requested database file. + * + * @throws NS_ERROR_OUT_OF_MEMORY + * If allocating a new storage object fails. + * @throws NS_ERROR_FILE_CORRUPTED + * If the database file is corrupted. + */ + mozIStorageConnection openDatabase( + in nsIFile aDatabaseFile, [optional] in unsigned long aConnectionFlags); + + /** + * Open a connection to the specified file that doesn't share a sqlite cache. + * + * Without a shared-cache, each connection uses its own pages cache, which + * may be memory inefficient with a large number of connections, in such a + * case so you should use openDatabase instead. On the other side, if cache + * contention may be an issue, for instance when concurrency is important to + * ensure responsiveness, using unshared connections may be a + * performance win. + * + * ========== + * DANGER + * ========== + * + * If you have more than one connection to a file, you MUST use the EXACT + * SAME NAME for the file each time, including case. The sqlite code uses + * a simple string compare to see if there is already a connection. Opening + * a connection to "Foo.sqlite" and "foo.sqlite" will CORRUPT YOUR DATABASE. + * + * The connection object returned by this function is not threadsafe. You + * must use it only from the thread you created it from. + * + * @param aDatabaseFile + * A nsIFile that represents the database that is to be opened. + * @param [optional] aConnectionFlags + * A set of flags to enable optional features for the returned + * synchronous connection object. + * Currently supports CONNECTION_INTERRUPTIBLE flag. + * For full details, please refer to the documentation of the flag. + * + * @returns a mozIStorageConnection for the requested database file. + * + * @throws NS_ERROR_OUT_OF_MEMORY + * If allocating a new storage object fails. + * @throws NS_ERROR_FILE_CORRUPTED + * If the database file is corrupted. + */ + mozIStorageConnection openUnsharedDatabase( + in nsIFile aDatabaseFile, [optional] in unsigned long aConnectionFlags); + + /** + * See openDatabase(). Exactly the same only initialized with a file URL. + * Custom parameters can be passed to SQLite and VFS implementations through + * the query part of the URL. + * + * @param aURL + * A nsIFileURL that represents the database that is to be opened. + * @param [optional] aTelemetryFilename + * The name to use for the database in telemetry. Only needed if the + * actual filename can contain sensitive information. + * @param [optional] aConnectionFlags + * A set of flags to enable optional features for the returned + * synchronous connection object. + * Currently supports CONNECTION_INTERRUPTIBLE flag. + * For full details, please refer to the documentation of the flag. + */ + mozIStorageConnection openDatabaseWithFileURL( + in nsIFileURL aFileURL, [optional] in ACString aTelemetryFilename, + [optional] in unsigned long aConnectionFlags); +}; + +%{C++ + +constexpr auto kMozStorageMemoryStorageKey = "memory"_ns; + +%} |