1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/storage/public/mozIStorageConnection.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,241 @@
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 +#include "mozIStorageAsyncConnection.idl"
1.11 +
1.12 +interface mozIStorageAggregateFunction;
1.13 +interface mozIStorageCompletionCallback;
1.14 +interface mozIStorageFunction;
1.15 +interface mozIStorageProgressHandler;
1.16 +interface mozIStorageBaseStatement;
1.17 +interface mozIStorageStatement;
1.18 +interface mozIStorageAsyncStatement;
1.19 +interface mozIStorageStatementCallback;
1.20 +interface mozIStoragePendingStatement;
1.21 +interface nsIFile;
1.22 +
1.23 +/**
1.24 + * mozIStorageConnection represents a database connection attached to
1.25 + * a specific file or to the in-memory data storage. It is the
1.26 + * primary interface for interacting with a database, including
1.27 + * creating prepared statements, executing SQL, and examining database
1.28 + * errors.
1.29 + *
1.30 + * @note From the main thread, you should rather use mozIStorageAsyncConnection.
1.31 + *
1.32 + * @threadsafe
1.33 + */
1.34 +[scriptable, uuid(4aa2ac47-8d24-4004-9b31-ec0bd85f0cc3)]
1.35 +interface mozIStorageConnection : mozIStorageAsyncConnection {
1.36 + /**
1.37 + * Closes a database connection. Callers must finalize all statements created
1.38 + * for this connection prior to calling this method. It is illegal to use
1.39 + * call this method if any asynchronous statements have been executed on this
1.40 + * connection.
1.41 + *
1.42 + * @throws NS_ERROR_UNEXPECTED
1.43 + * If any statement has been executed asynchronously on this object.
1.44 + * @throws NS_ERROR_UNEXPECTED
1.45 + * If is called on a thread other than the one that opened it.
1.46 + */
1.47 + void close();
1.48 +
1.49 + /**
1.50 + * Clones a database connection and makes the clone read only if needed.
1.51 + *
1.52 + * @param aReadOnly
1.53 + * If true, the returned database should be put into read-only mode.
1.54 + * Defaults to false.
1.55 + * @return the cloned database connection.
1.56 + *
1.57 + * @throws NS_ERROR_UNEXPECTED
1.58 + * If this connection is a memory database.
1.59 + * @note If your connection is already read-only, you will get a read-only
1.60 + * clone.
1.61 + * @note Due to a bug in SQLite, if you use the shared cache (openDatabase),
1.62 + * you end up with the same privileges as the first connection opened
1.63 + * regardless of what is specified in aReadOnly.
1.64 + * @note The following pragmas are copied over to a read-only clone:
1.65 + * - cache_size
1.66 + * - temp_store
1.67 + * The following pragmas are copied over to a writeable clone:
1.68 + * - cache_size
1.69 + * - temp_store
1.70 + * - foreign_keys
1.71 + * - journal_size_limit
1.72 + * - synchronous
1.73 + * - wal_autocheckpoint
1.74 + *
1.75 + */
1.76 + mozIStorageConnection clone([optional] in boolean aReadOnly);
1.77 +
1.78 + /**
1.79 + * The default size for SQLite database pages used by mozStorage for new
1.80 + * databases.
1.81 + */
1.82 + readonly attribute long defaultPageSize;
1.83 +
1.84 + /**
1.85 + * Indicates if the connection is open and ready to use. This will be false
1.86 + * if the connection failed to open, or it has been closed.
1.87 + */
1.88 + readonly attribute boolean connectionReady;
1.89 +
1.90 + /**
1.91 + * lastInsertRowID returns the row ID from the last INSERT
1.92 + * operation.
1.93 + */
1.94 + readonly attribute long long lastInsertRowID;
1.95 +
1.96 + /**
1.97 + * affectedRows returns the number of database rows that were changed or
1.98 + * inserted or deleted by last operation.
1.99 + */
1.100 + readonly attribute long affectedRows;
1.101 +
1.102 + /**
1.103 + * The last error SQLite error code.
1.104 + */
1.105 + readonly attribute long lastError;
1.106 +
1.107 + /**
1.108 + * The last SQLite error as a string (in english, straight from the
1.109 + * sqlite library).
1.110 + */
1.111 + readonly attribute AUTF8String lastErrorString;
1.112 +
1.113 + /**
1.114 + * The schema version of the database. This should not be used until the
1.115 + * database is ready. The schema will be reported as zero if it is not set.
1.116 + */
1.117 + attribute long schemaVersion;
1.118 +
1.119 + //////////////////////////////////////////////////////////////////////////////
1.120 + //// Statement creation
1.121 +
1.122 + /**
1.123 + * Create a mozIStorageStatement for the given SQL expression. The
1.124 + * expression may use ? to indicate sequential numbered arguments,
1.125 + * ?1, ?2 etc. to indicate specific numbered arguments or :name and
1.126 + * $var to indicate named arguments.
1.127 + *
1.128 + * @param aSQLStatement
1.129 + * The SQL statement to execute.
1.130 + * @return a new mozIStorageStatement
1.131 + */
1.132 + mozIStorageStatement createStatement(in AUTF8String aSQLStatement);
1.133 +
1.134 + /**
1.135 + * Execute a SQL expression, expecting no arguments.
1.136 + *
1.137 + * @param aSQLStatement The SQL statement to execute
1.138 + */
1.139 + void executeSimpleSQL(in AUTF8String aSQLStatement);
1.140 +
1.141 + /**
1.142 + * Check if the given table exists.
1.143 + *
1.144 + * @param aTableName
1.145 + * The table to check
1.146 + * @return TRUE if table exists, FALSE otherwise.
1.147 + */
1.148 + boolean tableExists(in AUTF8String aTableName);
1.149 +
1.150 + /**
1.151 + * Check if the given index exists.
1.152 + *
1.153 + * @param aIndexName The index to check
1.154 + * @return TRUE if the index exists, FALSE otherwise.
1.155 + */
1.156 + boolean indexExists(in AUTF8String aIndexName);
1.157 +
1.158 + //////////////////////////////////////////////////////////////////////////////
1.159 + //// Transactions
1.160 +
1.161 + /**
1.162 + * Returns true if a transaction is active on this connection.
1.163 + */
1.164 + readonly attribute boolean transactionInProgress;
1.165 +
1.166 + /**
1.167 + * Begin a new transaction. sqlite default transactions are deferred.
1.168 + * If a transaction is active, throws an error.
1.169 + */
1.170 + void beginTransaction();
1.171 +
1.172 + /**
1.173 + * Begins a new transaction with the given type.
1.174 + */
1.175 + const int32_t TRANSACTION_DEFERRED = 0;
1.176 + const int32_t TRANSACTION_IMMEDIATE = 1;
1.177 + const int32_t TRANSACTION_EXCLUSIVE = 2;
1.178 + void beginTransactionAs(in int32_t transactionType);
1.179 +
1.180 + /**
1.181 + * Commits the current transaction. If no transaction is active,
1.182 + * @throws NS_ERROR_UNEXPECTED.
1.183 + * @throws NS_ERROR_NOT_INITIALIZED.
1.184 + */
1.185 + void commitTransaction();
1.186 +
1.187 + /**
1.188 + * Rolls back the current transaction. If no transaction is active,
1.189 + * @throws NS_ERROR_UNEXPECTED.
1.190 + * @throws NS_ERROR_NOT_INITIALIZED.
1.191 + */
1.192 + void rollbackTransaction();
1.193 +
1.194 + //////////////////////////////////////////////////////////////////////////////
1.195 + //// Tables
1.196 +
1.197 + /**
1.198 + * Create the table with the given name and schema.
1.199 + *
1.200 + * If the table already exists, NS_ERROR_FAILURE is thrown.
1.201 + * (XXX at some point in the future it will check if the schema is
1.202 + * the same as what is specified, but that doesn't happen currently.)
1.203 + *
1.204 + * @param aTableName
1.205 + * The table name to be created, consisting of [A-Za-z0-9_], and
1.206 + * beginning with a letter.
1.207 + * @param aTableSchema
1.208 + * The schema of the table; what would normally go between the parens
1.209 + * in a CREATE TABLE statement: e.g., "foo INTEGER, bar STRING".
1.210 + *
1.211 + * @throws NS_ERROR_FAILURE
1.212 + * If the table already exists or could not be created for any other
1.213 + * reason.
1.214 + */
1.215 + void createTable(in string aTableName,
1.216 + in string aTableSchema);
1.217 +
1.218 + /**
1.219 + * Controls SQLITE_FCNTL_CHUNK_SIZE setting in sqlite. This helps avoid fragmentation
1.220 + * by growing/shrinking the database file in SQLITE_FCNTL_CHUNK_SIZE increments. To
1.221 + * conserve memory on systems short on storage space, this function will have no effect
1.222 + * on mobile devices or if less than 500MiB of space is left available.
1.223 + *
1.224 + * @param aIncrement
1.225 + * The database file will grow in multiples of chunkSize.
1.226 + * @param aDatabaseName
1.227 + * Sqlite database name. "" means pass NULL for zDbName to sqlite3_file_control.
1.228 + * See http://sqlite.org/c3ref/file_control.html for more details.
1.229 + * @throws NS_ERROR_FILE_TOO_BIG
1.230 + * If the system is short on storage space.
1.231 + */
1.232 + void setGrowthIncrement(in int32_t aIncrement, in AUTF8String aDatabaseName);
1.233 +
1.234 + /**
1.235 + * Enable a predefined virtual table implementation.
1.236 + *
1.237 + * @param aModuleName
1.238 + * The module to enable. Only "filesystem" is currently supported.
1.239 + *
1.240 + * @throws NS_ERROR_FAILURE
1.241 + * For unknown module names.
1.242 + */
1.243 + [noscript] void enableModule(in ACString aModuleName);
1.244 +};
