storage/mozIStorageBaseStatement.idl
author Nathan Froyd <froydnj@mozilla.com>
Wed, 03 Apr 2019 00:06:04 +0000
changeset 467750 1b9e5f4b0589a636233affb84666a469a4cc4ef5
parent 373142 46153627ee5fa17c8cc67a76a9a468b36cfd1b52
child 474137 41f28d23024ebecf5445896cd3b6b39a6b650a9d
permissions -rw-r--r--
Bug 1537643 - update cc crate; r=glandium This update from the official sources brings in the changes that we were using glandium's fork for, as well as changes enabling us to tweak more settings on Windows. Differential Revision: https://phabricator.services.mozilla.com/D25888

/* -*- 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, 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);
};