storage/mozIStorageBaseStatement.idl
author Brian Stack <bstack@mozilla.com>
Wed, 12 Apr 2017 21:01:46 -0700
changeset 404168 5748607f3014e8cec573fccebce5dcbf83b6ffd6
parent 277037 ad01543457e739b4eee7a245e16734a3ecfd10ad
child 425094 46153627ee5fa17c8cc67a76a9a468b36cfd1b52
permissions -rw-r--r--
Bug 591688 - Notify when decision task fails r=dustin,gps This uses the email provided by mozilla-taskcluster to find who to email about failed decision tasks. It also adds some validation of the try syntax that we've previously ignored. Any platforms or build types specified in try sytax that don't exist in the full task graph will throw an error. MozReview-Commit-ID: JOKkLle7hEe

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

  /**
   * 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);
  [deprecated] void bindStringAsBlobParameter(
    in unsigned long aParamIndex,
    in AString aValue);
  [deprecated] void bindUTF8StringAsBlobParameter(
    in unsigned long aParamIndex,
    in AUTF8String aValue);
  [deprecated] void bindAdoptedBlobParameter(
    in unsigned long aParamIndex,
    [array,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);
};