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