/* -*- 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 is called on a thread other than the one that opened it. */ void asyncClose([optional] in mozIStorageCompletionCallback aCallback); /** * Clone a database and make the clone read only if needed. * * @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(); };