mozIStorageService.idl (12278B)
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 %{C++ 9 10 #include "nsLiteralString.h" 11 12 %} 13 14 interface mozIStorageConnection; 15 interface nsIFile; 16 interface nsIFileURL; 17 interface nsIPropertyBag2; 18 interface nsIVariant; 19 interface mozIStorageCompletionCallback; 20 21 /** 22 * PRIVACY WARNING 23 * =============== 24 * 25 * Database file names can be exposed through telemetry and in crash reports on 26 * the https://crash-stats.mozilla.org site, to allow recognizing the affected 27 * database. 28 * if your database name may contain privacy sensitive information, e.g. an 29 * URL origin, you should use openDatabaseWithFileURL and pass an explicit 30 * TelemetryFilename to it. That name will be used both for telemetry and for 31 * thread names in crash reports. 32 * If you have different needs (e.g. using the javascript module or an async 33 * connection from the main thread) please coordinate with the mozStorage peers. 34 */ 35 36 /** 37 * The mozIStorageService interface is intended to be implemented by 38 * a service that can create storage connections (mozIStorageConnection) 39 * to either a well-known profile database or to a specific database file. 40 * 41 * This is the only way to open a database connection. 42 * 43 * @note The first reference to mozIStorageService must be made on the main 44 * thread. 45 */ 46 [scriptable, uuid(07b6b2f5-6d97-47b4-9584-e65bc467fe9e)] 47 interface mozIStorageService : nsISupports { 48 /** 49 * Open the database with default flags in default mode. 50 */ 51 const unsigned long OPEN_DEFAULT = 0; 52 53 /** 54 * Open the database with a shared cache. The shared-cache mode 55 * is more memory-efficient when many connections to the same database 56 * are expected, though, the connections will contend the cache resource. 57 * When performance matters, working without a shared-cache will 58 * improve concurrency. @see openUnsharedDatabase 59 */ 60 const unsigned long OPEN_SHARED = 1 << 0; 61 62 /** 63 * Open the underlying database in read-only mode. 64 */ 65 const unsigned long OPEN_READONLY = 1 << 1; 66 67 /** 68 * Allow simultaneous access to an asynchronous read-only database 69 * without any file locking. 70 * 71 * For synchronous database, the flag has no effect. 72 * 73 * Specifying the OPEN_IGNORE_LOCKING_MODE flag will automatically 74 * turn on the OPEN_READONLY flag. 75 */ 76 const unsigned long OPEN_IGNORE_LOCKING_MODE = 1 << 2; 77 78 /** 79 * Allow multi-process access to the database file. 80 * Normally this option is disabled as exclusive locking performs better 81 * and provides some protection against third party manipulation of hot 82 * databases. Note however this option only shows its effects on Unix 83 * systems because exclusive locking is not yet implemented on Windows. 84 */ 85 const unsigned long OPEN_NOT_EXCLUSIVE = 1 << 3; 86 87 /** 88 * All optional connection object features are off. 89 */ 90 const unsigned long CONNECTION_DEFAULT = 0; 91 92 /** 93 * Enable Interrupt-method for the synchronous connection object 94 * returned by openDatabase, openSpecialDatabase, openUnsharedDatabase 95 * or openDatabaseWithFileURL calls. 96 * 97 * When this flag is not set, Interrupt-method of a 98 * synchronous connection must not be used. 99 * 100 * Asynchronous connection is always interruptible and the flag 101 * does not change anything. 102 * 103 * The following are among the potential risks side effects of 104 * calling the Interrupt-method: 105 * - new queries started on a different thread after the 106 * interrupt call, but before its completion, are interrupted as if 107 * they had been running prior to the interrupt call. Thus thread 108 * synchronization is necessary. 109 * - calls to close the database will wait until the interruption 110 * finishes. 111 */ 112 const unsigned long CONNECTION_INTERRUPTIBLE = 1 << 0; 113 114 /** 115 * Open an asynchronous connection to a database. 116 * 117 * This method MUST be called from the main thread. The connection object 118 * returned by this function is not threadsafe. You MUST use it only from 119 * the main thread. 120 * 121 * If you have more than one connection to a file, you MUST use the EXACT 122 * SAME NAME for the file each time, including case. The sqlite code uses 123 * a simple string compare to see if there is already a connection. Opening 124 * a connection to "Foo.sqlite" and "foo.sqlite" will CORRUPT YOUR DATABASE. 125 * 126 * @param aDatabaseStore Either a nsIFile representing the file that contains 127 * the database or a special string to open a special database. The special 128 * string may be: 129 * - "memory" to open an in-memory database. 130 * 131 * @param aOpenFlags 132 * A set of flags to open the database with optional features. 133 * See OPEN_* options above. 134 * For full details, please refer to the documentation of the flags. 135 * 136 * @param aConnectionFlags 137 * A set of flags to enable optional features for the returned 138 * asynchronous connection object. 139 * Currently supports CONNECTION_INTERRUPTIBLE flag. 140 * For full details, please refer to the documentation of the flag. 141 * 142 * @param aCallback A callback that will receive the result of the operation. 143 * In case of error, it may receive as status: 144 * - NS_ERROR_OUT_OF_MEMORY if allocating a new storage object fails. 145 * - NS_ERROR_FILE_CORRUPTED if the database file is corrupted. 146 * In case of success, it receives as argument the new database 147 * connection, as an instance of |mozIStorageAsyncConnection|. 148 * 149 * @throws NS_ERROR_INVALID_ARG if |aDatabaseStore| is neither a file nor 150 * one of the special strings understood by this method, or if one of 151 * the options passed through |aOptions| does not have 152 * the right type. 153 * @throws NS_ERROR_NOT_SAME_THREAD if called from a thread other than the 154 * main thread. 155 */ 156 void openAsyncDatabase(in nsIVariant aDatabaseStore, 157 in unsigned long aOpenFlags, 158 in unsigned long aConnectionFlags, 159 in mozIStorageCompletionCallback aCallback); 160 161 /** 162 * Get a connection to a named special database storage. 163 * 164 * @param aStorageKey a string key identifying the type of storage 165 * requested. Valid values include: "memory". 166 * 167 * @param aName an optional string identifying the name of the database. 168 * If omitted, a filename of ":memory:" will be used which results in a 169 * private in-memory database specific to this connection, making it 170 * impossible to clone the in-memory database. If you want to be able to 171 * clone the connection (or otherwise connect to the in-memory database from 172 * a connection), then you must pick a name that's sufficiently unique within 173 * the process to not collide with other mozStorage users. 174 * 175 * @param [optional] aConnectionFlags 176 * A set of flags to enable optional features for the returned 177 * synchronous connection object. 178 * Currently supports CONNECTION_INTERRUPTIBLE flag. 179 * For full details, please refer to the documentation of the flag. 180 * 181 * @see openDatabase for restrictions on how database connections may be 182 * used. For the profile database, you should only access it from the main 183 * thread since other callers may also have connections. 184 * 185 * @returns a new mozIStorageConnection for the requested 186 * storage database. 187 * 188 * @throws NS_ERROR_INVALID_ARG if aStorageKey is invalid. 189 */ 190 mozIStorageConnection openSpecialDatabase( 191 in ACString aStorageKey, 192 [optional] in ACString aName, 193 [optional] in unsigned long aConnectionFlags); 194 195 /** 196 * Open a connection to the specified file. 197 * 198 * Consumers should check mozIStorageConnection::connectionReady to ensure 199 * that they can use the database. If this value is false, it is strongly 200 * recommended that the database be backed up with 201 * mozIStorageConnection::backupDB so user data is not lost. 202 * 203 * ========== 204 * DANGER 205 * ========== 206 * 207 * If you have more than one connection to a file, you MUST use the EXACT 208 * SAME NAME for the file each time, including case. The sqlite code uses 209 * a simple string compare to see if there is already a connection. Opening 210 * a connection to "Foo.sqlite" and "foo.sqlite" will CORRUPT YOUR DATABASE. 211 * 212 * The connection object returned by this function is not threadsafe. You 213 * must use it only from the thread you created it from. 214 * 215 * @param aDatabaseFile 216 * A nsIFile that represents the database that is to be opened. 217 * @param [optional] aConnectionFlags 218 * A set of flags to enable optional features for the returned 219 * synchronous connection object. 220 * Currently supports CONNECTION_INTERRUPTIBLE flag. 221 * For full details, please refer to the documentation of the flag. 222 * 223 * @returns a mozIStorageConnection for the requested database file. 224 * 225 * @throws NS_ERROR_OUT_OF_MEMORY 226 * If allocating a new storage object fails. 227 * @throws NS_ERROR_FILE_CORRUPTED 228 * If the database file is corrupted. 229 */ 230 mozIStorageConnection openDatabase( 231 in nsIFile aDatabaseFile, [optional] in unsigned long aConnectionFlags); 232 233 /** 234 * Open a connection to the specified file that doesn't share a sqlite cache. 235 * 236 * Without a shared-cache, each connection uses its own pages cache, which 237 * may be memory inefficient with a large number of connections, in such a 238 * case so you should use openDatabase instead. On the other side, if cache 239 * contention may be an issue, for instance when concurrency is important to 240 * ensure responsiveness, using unshared connections may be a 241 * performance win. 242 * 243 * ========== 244 * DANGER 245 * ========== 246 * 247 * If you have more than one connection to a file, you MUST use the EXACT 248 * SAME NAME for the file each time, including case. The sqlite code uses 249 * a simple string compare to see if there is already a connection. Opening 250 * a connection to "Foo.sqlite" and "foo.sqlite" will CORRUPT YOUR DATABASE. 251 * 252 * The connection object returned by this function is not threadsafe. You 253 * must use it only from the thread you created it from. 254 * 255 * @param aDatabaseFile 256 * A nsIFile that represents the database that is to be opened. 257 * @param [optional] aConnectionFlags 258 * A set of flags to enable optional features for the returned 259 * synchronous connection object. 260 * Currently supports CONNECTION_INTERRUPTIBLE flag. 261 * For full details, please refer to the documentation of the flag. 262 * 263 * @returns a mozIStorageConnection for the requested database file. 264 * 265 * @throws NS_ERROR_OUT_OF_MEMORY 266 * If allocating a new storage object fails. 267 * @throws NS_ERROR_FILE_CORRUPTED 268 * If the database file is corrupted. 269 */ 270 mozIStorageConnection openUnsharedDatabase( 271 in nsIFile aDatabaseFile, [optional] in unsigned long aConnectionFlags); 272 273 /** 274 * See openDatabase(). Exactly the same only initialized with a file URL. 275 * Custom parameters can be passed to SQLite and VFS implementations through 276 * the query part of the URL. 277 * 278 * @param aURL 279 * A nsIFileURL that represents the database that is to be opened. 280 * @param [optional] aTelemetryFilename 281 * The name to use for the database in telemetry. Only needed if the 282 * actual filename can contain sensitive information. 283 * @param [optional] aConnectionFlags 284 * A set of flags to enable optional features for the returned 285 * synchronous connection object. 286 * Currently supports CONNECTION_INTERRUPTIBLE flag. 287 * For full details, please refer to the documentation of the flag. 288 */ 289 mozIStorageConnection openDatabaseWithFileURL( 290 in nsIFileURL aFileURL, [optional] in ACString aTelemetryFilename, 291 [optional] in unsigned long aConnectionFlags); 292 }; 293 294 %{C++ 295 296 constexpr auto kMozStorageMemoryStorageKey = "memory"_ns; 297 298 %}