mozIStorageConnection.idl (9704B)
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 #include "mozIStorageAsyncConnection.idl" 8 9 %{C++ 10 namespace mozilla::dom::quota { 11 class QuotaObject; 12 } 13 14 namespace mozilla::storage { 15 class SQLiteMutex; 16 class SQLiteMutexAutoLock; 17 } 18 19 %} 20 21 [ptr] native QuotaObject(mozilla::dom::quota::QuotaObject); 22 native SQLiteMutex(mozilla::storage::SQLiteMutex&); 23 native SQLiteMutexAutoLock(const mozilla::storage::SQLiteMutexAutoLock&); 24 25 interface mozIStorageAggregateFunction; 26 interface mozIStorageCompletionCallback; 27 interface mozIStorageFunction; 28 interface mozIStorageProgressHandler; 29 interface mozIStorageBaseStatement; 30 interface mozIStorageStatement; 31 interface mozIStorageAsyncStatement; 32 interface mozIStorageStatementCallback; 33 interface mozIStoragePendingStatement; 34 interface nsIFile; 35 36 /** 37 * mozIStorageConnection represents a database connection attached to 38 * a specific file or to the in-memory data storage. It is the 39 * primary interface for interacting with a database, including 40 * creating prepared statements, executing SQL, and examining database 41 * errors. 42 * 43 * @note From the main thread, you should rather use mozIStorageAsyncConnection. 44 * 45 * @threadsafe 46 */ 47 [scriptable, builtinclass, uuid(4aa2ac47-8d24-4004-9b31-ec0bd85f0cc3)] 48 interface mozIStorageConnection : mozIStorageAsyncConnection { 49 /** 50 * Closes a database connection. Callers must finalize all statements created 51 * for this connection prior to calling this method. It is illegal to use 52 * call this method if any asynchronous statements have been executed on this 53 * connection. 54 * 55 * @throws NS_ERROR_UNEXPECTED 56 * If any statement has been executed asynchronously on this object. 57 * @throws NS_ERROR_UNEXPECTED 58 * If is called on a thread other than the one that opened it. 59 */ 60 void close(); 61 62 /** 63 * Clones a database connection and makes the clone read only if needed. 64 * SQL Functions and attached on-disk databases are applied to the new clone. 65 * 66 * @param aReadOnly 67 * If true, the returned database should be put into read-only mode. 68 * Defaults to false. 69 * @return the cloned database connection. 70 * 71 * @throws NS_ERROR_UNEXPECTED 72 * If this connection is a memory database. 73 * @note If your connection is already read-only, you will get a read-only 74 * clone. 75 * @note Due to a bug in SQLite, if you use the shared cache (openDatabase), 76 * you end up with the same privileges as the first connection opened 77 * regardless of what is specified in aReadOnly. 78 * @note The following pragmas are copied over to a read-only clone: 79 * - cache_size 80 * - temp_store 81 * The following pragmas are copied over to a writeable clone: 82 * - cache_size 83 * - temp_store 84 * - foreign_keys 85 * - journal_size_limit 86 * - synchronous 87 * - wal_autocheckpoint 88 * All SQL functions are copied over to read-only and writeable clones. 89 * Additionally, all temporary tables, triggers, and views, as well as 90 * any indexes on temporary tables, are copied over to writeable clones. 91 * For temporary tables, only the schemas are copied, not their 92 * contents. 93 * 94 */ 95 mozIStorageConnection clone([optional] in boolean aReadOnly); 96 97 /** 98 * The default size for SQLite database pages used by mozStorage for new 99 * databases. 100 */ 101 readonly attribute long defaultPageSize; 102 103 /** 104 * Indicates if the connection is open and ready to use. This will be false 105 * if the connection failed to open, or it has been closed. 106 */ 107 readonly attribute boolean connectionReady; 108 109 /** 110 * lastInsertRowID returns the row ID from the last INSERT 111 * operation. 112 */ 113 readonly attribute long long lastInsertRowID; 114 115 /** 116 * affectedRows returns the number of database rows that were changed or 117 * inserted or deleted by last operation. 118 */ 119 readonly attribute long affectedRows; 120 121 /** 122 * The last error SQLite error code. 123 */ 124 readonly attribute long lastError; 125 126 /** 127 * The last SQLite error as a string (in english, straight from the 128 * sqlite library). 129 */ 130 readonly attribute AUTF8String lastErrorString; 131 132 /** 133 * The schema version of the database. This should not be used until the 134 * database is ready. The schema will be reported as zero if it is not set. 135 */ 136 attribute long schemaVersion; 137 138 ////////////////////////////////////////////////////////////////////////////// 139 //// Statement creation 140 141 /** 142 * Create a mozIStorageStatement for the given SQL expression. The 143 * expression may use ? to indicate sequential numbered arguments, 144 * ?1, ?2 etc. to indicate specific numbered arguments or :name and 145 * $var to indicate named arguments. 146 * 147 * @param aSQLStatement 148 * The SQL statement to execute. 149 * @return a new mozIStorageStatement 150 */ 151 mozIStorageStatement createStatement(in AUTF8String aSQLStatement); 152 153 /** 154 * Execute a SQL expression, expecting no arguments. 155 * 156 * @param aSQLStatement The SQL statement to execute 157 */ 158 void executeSimpleSQL(in AUTF8String aSQLStatement); 159 160 /** 161 * Check if the given table exists. 162 * 163 * @param aTableName 164 * The table to check 165 * @return TRUE if table exists, FALSE otherwise. 166 */ 167 boolean tableExists(in AUTF8String aTableName); 168 169 /** 170 * Check if the given index exists. 171 * 172 * @param aIndexName The index to check 173 * @return TRUE if the index exists, FALSE otherwise. 174 */ 175 boolean indexExists(in AUTF8String aIndexName); 176 177 ////////////////////////////////////////////////////////////////////////////// 178 //// Transactions 179 180 /** 181 * Begin a new transaction. If a transaction is active, throws an error. 182 */ 183 void beginTransaction(); 184 185 /** 186 * Commits the current transaction. If no transaction is active, 187 * @throws NS_ERROR_UNEXPECTED. 188 * @throws NS_ERROR_NOT_INITIALIZED. 189 */ 190 void commitTransaction(); 191 192 /** 193 * Rolls back the current transaction. If no transaction is active, 194 * @throws NS_ERROR_UNEXPECTED. 195 * @throws NS_ERROR_NOT_INITIALIZED. 196 */ 197 void rollbackTransaction(); 198 199 ////////////////////////////////////////////////////////////////////////////// 200 //// Tables 201 202 /** 203 * Create the table with the given name and schema. 204 * 205 * If the table already exists, NS_ERROR_FAILURE is thrown. 206 * (XXX at some point in the future it will check if the schema is 207 * the same as what is specified, but that doesn't happen currently.) 208 * 209 * @param aTableName 210 * The table name to be created, consisting of [A-Za-z0-9_], and 211 * beginning with a letter. 212 * @param aTableSchema 213 * The schema of the table; what would normally go between the parens 214 * in a CREATE TABLE statement: e.g., "foo INTEGER, bar STRING". 215 * 216 * @throws NS_ERROR_FAILURE 217 * If the table already exists or could not be created for any other 218 * reason. 219 */ 220 void createTable(in string aTableName, 221 in string aTableSchema); 222 223 /** 224 * Controls SQLITE_FCNTL_CHUNK_SIZE setting in sqlite. This helps avoid fragmentation 225 * by growing/shrinking the database file in SQLITE_FCNTL_CHUNK_SIZE increments. To 226 * conserve memory on systems short on storage space, this function will have no effect 227 * on mobile devices or if less than 500MiB of space is left available. 228 * 229 * @param aIncrement 230 * The database file will grow in multiples of chunkSize. 231 * @param aDatabaseName 232 * Sqlite database name. "" means pass NULL for zDbName to sqlite3_file_control. 233 * See http://sqlite.org/c3ref/file_control.html for more details. 234 * @throws NS_ERROR_FILE_TOO_BIG 235 * If the system is short on storage space. 236 */ 237 void setGrowthIncrement(in int32_t aIncrement, in AUTF8String aDatabaseName); 238 239 /** 240 * Enable a predefined virtual table implementation. 241 * 242 * @param aModuleName 243 * The module to enable. Only "filesystem" is currently supported. 244 * 245 * @throws NS_ERROR_FAILURE 246 * For unknown module names. 247 */ 248 [noscript] void enableModule(in ACString aModuleName); 249 250 /** 251 * Get quota objects. 252 * 253 * @param[out] aDatabaseQuotaObject 254 * The QuotaObject associated with the database file. 255 * @param[out] aJournalQuotaObject 256 * The QuotaObject associated with the journal file. 257 * 258 * @throws NS_ERROR_NOT_INITIALIZED. 259 */ 260 [noscript] void getQuotaObjects(out QuotaObject aDatabaseQuotaObject, 261 out QuotaObject aJournalQuotaObject); 262 263 /** 264 * The mutex used for protection of operations (BEGIN/COMMIT/ROLLBACK) in 265 * mozStorageTransaction. The lock must be held in a way that spans whole 266 * operation, not just when accessing the nesting level. 267 */ 268 [notxpcom, nostdcall] readonly attribute SQLiteMutex sharedDBMutex; 269 270 /** 271 * Helper methods for managing the transaction nesting level. The methods 272 * must be called with a proof of lock. Currently only used by 273 * mozStorageTransaction. 274 */ 275 [notxpcom, nostdcall] unsigned long getTransactionNestingLevel( 276 in SQLiteMutexAutoLock aProofOfLock); 277 278 [notxpcom, nostdcall] unsigned long increaseTransactionNestingLevel( 279 in SQLiteMutexAutoLock aProofOfLock); 280 281 [notxpcom, nostdcall] unsigned long decreaseTransactionNestingLevel( 282 in SQLiteMutexAutoLock aProofOfLock); 283 };