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

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

storage/public/mozIStorageConnection.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"
 #include "mozIStorageAsyncConnection.idl"
 interface mozIStorageAggregateFunction;
 interface mozIStorageCompletionCallback;
 interface mozIStorageFunction;
 interface mozIStorageProgressHandler;
 interface mozIStorageBaseStatement;
 interface mozIStorageStatement;
 interface mozIStorageAsyncStatement;
 interface mozIStorageStatementCallback;
 interface mozIStoragePendingStatement;
 interface nsIFile;
 /**
  * mozIStorageConnection represents a database connection attached to
  * a specific file or to the in-memory data storage.  It is the
  * primary interface for interacting with a database, including
  * creating prepared statements, executing SQL, and examining database
  * errors.
  *
  * @note From the main thread, you should rather use mozIStorageAsyncConnection.
  *
  * @threadsafe
  */
 [scriptable, uuid(4aa2ac47-8d24-4004-9b31-ec0bd85f0cc3)]
 interface mozIStorageConnection : mozIStorageAsyncConnection {
   /**
    * Closes a database connection.  Callers must finalize all statements created
    * for this connection prior to calling this method.  It is illegal to use
    * call this method if any asynchronous statements have been executed on this
    * connection.
    *
    * @throws NS_ERROR_UNEXPECTED
    *         If any statement has been executed asynchronously on this object.
    * @throws NS_ERROR_UNEXPECTED
    *         If is called on a thread other than the one that opened it.
    */
   void close();
   /**
    * Clones a database connection and makes the clone read only if needed.
    *
    * @param aReadOnly
    *        If true, the returned database should be put into read-only mode.
    *        Defaults to false.
    * @return the cloned database connection.
    *
    * @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 (openDatabase),
    *       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
    *
    */
   mozIStorageConnection clone([optional] in boolean aReadOnly);
   /**
    * The default size for SQLite database pages used by mozStorage for new
    * databases.
    */
   readonly attribute long defaultPageSize;
   /**
    * Indicates if the connection is open and ready to use.  This will be false
    * if the connection failed to open, or it has been closed.
    */
   readonly attribute boolean connectionReady;
   /**
    * lastInsertRowID returns the row ID from the last INSERT
    * operation.
    */
   readonly attribute long long lastInsertRowID;
   /**
    * affectedRows returns the number of database rows that were changed or
    * inserted or deleted by last operation.
    */
   readonly attribute long affectedRows;
   /**
    * The last error SQLite error code.
    */
   readonly attribute long lastError;
   /**
    * The last SQLite error as a string (in english, straight from the
    * sqlite library).
    */
   readonly attribute AUTF8String lastErrorString;
   /**
    * The schema version of the database.  This should not be used until the
    * database is ready.  The schema will be reported as zero if it is not set.
    */
   attribute long schemaVersion;
   //////////////////////////////////////////////////////////////////////////////
   //// Statement creation
   /**
    * Create a mozIStorageStatement for the given SQL expression.  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 mozIStorageStatement
    */
   mozIStorageStatement createStatement(in AUTF8String aSQLStatement);
   /**
    * Execute a SQL expression, expecting no arguments.
    *
    * @param aSQLStatement  The SQL statement to execute
    */
   void executeSimpleSQL(in AUTF8String aSQLStatement);
   /**
    * Check if the given table exists.
    *
    * @param aTableName
    *        The table to check
    * @return TRUE if table exists, FALSE otherwise.
    */
   boolean tableExists(in AUTF8String aTableName);
   /**
    * Check if the given index exists.
    *
    * @param aIndexName   The index to check
    * @return TRUE if the index exists, FALSE otherwise.
    */
   boolean indexExists(in AUTF8String aIndexName);
   //////////////////////////////////////////////////////////////////////////////
   //// Transactions
   /**
    * Returns true if a transaction is active on this connection.
    */
   readonly attribute boolean transactionInProgress;
   /**
    * Begin a new transaction.  sqlite default transactions are deferred.
    * If a transaction is active, throws an error.
    */
   void beginTransaction();
   /**
    * Begins a new transaction with the given type.
    */
   const int32_t TRANSACTION_DEFERRED = 0;
   const int32_t TRANSACTION_IMMEDIATE = 1;
   const int32_t TRANSACTION_EXCLUSIVE = 2;
   void beginTransactionAs(in int32_t transactionType);
   /**
    * Commits the current transaction.  If no transaction is active,
    * @throws NS_ERROR_UNEXPECTED.
    * @throws NS_ERROR_NOT_INITIALIZED.
    */
   void commitTransaction();
   /**
    * Rolls back the current transaction.  If no transaction is active,
    * @throws NS_ERROR_UNEXPECTED.
    * @throws NS_ERROR_NOT_INITIALIZED.
    */
   void rollbackTransaction();
   //////////////////////////////////////////////////////////////////////////////
   //// Tables
   /**
    * Create the table with the given name and schema.
    *
    * If the table already exists, NS_ERROR_FAILURE is thrown.
    * (XXX at some point in the future it will check if the schema is
    * the same as what is specified, but that doesn't happen currently.)
    *
    * @param aTableName
    *        The table name to be created, consisting of [A-Za-z0-9_], and
    *        beginning with a letter.
    * @param aTableSchema
    *        The schema of the table; what would normally go between the parens
    *        in a CREATE TABLE statement: e.g., "foo  INTEGER, bar STRING".
    *
    * @throws NS_ERROR_FAILURE
    *         If the table already exists or could not be created for any other
    *         reason.
    */
   void createTable(in string aTableName,
                    in string aTableSchema);
   /**
    * Controls SQLITE_FCNTL_CHUNK_SIZE setting in sqlite. This helps avoid fragmentation
    * by growing/shrinking the database file in SQLITE_FCNTL_CHUNK_SIZE increments. To
    * conserve memory on systems short on storage space, this function will have no effect
    * on mobile devices or if less than 500MiB of space is left available.
    *
    * @param aIncrement
    *        The database file will grow in multiples of chunkSize.
    * @param aDatabaseName
    *        Sqlite database name. "" means pass NULL for zDbName to sqlite3_file_control.
    *        See http://sqlite.org/c3ref/file_control.html for more details.
    * @throws NS_ERROR_FILE_TOO_BIG
    *         If the system is short on storage space.
    */
   void setGrowthIncrement(in int32_t aIncrement, in AUTF8String aDatabaseName);
   /**
    * Enable a predefined virtual table implementation.
    *
    * @param aModuleName
    *        The module to enable. Only "filesystem" is currently supported.
    *
    * @throws NS_ERROR_FAILURE
    *         For unknown module names.
    */
   [noscript] void enableModule(in ACString aModuleName);
 };

The Tor Browser / annotate

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

storage/public/mozIStorageConnection.idl