storage/public/mozIStorageBaseStatement.idl

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
   2  * vim: sw=2 ts=2 sts=2 et
   3  * This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 #include "nsISupports.idl"
   8 #include "mozIStorageBindingParams.idl"
   9
  10 interface mozIStorageConnection;
  11 interface mozIStorageStatementCallback;
  12 interface mozIStoragePendingStatement;
  13 interface mozIStorageBindingParams;
  14 interface mozIStorageBindingParamsArray;
  15
  16 /**
  17  * The base interface for both pure asynchronous storage statements
  18  * (mozIStorageAsyncStatement) and 'classic' storage statements
  19  * (mozIStorageStatement) that can be used for both synchronous and asynchronous
  20  * purposes.
  21  */
  22 [scriptable, uuid(5d34f333-ed3f-4aa2-ba51-f2a8b0cfa33a)]
  23 interface mozIStorageBaseStatement : mozIStorageBindingParams {
  24   /**
  25    * Finalizes a statement so you can successfully close a database connection.
  26    * Once a statement has been finalized it can no longer be used for any
  27    * purpose.
  28    *
  29    * Statements are implicitly finalized when their reference counts hits zero.
  30    * If you are a native (C++) caller this is accomplished by setting all of
  31    * your nsCOMPtr instances to be NULL.  If you are operating from JavaScript
  32    * code then you cannot rely on this behavior because of the involvement of
  33    * garbage collection.
  34    *
  35    * When finalizing an asynchronous statement you do not need to worry about
  36    * whether the statement has actually been executed by the asynchronous
  37    * thread; you just need to call finalize after your last call to executeAsync
  38    * involving the statement.  However, you do need to use asyncClose instead of
  39    * close on the connection if any statements have been used asynchronously.
  40    */
  41   void finalize();
  42
  43   /**
  44    * Bind the given value at the given numeric index.
  45    *
  46    * @param aParamIndex
  47    *        0-based index, 0 corresponding to the first numbered argument or
  48    *        "?1".
  49    * @param aValue
  50    *        Argument value.
  51    * @param aValueSize
  52    *        Length of aValue in bytes.
  53    * @{
  54    */
  55   [deprecated] void bindUTF8StringParameter(in unsigned long aParamIndex,
  56                                             in AUTF8String aValue);
  57   [deprecated] void bindStringParameter(in unsigned long aParamIndex,
  58                                         in AString aValue);
  59   [deprecated] void bindDoubleParameter(in unsigned long aParamIndex,
  60                                         in double aValue);
  61   [deprecated] void bindInt32Parameter(in unsigned long aParamIndex,
  62                                        in long aValue);
  63   [deprecated] void bindInt64Parameter(in unsigned long aParamIndex,
  64                                        in long long aValue);
  65   [deprecated] void bindNullParameter(in unsigned long aParamIndex);
  66   [deprecated] void bindBlobParameter(
  67     in unsigned long aParamIndex,
  68     [array,const,size_is(aValueSize)] in octet aValue,
  69     in unsigned long aValueSize);
  70   [deprecated] void bindAdoptedBlobParameter(
  71     in unsigned long aParamIndex,
  72     [array,size_is(aValueSize)] in octet aValue,
  73     in unsigned long aValueSize);
  74   /**@}*/
  75
  76   /**
  77    * Binds the array of parameters to the statement.  When executeAsync is
  78    * called, all the parameters in aParameters are bound and then executed.
  79    *
  80    * @param aParameters
  81    *        The array of parameters to bind to the statement upon execution.
  82    *
  83    * @note This is only works on statements being used asynchronously.
  84    */
  85   void bindParameters(in mozIStorageBindingParamsArray aParameters);
  86
  87   /**
  88    * Creates a new mozIStorageBindingParamsArray that can be used to bind
  89    * multiple sets of data to a statement with bindParameters.
  90    *
  91    * @return a mozIStorageBindingParamsArray that multiple sets of parameters
  92    *         can be bound to.
  93    *
  94    * @note This is only useful for statements being used asynchronously.
  95    */
  96   mozIStorageBindingParamsArray newBindingParamsArray();
  97
  98   /**
  99    * Execute a query asynchronously using any currently bound parameters.  This
 100    * statement can be reused immediately, and reset does not need to be called.
 101    *
 102    * @note If you have any custom defined functions, they must be re-entrant
 103    *       since they can be called on multiple threads.
 104    *
 105    * @param aCallback [optional]
 106    *        The callback object that will be notified of progress, errors, and
 107    *        completion.
 108    * @return an object that can be used to cancel the statements execution.
 109    */
 110   mozIStoragePendingStatement executeAsync(
 111     [optional] in mozIStorageStatementCallback aCallback
 112   );
 113
 114   /**
 115    * The statement is not usable, either because it failed to initialize or
 116    * was explicitly finalized.
 117    */
 118   const long MOZ_STORAGE_STATEMENT_INVALID = 0;
 119   /**
 120    * The statement is usable.
 121    */
 122   const long MOZ_STORAGE_STATEMENT_READY = 1;
 123   /**
 124    * Indicates that the statement is executing and the row getters may be used.
 125    *
 126    * @note This is only relevant for mozIStorageStatement instances being used
 127    *       in a synchronous fashion.
 128    */
 129   const long MOZ_STORAGE_STATEMENT_EXECUTING = 2;
 130
 131   /**
 132    * Find out whether the statement is usable (has not been finalized).
 133    */
 134   readonly attribute long state;
 135
 136   /**
 137    * Escape a string for SQL LIKE search.
 138    *
 139    * @note Consumers will have to use same escape char when doing statements
 140    *       such as:   ...LIKE '?1' ESCAPE '/'...
 141    *
 142    * @param aValue
 143    *        The string to escape for SQL LIKE.
 144    * @param aEscapeChar
 145    *        The escape character.
 146    * @return an AString of an escaped version of aValue
 147    *         (%, _ and the escape char are escaped with the escape char)
 148    *         For example, we will convert "foo/bar_baz%20cheese"
 149    *         into "foo//bar/_baz/%20cheese" (if the escape char is '/').
 150    */
 151   AString escapeStringForLIKE(in AString aValue, in wchar aEscapeChar);
 152 };