summaryrefslogtreecommitdiffstats
path: root/storage/mozIStorageService.idl
blob: 22c1dc05654059c1d86904c1f721457b90f1843d (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
/* -*- 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"

%{C++

#include "nsLiteralString.h"

%}

interface mozIStorageConnection;
interface nsIFile;
interface nsIFileURL;
interface nsIPropertyBag2;
interface nsIVariant;
interface mozIStorageCompletionCallback;

/**
 * PRIVACY WARNING
 * ===============
 *
 * Database file names can be exposed through telemetry and in crash reports on
 * the https://crash-stats.mozilla.org site, to allow recognizing the affected
 * database.
 * if your database name may contain privacy sensitive information, e.g. an
 * URL origin, you should use openDatabaseWithFileURL and pass an explicit
 * TelemetryFilename to it. That name will be used both for telemetry and for
 * thread names in crash reports.
 * If you have different needs (e.g. using the javascript module or an async
 * connection from the main thread) please coordinate with the mozStorage peers.
 */

/**
 * The mozIStorageService interface is intended to be implemented by
 * a service that can create storage connections (mozIStorageConnection)
 * to either a well-known profile database or to a specific database file.
 *
 * This is the only way to open a database connection.
 *
 * @note The first reference to mozIStorageService must be made on the main
 * thread.
 */
[scriptable, uuid(07b6b2f5-6d97-47b4-9584-e65bc467fe9e)]
interface mozIStorageService : nsISupports {
  /**
   * Open the database with default flags in default mode.
   */
  const unsigned long OPEN_DEFAULT = 0;

  /**
   * Open the database with a shared cache. The shared-cache mode
   * is more memory-efficient when many connections to the same database
   * are expected, though, the connections will contend the cache resource.
   * When performance matters, working without a shared-cache will
   * improve concurrency.  @see openUnsharedDatabase
   */
  const unsigned long OPEN_SHARED = 1 << 0;

  /**
   * Open the underlying database in read-only mode.
   */
  const unsigned long OPEN_READONLY = 1 << 1;

  /**
   * Allow simultaneous access to an asynchronous read-only database
   * without any file locking.
   *
   * For synchronous database, the flag has no effect.
   *
   * Specifying the OPEN_IGNORE_LOCKING_MODE flag will automatically
   * turn on the OPEN_READONLY flag.
   */
  const unsigned long OPEN_IGNORE_LOCKING_MODE = 1 << 2;

  /**
   * All optional connection object features are off.
   */
  const unsigned long CONNECTION_DEFAULT = 0;

  /**
   * Enable Interrupt-method for the synchronous connection object
   * returned by openDatabase, openSpecialDatabase, openUnsharedDatabase
   * or openDatabaseWithFileURL calls.
   *
   * When this flag is not set, Interrupt-method of a
   * synchronous connection must not be used.
   *
   * Asynchronous connection is always interruptible and the flag
   * does not change anything.
   *
   * The following are among the potential risks side effects of
   * calling the Interrupt-method:
   *   - new queries started on a different thread after the
   *     interrupt call, but before its completion, are interrupted as if
   *     they had been running prior to the interrupt call. Thus thread
   *     synchronization is necessary.
   *   - calls to close the database will wait until the interruption
   *     finishes.
   */
  const unsigned long CONNECTION_INTERRUPTIBLE = 1 << 0;

  /**
   * Open an asynchronous connection to a database.
   *
   * This method MUST be called from the main thread. The connection object
   * returned by this function is not threadsafe. You MUST use it only from
   * the main thread.
   *
   * If you have more than one connection to a file, you MUST use the EXACT
   * SAME NAME for the file each time, including case. The sqlite code uses
   * a simple string compare to see if there is already a connection. Opening
   * a connection to "Foo.sqlite" and "foo.sqlite" will CORRUPT YOUR DATABASE.
   *
   * @param aDatabaseStore Either a nsIFile representing the file that contains
   * the database or a special string to open a special database. The special
   * string may be:
   * - "memory" to open an in-memory database.
   *
   * @param aOpenFlags
   *        A set of flags to open the database with optional features.
   *        Currently supports OPEN_SHARED, OPEN_READONLY and
   *        OPEN_IGNORE_LOCKING_MODE flags.
   *        For full details, please refer to the documentation of the flags.
   *
   * @param aConnectionFlags
   *        A set of flags to enable optional features for the returned
   *        asynchronous connection object.
   *        Currently supports CONNECTION_INTERRUPTIBLE flag.
   *        For full details, please refer to the documentation of the flag.
   *
   * @param aCallback A callback that will receive the result of the operation.
   *  In case of error, it may receive as status:
   *  - NS_ERROR_OUT_OF_MEMORY if allocating a new storage object fails.
   *  - NS_ERROR_FILE_CORRUPTED if the database file is corrupted.
   *  In case of success, it receives as argument the new database
   *  connection, as an instance of |mozIStorageAsyncConnection|.
   *
   * @throws NS_ERROR_INVALID_ARG if |aDatabaseStore| is neither a file nor
   *         one of the special strings understood by this method, or if one of
   *         the options passed through |aOptions| does not have
   *         the right type.
   * @throws NS_ERROR_NOT_SAME_THREAD if called from a thread other than the
   *         main thread.
   */
  void openAsyncDatabase(in nsIVariant aDatabaseStore,
                         in unsigned long aOpenFlags,
                         in unsigned long aConnectionFlags,
                         in mozIStorageCompletionCallback aCallback);

  /**
   * Get a connection to a named special database storage.
   *
   * @param aStorageKey a string key identifying the type of storage
   * requested.  Valid values include: "memory".
   *
   * @param aName an optional string identifying the name of the database.
   * If omitted, a filename of ":memory:" will be used which results in a
   * private in-memory database specific to this connection, making it
   * impossible to clone the in-memory database. If you want to be able to
   * clone the connection (or otherwise connect to the in-memory database from
   * a connection), then you must pick a name that's sufficiently unique within
   * the process to not collide with other mozStorage users.
   *
   * @param [optional] aConnectionFlags
   *        A set of flags to enable optional features for the returned
   *        synchronous connection object.
   *        Currently supports CONNECTION_INTERRUPTIBLE flag.
   *        For full details, please refer to the documentation of the flag.
   *
   * @see openDatabase for restrictions on how database connections may be
   * used. For the profile database, you should only access it from the main
   * thread since other callers may also have connections.
   *
   * @returns a new mozIStorageConnection for the requested
   * storage database.
   *
   * @throws NS_ERROR_INVALID_ARG if aStorageKey is invalid.
   */
  mozIStorageConnection openSpecialDatabase(
      in ACString aStorageKey,
      [optional] in ACString aName,
      [optional] in unsigned long aConnectionFlags);

  /**
   * Open a connection to the specified file.
   *
   * Consumers should check mozIStorageConnection::connectionReady to ensure
   * that they can use the database.  If this value is false, it is strongly
   * recommended that the database be backed up with
   * mozIStorageConnection::backupDB so user data is not lost.
   *
   * ==========
   *   DANGER
   * ==========
   *
   * If you have more than one connection to a file, you MUST use the EXACT
   * SAME NAME for the file each time, including case. The sqlite code uses
   * a simple string compare to see if there is already a connection. Opening
   * a connection to "Foo.sqlite" and "foo.sqlite" will CORRUPT YOUR DATABASE.
   *
   * The connection object returned by this function is not threadsafe. You
   * must use it only from the thread you created it from.
   *
   * @param aDatabaseFile
   *        A nsIFile that represents the database that is to be opened.
   * @param [optional] aConnectionFlags
   *        A set of flags to enable optional features for the returned
   *        synchronous connection object.
   *        Currently supports CONNECTION_INTERRUPTIBLE flag.
   *        For full details, please refer to the documentation of the flag.
   *
   * @returns a mozIStorageConnection for the requested database file.
   *
   * @throws NS_ERROR_OUT_OF_MEMORY
   *         If allocating a new storage object fails.
   * @throws NS_ERROR_FILE_CORRUPTED
   *         If the database file is corrupted.
   */
  mozIStorageConnection openDatabase(
      in nsIFile aDatabaseFile, [optional] in unsigned long aConnectionFlags);

  /**
   * Open a connection to the specified file that doesn't share a sqlite cache.
   *
   * Without a shared-cache, each connection uses its own pages cache, which
   * may be memory inefficient with a large number of connections, in such a
   * case so you should use openDatabase instead.  On the other side, if cache
   * contention may be an issue, for instance when concurrency is important to
   * ensure responsiveness, using unshared connections may be a
   * performance win.
   *
   * ==========
   *   DANGER
   * ==========
   *
   * If you have more than one connection to a file, you MUST use the EXACT
   * SAME NAME for the file each time, including case. The sqlite code uses
   * a simple string compare to see if there is already a connection. Opening
   * a connection to "Foo.sqlite" and "foo.sqlite" will CORRUPT YOUR DATABASE.
   *
   * The connection object returned by this function is not threadsafe. You
   * must use it only from the thread you created it from.
   *
   * @param aDatabaseFile
   *        A nsIFile that represents the database that is to be opened.
   * @param [optional] aConnectionFlags
   *        A set of flags to enable optional features for the returned
   *        synchronous connection object.
   *        Currently supports CONNECTION_INTERRUPTIBLE flag.
   *        For full details, please refer to the documentation of the flag.
   *
   * @returns a mozIStorageConnection for the requested database file.
   *
   * @throws NS_ERROR_OUT_OF_MEMORY
   *         If allocating a new storage object fails.
   * @throws NS_ERROR_FILE_CORRUPTED
   *         If the database file is corrupted.
   */
  mozIStorageConnection openUnsharedDatabase(
      in nsIFile aDatabaseFile, [optional] in unsigned long aConnectionFlags);

  /**
   * See openDatabase(). Exactly the same only initialized with a file URL.
   * Custom parameters can be passed to SQLite and VFS implementations through
   * the query part of the URL.
   *
   * @param aURL
   *        A nsIFileURL that represents the database that is to be opened.
   * @param [optional] aTelemetryFilename
   *        The name to use for the database in telemetry. Only needed if the
   *        actual filename can contain sensitive information.
   * @param [optional] aConnectionFlags
   *        A set of flags to enable optional features for the returned
   *        synchronous connection object.
   *        Currently supports CONNECTION_INTERRUPTIBLE flag.
   *        For full details, please refer to the documentation of the flag.
   */
  mozIStorageConnection openDatabaseWithFileURL(
      in nsIFileURL aFileURL, [optional] in ACString aTelemetryFilename,
      [optional] in unsigned long aConnectionFlags);
};

%{C++

constexpr auto kMozStorageMemoryStorageKey = "memory"_ns;

%}