1 /* -*- Mode: idl; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
2 /* ***** BEGIN LICENSE BLOCK *****
3 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
4 *
5 * The contents of this file are subject to the Mozilla Public License Version
6 * 1.1 (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 * http://www.mozilla.org/MPL/
9 *
10 * Software distributed under the License is distributed on an "AS IS" basis,
11 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
12 * for the specific language governing rights and limitations under the
13 * License.
14 *
15 * The Original Code is Oracle Corporation code.
16 *
17 * The Initial Developer of the Original Code is
18 * Oracle Corporation
19 * Portions created by the Initial Developer are Copyright (C) 2004
20 * the Initial Developer. All Rights Reserved.
21 *
22 * Contributor(s):
23 * Vladimir Vukicevic <vladimir.vukicevic@oracle.com>
24 * Brett Wilson <brettw@gmail.com>
25 * Shawn Wilsher <me@shawnwilsher.com>
26 * Lev Serebryakov <lev@serebryakov.spb.ru>
27 *
28 * Alternatively, the contents of this file may be used under the terms of
29 * either the GNU General Public License Version 2 or later (the "GPL"), or
30 * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
31 * in which case the provisions of the GPL or the LGPL are applicable instead
32 * of those above. If you wish to allow use of your version of this file only
33 * under the terms of either the GPL or the LGPL, and not to allow others to
34 * use your version of this file under the terms of the MPL, indicate your
35 * decision by deleting the provisions above and replace them with the notice
36 * and other provisions required by the GPL or the LGPL. If you do not delete
37 * the provisions above, a recipient may use your version of this file under
38 * the terms of any one of the MPL, the GPL or the LGPL.
39 *
40 * ***** END LICENSE BLOCK ***** */
41
42 #include "nsISupports.idl"
43
44 interface mozIStorageAggregateFunction;
45 interface mozIStorageFunction;
46 interface mozIStorageProgressHandler;
47 interface mozIStorageStatement;
48 interface nsIFile;
49
50 /**
51 * mozIStorageConnection represents a database connection attached to
52 * a specific file or to the in-memory data storage. It is the
53 * primary interface for interacting with a database, including
54 * creating prepared statements, executing SQL, and examining database
55 * errors.
56 */
57 [scriptable, uuid(623f9ddb-434b-4d39-bc2d-1c617da241d0)]
58 interface mozIStorageConnection : nsISupports {
59 /*
60 * Initialization and status
61 */
62
63 /**
64 * Closes a database connection. C++ callers should simply set the database
65 * variable to NULL.
66 */
67 void close();
68
69 /**
70 * Indicates if the connection is open and ready to use. This will be false
71 * if the connection failed to open, or it has been closed.
72 */
73 readonly attribute boolean connectionReady;
74
75 /**
76 * The current database nsIFile. Null if the database
77 * connection refers to an in-memory database.
78 */
79 readonly attribute nsIFile databaseFile;
80
81 /**
82 * lastInsertRowID returns the row ID from the last INSERT
83 * operation.
84 */
85 readonly attribute long long lastInsertRowID;
86
87 /**
88 * The last error SQLite error code.
89 */
90 readonly attribute long lastError;
91
92 /**
93 * The last SQLite error as a string (in english, straight from the
94 * sqlite library).
95 */
96 readonly attribute AUTF8String lastErrorString;
97
98 /**
99 * The schema version of the database. This should not be used until the
100 * database is ready. The schema will be reported as zero if it is not set.
101 */
102 attribute long schemaVersion;
103
104 /*
105 * Statement creation
106 */
107
108 /**
109 * Create a mozIStorageStatement for the given SQL expression. The
110 * expression may use ? to indicate sequential numbered arguments,
111 * ?1, ?2 etc. to indicate specific numbered arguments or :name and
112 * $var to indicate named arguments.
113 *
114 * @param aSQLStatement The SQL statement to execute
115 *
116 * @returns a new mozIStorageStatement
117 */
118 mozIStorageStatement createStatement(in AUTF8String aSQLStatement);
119
120 /**
121 * Execute a SQL expression, expecting no arguments.
122 *
123 * @param aSQLStatement The SQL statement to execute
124 */
125 void executeSimpleSQL(in AUTF8String aSQLStatement);
126
127 /**
128 * Check if the given table exists.
129 *
130 * @param aTableName The table to check
131 * @returns TRUE if table exists, FALSE otherwise.
132 */
133 boolean tableExists(in AUTF8String aTableName);
134
135 /**
136 * Check if the given index exists.
137 *
138 * @param aIndexName The index to check
139 * @returns TRUE if the index exists, FALSE otherwise.
140 */
141 boolean indexExists(in AUTF8String aIndexName);
142
143
144 /*
145 * Transactions
146 */
147
148 /**
149 * Returns true if a transaction is active on this connection.
150 */
151 readonly attribute boolean transactionInProgress;
152
153 /**
154 * Begin a new transaction. sqlite default transactions are deferred.
155 * If a transaction is active, throws an error.
156 */
157 void beginTransaction();
158
159 /**
160 * Begins a new transaction with the given type.
161 */
162 const PRInt32 TRANSACTION_DEFERRED = 0;
163 const PRInt32 TRANSACTION_IMMEDIATE = 1;
164 const PRInt32 TRANSACTION_EXCLUSIVE = 2;
165 void beginTransactionAs(in PRInt32 transactionType);
166
167 /**
168 * Commits the current transaction. If no transaction is active,
169 * @throws NS_ERROR_STORAGE_NO_TRANSACTION.
170 */
171 void commitTransaction();
172
173 /**
174 * Rolls back the current transaction. If no transaction is active,
175 * @throws NS_ERROR_STORAGE_NO_TRANSACTION.
176 */
177 void rollbackTransaction();
178
179 /*
180 * Tables
181 */
182
183 /**
184 * Create the table with the given name and schema.
185 *
186 * If the table already exists, NS_ERROR_FAILURE is thrown.
187 * (XXX at some point in the future it will check if the schema is
188 * the same as what is specified, but that doesn't happen currently.)
189 *
190 * @param aTableName the table name to be created, consisting of
191 * [A-Za-z0-9_], and beginning with a letter.
192 *
193 * @param aTableSchema the schema of the table; what would normally
194 * go between the parens in a CREATE TABLE statement: e.g., "foo
195 * INTEGER, bar STRING".
196 *
197 * @throws NS_ERROR_FAILURE if the table already exists or could not
198 * be created for any other reason.
199 *
200 */
201 void createTable(in string aTableName,
202 in string aTableSchema);
203
204 /*
205 * Functions
206 */
207
208 /**
209 * Create a new SQLite function
210 *
211 * @param aFunctionName The name of function to create, as seen in SQL.
212 * @param aNumArguments The number of arguments the function takes. Pass
213 * -1 for variable-argument functions.
214 * @param aFunction The instance of mozIStorageFunction, which implements
215 * the function in question.
216 */
217 void createFunction(in AUTF8String aFunctionName,
218 in long aNumArguments,
219 in mozIStorageFunction aFunction);
220
221 /**
222 * Create a new SQLite aggregate function
223 *
224 * @param aFunctionName The name of aggregate function to create, as seen
225 * in SQL.
226 * @param aNumArguments The number of arguments the function takes. Pass
227 * -1 for variable-argument functions.
228 * @param aFunction The instance of mozIStorageAggreagteFunction,
229 * which implements the function in question.
230 */
231 void createAggregateFunction(in AUTF8String aFunctionName,
232 in long aNumArguments,
233 in mozIStorageAggregateFunction aFunction);
234 /**
235 * Delete custom SQLite function (simple or aggregate one)
236 *
237 * @param aFunctionName The name of function to remove.
238 */
239 void removeFunction(in AUTF8String aFunctionName);
240
241 /**
242 * Sets a progress handler. Only one handler can be registered at a time.
243 * If you need more than one, you need to chain them yourself.
244 *
245 * @param aGranularity The number of SQL virtual machine steps between
246 * progress handler callbacks.
247 * @param aHandler The instance of mozIStorageProgressHandler.
248 *
249 * @return previous registered handler.
250 */
251 mozIStorageProgressHandler setProgressHandler(in PRInt32 aGranularity,
252 in mozIStorageProgressHandler aHandler);
253
254 /**
255 * Remove a progress handler.
256 *
257 * @return previous registered handler.
258 */
259 mozIStorageProgressHandler removeProgressHandler();
260 };