storage/mozIStorageValueArray.idl

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 #include "nsISupports.idl"
   7 %{C++
   8 #include "mozilla/DebugOnly.h"
   9 %}
  10
  11 [ptr] native octetPtr(uint8_t);
  12
  13 /**
  14  * mozIStorageValueArray wraps an array of SQL values, such as a single database
  15  * row.
  16  */
  17 [scriptable, uuid(6e6306f4-ffa7-40f5-96ca-36159ce8f431)]
  18 interface mozIStorageValueArray : nsISupports {
  19   /**
  20    * These type values are returned by getTypeOfIndex
  21    * to indicate what type of value is present at
  22    * a given column.
  23    */
  24   const long VALUE_TYPE_NULL = 0;
  25   const long VALUE_TYPE_INTEGER = 1;
  26   const long VALUE_TYPE_FLOAT = 2;
  27   const long VALUE_TYPE_TEXT = 3;
  28   const long VALUE_TYPE_BLOB = 4;
  29
  30   /**
  31    * numEntries
  32    *
  33    * number of entries in the array (each corresponding to a column
  34    * in the database row)
  35    */
  36   readonly attribute unsigned long numEntries;
  37
  38   /**
  39    * Returns the type of the value at the given column index;
  40    * one of VALUE_TYPE_NULL, VALUE_TYPE_INTEGER, VALUE_TYPE_FLOAT,
  41    * VALUE_TYPE_TEXT, VALUE_TYPE_BLOB.
  42    */
  43   long getTypeOfIndex(in unsigned long aIndex);
  44
  45   /**
  46    * Obtain a value for the given entry (column) index.
  47    * Due to SQLite's type conversion rules, any of these are valid
  48    * for any column regardless of the column's data type.  However,
  49    * if the specific type matters, getTypeOfIndex should be used
  50    * first to identify the column type, and then the appropriate
  51    * get method should be called.
  52    *
  53    * If you ask for a string value for a NULL column, you will get an empty
  54    * string with IsVoid set to distinguish it from an explicitly set empty
  55    * string.
  56    */
  57   long getInt32(in unsigned long aIndex);
  58   long long getInt64(in unsigned long aIndex);
  59   double getDouble(in unsigned long aIndex);
  60   AUTF8String getUTF8String(in unsigned long aIndex);
  61   AString getString(in unsigned long aIndex);
  62
  63   // data will be NULL if dataSize = 0
  64   void getBlob(in unsigned long aIndex, out unsigned long aDataSize, [array,size_is(aDataSize)] out octet aData);
  65   AString getBlobAsString(in unsigned long aIndex);
  66   AUTF8String getBlobAsUTF8String(in unsigned long aIndex);
  67   boolean getIsNull(in unsigned long aIndex);
  68
  69   /**
  70    * Returns a shared string pointer.
  71    *
  72    * @param aIndex
  73    *        0-based colummn index.
  74    * @param aByteLength
  75    *        The number of bytes in the string or blob. This is the same as the
  76    *        number of characters for UTF-8 strings, and twice the number of
  77    *        characters for UTF-16 strings.
  78    * @param aResult
  79    *        A pointer to the string or blob.
  80    */
  81   [noscript] void getSharedUTF8String(in unsigned long aIndex, out unsigned long aByteLength, [shared,retval] out string aResult);
  82   [noscript] void getSharedString(in unsigned long aIndex, out unsigned long aByteLength, [shared,retval] out wstring aResult);
  83   [noscript] void getSharedBlob(in unsigned long aIndex, out unsigned long aByteLength, [shared,retval] out octetPtr aResult);
  84
  85   /**
  86    * Getters for native code that return their values as
  87    * the return type, for convenience and sanity.
  88    *
  89    * Not virtual; no vtable bloat.
  90    */
  91
  92 %{C++
  93   inline int32_t AsInt32(uint32_t idx) {
  94     int32_t v = 0;
  95     mozilla::DebugOnly<nsresult> rv = GetInt32(idx, &v);
  96     MOZ_ASSERT(NS_SUCCEEDED(rv) || IsNull(idx),
  97                "Getting value failed, wrong column index?");
  98     return v;
  99   }
 100
 101   inline int64_t AsInt64(uint32_t idx) {
 102     int64_t v = 0;
 103     mozilla::DebugOnly<nsresult> rv = GetInt64(idx, &v);
 104     MOZ_ASSERT(NS_SUCCEEDED(rv) || IsNull(idx),
 105                "Getting value failed, wrong column index?");
 106     return v;
 107   }
 108
 109   inline double AsDouble(uint32_t idx) {
 110     double v = 0.0;
 111     mozilla::DebugOnly<nsresult> rv = GetDouble(idx, &v);
 112     MOZ_ASSERT(NS_SUCCEEDED(rv) || IsNull(idx),
 113                "Getting value failed, wrong column index?");
 114     return v;
 115   }
 116
 117   inline const char* AsSharedUTF8String(uint32_t idx, uint32_t *len) {
 118     const char *str = nullptr;
 119     *len = 0;
 120     mozilla::DebugOnly<nsresult> rv = GetSharedUTF8String(idx, len, &str);
 121     MOZ_ASSERT(NS_SUCCEEDED(rv) || IsNull(idx),
 122                "Getting value failed, wrong column index?");
 123     return str;
 124   }
 125
 126   inline const char16_t* AsSharedWString(uint32_t idx, uint32_t *len) {
 127     const char16_t *str = nullptr;
 128     *len = 0;
 129     mozilla::DebugOnly<nsresult> rv = GetSharedString(idx, len, &str);
 130     MOZ_ASSERT(NS_SUCCEEDED(rv) || IsNull(idx),
 131                "Getting value failed, wrong column index?");
 132     return str;
 133   }
 134
 135   inline const uint8_t* AsSharedBlob(uint32_t idx, uint32_t *len) {
 136     const uint8_t *blob = nullptr;
 137     *len = 0;
 138     mozilla::DebugOnly<nsresult> rv = GetSharedBlob(idx, len, &blob);
 139     MOZ_ASSERT(NS_SUCCEEDED(rv) || IsNull(idx),
 140                "Getting value failed, wrong column index?");
 141     return blob;
 142   }
 143
 144   inline bool IsNull(uint32_t idx) {
 145     bool b = false;
 146     mozilla::DebugOnly<nsresult> rv = GetIsNull(idx, &b);
 147     MOZ_ASSERT(NS_SUCCEEDED(rv),
 148                "Getting value failed, wrong column index?");
 149     return b;
 150   }
 151
 152 %}
 153
 154 };