summaryrefslogtreecommitdiffstats
path: root/storage/mozIStorageAsyncConnection.idl
diff options
context:
space:
mode:
Diffstat (limited to 'storage/mozIStorageAsyncConnection.idl')
-rw-r--r--storage/mozIStorageAsyncConnection.idl336
1 files changed, 336 insertions, 0 deletions
diff --git a/storage/mozIStorageAsyncConnection.idl b/storage/mozIStorageAsyncConnection.idl
new file mode 100644
index 0000000000..6c05385007
--- /dev/null
+++ b/storage/mozIStorageAsyncConnection.idl
@@ -0,0 +1,336 @@
+/* -*- 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"
+
+interface mozIStorageCompletionCallback;
+interface mozIStorageFunction;
+interface mozIStorageProgressHandler;
+interface mozIStorageBaseStatement;
+interface mozIStorageStatement;
+interface mozIStorageAsyncStatement;
+interface mozIStorageStatementCallback;
+interface mozIStoragePendingStatement;
+interface nsIFile;
+
+/**
+ * mozIStorageAsyncConnection represents an asynchronous database
+ * connection attached to a specific file or to an in-memory data
+ * storage. It is the primary interface for interacting with a
+ * database from the main thread, including creating prepared
+ * statements, executing SQL, and examining database errors.
+ */
+[scriptable, uuid(8bfd34d5-4ddf-4e4b-89dd-9b14f33534c6)]
+interface mozIStorageAsyncConnection : nsISupports {
+ /**
+ * Transaction behavior constants.
+ */
+ const int32_t TRANSACTION_DEFAULT = -1;
+ const int32_t TRANSACTION_DEFERRED = 0;
+ const int32_t TRANSACTION_IMMEDIATE = 1;
+ const int32_t TRANSACTION_EXCLUSIVE = 2;
+
+ /**
+ * The default behavior for all transactions run on this connection. Defaults
+ * to `TRANSACTION_DEFERRED`, and can be overridden for individual
+ * transactions.
+ */
+ attribute int32_t defaultTransactionType;
+
+ /**
+ * The maximum number of bound parameters for statements executed on this
+ * connection. If your statement has more params than this limit, you'll
+ * need to chunk them into multiple statements. See `PlacesUtils.chunkArray`
+ * and its callers in Places for examples of how to do this, or read on for
+ * an overview.
+ *
+ * Keep in mind that the variable limit is for the _total_ number of
+ * parameters, including ones bound by name (using the `:VVV`, `@VVV`, or
+ * `?VVV` syntax) and index (`?` and `?NNN`).
+ *
+ * This means, when chunking:
+ *
+ * - If you're binding 1 param per 1 value per chunk (for example, if you
+ * have a list of GUIDs and a clause like `WHERE guid IN (?, ?, ?, ...)`,
+ * your chunk length is just `variableLimit`.
+ * - If you're binding 1 param per 1 value per chunk, but using that
+ * param in multiple positions in the query (for example, `WHERE url_hash
+ * IN (hash(?1), hash(?2), ...) AND url IN (?1, ?2, ...)`), you can use the
+ * `?NNN` syntax with a chunk length of `variableLimit`.
+ * - If you're binding N params per 1 value per chunk (for example, if you
+ * have a list of items with GUIDs and parent GUIDs, and you want to bind
+ * both), your chunk length is `variableLimit / N`, since you're binding
+ * two params for each element.
+ * - If you're binding K params per L values per chunk, plus M fixed ones
+ * (for example, `WHERE parentGuid = :parentGuid AND guid IN (?, ?, ...)`),
+ * your chunk length is `variableLimit - M`, to ensure there's space for the
+ * fixed variables.
+ *
+ * If you bind more params than this limit, `create{Async}Statement` will
+ * fail with a "too many SQL variables" error.
+ */
+ readonly attribute int32_t variableLimit;
+
+ /**
+ * Returns true if a transaction is active on this connection.
+ *
+ * Note that this is true if a transaction is active on the connection,
+ * regardless of how it was opened. There are several ways to open one:
+ *
+ * 1. Explicitly calling `beginTransaction` on a `mozIStorageConnection`.
+ * 2. Calling `executeSimpleSQL("BEGIN")` or
+ * `createStatement("BEGIN").execute()` on a `mozIStorageConnection`.
+ * 3. Executing an async statement, like
+ * `createAsyncStatement("BEGIN").executeAsync(...)`. This is what
+ * `Sqlite.sys.mjs` does under the hood.
+ *
+ * Because of this, it's important *not* to use this attribute to decide
+ * whether to *commit* the active transaction, because the caller that opened
+ * it may not expect that. This is why both `mozStorageTransaction` and
+ * `Sqlite.sys.mjs` use an internal variable (`mHasTransaction` for the former;
+ * `_hasInProgressTransaction` for the latter) to check if their transaction
+ * is already in progress, instead of just checking this attribute before
+ * committing. Otherwise, mozStorage might accidentally commit (or roll back!)
+ * a transaction started by `Sqlite.sys.mjs`, and vice versa.
+ */
+ readonly attribute boolean transactionInProgress;
+
+ /**
+ * Close this database connection, allowing all pending statements
+ * to complete first.
+ *
+ * @param aCallback [optional]
+ * A callback that will be notified when the close is completed,
+ * with the following arguments:
+ * - status: the status of the call
+ * - value: |null|
+ *
+ * @throws NS_ERROR_NOT_SAME_THREAD
+ * If called on a thread other than the one that opened it. The
+ * callback will not be dispatched.
+ * @throws NS_ERROR_NOT_INITIALIZED
+ * If called on a connection that has already been closed or was
+ * never properly opened. The callback will still be dispatched
+ * to the main thread despite the returned error.
+ * @note If this call should fail, the callback won't be invoked.
+ */
+ void asyncClose([optional] in mozIStorageCompletionCallback aCallback);
+
+ /**
+ * Forcibly closes a database connection synchronously.
+ * This should only be used when it's required to close and replace the
+ * database synchronously to return control to the consumer, for example in
+ * case of a detected corruption on database opening.
+ * Since this spins the events loop, it should be used only in very particular
+ * and rare situations, or it may cause unexpected consequences (crashes).
+ *
+ * @throws NS_ERROR_NOT_SAME_THREAD
+ * If called on a thread other than the one that opened it.
+ */
+ [noscript] void spinningSynchronousClose();
+
+ /**
+ * Clone a database and make the clone read only if needed.
+ * SQL Functions and attached on-disk databases are applied to the new clone.
+ *
+ * @param aReadOnly
+ * If true, the returned database should be put into read-only mode.
+ *
+ * @param aCallback
+ * A callback that will be notified when the operation is complete,
+ * with the following arguments:
+ * - status: the status of the operation
+ * - value: in case of success, an intance of
+ * mozIStorageAsyncConnection cloned from this one.
+ *
+ * @throws NS_ERROR_NOT_SAME_THREAD
+ * If is called on a thread other than the one that opened it.
+ * @throws NS_ERROR_UNEXPECTED
+ * If this connection is a memory database.
+ *
+ * @note If your connection is already read-only, you will get a read-only
+ * clone.
+ * @note The resulting connection will implement `mozIStorageConnection`, but
+ * all synchronous methods will throw if called from the main thread.
+ * @note Due to a bug in SQLite, if you use the shared cache
+ * (see mozIStorageService), you end up with the same privileges as the
+ * first connection opened regardless of what is specified in aReadOnly.
+ * @note The following pragmas are copied over to a read-only clone:
+ * - cache_size
+ * - temp_store
+ * The following pragmas are copied over to a writeable clone:
+ * - cache_size
+ * - temp_store
+ * - foreign_keys
+ * - journal_size_limit
+ * - synchronous
+ * - wal_autocheckpoint
+ * All SQL functions are copied over to read-only and writeable clones.
+ * Additionally, all temporary tables, triggers, and views, as well as
+ * any indexes on temporary tables, are copied over to writeable clones.
+ * For temporary tables, only the schemas are copied, not their
+ * contents.
+ */
+ void asyncClone(in boolean aReadOnly,
+ in mozIStorageCompletionCallback aCallback);
+
+ /**
+ * The current database nsIFile. Null if the database
+ * connection refers to an in-memory database.
+ */
+ readonly attribute nsIFile databaseFile;
+
+ /**
+ * Causes any pending database operation to abort and return at the first
+ * opportunity.
+ * @note this cannot be used on mozIStorageConnection unless the connection is
+ * explicitly marked as `interruptible`. For more details, please
+ * refer to CONNECTION_INTERRUPTIBLE in mozIStorageService.
+ * @note operations that are nearly complete may still be able to complete.
+ * @throws if used on an unsupported connection type, or a closed connection.
+ */
+ void interrupt();
+
+ /**
+ * Vacuum the main database plus all the attached one.
+ * If the database is in auto_vacuum = INCREMENTAL mode, this executes an
+ * incremental_vacuum, otherwise it will always execute a full vacuum.
+ *
+ * While it's possible to invoke this method directly, it's suggested, when
+ * possible, to use the VacuumManager instead.
+ * That means registering your component for the "vacuum-participant" XPCOM
+ * category, and implement the mozIStorageVacuumParticipant interface.
+ *
+ * @param [aCallback] Completion callback invoked once the operation is
+ * complete.
+ * @param [aUseIncremental] When set to true, this will try to convert the
+ * main schema to auto_vacuum = INCREMENTAL mode, if it's not set yet.
+ * When set to false, it will try to set auto_vacuum = NONE.
+ * Note a full vacuum will be executed if the auto_vacuum mode must be
+ * changed, otherwise an incremental vacuum will happen if the database
+ * is already in INCREMENTAL mode.
+ * @param [aSetPageSize] This can be used to change the database page_size, a
+ * full vacuum will be executed to persist the change. If the page
+ * size is already correct, or you pass 0, this will be a no-op.
+ * @throws If it's not possible to start the async vacuum operation, note in
+ * this case the callback won't be invoked.
+ * @note Vacuum will fail inside a transaction, or if there is an ongoing
+ * read statement.
+ */
+ void asyncVacuum(
+ [optional] in mozIStorageCompletionCallback aCallback,
+ [optional] in boolean aUseIncremental,
+ [optional] in long aSetPageSize
+ );
+
+ //////////////////////////////////////////////////////////////////////////////
+ //// Statement creation
+
+ /**
+ * Create an asynchronous statement for the given SQL. An
+ * asynchronous statement can only be used to dispatch asynchronous
+ * requests to the asynchronous execution thread and cannot be used
+ * to take any synchronous actions on the database.
+ *
+ * The expression may use ? to indicate sequential numbered arguments,
+ * ?1, ?2 etc. to indicate specific numbered arguments or :name and
+ * $var to indicate named arguments.
+ *
+ * @param aSQLStatement
+ * The SQL statement to execute.
+ * @return a new mozIStorageAsyncStatement
+ * @note The statement is created lazily on first execution.
+ */
+ mozIStorageAsyncStatement createAsyncStatement(in AUTF8String aSQLStatement);
+
+ /**
+ * Execute an array of statements created with this connection using
+ * any currently bound parameters. When the array contains multiple
+ * statements, the execution is wrapped in a single
+ * transaction. These statements can be reused immediately, and
+ * reset does not need to be called.
+ *
+ * @param aStatements
+ * The array of statements to execute asynchronously, in the order they
+ * are given in the array.
+ * @param aCallback [optional]
+ * The callback object that will be notified of progress, errors, and
+ * completion.
+ * @return an object that can be used to cancel the statements execution.
+ *
+ * @note If you have any custom defined functions, they must be
+ * re-entrant since they can be called on multiple threads.
+ */
+ mozIStoragePendingStatement executeAsync(
+ in Array<mozIStorageBaseStatement> aStatements,
+ [optional] in mozIStorageStatementCallback aCallback
+ );
+
+ /**
+ * Execute asynchronously an SQL expression, expecting no arguments.
+ *
+ * @param aSQLStatement
+ * The SQL statement to execute
+ * @param aCallback [optional]
+ * The callback object that will be notified of progress, errors, and
+ * completion.
+ * @return an object that can be used to cancel the statement execution.
+ */
+ mozIStoragePendingStatement executeSimpleSQLAsync(
+ in AUTF8String aSQLStatement,
+ [optional] in mozIStorageStatementCallback aCallback);
+
+ //////////////////////////////////////////////////////////////////////////////
+ //// Functions
+
+ /**
+ * Create a new SQL function. If you use your connection on multiple threads,
+ * your function needs to be threadsafe, or it should only be called on one
+ * thread.
+ *
+ * @param aFunctionName
+ * The name of function to create, as seen in SQL.
+ * @param aNumArguments
+ * The number of arguments the function takes. Pass -1 for
+ * variable-argument functions.
+ * @param aFunction
+ * The instance of mozIStorageFunction, which implements the function
+ * in question.
+ */
+ void createFunction(in AUTF8String aFunctionName,
+ in long aNumArguments,
+ in mozIStorageFunction aFunction);
+
+ /**
+ * Delete custom SQL function.
+ *
+ * @param aFunctionName
+ * The name of function to remove.
+ */
+ void removeFunction(in AUTF8String aFunctionName);
+
+ /**
+ * Sets a progress handler. Only one handler can be registered at a time.
+ * If you need more than one, you need to chain them yourself. This progress
+ * handler should be threadsafe if you use this connection object on more than
+ * one thread.
+ *
+ * @param aGranularity
+ * The number of SQL virtual machine steps between progress handler
+ * callbacks.
+ * @param aHandler
+ * The instance of mozIStorageProgressHandler.
+ * @return previous registered handler.
+ */
+ mozIStorageProgressHandler setProgressHandler(in int32_t aGranularity,
+ in mozIStorageProgressHandler aHandler);
+
+ /**
+ * Remove a progress handler.
+ *
+ * @return previous registered handler.
+ */
+ mozIStorageProgressHandler removeProgressHandler();
+};