storage/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, builtinclass, uuid(16ca67aa-1325-43e2-aac7-859afd1590b2)]
  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    * Binds the array of parameters to the statement.  When executeAsync is
  45    * called, all the parameters in aParameters are bound and then executed.
  46    *
  47    * @param aParameters
  48    *        The array of parameters to bind to the statement upon execution.
  49    *
  50    * @note This is only works on statements being used asynchronously.
  51    */
  52   void bindParameters(in mozIStorageBindingParamsArray aParameters);
  53
  54   /**
  55    * Creates a new mozIStorageBindingParamsArray that can be used to bind
  56    * multiple sets of data to a statement with bindParameters.
  57    *
  58    * @return a mozIStorageBindingParamsArray that multiple sets of parameters
  59    *         can be bound to.
  60    *
  61    * @note This is only useful for statements being used asynchronously.
  62    */
  63   mozIStorageBindingParamsArray newBindingParamsArray();
  64
  65   /**
  66    * Execute a query asynchronously using any currently bound parameters.  This
  67    * statement can be reused immediately, and reset does not need to be called.
  68    *
  69    * @note If you have any custom defined functions, they must be re-entrant
  70    *       since they can be called on multiple threads.
  71    *
  72    * @param aCallback [optional]
  73    *        The callback object that will be notified of progress, errors, and
  74    *        completion.
  75    * @return an object that can be used to cancel the statements execution.
  76    */
  77   mozIStoragePendingStatement executeAsync(
  78     [optional] in mozIStorageStatementCallback aCallback
  79   );
  80
  81   /**
  82    * The statement is not usable, either because it failed to initialize or
  83    * was explicitly finalized.
  84    */
  85   const long MOZ_STORAGE_STATEMENT_INVALID = 0;
  86   /**
  87    * The statement is usable.
  88    */
  89   const long MOZ_STORAGE_STATEMENT_READY = 1;
  90   /**
  91    * Indicates that the statement is executing and the row getters may be used.
  92    *
  93    * @note This is only relevant for mozIStorageStatement instances being used
  94    *       in a synchronous fashion.
  95    */
  96   const long MOZ_STORAGE_STATEMENT_EXECUTING = 2;
  97
  98   /**
  99    * Find out whether the statement is usable (has not been finalized).
 100    */
 101   readonly attribute long state;
 102
 103   /**
 104    * Escape a string for SQL LIKE search.
 105    *
 106    * @note Consumers will have to use same escape char when doing statements
 107    *       such as:   ...LIKE '?1' ESCAPE '/'...
 108    *
 109    * @param aValue
 110    *        The string to escape for SQL LIKE.
 111    * @param aEscapeChar
 112    *        The escape character.
 113    * @return an AString of an escaped version of aValue
 114    *         (%, _ and the escape char are escaped with the escape char)
 115    *         For example, we will convert "foo/bar_baz%20cheese"
 116    *         into "foo//bar/_baz/%20cheese" (if the escape char is '/').
 117    */
 118   AString escapeStringForLIKE(in AString aValue, in wchar aEscapeChar);
 119
 120   /**
 121    * The same as above, but for UTF8 strings.
 122    */
 123   AUTF8String escapeUTF8StringForLIKE(in AUTF8String aValue,
 124                                       in char aEscapeChar);
 125 };