mozIStorageAsyncConnection.idl (18418B)
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/. */ 5 6 #include "nsISupports.idl" 7 8 interface mozIStorageCompletionCallback; 9 interface mozIStorageFunction; 10 interface mozIStorageProgressHandler; 11 interface mozIStorageBaseStatement; 12 interface mozIStorageStatement; 13 interface mozIStorageAsyncStatement; 14 interface mozIStorageStatementCallback; 15 interface mozIStoragePendingStatement; 16 interface nsIFile; 17 18 /** 19 * mozIStorageAsyncConnection represents an asynchronous database 20 * connection attached to a specific file or to an in-memory data 21 * storage. It is the primary interface for interacting with a 22 * database from the main thread, including creating prepared 23 * statements, executing SQL, and examining database errors. 24 */ 25 [scriptable, uuid(8bfd34d5-4ddf-4e4b-89dd-9b14f33534c6)] 26 interface mozIStorageAsyncConnection : nsISupports { 27 /** 28 * Transaction behavior constants. 29 */ 30 const int32_t TRANSACTION_DEFAULT = -1; 31 const int32_t TRANSACTION_DEFERRED = 0; 32 const int32_t TRANSACTION_IMMEDIATE = 1; 33 const int32_t TRANSACTION_EXCLUSIVE = 2; 34 35 /** 36 * The default behavior for all transactions run on this connection. Defaults 37 * to `TRANSACTION_DEFERRED`, and can be overridden for individual 38 * transactions. 39 */ 40 attribute int32_t defaultTransactionType; 41 42 /** 43 * The maximum number of bound parameters for statements executed on this 44 * connection. If your statement has more params than this limit, you'll 45 * need to chunk them into multiple statements. See `PlacesUtils.chunkArray` 46 * and its callers in Places for examples of how to do this, or read on for 47 * an overview. 48 * 49 * Keep in mind that the variable limit is for the _total_ number of 50 * parameters, including ones bound by name (using the `:VVV`, `@VVV`, or 51 * `?VVV` syntax) and index (`?` and `?NNN`). 52 * 53 * This means, when chunking: 54 * 55 * - If you're binding 1 param per 1 value per chunk (for example, if you 56 * have a list of GUIDs and a clause like `WHERE guid IN (?, ?, ?, ...)`, 57 * your chunk length is just `variableLimit`. 58 * - If you're binding 1 param per 1 value per chunk, but using that 59 * param in multiple positions in the query (for example, `WHERE url_hash 60 * IN (hash(?1), hash(?2), ...) AND url IN (?1, ?2, ...)`), you can use the 61 * `?NNN` syntax with a chunk length of `variableLimit`. 62 * - If you're binding N params per 1 value per chunk (for example, if you 63 * have a list of items with GUIDs and parent GUIDs, and you want to bind 64 * both), your chunk length is `variableLimit / N`, since you're binding 65 * two params for each element. 66 * - If you're binding K params per L values per chunk, plus M fixed ones 67 * (for example, `WHERE parentGuid = :parentGuid AND guid IN (?, ?, ...)`), 68 * your chunk length is `variableLimit - M`, to ensure there's space for the 69 * fixed variables. 70 * 71 * If you bind more params than this limit, `create{Async}Statement` will 72 * fail with a "too many SQL variables" error. 73 * It's possible to lower the limit, but it's not possible to set it higher 74 * than the default value, passing an higher value will silently truncate to 75 * the default. Lowering the limit is particularly useful for testing code 76 * that may bind many variables. 77 */ 78 attribute int32_t variableLimit; 79 80 /** 81 * Returns true if a transaction is active on this connection. 82 * 83 * Note that this is true if a transaction is active on the connection, 84 * regardless of how it was opened. There are several ways to open one: 85 * 86 * 1. Explicitly calling `beginTransaction` on a `mozIStorageConnection`. 87 * 2. Calling `executeSimpleSQL("BEGIN")` or 88 * `createStatement("BEGIN").execute()` on a `mozIStorageConnection`. 89 * 3. Executing an async statement, like 90 * `createAsyncStatement("BEGIN").executeAsync(...)`. This is what 91 * `Sqlite.sys.mjs` does under the hood. 92 * 93 * Because of this, it's important *not* to use this attribute to decide 94 * whether to *commit* the active transaction, because the caller that opened 95 * it may not expect that. This is why both `mozStorageTransaction` and 96 * `Sqlite.sys.mjs` use an internal variable (`mHasTransaction` for the former; 97 * `_hasInProgressTransaction` for the latter) to check if their transaction 98 * is already in progress, instead of just checking this attribute before 99 * committing. Otherwise, mozStorage might accidentally commit (or roll back!) 100 * a transaction started by `Sqlite.sys.mjs`, and vice versa. 101 */ 102 readonly attribute boolean transactionInProgress; 103 104 /** 105 * Close this database connection, allowing all pending statements 106 * to complete first. 107 * 108 * @param aCallback [optional] 109 * A callback that will be notified when the close is completed, 110 * with the following arguments: 111 * - status: the status of the call 112 * - value: |null| 113 * 114 * @throws NS_ERROR_NOT_SAME_THREAD 115 * If called on a thread other than the one that opened it. The 116 * callback will not be dispatched. 117 * @throws NS_ERROR_NOT_INITIALIZED 118 * If called on a connection that has already been closed or was 119 * never properly opened. The callback will still be dispatched 120 * to the main thread despite the returned error. 121 * @note If this call should fail, the callback won't be invoked. 122 */ 123 void asyncClose([optional] in mozIStorageCompletionCallback aCallback); 124 125 /** 126 * Forcibly closes a database connection synchronously. 127 * This should only be used when it's required to close and replace the 128 * database synchronously to return control to the consumer, for example in 129 * case of a detected corruption on database opening. 130 * Since this spins the events loop, it should be used only in very particular 131 * and rare situations, or it may cause unexpected consequences (crashes). 132 * 133 * @throws NS_ERROR_NOT_SAME_THREAD 134 * If called on a thread other than the one that opened it. 135 */ 136 [noscript] void spinningSynchronousClose(); 137 138 /** 139 * Clone a database connection and make the clone read only if needed. 140 * SQL Functions and attached on-disk databases are applied to the new clone. 141 * 142 * @param aReadOnly 143 * If true, the returned database should be put into read-only mode. 144 * 145 * @param aCallback 146 * A callback that will be notified when the operation is complete, 147 * with the following arguments: 148 * - status: the status of the operation 149 * - value: in case of success, an intance of 150 * mozIStorageAsyncConnection cloned from this one. 151 * 152 * @throws NS_ERROR_NOT_SAME_THREAD 153 * If is called on a thread other than the one that opened it. 154 * @throws NS_ERROR_UNEXPECTED 155 * If this connection is a memory database. 156 * 157 * @note If your connection is already read-only, you will get a read-only 158 * clone. 159 * @note The resulting connection will implement `mozIStorageConnection`, but 160 * all synchronous methods will throw if called from the main thread. 161 * @note Due to a bug in SQLite, if you use the shared cache 162 * (see mozIStorageService), you end up with the same privileges as the 163 * first connection opened regardless of what is specified in aReadOnly. 164 * @note The following pragmas are copied over to a read-only clone: 165 * - cache_size 166 * - temp_store 167 * The following pragmas are copied over to a writeable clone: 168 * - cache_size 169 * - temp_store 170 * - foreign_keys 171 * - journal_size_limit 172 * - synchronous 173 * - wal_autocheckpoint 174 * All SQL functions are copied over to read-only and writeable clones. 175 * Additionally, all temporary tables, triggers, and views, as well as 176 * any indexes on temporary tables, are copied over to writeable clones. 177 * For temporary tables, only the schemas are copied, not their 178 * contents. 179 */ 180 void asyncClone(in boolean aReadOnly, 181 in mozIStorageCompletionCallback aCallback); 182 183 /** 184 * The current database nsIFile. Null if the database 185 * connection refers to an in-memory database. 186 */ 187 readonly attribute nsIFile databaseFile; 188 189 /** 190 * Causes any pending database operation to abort and return at the first 191 * opportunity. 192 * @note this cannot be used on mozIStorageConnection unless the connection is 193 * explicitly marked as `interruptible`. For more details, please 194 * refer to CONNECTION_INTERRUPTIBLE in mozIStorageService. 195 * @note operations that are nearly complete may still be able to complete. 196 * @throws if used on an unsupported connection type, or a closed connection. 197 */ 198 void interrupt(); 199 200 /** 201 * Vacuum the main database plus all the attached one. 202 * If the database is in auto_vacuum = INCREMENTAL mode, this executes an 203 * incremental_vacuum, otherwise it will always execute a full vacuum. 204 * 205 * While it's possible to invoke this method directly, it's suggested, when 206 * possible, to use the VacuumManager instead. 207 * That means registering your component for the "vacuum-participant" XPCOM 208 * category, and implement the mozIStorageVacuumParticipant interface. 209 * 210 * @param [aCallback] Completion callback invoked once the operation is 211 * complete. 212 * @param [aUseIncremental] When set to true, this will try to convert the 213 * main schema to auto_vacuum = INCREMENTAL mode, if it's not set yet. 214 * When set to false, it will try to set auto_vacuum = NONE. 215 * Note a full vacuum will be executed if the auto_vacuum mode must be 216 * changed, otherwise an incremental vacuum will happen if the database 217 * is already in INCREMENTAL mode. 218 * @param [aSetPageSize] This can be used to change the database page_size, a 219 * full vacuum will be executed to persist the change. If the page 220 * size is already correct, or you pass 0, this will be a no-op. 221 * @throws If it's not possible to start the async vacuum operation, note in 222 * this case the callback won't be invoked. 223 * @note Vacuum will fail inside a transaction, or if there is an ongoing 224 * read statement. 225 */ 226 void asyncVacuum( 227 [optional] in mozIStorageCompletionCallback aCallback, 228 [optional] in boolean aUseIncremental, 229 [optional] in long aSetPageSize 230 ); 231 232 ////////////////////////////////////////////////////////////////////////////// 233 //// Statement creation 234 235 /** 236 * Create an asynchronous statement for the given SQL. An 237 * asynchronous statement can only be used to dispatch asynchronous 238 * requests to the asynchronous execution thread and cannot be used 239 * to take any synchronous actions on the database. 240 * 241 * The expression may use ? to indicate sequential numbered arguments, 242 * ?1, ?2 etc. to indicate specific numbered arguments or :name and 243 * $var to indicate named arguments. 244 * 245 * @param aSQLStatement 246 * The SQL statement to execute. 247 * @return a new mozIStorageAsyncStatement 248 * @note The statement is created lazily on first execution. 249 */ 250 mozIStorageAsyncStatement createAsyncStatement(in AUTF8String aSQLStatement); 251 252 /** 253 * Execute an array of statements created with this connection using 254 * any currently bound parameters. When the array contains multiple 255 * statements, the execution is wrapped in a single 256 * transaction. These statements can be reused immediately, and 257 * reset does not need to be called. 258 * 259 * @param aStatements 260 * The array of statements to execute asynchronously, in the order they 261 * are given in the array. 262 * @param aCallback [optional] 263 * The callback object that will be notified of progress, errors, and 264 * completion. 265 * @return an object that can be used to cancel the statements execution. 266 * 267 * @note If you have any custom defined functions, they must be 268 * re-entrant since they can be called on multiple threads. 269 */ 270 mozIStoragePendingStatement executeAsync( 271 in Array<mozIStorageBaseStatement> aStatements, 272 [optional] in mozIStorageStatementCallback aCallback 273 ); 274 275 /** 276 * Execute asynchronously an SQL expression, expecting no arguments. 277 * 278 * @param aSQLStatement 279 * The SQL statement to execute 280 * @param aCallback [optional] 281 * The callback object that will be notified of progress, errors, and 282 * completion. 283 * @return an object that can be used to cancel the statement execution. 284 */ 285 mozIStoragePendingStatement executeSimpleSQLAsync( 286 in AUTF8String aSQLStatement, 287 [optional] in mozIStorageStatementCallback aCallback); 288 289 290 /** 291 * Loads a Sqlite Run-Time Loadable Extension as defined at 292 * https://www.sqlite.org/loadext.html. 293 * Only a predetermined list of extensions can be loaded, that are statically 294 * linked in the shared library containing SQLite. The currently supported 295 * extensions are: 296 * - fts5 297 * A Full-Text search module, see https://www.sqlite.org/fts5.html 298 * 299 * New extensions can be added to the third_party/sqlite3/ext/ folder and then 300 * to this list, after a Storage peer has reviewed the request by verifying 301 * licensing, and code reliability. 302 * Extensions that must be loaded for all the connections should instead use 303 * sqlite3_auto_extension() (this must happen after sqlite3_config(), as it 304 * implicitly calls sqlite3_initialize()). 305 * 306 * @param aExtensionName 307 * The extension to load, see the above list for supported values. 308 * @param aCallback 309 * A callback that will be notified when the operation is complete, 310 * with the following arguments: 311 * - status: the status of the operation, use this to check if loading 312 * the extension was successful as it may be partly asynchronous. 313 * - value: unused. 314 * @throws NS_ERROR_INVALID_ARG 315 * For unsupported extension names. 316 * @throws NS_ERROR_NOT_INITIALIZED 317 * If the connection is not open. 318 * @throws NS_ERROR_UEXPECTED 319 * If it was not possible to enable extensions loading. 320 */ 321 void loadExtension(in AUTF8String aExtensionName, 322 [optional] in mozIStorageCompletionCallback aCallback); 323 324 ////////////////////////////////////////////////////////////////////////////// 325 //// Functions 326 327 /** 328 * Create a new SQL function. If you use your connection on multiple threads, 329 * your function needs to be threadsafe, or it should only be called on one 330 * thread. 331 * 332 * @param aFunctionName 333 * The name of function to create, as seen in SQL. 334 * @param aNumArguments 335 * The number of arguments the function takes. Pass -1 for 336 * variable-argument functions. 337 * @param aFunction 338 * The instance of mozIStorageFunction, which implements the function 339 * in question. 340 */ 341 void createFunction(in AUTF8String aFunctionName, 342 in long aNumArguments, 343 in mozIStorageFunction aFunction); 344 345 /** 346 * Delete custom SQL function. 347 * 348 * @param aFunctionName 349 * The name of function to remove. 350 */ 351 void removeFunction(in AUTF8String aFunctionName); 352 353 /** 354 * Sets a progress handler. Only one handler can be registered at a time. 355 * If you need more than one, you need to chain them yourself. This progress 356 * handler should be threadsafe if you use this connection object on more than 357 * one thread. 358 * 359 * @param aGranularity 360 * The number of SQL virtual machine steps between progress handler 361 * callbacks. 362 * @param aHandler 363 * The instance of mozIStorageProgressHandler. 364 * @return previous registered handler. 365 */ 366 mozIStorageProgressHandler setProgressHandler(in int32_t aGranularity, 367 in mozIStorageProgressHandler aHandler); 368 369 /** 370 * Remove a progress handler. 371 * 372 * @return previous registered handler. 373 */ 374 mozIStorageProgressHandler removeProgressHandler(); 375 376 /** 377 * Makes a copy of a database asynchronously. This method can do an online 378 * backup of the database file, even if there are open connections actively 379 * using it (as a normal file copy can only be made if no connections are 380 * open on the database). 381 * 382 * While the copy is in the process of being made, the destination file 383 * will have a .tmp extension appended to it. In the event of a crash 384 * during the copy, this .tmp file will continue to exist, but will be 385 * an unusable partial copy. 386 * 387 * Once the copy has been completed, this method will automatically remove 388 * the .tmp extension. 389 * 390 * @param aDestinationFile 391 * The destination on the file system to write the database copy. 392 * @param aCallback 393 * A callback that will be notified when the operation is complete, 394 * with the following arguments: 395 * - status: the status of the operation, use this to check if making 396 * the copy was successful. 397 * - value: unused. 398 * @param [aPagesPerStep=5] 399 * The number of pages in the database to copy per step. Defaults to 5 400 * if omitted or set to 0. 401 * @param [aStepDelayMs=250] 402 * The number of milliseconds to wait between each step. Defaults to 403 * 250 if omitted or set to 0. 404 * @throws NS_ERROR_ABORT 405 * If the application has begun the process of shutting down already. 406 * @throws NS_ERROR_NOT_INITIALIZED 407 * If the connection has already started or completed closing. 408 * @throws NS_ERROR_NOT_AVAILABLE 409 * If the database does not support asynchronous operations. 410 * @throws NS_ERROR_NOT_INITIALIZED 411 * If the execution thread cannot be acquired. 412 */ 413 void backupToFileAsync(in nsIFile aDestinationFile, 414 in mozIStorageCompletionCallback aCallback, 415 [optional] in unsigned long aPagesPerStep, 416 [optional] in unsigned long aStepDelayMs); 417 };