storage/public/mozIStorageStatement.idl

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
   2  * vim: sw=2 ts=2 sts=2 expandtab
   3  * ***** BEGIN LICENSE BLOCK *****
   4  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   5  *
   6  * The contents of this file are subject to the Mozilla Public License Version
   7  * 1.1 (the "License"); you may not use this file except in compliance with
   8  * the License. You may obtain a copy of the License at
   9  * http://www.mozilla.org/MPL/
  10  *
  11  * Software distributed under the License is distributed on an "AS IS" basis,
  12  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  13  * for the specific language governing rights and limitations under the
  14  * License.
  15  *
  16  * The Original Code is Oracle Corporation code.
  17  *
  18  * The Initial Developer of the Original Code is
  19  *  Oracle Corporation
  20  * Portions created by the Initial Developer are Copyright (C) 2004
  21  * the Initial Developer. All Rights Reserved.
  22  *
  23  * Contributor(s):
  24  *   Vladimir Vukicevic <vladimir.vukicevic@oracle.com>
  25  *
  26  * Alternatively, the contents of this file may be used under the terms of
  27  * either the GNU General Public License Version 2 or later (the "GPL"), or
  28  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  29  * in which case the provisions of the GPL or the LGPL are applicable instead
  30  * of those above. If you wish to allow use of your version of this file only
  31  * under the terms of either the GPL or the LGPL, and not to allow others to
  32  * use your version of this file under the terms of the MPL, indicate your
  33  * decision by deleting the provisions above and replace them with the notice
  34  * and other provisions required by the GPL or the LGPL. If you do not delete
  35  * the provisions above, a recipient may use your version of this file under
  36  * the terms of any one of the MPL, the GPL or the LGPL.
  37  *
  38  * ***** END LICENSE BLOCK ***** */
  39
  40 #include "nsISupports.idl"
  41 #include "mozIStorageValueArray.idl"
  42
  43 interface mozIStorageConnection;
  44 interface mozIStorageDataSet;
  45 interface nsISimpleEnumerator;
  46 interface mozIStorageStatementCallback;
  47 interface mozIStoragePendingStatement;
  48
  49 [ptr] native sqlite3stmtptr(struct sqlite3_stmt);
  50
  51 [scriptable, uuid(4a712295-d076-4007-9c78-8c0e15373b9f)]
  52 interface mozIStorageStatement : mozIStorageValueArray {
  53   /**
  54    * Finalizes a statement so you can successfully close a database connection.
  55    * This method does not need to be used from native callers since you can just
  56    * set the statement to null, but is extremely useful to JS callers.
  57    */
  58   void finalize();
  59
  60   /**
  61    * Create a clone of this statement, by initializing a new statement
  62    * with the same connection and same SQL statement as this one.  It
  63    * does not preserve statement state; that is, if a statement is
  64    * being executed when it is cloned, the new statement will not be
  65    * executing.
  66    */
  67   mozIStorageStatement clone();
  68
  69   /*
  70    * Number of parameters
  71    */
  72   readonly attribute unsigned long parameterCount;
  73
  74   /**
  75    * Name of nth parameter, if given
  76    */
  77   AUTF8String getParameterName(in unsigned long aParamIndex);
  78
  79   /**
  80    * Returns the index of the named parameter.
  81    *
  82    * @param aName The name of the parameter you want the index for.
  83    * @return The index of the named parameter.
  84    */
  85   unsigned long getParameterIndex(in AUTF8String aName);
  86
  87   /**
  88    * Number of columns returned
  89    */
  90   readonly attribute unsigned long columnCount;
  91
  92   /**
  93    * Name of nth column
  94    */
  95   AUTF8String getColumnName(in unsigned long aColumnIndex);
  96
  97   /**
  98    * Obtains the index of the column with the specified name.
  99    *
 100    * @param aName The name of the column.
 101    * @return The index of the column with the specified name.
 102    */
 103   unsigned long getColumnIndex(in AUTF8String aName);
 104
 105   /**
 106    * Obtains the declared column type of a prepared statement.
 107    *
 108    * @param aParamIndex The zero-based index of the column who's declared type
 109    *                    we are interested in.
 110    * @returns the declared index type.
 111    */
 112   AUTF8String getColumnDecltype(in unsigned long aParamIndex);
 113
 114   /**
 115    * Reset parameters/statement execution
 116    */
 117   void reset();
 118
 119   /**
 120    * Bind the given value to the parameter at aParamIndex. Index 0
 121    * denotes the first numbered argument or ?1.
 122    */
 123   void bindUTF8StringParameter(in unsigned long aParamIndex,
 124                                in AUTF8String aValue);
 125   void bindStringParameter(in unsigned long aParamIndex, in AString aValue);
 126   void bindDoubleParameter(in unsigned long aParamIndex, in double aValue);
 127   void bindInt32Parameter(in unsigned long aParamIndex, in long aValue);
 128   void bindInt64Parameter(in unsigned long aParamIndex, in long long aValue);
 129   void bindNullParameter(in unsigned long aParamIndex);
 130   void bindBlobParameter(in unsigned long aParamIndex,
 131                          [array,const,size_is(aValueSize)] in octet aValue,
 132                          in unsigned long aValueSize);
 133
 134   /**
 135    * Execute the query, ignoring any results.  This is accomplished by
 136    * calling step() once, and then calling reset().
 137    *
 138    * Error and last insert info, etc. are available from
 139    * the mozStorageConnection.
 140    */
 141   void execute();
 142
 143   /**
 144    * Execute a query, using any currently-bound parameters.  Reset
 145    * must be called on the statement after the last call of
 146    * executeStep.
 147    *
 148    * @returns a boolean indicating whether there are more rows or not;
 149    * row data may be accessed using mozIStorageValueArray methods on
 150    * the statement.
 151    *
 152    */
 153   boolean executeStep();
 154
 155   /**
 156    * Execute a query asynchronously using any currently bound parameters.  This
 157    * statement can be reused immediately, and reset does not need to be called.
 158    *
 159    * @param aCallback [optional]
 160    *        The callback object that will be notified of progress, errors, and
 161    *        completion.
 162    * @returns an object that can be used to cancel the statements execution.
 163    */
 164   mozIStoragePendingStatement executeAsync(
 165     [optional] in mozIStorageStatementCallback aCallback
 166   );
 167
 168   /**
 169    * The current state.  Row getters are only valid while
 170    * the statement is in the "executing" state.
 171    */
 172   const long MOZ_STORAGE_STATEMENT_INVALID = 0;
 173   const long MOZ_STORAGE_STATEMENT_READY = 1;
 174   const long MOZ_STORAGE_STATEMENT_EXECUTING = 2;
 175
 176   readonly attribute long state;
 177
 178   [noscript,notxpcom] sqlite3stmtptr getNativeStatementPointer();
 179
 180   /**
 181    * Escape a string for SQL LIKE search.
 182    *
 183    * @param     aValue the string to escape for SQL LIKE
 184    * @param     aEscapeChar the escape character
 185    * @returns   an AString of an escaped version of aValue
 186    *            (%, _ and the escape char are escaped with the escape char)
 187    *            For example, we will convert "foo/bar_baz%20cheese"
 188    *            into "foo//bar/_baz/%20cheese" (if the escape char is '/').
 189    * @note      consumers will have to use same escape char
 190    *            when doing statements such as:   ...LIKE '?1' ESCAPE '/'...
 191    */
 192   AString escapeStringForLIKE(in AString aValue, in wchar aEscapeChar);
 193 };