summaryrefslogtreecommitdiffstats
path: root/storage/mozIStorageBaseStatement.idl
diff options
context:
space:
mode:
Diffstat (limited to 'storage/mozIStorageBaseStatement.idl')
-rw-r--r--storage/mozIStorageBaseStatement.idl125
1 files changed, 125 insertions, 0 deletions
diff --git a/storage/mozIStorageBaseStatement.idl b/storage/mozIStorageBaseStatement.idl
new file mode 100644
index 0000000000..cd869d8fde
--- /dev/null
+++ b/storage/mozIStorageBaseStatement.idl
@@ -0,0 +1,125 @@
+/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
+ * vim: sw=2 ts=2 sts=2 et
+ * 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"
+#include "mozIStorageBindingParams.idl"
+
+interface mozIStorageConnection;
+interface mozIStorageStatementCallback;
+interface mozIStoragePendingStatement;
+interface mozIStorageBindingParams;
+interface mozIStorageBindingParamsArray;
+
+/**
+ * The base interface for both pure asynchronous storage statements
+ * (mozIStorageAsyncStatement) and 'classic' storage statements
+ * (mozIStorageStatement) that can be used for both synchronous and asynchronous
+ * purposes.
+ */
+[scriptable, builtinclass, uuid(16ca67aa-1325-43e2-aac7-859afd1590b2)]
+interface mozIStorageBaseStatement : mozIStorageBindingParams {
+ /**
+ * Finalizes a statement so you can successfully close a database connection.
+ * Once a statement has been finalized it can no longer be used for any
+ * purpose.
+ *
+ * Statements are implicitly finalized when their reference counts hits zero.
+ * If you are a native (C++) caller this is accomplished by setting all of
+ * your nsCOMPtr instances to be NULL. If you are operating from JavaScript
+ * code then you cannot rely on this behavior because of the involvement of
+ * garbage collection.
+ *
+ * When finalizing an asynchronous statement you do not need to worry about
+ * whether the statement has actually been executed by the asynchronous
+ * thread; you just need to call finalize after your last call to executeAsync
+ * involving the statement. However, you do need to use asyncClose instead of
+ * close on the connection if any statements have been used asynchronously.
+ */
+ void finalize();
+
+ /**
+ * Binds the array of parameters to the statement. When executeAsync is
+ * called, all the parameters in aParameters are bound and then executed.
+ *
+ * @param aParameters
+ * The array of parameters to bind to the statement upon execution.
+ *
+ * @note This is only works on statements being used asynchronously.
+ */
+ void bindParameters(in mozIStorageBindingParamsArray aParameters);
+
+ /**
+ * Creates a new mozIStorageBindingParamsArray that can be used to bind
+ * multiple sets of data to a statement with bindParameters.
+ *
+ * @return a mozIStorageBindingParamsArray that multiple sets of parameters
+ * can be bound to.
+ *
+ * @note This is only useful for statements being used asynchronously.
+ */
+ mozIStorageBindingParamsArray newBindingParamsArray();
+
+ /**
+ * Execute a query asynchronously using any currently bound parameters. This
+ * statement can be reused immediately, and reset does not need to be called.
+ *
+ * @note If you have any custom defined functions, they must be re-entrant
+ * since they can be called on multiple threads.
+ *
+ * @param aCallback [optional]
+ * The callback object that will be notified of progress, errors, and
+ * completion.
+ * @return an object that can be used to cancel the statements execution.
+ */
+ mozIStoragePendingStatement executeAsync(
+ [optional] in mozIStorageStatementCallback aCallback
+ );
+
+ /**
+ * The statement is not usable, either because it failed to initialize or
+ * was explicitly finalized.
+ */
+ const long MOZ_STORAGE_STATEMENT_INVALID = 0;
+ /**
+ * The statement is usable.
+ */
+ const long MOZ_STORAGE_STATEMENT_READY = 1;
+ /**
+ * Indicates that the statement is executing and the row getters may be used.
+ *
+ * @note This is only relevant for mozIStorageStatement instances being used
+ * in a synchronous fashion.
+ */
+ const long MOZ_STORAGE_STATEMENT_EXECUTING = 2;
+
+ /**
+ * Find out whether the statement is usable (has not been finalized).
+ */
+ readonly attribute long state;
+
+ /**
+ * Escape a string for SQL LIKE search.
+ *
+ * @note Consumers will have to use same escape char when doing statements
+ * such as: ...LIKE '?1' ESCAPE '/'...
+ *
+ * @param aValue
+ * The string to escape for SQL LIKE.
+ * @param aEscapeChar
+ * The escape character.
+ * @return an AString of an escaped version of aValue
+ * (%, _ and the escape char are escaped with the escape char)
+ * For example, we will convert "foo/bar_baz%20cheese"
+ * into "foo//bar/_baz/%20cheese" (if the escape char is '/').
+ */
+ AString escapeStringForLIKE(in AString aValue, in wchar aEscapeChar);
+
+ /**
+ * The same as above, but for UTF8 strings.
+ */
+ AUTF8String escapeUTF8StringForLIKE(in AUTF8String aValue,
+ in char aEscapeChar);
+};