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   [noscript] void getSharedUTF8String(in unsigned long aIndex, out unsigned long aLength, [shared,retval] out string aResult);
  73   [noscript] void getSharedString(in unsigned long aIndex, out unsigned long aLength, [shared,retval] out wstring aResult);
  74   [noscript] void getSharedBlob(in unsigned long aIndex, out unsigned long aLength, [shared,retval] out octetPtr aResult);
  75
  76 %{C++
  77   /**
  78    * Getters for native code that return their values as
  79    * the return type, for convenience and sanity.
  80    *
  81    * Not virtual; no vtable bloat.
  82    */
  83
  84   inline int32_t AsInt32(uint32_t idx) {
  85     int32_t v = 0;
  86     mozilla::DebugOnly<nsresult> rv = GetInt32(idx, &v);
  87     MOZ_ASSERT(NS_SUCCEEDED(rv) || IsNull(idx),
  88                "Getting value failed, wrong column index?");
  89     return v;
  90   }
  91
  92   inline int64_t AsInt64(uint32_t idx) {
  93     int64_t v = 0;
  94     mozilla::DebugOnly<nsresult> rv = GetInt64(idx, &v);
  95     MOZ_ASSERT(NS_SUCCEEDED(rv) || IsNull(idx),
  96                "Getting value failed, wrong column index?");
  97     return v;
  98   }
  99
 100   inline double AsDouble(uint32_t idx) {
 101     double v = 0.0;
 102     mozilla::DebugOnly<nsresult> rv = GetDouble(idx, &v);
 103     MOZ_ASSERT(NS_SUCCEEDED(rv) || IsNull(idx),
 104                "Getting value failed, wrong column index?");
 105     return v;
 106   }
 107
 108   inline const char* AsSharedUTF8String(uint32_t idx, uint32_t *len) {
 109     const char *str = nullptr;
 110     *len = 0;
 111     mozilla::DebugOnly<nsresult> rv = GetSharedUTF8String(idx, len, &str);
 112     MOZ_ASSERT(NS_SUCCEEDED(rv) || IsNull(idx),
 113                "Getting value failed, wrong column index?");
 114     return str;
 115   }
 116
 117   inline const char16_t* AsSharedWString(uint32_t idx, uint32_t *len) {
 118     const char16_t *str = nullptr;
 119     *len = 0;
 120     mozilla::DebugOnly<nsresult> rv = GetSharedString(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 uint8_t* AsSharedBlob(uint32_t idx, uint32_t *len) {
 127     const uint8_t *blob = nullptr;
 128     *len = 0;
 129     mozilla::DebugOnly<nsresult> rv = GetSharedBlob(idx, len, &blob);
 130     MOZ_ASSERT(NS_SUCCEEDED(rv) || IsNull(idx),
 131                "Getting value failed, wrong column index?");
 132     return blob;
 133   }
 134
 135   inline bool IsNull(uint32_t idx) {
 136     bool b = false;
 137     mozilla::DebugOnly<nsresult> rv = GetIsNull(idx, &b);
 138     MOZ_ASSERT(NS_SUCCEEDED(rv),
 139                "Getting value failed, wrong column index?");
 140     return b;
 141   }
 142
 143 %}
 144
 145 };