storage/public/mozIStorageAsyncConnection.idl@b8a032363ba2
storage/public/mozIStorageAsyncConnection.idl
Thu, 22 Jan 2015 13:21:57 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Thu, 22 Jan 2015 13:21:57 +0100
- branch
- TOR_BUG_9701
- changeset 15
- b8a032363ba2
- permissions
- -rw-r--r--
Incorporate requested changes from Mozilla in review:
https://bugzilla.mozilla.org/show_bug.cgi?id=1123480#c6
1 /* -*- Mode: idl; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
2 /* This Source Code Form is subject to the terms of the Mozilla Public
3 * License, v. 2.0. If a copy of the MPL was not distributed with this
4 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
6 #include "nsISupports.idl"
8 interface mozIStorageAggregateFunction;
9 interface mozIStorageCompletionCallback;
10 interface mozIStorageFunction;
11 interface mozIStorageProgressHandler;
12 interface mozIStorageBaseStatement;
13 interface mozIStorageStatement;
14 interface mozIStorageAsyncStatement;
15 interface mozIStorageStatementCallback;
16 interface mozIStoragePendingStatement;
17 interface nsIFile;
19 /**
20 * mozIStorageAsyncConnection represents an asynchronous database
21 * connection attached to a specific file or to an in-memory data
22 * storage. It is the primary interface for interacting with a
23 * database from the main thread, including creating prepared
24 * statements, executing SQL, and examining database errors.
25 */
26 [scriptable, uuid(8bfd34d5-4ddf-4e4b-89dd-9b14f33534c6)]
27 interface mozIStorageAsyncConnection : nsISupports {
28 /**
29 * Close this database connection, allowing all pending statements
30 * to complete first.
31 *
32 * @param aCallback [optional]
33 * A callback that will be notified when the close is completed,
34 * with the following arguments:
35 * - status: the status of the call
36 * - value: |null|
37 *
38 * @throws NS_ERROR_NOT_SAME_THREAD
39 * If is called on a thread other than the one that opened it.
40 */
41 void asyncClose([optional] in mozIStorageCompletionCallback aCallback);
43 /**
44 * Clone a database and make the clone read only if needed.
45 *
46 * @param aReadOnly
47 * If true, the returned database should be put into read-only mode.
48 *
49 * @param aCallback
50 * A callback that will be notified when the operation is complete,
51 * with the following arguments:
52 * - status: the status of the operation
53 * - value: in case of success, an intance of
54 * mozIStorageAsyncConnection cloned from this one.
55 *
56 * @throws NS_ERROR_NOT_SAME_THREAD
57 * If is called on a thread other than the one that opened it.
58 * @throws NS_ERROR_UNEXPECTED
59 * If this connection is a memory database.
60 *
61 * @note If your connection is already read-only, you will get a read-only
62 * clone.
63 * @note Due to a bug in SQLite, if you use the shared cache
64 * (see mozIStorageService), you end up with the same privileges as the
65 * first connection opened regardless of what is specified in aReadOnly.
66 * @note The following pragmas are copied over to a read-only clone:
67 * - cache_size
68 * - temp_store
69 * The following pragmas are copied over to a writeable clone:
70 * - cache_size
71 * - temp_store
72 * - foreign_keys
73 * - journal_size_limit
74 * - synchronous
75 * - wal_autocheckpoint
76 */
77 void asyncClone(in boolean aReadOnly,
78 in mozIStorageCompletionCallback aCallback);
80 /**
81 * The current database nsIFile. Null if the database
82 * connection refers to an in-memory database.
83 */
84 readonly attribute nsIFile databaseFile;
86 //////////////////////////////////////////////////////////////////////////////
87 //// Statement creation
89 /**
90 * Create an asynchronous statement for the given SQL. An
91 * asynchronous statement can only be used to dispatch asynchronous
92 * requests to the asynchronous execution thread and cannot be used
93 * to take any synchronous actions on the database.
94 *
95 * The expression may use ? to indicate sequential numbered arguments,
96 * ?1, ?2 etc. to indicate specific numbered arguments or :name and
97 * $var to indicate named arguments.
98 *
99 * @param aSQLStatement
100 * The SQL statement to execute.
101 * @return a new mozIStorageAsyncStatement
102 * @note The statement is created lazily on first execution.
103 */
104 mozIStorageAsyncStatement createAsyncStatement(in AUTF8String aSQLStatement);
106 /**
107 * Execute an array of statements created with this connection using
108 * any currently bound parameters. When the array contains multiple
109 * statements, the execution is wrapped in a single
110 * transaction. These statements can be reused immediately, and
111 * reset does not need to be called.
112 *
113 * @param aStatements
114 * The array of statements to execute asynchronously, in the order they
115 * are given in the array.
116 * @param aNumStatements
117 * The number of statements in aStatements.
118 * @param aCallback [optional]
119 * The callback object that will be notified of progress, errors, and
120 * completion.
121 * @return an object that can be used to cancel the statements execution.
122 *
123 * @note If you have any custom defined functions, they must be
124 * re-entrant since they can be called on multiple threads.
125 */
126 mozIStoragePendingStatement executeAsync(
127 [array, size_is(aNumStatements)] in mozIStorageBaseStatement aStatements,
128 in unsigned long aNumStatements,
129 [optional] in mozIStorageStatementCallback aCallback
130 );
132 /**
133 * Execute asynchronously an SQL expression, expecting no arguments.
134 *
135 * @param aSQLStatement
136 * The SQL statement to execute
137 * @param aCallback [optional]
138 * The callback object that will be notified of progress, errors, and
139 * completion.
140 * @return an object that can be used to cancel the statement execution.
141 */
142 mozIStoragePendingStatement executeSimpleSQLAsync(
143 in AUTF8String aSQLStatement,
144 [optional] in mozIStorageStatementCallback aCallback);
146 //////////////////////////////////////////////////////////////////////////////
147 //// Functions
149 /**
150 * Create a new SQL function. If you use your connection on multiple threads,
151 * your function needs to be threadsafe, or it should only be called on one
152 * thread.
153 *
154 * @param aFunctionName
155 * The name of function to create, as seen in SQL.
156 * @param aNumArguments
157 * The number of arguments the function takes. Pass -1 for
158 * variable-argument functions.
159 * @param aFunction
160 * The instance of mozIStorageFunction, which implements the function
161 * in question.
162 */
163 void createFunction(in AUTF8String aFunctionName,
164 in long aNumArguments,
165 in mozIStorageFunction aFunction);
167 /**
168 * Create a new SQL aggregate function. If you use your connection on
169 * multiple threads, your function needs to be threadsafe, or it should only
170 * be called on one thread.
171 *
172 * @param aFunctionName
173 * The name of aggregate function to create, as seen in SQL.
174 * @param aNumArguments
175 * The number of arguments the function takes. Pass -1 for
176 * variable-argument functions.
177 * @param aFunction
178 * The instance of mozIStorageAggreagteFunction, which implements the
179 * function in question.
180 */
181 void createAggregateFunction(in AUTF8String aFunctionName,
182 in long aNumArguments,
183 in mozIStorageAggregateFunction aFunction);
184 /**
185 * Delete custom SQL function (simple or aggregate one).
186 *
187 * @param aFunctionName
188 * The name of function to remove.
189 */
190 void removeFunction(in AUTF8String aFunctionName);
192 /**
193 * Sets a progress handler. Only one handler can be registered at a time.
194 * If you need more than one, you need to chain them yourself. This progress
195 * handler should be threadsafe if you use this connection object on more than
196 * one thread.
197 *
198 * @param aGranularity
199 * The number of SQL virtual machine steps between progress handler
200 * callbacks.
201 * @param aHandler
202 * The instance of mozIStorageProgressHandler.
203 * @return previous registered handler.
204 */
205 mozIStorageProgressHandler setProgressHandler(in int32_t aGranularity,
206 in mozIStorageProgressHandler aHandler);
208 /**
209 * Remove a progress handler.
210 *
211 * @return previous registered handler.
212 */
213 mozIStorageProgressHandler removeProgressHandler();
214 };
