storage/public/mozIStorageBaseStatement.idl
author Ehsan Akhgari <ehsan@mozilla.com>
Wed, 12 Dec 2012 00:05:49 -0500
changeset 115629 553a3bcf1fe771c09cdfd1640e8059c312622b4a
parent 94475 f4157e8c410708d76703f19e4dfb61859bfe32d8
child 172361 8799ec066a38422333507f0be2ab6c6595593f99
permissions -rw-r--r--
Backed out 7 changesets (bug 769288) because of leaks Backed out changeset b2fb475b6e4e (bug 769288) Backed out changeset 912331d0c2fd (bug 769288) Backed out changeset 6d8d78bd56a9 (bug 769288) Backed out changeset e75cd1e1fca3 (bug 769288) Backed out changeset e10c24f10bd2 (bug 769288) Backed out changeset 7b0fdedb4fa9 (bug 769288) Backed out changeset 42b468942a84 (bug 769288)

/* -*- 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(da2ec336-fbbb-4ba1-9778-8c9825980d01)]
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();

  /**
   * Bind the given value at the given numeric index.
   *
   * @param aParamIndex
   *        0-based index, 0 corresponding to the first numbered argument or
   *        "?1".
   * @param aValue
   *        Argument value.
   * @param aValueSize
   *        Length of aValue in bytes.
   * @{
   */
  [deprecated] void bindUTF8StringParameter(in unsigned long aParamIndex,
                                            in AUTF8String aValue);
  [deprecated] void bindStringParameter(in unsigned long aParamIndex,
                                        in AString aValue);
  [deprecated] void bindDoubleParameter(in unsigned long aParamIndex,
                                        in double aValue);
  [deprecated] void bindInt32Parameter(in unsigned long aParamIndex,
                                       in long aValue);
  [deprecated] void bindInt64Parameter(in unsigned long aParamIndex,
                                       in long long aValue);
  [deprecated] void bindNullParameter(in unsigned long aParamIndex);
  [deprecated] void bindBlobParameter(
    in unsigned long aParamIndex,
    [array,const,size_is(aValueSize)] in octet aValue,
    in unsigned long aValueSize);
  /**@}*/

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