storage/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, builtinclass, uuid(5f567c35-6c32-4140-828c-683ea49cfd3a)]
  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    * Reset parameters/statement execution
  70    */
  71   void reset();
  72
  73   /**
  74    * Execute the query, ignoring any results.  This is accomplished by
  75    * calling executeStep() once, and then calling reset().
  76    *
  77    * Error and last insert info, etc. are available from
  78    * the mozStorageConnection.
  79    */
  80   void execute();
  81
  82   /**
  83    * Execute a query, using any currently-bound parameters.  Reset
  84    * must be called on the statement after the last call of
  85    * executeStep.
  86    *
  87    * @return a boolean indicating whether there are more rows or not;
  88    *         row data may be accessed using mozIStorageValueArray methods on
  89    *         the statement.
  90    */
  91   boolean executeStep();
  92
  93   /**
  94    * Execute a query, using any currently-bound parameters.  Reset is called
  95    * when no more data is returned.  This method is only available to JavaScript
  96    * consumers.
  97    *
  98    * @deprecated As of Mozilla 1.9.2 in favor of executeStep().
  99    *
 100    * @return a boolean indicating whether there are more rows or not.
 101    *
 102    * [deprecated] boolean step();
 103    */
 104
 105   /**
 106    * Obtains the current list of named parameters, which are settable.  This
 107    * property is only available to JavaScript consumers.
 108    *
 109    * readonly attribute mozIStorageStatementParams params;
 110    */
 111
 112   /**
 113    * Obtains the current row, with access to all the data members by name.  This
 114    * property is only available to JavaScript consumers.
 115    *
 116    * readonly attribute mozIStorageStatementRow row;
 117    */
 118
 119   //////////////////////////////////////////////////////////////////////////////
 120   //// Copied contents of mozIStorageValueArray
 121
 122   /**
 123    * These type values are returned by getTypeOfIndex
 124    * to indicate what type of value is present at
 125    * a given column.
 126    */
 127   const long VALUE_TYPE_NULL = 0;
 128   const long VALUE_TYPE_INTEGER = 1;
 129   const long VALUE_TYPE_FLOAT = 2;
 130   const long VALUE_TYPE_TEXT = 3;
 131   const long VALUE_TYPE_BLOB = 4;
 132
 133   /**
 134    * The number of entries in the array (each corresponding to a column in the
 135    * database row)
 136    */
 137   readonly attribute unsigned long numEntries;
 138
 139   /**
 140    * Indicate the data type of the current result row for the the given column.
 141    * SQLite will perform type conversion if you ask for a value as a different
 142    * type than it is stored as.
 143    *
 144    * @param aIndex
 145    *        0-based column index.
 146    * @return The type of the value at the given column index; one of
 147    *         VALUE_TYPE_NULL, VALUE_TYPE_INTEGER, VALUE_TYPE_FLOAT,
 148    *         VALUE_TYPE_TEXT, VALUE_TYPE_BLOB.
 149    */
 150   long getTypeOfIndex(in unsigned long aIndex);
 151
 152   /**
 153    * Retrieve the contents of a column from the current result row as a
 154    * variant.
 155    *
 156    * @param aIndex
 157    *        0-based colummn index.
 158    * @return A variant with the type of the column value.
 159    */
 160   nsIVariant getVariant(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   /**
 212    * Retrieve the contents of a Blob column from the current result row as a
 213    * string.
 214    *
 215    * @param aIndex
 216    *        0-based colummn index.
 217    * @return The value for the result Blob column interpreted as a String.
 218    *         No encoding conversion is performed.
 219    */
 220   AString getBlobAsString(in unsigned long aIndex);
 221
 222   /**
 223    * Retrieve the contents of a Blob column from the current result row as a
 224    * UTF8 string.
 225    *
 226    * @param aIndex
 227    *        0-based colummn index.
 228    * @return The value for the result Blob column interpreted as a UTF8 String.
 229    *         No encoding conversion is performed.
 230    */
 231   AUTF8String getBlobAsUTF8String(in unsigned long aIndex);
 232
 233   /**
 234    * Check whether the given column in the current result row is NULL.
 235    *
 236    * @param aIndex
 237    *        0-based colummn index.
 238    * @return true if the value for the result column is null.
 239    */
 240   boolean getIsNull(in unsigned long aIndex);
 241
 242   /**
 243    * Returns a shared string pointer.
 244    *
 245    * @param aIndex
 246    *        0-based colummn index.
 247    * @param aByteLength
 248    *        The number of bytes in the string or blob. This is the same as the
 249    *        number of characters for UTF-8 strings, and twice the number of
 250    *        characters for UTF-16 strings.
 251    * @param aResult
 252    *        A pointer to the string or blob.
 253    */
 254   [noscript] void getSharedUTF8String(in unsigned long aIndex, out unsigned long aByteLength, [shared,retval] out string aResult);
 255   [noscript] void getSharedString(in unsigned long aIndex, out unsigned long aByteLength, [shared,retval] out wstring aResult);
 256   [noscript] void getSharedBlob(in unsigned long aIndex, out unsigned long aByteLength, [shared,retval] out octetPtr aResult);
 257
 258 %{C++
 259   /**
 260    * Getters for native code that return their values as
 261    * the return type, for convenience and sanity.
 262    *
 263    * Not virtual; no vtable bloat.
 264    */
 265
 266   inline int32_t AsInt32(uint32_t idx) {
 267     int32_t v = 0;
 268     mozilla::DebugOnly<nsresult> rv = GetInt32(idx, &v);
 269     MOZ_ASSERT(NS_SUCCEEDED(rv) || IsNull(idx),
 270                "Getting value failed, wrong column index?");
 271     return v;
 272   }
 273
 274   inline int64_t AsInt64(uint32_t idx) {
 275     int64_t v = 0;
 276     mozilla::DebugOnly<nsresult> rv = GetInt64(idx, &v);
 277     MOZ_ASSERT(NS_SUCCEEDED(rv) || IsNull(idx),
 278                "Getting value failed, wrong column index?");
 279     return v;
 280   }
 281
 282   inline double AsDouble(uint32_t idx) {
 283     double v = 0.0;
 284     mozilla::DebugOnly<nsresult> rv = GetDouble(idx, &v);
 285     MOZ_ASSERT(NS_SUCCEEDED(rv) || IsNull(idx),
 286                "Getting value failed, wrong column index?");
 287     return v;
 288   }
 289
 290   inline const char* AsSharedUTF8String(uint32_t idx, uint32_t *len) {
 291     const char *str = nullptr;
 292     *len = 0;
 293     mozilla::DebugOnly<nsresult> rv = GetSharedUTF8String(idx, len, &str);
 294     MOZ_ASSERT(NS_SUCCEEDED(rv) || IsNull(idx),
 295                "Getting value failed, wrong column index?");
 296     return str;
 297   }
 298
 299   inline const char16_t* AsSharedWString(uint32_t idx, uint32_t *len) {
 300     const char16_t *str = nullptr;
 301     *len = 0;
 302     mozilla::DebugOnly<nsresult> rv = GetSharedString(idx, len, &str);
 303     MOZ_ASSERT(NS_SUCCEEDED(rv) || IsNull(idx),
 304                "Getting value failed, wrong column index?");
 305     return str;
 306   }
 307
 308   inline const uint8_t* AsSharedBlob(uint32_t idx, uint32_t *len) {
 309     const uint8_t *blob = nullptr;
 310     *len = 0;
 311     mozilla::DebugOnly<nsresult> rv = GetSharedBlob(idx, len, &blob);
 312     MOZ_ASSERT(NS_SUCCEEDED(rv) || IsNull(idx),
 313                "Getting value failed, wrong column index?");
 314     return blob;
 315   }
 316
 317   inline bool IsNull(uint32_t idx) {
 318     bool b = false;
 319     mozilla::DebugOnly<nsresult> rv = GetIsNull(idx, &b);
 320     MOZ_ASSERT(NS_SUCCEEDED(rv),
 321                "Getting value failed, wrong column index?");
 322     return b;
 323   }
 324
 325 %}
 326 };