michael@0: /* -*- Mode: idl; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public michael@0: * License, v. 2.0. If a copy of the MPL was not distributed with this michael@0: * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ michael@0: michael@0: #include "nsISupports.idl" michael@0: michael@0: interface mozIStorageAggregateFunction; michael@0: interface mozIStorageCompletionCallback; michael@0: interface mozIStorageFunction; michael@0: interface mozIStorageProgressHandler; michael@0: interface mozIStorageBaseStatement; michael@0: interface mozIStorageStatement; michael@0: interface mozIStorageAsyncStatement; michael@0: interface mozIStorageStatementCallback; michael@0: interface mozIStoragePendingStatement; michael@0: interface nsIFile; michael@0: michael@0: /** michael@0: * mozIStorageAsyncConnection represents an asynchronous database michael@0: * connection attached to a specific file or to an in-memory data michael@0: * storage. It is the primary interface for interacting with a michael@0: * database from the main thread, including creating prepared michael@0: * statements, executing SQL, and examining database errors. michael@0: */ michael@0: [scriptable, uuid(8bfd34d5-4ddf-4e4b-89dd-9b14f33534c6)] michael@0: interface mozIStorageAsyncConnection : nsISupports { michael@0: /** michael@0: * Close this database connection, allowing all pending statements michael@0: * to complete first. michael@0: * michael@0: * @param aCallback [optional] michael@0: * A callback that will be notified when the close is completed, michael@0: * with the following arguments: michael@0: * - status: the status of the call michael@0: * - value: |null| michael@0: * michael@0: * @throws NS_ERROR_NOT_SAME_THREAD michael@0: * If is called on a thread other than the one that opened it. michael@0: */ michael@0: void asyncClose([optional] in mozIStorageCompletionCallback aCallback); michael@0: michael@0: /** michael@0: * Clone a database and make the clone read only if needed. michael@0: * michael@0: * @param aReadOnly michael@0: * If true, the returned database should be put into read-only mode. michael@0: * michael@0: * @param aCallback michael@0: * A callback that will be notified when the operation is complete, michael@0: * with the following arguments: michael@0: * - status: the status of the operation michael@0: * - value: in case of success, an intance of michael@0: * mozIStorageAsyncConnection cloned from this one. michael@0: * michael@0: * @throws NS_ERROR_NOT_SAME_THREAD michael@0: * If is called on a thread other than the one that opened it. michael@0: * @throws NS_ERROR_UNEXPECTED michael@0: * If this connection is a memory database. michael@0: * michael@0: * @note If your connection is already read-only, you will get a read-only michael@0: * clone. michael@0: * @note Due to a bug in SQLite, if you use the shared cache michael@0: * (see mozIStorageService), you end up with the same privileges as the michael@0: * first connection opened regardless of what is specified in aReadOnly. michael@0: * @note The following pragmas are copied over to a read-only clone: michael@0: * - cache_size michael@0: * - temp_store michael@0: * The following pragmas are copied over to a writeable clone: michael@0: * - cache_size michael@0: * - temp_store michael@0: * - foreign_keys michael@0: * - journal_size_limit michael@0: * - synchronous michael@0: * - wal_autocheckpoint michael@0: */ michael@0: void asyncClone(in boolean aReadOnly, michael@0: in mozIStorageCompletionCallback aCallback); michael@0: michael@0: /** michael@0: * The current database nsIFile. Null if the database michael@0: * connection refers to an in-memory database. michael@0: */ michael@0: readonly attribute nsIFile databaseFile; michael@0: michael@0: ////////////////////////////////////////////////////////////////////////////// michael@0: //// Statement creation michael@0: michael@0: /** michael@0: * Create an asynchronous statement for the given SQL. An michael@0: * asynchronous statement can only be used to dispatch asynchronous michael@0: * requests to the asynchronous execution thread and cannot be used michael@0: * to take any synchronous actions on the database. michael@0: * michael@0: * The expression may use ? to indicate sequential numbered arguments, michael@0: * ?1, ?2 etc. to indicate specific numbered arguments or :name and michael@0: * $var to indicate named arguments. michael@0: * michael@0: * @param aSQLStatement michael@0: * The SQL statement to execute. michael@0: * @return a new mozIStorageAsyncStatement michael@0: * @note The statement is created lazily on first execution. michael@0: */ michael@0: mozIStorageAsyncStatement createAsyncStatement(in AUTF8String aSQLStatement); michael@0: michael@0: /** michael@0: * Execute an array of statements created with this connection using michael@0: * any currently bound parameters. When the array contains multiple michael@0: * statements, the execution is wrapped in a single michael@0: * transaction. These statements can be reused immediately, and michael@0: * reset does not need to be called. michael@0: * michael@0: * @param aStatements michael@0: * The array of statements to execute asynchronously, in the order they michael@0: * are given in the array. michael@0: * @param aNumStatements michael@0: * The number of statements in aStatements. michael@0: * @param aCallback [optional] michael@0: * The callback object that will be notified of progress, errors, and michael@0: * completion. michael@0: * @return an object that can be used to cancel the statements execution. michael@0: * michael@0: * @note If you have any custom defined functions, they must be michael@0: * re-entrant since they can be called on multiple threads. michael@0: */ michael@0: mozIStoragePendingStatement executeAsync( michael@0: [array, size_is(aNumStatements)] in mozIStorageBaseStatement aStatements, michael@0: in unsigned long aNumStatements, michael@0: [optional] in mozIStorageStatementCallback aCallback michael@0: ); michael@0: michael@0: /** michael@0: * Execute asynchronously an SQL expression, expecting no arguments. michael@0: * michael@0: * @param aSQLStatement michael@0: * The SQL statement to execute michael@0: * @param aCallback [optional] michael@0: * The callback object that will be notified of progress, errors, and michael@0: * completion. michael@0: * @return an object that can be used to cancel the statement execution. michael@0: */ michael@0: mozIStoragePendingStatement executeSimpleSQLAsync( michael@0: in AUTF8String aSQLStatement, michael@0: [optional] in mozIStorageStatementCallback aCallback); michael@0: michael@0: ////////////////////////////////////////////////////////////////////////////// michael@0: //// Functions michael@0: michael@0: /** michael@0: * Create a new SQL function. If you use your connection on multiple threads, michael@0: * your function needs to be threadsafe, or it should only be called on one michael@0: * thread. michael@0: * michael@0: * @param aFunctionName michael@0: * The name of function to create, as seen in SQL. michael@0: * @param aNumArguments michael@0: * The number of arguments the function takes. Pass -1 for michael@0: * variable-argument functions. michael@0: * @param aFunction michael@0: * The instance of mozIStorageFunction, which implements the function michael@0: * in question. michael@0: */ michael@0: void createFunction(in AUTF8String aFunctionName, michael@0: in long aNumArguments, michael@0: in mozIStorageFunction aFunction); michael@0: michael@0: /** michael@0: * Create a new SQL aggregate function. If you use your connection on michael@0: * multiple threads, your function needs to be threadsafe, or it should only michael@0: * be called on one thread. michael@0: * michael@0: * @param aFunctionName michael@0: * The name of aggregate function to create, as seen in SQL. michael@0: * @param aNumArguments michael@0: * The number of arguments the function takes. Pass -1 for michael@0: * variable-argument functions. michael@0: * @param aFunction michael@0: * The instance of mozIStorageAggreagteFunction, which implements the michael@0: * function in question. michael@0: */ michael@0: void createAggregateFunction(in AUTF8String aFunctionName, michael@0: in long aNumArguments, michael@0: in mozIStorageAggregateFunction aFunction); michael@0: /** michael@0: * Delete custom SQL function (simple or aggregate one). michael@0: * michael@0: * @param aFunctionName michael@0: * The name of function to remove. michael@0: */ michael@0: void removeFunction(in AUTF8String aFunctionName); michael@0: michael@0: /** michael@0: * Sets a progress handler. Only one handler can be registered at a time. michael@0: * If you need more than one, you need to chain them yourself. This progress michael@0: * handler should be threadsafe if you use this connection object on more than michael@0: * one thread. michael@0: * michael@0: * @param aGranularity michael@0: * The number of SQL virtual machine steps between progress handler michael@0: * callbacks. michael@0: * @param aHandler michael@0: * The instance of mozIStorageProgressHandler. michael@0: * @return previous registered handler. michael@0: */ michael@0: mozIStorageProgressHandler setProgressHandler(in int32_t aGranularity, michael@0: in mozIStorageProgressHandler aHandler); michael@0: michael@0: /** michael@0: * Remove a progress handler. michael@0: * michael@0: * @return previous registered handler. michael@0: */ michael@0: mozIStorageProgressHandler removeProgressHandler(); michael@0: };