storage/public/mozIStorageService.idl@8bccb770b82d
storage/public/mozIStorageService.idl
Wed, 31 Dec 2014 13:27:57 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Wed, 31 Dec 2014 13:27:57 +0100
- branch
- TOR_BUG_3246
- changeset 6
- 8bccb770b82d
- permissions
- -rw-r--r--
Ignore runtime configuration files generated during quality assurance.
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/. */
6 #include "nsISupports.idl"
8 interface mozIStorageConnection;
9 interface nsIFile;
10 interface nsIFileURL;
11 interface nsIPropertyBag2;
12 interface nsIVariant;
13 interface mozIStorageCompletionCallback;
15 /**
16 * The mozIStorageService interface is intended to be implemented by
17 * a service that can create storage connections (mozIStorageConnection)
18 * to either a well-known profile database or to a specific database file.
19 *
20 * This is the only way to open a database connection.
21 *
22 * @note The first reference to mozIStorageService must be made on the main
23 * thread.
24 */
25 [scriptable, uuid(07b6b2f5-6d97-47b4-9584-e65bc467fe9e)]
26 interface mozIStorageService : nsISupports {
27 /**
28 * Open an asynchronous connection to a database.
29 *
30 * This method MUST be called from the main thread. The connection object
31 * returned by this function is not threadsafe. You MUST use it only from
32 * the main thread.
33 *
34 * If you have more than one connection to a file, you MUST use the EXACT
35 * SAME NAME for the file each time, including case. The sqlite code uses
36 * a simple string compare to see if there is already a connection. Opening
37 * a connection to "Foo.sqlite" and "foo.sqlite" will CORRUPT YOUR DATABASE.
38 *
39 * @param aDatabaseStore Either a nsIFile representing the file that contains
40 * the database or a special string to open a special database. The special
41 * string may be:
42 * - "memory" to open an in-memory database.
43 *
44 * @param aOptions A set of options (may be null). Options may contain:
45 * - bool shared (defaults to |false|).
46 * -- If |true|, opens the database with a shared-cache. The
47 * shared-cache mode is more memory-efficient when many
48 * connections to the same database are expected, though, the
49 * connections will contend the cache resource. In any cases
50 * where performance matter, working without a shared-cache will
51 * improve concurrency. @see openUnsharedDatabase
52 *
53 * - int growthIncrement (defaults to none).
54 * -- Set the growth increment for the main database. This hints SQLite to
55 * grow the database file by a given chunk size and may reduce
56 * filesystem fragmentation on large databases.
57 * @see mozIStorageConnection::setGrowthIncrement
58 *
59 * @param aCallback A callback that will receive the result of the operation.
60 * In case of error, it may receive as status:
61 * - NS_ERROR_OUT_OF_MEMORY if allocating a new storage object fails.
62 * - NS_ERROR_FILE_CORRUPTED if the database file is corrupted.
63 * In case of success, it receives as argument the new database
64 * connection, as an instance of |mozIStorageAsyncConnection|.
65 *
66 * @throws NS_ERROR_INVALID_ARG if |aDatabaseStore| is neither a file nor
67 * one of the special strings understood by this method, or if one of
68 * the options passed through |aOptions| does not have the right type.
69 * @throws NS_ERROR_NOT_SAME_THREAD if called from a thread other than the
70 * main thread.
71 */
72 void openAsyncDatabase(in nsIVariant aDatabaseStore,
73 [optional] in nsIPropertyBag2 aOptions,
74 in mozIStorageCompletionCallback aCallback);
75 /**
76 * Get a connection to a named special database storage.
77 *
78 * @param aStorageKey a string key identifying the type of storage
79 * requested. Valid values include: "memory".
80 *
81 * @see openDatabase for restrictions on how database connections may be
82 * used. For the profile database, you should only access it from the main
83 * thread since other callers may also have connections.
84 *
85 * @returns a new mozIStorageConnection for the requested
86 * storage database.
87 *
88 * @throws NS_ERROR_INVALID_ARG if aStorageKey is invalid.
89 */
90 mozIStorageConnection openSpecialDatabase(in string aStorageKey);
92 /**
93 * Open a connection to the specified file.
94 *
95 * Consumers should check mozIStorageConnection::connectionReady to ensure
96 * that they can use the database. If this value is false, it is strongly
97 * recommended that the database be backed up with
98 * mozIStorageConnection::backupDB so user data is not lost.
99 *
100 * ==========
101 * DANGER
102 * ==========
103 *
104 * If you have more than one connection to a file, you MUST use the EXACT
105 * SAME NAME for the file each time, including case. The sqlite code uses
106 * a simple string compare to see if there is already a connection. Opening
107 * a connection to "Foo.sqlite" and "foo.sqlite" will CORRUPT YOUR DATABASE.
108 *
109 * The connection object returned by this function is not threadsafe. You must
110 * use it only from the thread you created it from.
111 *
112 * @param aDatabaseFile
113 * A nsIFile that represents the database that is to be opened..
114 *
115 * @returns a mozIStorageConnection for the requested database file.
116 *
117 * @throws NS_ERROR_OUT_OF_MEMORY
118 * If allocating a new storage object fails.
119 * @throws NS_ERROR_FILE_CORRUPTED
120 * If the database file is corrupted.
121 */
122 mozIStorageConnection openDatabase(in nsIFile aDatabaseFile);
124 /**
125 * Open a connection to the specified file that doesn't share a sqlite cache.
126 *
127 * Without a shared-cache, each connection uses its own pages cache, which
128 * may be memory inefficient with a large number of connections, in such a
129 * case so you should use openDatabase instead. On the other side, if cache
130 * contention may be an issue, for instance when concurrency is important to
131 * ensure responsiveness, using unshared connections may be a performance win.
132 *
133 * ==========
134 * DANGER
135 * ==========
136 *
137 * If you have more than one connection to a file, you MUST use the EXACT
138 * SAME NAME for the file each time, including case. The sqlite code uses
139 * a simple string compare to see if there is already a connection. Opening
140 * a connection to "Foo.sqlite" and "foo.sqlite" will CORRUPT YOUR DATABASE.
141 *
142 * The connection object returned by this function is not threadsafe. You must
143 * use it only from the thread you created it from.
144 *
145 * @param aDatabaseFile
146 * A nsIFile that represents the database that is to be opened.
147 *
148 * @returns a mozIStorageConnection for the requested database file.
149 *
150 * @throws NS_ERROR_OUT_OF_MEMORY
151 * If allocating a new storage object fails.
152 * @throws NS_ERROR_FILE_CORRUPTED
153 * If the database file is corrupted.
154 */
155 mozIStorageConnection openUnsharedDatabase(in nsIFile aDatabaseFile);
157 /**
158 * See openDatabase(). Exactly the same only initialized with a file URL.
159 * Custom parameters can be passed to SQLite and VFS implementations through
160 * the query part of the URL.
161 *
162 * @param aURL
163 * A nsIFileURL that represents the database that is to be opened.
164 */
165 mozIStorageConnection openDatabaseWithFileURL(in nsIFileURL aFileURL);
167 /*
168 * Utilities
169 */
171 /**
172 * Copies the specified database file to the specified parent directory with
173 * the specified file name. If the parent directory is not specified, it
174 * places the backup in the same directory as the current file. This function
175 * ensures that the file being created is unique.
176 *
177 * @param aDBFile
178 * The database file that will be backed up.
179 * @param aBackupFileName
180 * The name of the new backup file to create.
181 * @param [optional] aBackupParentDirectory
182 * The directory you'd like the backup file to be placed.
183 * @return The nsIFile representing the backup file.
184 */
185 nsIFile backupDatabaseFile(in nsIFile aDBFile, in AString aBackupFileName,
186 [optional] in nsIFile aBackupParentDirectory);
187 };
189 %{C++
191 #define MOZ_STORAGE_MEMORY_STORAGE_KEY "memory"
193 %}
