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  * 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 "mozIStorageBaseStatement.idl"
   8 %{C++
   9 #include "mozilla/DebugOnly.h"
  10 %}
  11
  12 [ptr] native octetPtr(uint8_t);
  13
  14 /**
  15  * A SQL statement that can be used for both synchronous and asynchronous
  16  * purposes.
  17  */
  18 [scriptable, uuid(b3c4476e-c490-4e3b-9db1-e2d3a6f0287c)]
  19 interface mozIStorageStatement : mozIStorageBaseStatement {
  20   /**
  21    * Create a clone of this statement, by initializing a new statement
  22    * with the same connection and same SQL statement as this one.  It
  23    * does not preserve statement state; that is, if a statement is
  24    * being executed when it is cloned, the new statement will not be
  25    * executing.
  26    */
  27   mozIStorageStatement clone();
  28
  29   /*
  30    * Number of parameters
  31    */
  32   readonly attribute unsigned long parameterCount;
  33
  34   /**
  35    * Name of nth parameter, if given
  36    */
  37   AUTF8String getParameterName(in unsigned long aParamIndex);
  38
  39   /**
  40    * Returns the index of the named parameter.
  41    *
  42    * @param aName
  43    *        The name of the parameter you want the index for.  This does not
  44    *        include the leading ':'.
  45    * @return the index of the named parameter.
  46    */
  47   unsigned long getParameterIndex(in AUTF8String aName);
  48
  49   /**
  50    * Number of columns returned
  51    */
  52   readonly attribute unsigned long columnCount;
  53
  54   /**
  55    * Name of nth column
  56    */
  57   AUTF8String getColumnName(in unsigned long aColumnIndex);
  58
  59   /**
  60    * Obtains the index of the column with the specified name.
  61    *
  62    * @param aName
  63    *        The name of the column.
  64    * @return The index of the column with the specified name.
  65    */
  66   unsigned long getColumnIndex(in AUTF8String aName);
  67
  68   /**
  69    * Obtains the declared column type of a prepared statement.
  70    *
  71    * @param aParamIndex
  72    *        The zero-based index of the column who's declared type we are
  73    *        interested in.
  74    * @return the declared index type.
  75    */
  76   AUTF8String getColumnDecltype(in unsigned long aParamIndex);
  77
  78   /**
  79    * Reset parameters/statement execution
  80    */
  81   void reset();
  82
  83   /**
  84    * Execute the query, ignoring any results.  This is accomplished by
  85    * calling executeStep() once, and then calling reset().
  86    *
  87    * Error and last insert info, etc. are available from
  88    * the mozStorageConnection.
  89    */
  90   void execute();
  91
  92   /**
  93    * Execute a query, using any currently-bound parameters.  Reset
  94    * must be called on the statement after the last call of
  95    * executeStep.
  96    *
  97    * @return a boolean indicating whether there are more rows or not;
  98    *         row data may be accessed using mozIStorageValueArray methods on
  99    *         the statement.
 100    */
 101   boolean executeStep();
 102
 103   /**
 104    * Execute a query, using any currently-bound parameters.  Reset is called
 105    * when no more data is returned.  This method is only available to JavaScript
 106    * consumers.
 107    *
 108    * @deprecated As of Mozilla 1.9.2 in favor of executeStep().
 109    *
 110    * @return a boolean indicating whether there are more rows or not.
 111    *
 112    * [deprecated] boolean step();
 113    */
 114
 115   /**
 116    * Obtains the current list of named parameters, which are settable.  This
 117    * property is only available to JavaScript consumers.
 118    *
 119    * readonly attribute mozIStorageStatementParams params;
 120    */
 121
 122   /**
 123    * Obtains the current row, with access to all the data members by name.  This
 124    * property is only available to JavaScript consumers.
 125    *
 126    * readonly attribute mozIStorageStatementRow row;
 127    */
 128
 129   //////////////////////////////////////////////////////////////////////////////
 130   //// Copied contents of mozIStorageValueArray
 131
 132   /**
 133    * These type values are returned by getTypeOfIndex
 134    * to indicate what type of value is present at
 135    * a given column.
 136    */
 137   const long VALUE_TYPE_NULL = 0;
 138   const long VALUE_TYPE_INTEGER = 1;
 139   const long VALUE_TYPE_FLOAT = 2;
 140   const long VALUE_TYPE_TEXT = 3;
 141   const long VALUE_TYPE_BLOB = 4;
 142
 143   /**
 144    * The number of entries in the array (each corresponding to a column in the
 145    * database row)
 146    */
 147   readonly attribute unsigned long numEntries;
 148
 149   /**
 150    * Indicate the data type of the current result row for the the given column.
 151    * SQLite will perform type conversion if you ask for a value as a different
 152    * type than it is stored as.
 153    *
 154    * @param aIndex
 155    *        0-based column index.
 156    * @return The type of the value at the given column index; one of
 157    *         VALUE_TYPE_NULL, VALUE_TYPE_INTEGER, VALUE_TYPE_FLOAT,
 158    *         VALUE_TYPE_TEXT, VALUE_TYPE_BLOB.
 159    */
 160   long getTypeOfIndex(in unsigned long aIndex);
 161
 162   /**
 163    * Retrieve the contents of a column from the current result row as an
 164    * integer.
 165    *
 166    * @param aIndex
 167    *        0-based colummn index.
 168    * @return Column value interpreted as an integer per type conversion rules.
 169    * @{
 170    */
 171   long getInt32(in unsigned long aIndex);
 172   long long getInt64(in unsigned long aIndex);
 173   /** @} */
 174   /**
 175    * Retrieve the contents of a column from the current result row as a
 176    * floating point double.
 177    *
 178    * @param aIndex
 179    *        0-based colummn index.
 180    * @return Column value interpreted as a double per type conversion rules.
 181    */
 182   double getDouble(in unsigned long aIndex);
 183   /**
 184    * Retrieve the contents of a column from the current result row as a
 185    * string.
 186    *
 187    * @param aIndex
 188    *        0-based colummn index.
 189    * @return The value for the result column interpreted as a string.  If the
 190    *         stored value was NULL, you will get an empty string with IsVoid set
 191    *         to distinguish it from an explicitly set empty string.
 192    * @{
 193    */
 194   AUTF8String getUTF8String(in unsigned long aIndex);
 195   AString getString(in unsigned long aIndex);
 196   /** @} */
 197
 198   /**
 199    * Retrieve the contents of a column from the current result row as a
 200    * blob.
 201    *
 202    * @param aIndex
 203    *        0-based colummn index.
 204    * @param[out] aDataSize
 205    *             The number of bytes in the blob.
 206    * @param[out] aData
 207    *             The contents of the BLOB.  This will be NULL if aDataSize == 0.
 208    */
 209   void getBlob(in unsigned long aIndex, out unsigned long aDataSize, [array,size_is(aDataSize)] out octet aData);
 210   /**
 211    * Check whether the given column in the current result row is NULL.
 212    *
 213    * @param aIndex
 214    *        0-based colummn index.
 215    * @return true if the value for the result column is null.
 216    */
 217   boolean getIsNull(in unsigned long aIndex);
 218
 219   /**
 220    * Returns a shared string pointer
 221    */
 222   [noscript] void getSharedUTF8String(in unsigned long aIndex, out unsigned long aLength, [shared,retval] out string aResult);
 223   [noscript] void getSharedString(in unsigned long aIndex, out unsigned long aLength, [shared,retval] out wstring aResult);
 224   [noscript] void getSharedBlob(in unsigned long aIndex, out unsigned long aLength, [shared,retval] out octetPtr aResult);
 225
 226 %{C++
 227   /**
 228    * Getters for native code that return their values as
 229    * the return type, for convenience and sanity.
 230    *
 231    * Not virtual; no vtable bloat.
 232    */
 233
 234   inline int32_t AsInt32(uint32_t idx) {
 235     int32_t v = 0;
 236     mozilla::DebugOnly<nsresult> rv = GetInt32(idx, &v);
 237     NS_ABORT_IF_FALSE(NS_SUCCEEDED(rv) || IsNull(idx),
 238                       "Getting value failed, wrong column index?");
 239     return v;
 240   }
 241
 242   inline int64_t AsInt64(uint32_t idx) {
 243     int64_t v = 0;
 244     mozilla::DebugOnly<nsresult> rv = GetInt64(idx, &v);
 245     NS_ABORT_IF_FALSE(NS_SUCCEEDED(rv) || IsNull(idx),
 246                       "Getting value failed, wrong column index?");
 247     return v;
 248   }
 249
 250   inline double AsDouble(uint32_t idx) {
 251     double v = 0.0;
 252     mozilla::DebugOnly<nsresult> rv = GetDouble(idx, &v);
 253     NS_ABORT_IF_FALSE(NS_SUCCEEDED(rv) || IsNull(idx),
 254                       "Getting value failed, wrong column index?");
 255     return v;
 256   }
 257
 258   inline const char* AsSharedUTF8String(uint32_t idx, uint32_t *len) {
 259     const char *str = nullptr;
 260     *len = 0;
 261     mozilla::DebugOnly<nsresult> rv = GetSharedUTF8String(idx, len, &str);
 262     NS_ABORT_IF_FALSE(NS_SUCCEEDED(rv) || IsNull(idx),
 263                       "Getting value failed, wrong column index?");
 264     return str;
 265   }
 266
 267   inline const char16_t* AsSharedWString(uint32_t idx, uint32_t *len) {
 268     const char16_t *str = nullptr;
 269     *len = 0;
 270     mozilla::DebugOnly<nsresult> rv = GetSharedString(idx, len, &str);
 271     NS_ABORT_IF_FALSE(NS_SUCCEEDED(rv) || IsNull(idx),
 272                       "Getting value failed, wrong column index?");
 273     return str;
 274   }
 275
 276   inline const uint8_t* AsSharedBlob(uint32_t idx, uint32_t *len) {
 277     const uint8_t *blob = nullptr;
 278     *len = 0;
 279     mozilla::DebugOnly<nsresult> rv = GetSharedBlob(idx, len, &blob);
 280     NS_ABORT_IF_FALSE(NS_SUCCEEDED(rv) || IsNull(idx),
 281                       "Getting value failed, wrong column index?");
 282     return blob;
 283   }
 284
 285   inline bool IsNull(uint32_t idx) {
 286     bool b = false;
 287     mozilla::DebugOnly<nsresult> rv = GetIsNull(idx, &b);
 288     NS_ABORT_IF_FALSE(NS_SUCCEEDED(rv),
 289                       "Getting value failed, wrong column index?");
 290     return b;
 291   }
 292
 293 %}
 294 };