Adding upstream version 124.0.1.upstream/124.0.1

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

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);
+};