diff options
Diffstat (limited to 'storage/mozIStorageAsyncConnection.idl')
| -rw-r--r-- | storage/mozIStorageAsyncConnection.idl | 220 |
1 files changed, 220 insertions, 0 deletions
diff --git a/storage/mozIStorageAsyncConnection.idl b/storage/mozIStorageAsyncConnection.idl new file mode 100644 index 000000000..aeb2bf1b5 --- /dev/null +++ b/storage/mozIStorageAsyncConnection.idl @@ -0,0 +1,220 @@ +/* -*- 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 mozIStorageAggregateFunction; +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 { + /** + * 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. + */ + void asyncClose([optional] in mozIStorageCompletionCallback aCallback); + + /** + * 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 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 + */ + 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; + + ////////////////////////////////////////////////////////////////////////////// + //// 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 aNumStatements + * The number of statements in aStatements. + * @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( + [array, size_is(aNumStatements)] in mozIStorageBaseStatement aStatements, + in unsigned long aNumStatements, + [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); + + /** + * Create a new SQL aggregate 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 aggregate 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 mozIStorageAggreagteFunction, which implements the + * function in question. + */ + void createAggregateFunction(in AUTF8String aFunctionName, + in long aNumArguments, + in mozIStorageAggregateFunction aFunction); + /** + * Delete custom SQL function (simple or aggregate one). + * + * @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(); +}; |