The Tor Browser: storage/public/mozIStorageAsyncConnection.idl@97036ab72558 (annotated)

storage/public/mozIStorageAsyncConnection.idl@97036ab72558 (annotated)

storage/public/mozIStorageAsyncConnection.idl

Tue, 06 Jan 2015 21:39:09 +0100

author: Michael Schloh von Bennewitz <michael@schloh.com>
date: Tue, 06 Jan 2015 21:39:09 +0100
branch: TOR_BUG_9701
changeset 8: 97036ab72558
permissions: -rw-r--r--

Conditionally force memory storage according to privacy.thirdparty.isolate;
This solves Tor bug #9701, complying with disk avoidance documented in
https://www.torproject.org/projects/torbrowser/design/#disk-avoidance.

 /* -*- 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();
 };

The Tor Browser / annotate

storage/public/mozIStorageAsyncConnection.idl@97036ab72558 (annotated)

storage/public/mozIStorageAsyncConnection.idl