1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/storage/public/mozIStorageAsyncConnection.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,214 @@
1.4 +/* -*- Mode: idl; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +#include "nsISupports.idl"
1.10 +
1.11 +interface mozIStorageAggregateFunction;
1.12 +interface mozIStorageCompletionCallback;
1.13 +interface mozIStorageFunction;
1.14 +interface mozIStorageProgressHandler;
1.15 +interface mozIStorageBaseStatement;
1.16 +interface mozIStorageStatement;
1.17 +interface mozIStorageAsyncStatement;
1.18 +interface mozIStorageStatementCallback;
1.19 +interface mozIStoragePendingStatement;
1.20 +interface nsIFile;
1.21 +
1.22 +/**
1.23 + * mozIStorageAsyncConnection represents an asynchronous database
1.24 + * connection attached to a specific file or to an in-memory data
1.25 + * storage. It is the primary interface for interacting with a
1.26 + * database from the main thread, including creating prepared
1.27 + * statements, executing SQL, and examining database errors.
1.28 + */
1.29 +[scriptable, uuid(8bfd34d5-4ddf-4e4b-89dd-9b14f33534c6)]
1.30 +interface mozIStorageAsyncConnection : nsISupports {
1.31 + /**
1.32 + * Close this database connection, allowing all pending statements
1.33 + * to complete first.
1.34 + *
1.35 + * @param aCallback [optional]
1.36 + * A callback that will be notified when the close is completed,
1.37 + * with the following arguments:
1.38 + * - status: the status of the call
1.39 + * - value: |null|
1.40 + *
1.41 + * @throws NS_ERROR_NOT_SAME_THREAD
1.42 + * If is called on a thread other than the one that opened it.
1.43 + */
1.44 + void asyncClose([optional] in mozIStorageCompletionCallback aCallback);
1.45 +
1.46 + /**
1.47 + * Clone a database and make the clone read only if needed.
1.48 + *
1.49 + * @param aReadOnly
1.50 + * If true, the returned database should be put into read-only mode.
1.51 + *
1.52 + * @param aCallback
1.53 + * A callback that will be notified when the operation is complete,
1.54 + * with the following arguments:
1.55 + * - status: the status of the operation
1.56 + * - value: in case of success, an intance of
1.57 + * mozIStorageAsyncConnection cloned from this one.
1.58 + *
1.59 + * @throws NS_ERROR_NOT_SAME_THREAD
1.60 + * If is called on a thread other than the one that opened it.
1.61 + * @throws NS_ERROR_UNEXPECTED
1.62 + * If this connection is a memory database.
1.63 + *
1.64 + * @note If your connection is already read-only, you will get a read-only
1.65 + * clone.
1.66 + * @note Due to a bug in SQLite, if you use the shared cache
1.67 + * (see mozIStorageService), you end up with the same privileges as the
1.68 + * first connection opened regardless of what is specified in aReadOnly.
1.69 + * @note The following pragmas are copied over to a read-only clone:
1.70 + * - cache_size
1.71 + * - temp_store
1.72 + * The following pragmas are copied over to a writeable clone:
1.73 + * - cache_size
1.74 + * - temp_store
1.75 + * - foreign_keys
1.76 + * - journal_size_limit
1.77 + * - synchronous
1.78 + * - wal_autocheckpoint
1.79 + */
1.80 + void asyncClone(in boolean aReadOnly,
1.81 + in mozIStorageCompletionCallback aCallback);
1.82 +
1.83 + /**
1.84 + * The current database nsIFile. Null if the database
1.85 + * connection refers to an in-memory database.
1.86 + */
1.87 + readonly attribute nsIFile databaseFile;
1.88 +
1.89 + //////////////////////////////////////////////////////////////////////////////
1.90 + //// Statement creation
1.91 +
1.92 + /**
1.93 + * Create an asynchronous statement for the given SQL. An
1.94 + * asynchronous statement can only be used to dispatch asynchronous
1.95 + * requests to the asynchronous execution thread and cannot be used
1.96 + * to take any synchronous actions on the database.
1.97 + *
1.98 + * The expression may use ? to indicate sequential numbered arguments,
1.99 + * ?1, ?2 etc. to indicate specific numbered arguments or :name and
1.100 + * $var to indicate named arguments.
1.101 + *
1.102 + * @param aSQLStatement
1.103 + * The SQL statement to execute.
1.104 + * @return a new mozIStorageAsyncStatement
1.105 + * @note The statement is created lazily on first execution.
1.106 + */
1.107 + mozIStorageAsyncStatement createAsyncStatement(in AUTF8String aSQLStatement);
1.108 +
1.109 + /**
1.110 + * Execute an array of statements created with this connection using
1.111 + * any currently bound parameters. When the array contains multiple
1.112 + * statements, the execution is wrapped in a single
1.113 + * transaction. These statements can be reused immediately, and
1.114 + * reset does not need to be called.
1.115 + *
1.116 + * @param aStatements
1.117 + * The array of statements to execute asynchronously, in the order they
1.118 + * are given in the array.
1.119 + * @param aNumStatements
1.120 + * The number of statements in aStatements.
1.121 + * @param aCallback [optional]
1.122 + * The callback object that will be notified of progress, errors, and
1.123 + * completion.
1.124 + * @return an object that can be used to cancel the statements execution.
1.125 + *
1.126 + * @note If you have any custom defined functions, they must be
1.127 + * re-entrant since they can be called on multiple threads.
1.128 + */
1.129 + mozIStoragePendingStatement executeAsync(
1.130 + [array, size_is(aNumStatements)] in mozIStorageBaseStatement aStatements,
1.131 + in unsigned long aNumStatements,
1.132 + [optional] in mozIStorageStatementCallback aCallback
1.133 + );
1.134 +
1.135 + /**
1.136 + * Execute asynchronously an SQL expression, expecting no arguments.
1.137 + *
1.138 + * @param aSQLStatement
1.139 + * The SQL statement to execute
1.140 + * @param aCallback [optional]
1.141 + * The callback object that will be notified of progress, errors, and
1.142 + * completion.
1.143 + * @return an object that can be used to cancel the statement execution.
1.144 + */
1.145 + mozIStoragePendingStatement executeSimpleSQLAsync(
1.146 + in AUTF8String aSQLStatement,
1.147 + [optional] in mozIStorageStatementCallback aCallback);
1.148 +
1.149 + //////////////////////////////////////////////////////////////////////////////
1.150 + //// Functions
1.151 +
1.152 + /**
1.153 + * Create a new SQL function. If you use your connection on multiple threads,
1.154 + * your function needs to be threadsafe, or it should only be called on one
1.155 + * thread.
1.156 + *
1.157 + * @param aFunctionName
1.158 + * The name of function to create, as seen in SQL.
1.159 + * @param aNumArguments
1.160 + * The number of arguments the function takes. Pass -1 for
1.161 + * variable-argument functions.
1.162 + * @param aFunction
1.163 + * The instance of mozIStorageFunction, which implements the function
1.164 + * in question.
1.165 + */
1.166 + void createFunction(in AUTF8String aFunctionName,
1.167 + in long aNumArguments,
1.168 + in mozIStorageFunction aFunction);
1.169 +
1.170 + /**
1.171 + * Create a new SQL aggregate function. If you use your connection on
1.172 + * multiple threads, your function needs to be threadsafe, or it should only
1.173 + * be called on one thread.
1.174 + *
1.175 + * @param aFunctionName
1.176 + * The name of aggregate function to create, as seen in SQL.
1.177 + * @param aNumArguments
1.178 + * The number of arguments the function takes. Pass -1 for
1.179 + * variable-argument functions.
1.180 + * @param aFunction
1.181 + * The instance of mozIStorageAggreagteFunction, which implements the
1.182 + * function in question.
1.183 + */
1.184 + void createAggregateFunction(in AUTF8String aFunctionName,
1.185 + in long aNumArguments,
1.186 + in mozIStorageAggregateFunction aFunction);
1.187 + /**
1.188 + * Delete custom SQL function (simple or aggregate one).
1.189 + *
1.190 + * @param aFunctionName
1.191 + * The name of function to remove.
1.192 + */
1.193 + void removeFunction(in AUTF8String aFunctionName);
1.194 +
1.195 + /**
1.196 + * Sets a progress handler. Only one handler can be registered at a time.
1.197 + * If you need more than one, you need to chain them yourself. This progress
1.198 + * handler should be threadsafe if you use this connection object on more than
1.199 + * one thread.
1.200 + *
1.201 + * @param aGranularity
1.202 + * The number of SQL virtual machine steps between progress handler
1.203 + * callbacks.
1.204 + * @param aHandler
1.205 + * The instance of mozIStorageProgressHandler.
1.206 + * @return previous registered handler.
1.207 + */
1.208 + mozIStorageProgressHandler setProgressHandler(in int32_t aGranularity,
1.209 + in mozIStorageProgressHandler aHandler);
1.210 +
1.211 + /**
1.212 + * Remove a progress handler.
1.213 + *
1.214 + * @return previous registered handler.
1.215 + */
1.216 + mozIStorageProgressHandler removeProgressHandler();
1.217 +};
