michael@0: /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0:  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0: 
michael@0: #include "nsISupports.idl"
michael@0: %{C++
michael@0: #include "mozilla/DebugOnly.h"
michael@0: %}
michael@0: 
michael@0: [ptr] native octetPtr(uint8_t);
michael@0: 
michael@0: /**
michael@0:  * mozIStorageValueArray wraps an array of SQL values, such as a single database
michael@0:  * row.
michael@0:  */
michael@0: [scriptable, uuid(07b5b93e-113c-4150-863c-d247b003a55d)]
michael@0: interface mozIStorageValueArray : nsISupports {
michael@0:   /**
michael@0:    * These type values are returned by getTypeOfIndex
michael@0:    * to indicate what type of value is present at
michael@0:    * a given column.
michael@0:    */
michael@0:   const long VALUE_TYPE_NULL = 0;
michael@0:   const long VALUE_TYPE_INTEGER = 1;
michael@0:   const long VALUE_TYPE_FLOAT = 2;
michael@0:   const long VALUE_TYPE_TEXT = 3;
michael@0:   const long VALUE_TYPE_BLOB = 4;
michael@0: 
michael@0:   /**
michael@0:    * numEntries
michael@0:    *
michael@0:    * number of entries in the array (each corresponding to a column
michael@0:    * in the database row)
michael@0:    */
michael@0:   readonly attribute unsigned long numEntries;
michael@0: 
michael@0:   /**
michael@0:    * Returns the type of the value at the given column index;
michael@0:    * one of VALUE_TYPE_NULL, VALUE_TYPE_INTEGER, VALUE_TYPE_FLOAT,
michael@0:    * VALUE_TYPE_TEXT, VALUE_TYPE_BLOB.
michael@0:    */
michael@0:   long getTypeOfIndex(in unsigned long aIndex);
michael@0: 
michael@0:   /**
michael@0:    * Obtain a value for the given entry (column) index.
michael@0:    * Due to SQLite's type conversion rules, any of these are valid
michael@0:    * for any column regardless of the column's data type.  However,
michael@0:    * if the specific type matters, getTypeOfIndex should be used
michael@0:    * first to identify the column type, and then the appropriate
michael@0:    * get method should be called.
michael@0:    *
michael@0:    * If you ask for a string value for a NULL column, you will get an empty
michael@0:    * string with IsVoid set to distinguish it from an explicitly set empty
michael@0:    * string.
michael@0:    */
michael@0:   long getInt32(in unsigned long aIndex);
michael@0:   long long getInt64(in unsigned long aIndex);
michael@0:   double getDouble(in unsigned long aIndex);
michael@0:   AUTF8String getUTF8String(in unsigned long aIndex);
michael@0:   AString getString(in unsigned long aIndex);
michael@0: 
michael@0:   // data will be NULL if dataSize = 0
michael@0:   void getBlob(in unsigned long aIndex, out unsigned long aDataSize, [array,size_is(aDataSize)] out octet aData);
michael@0:   boolean getIsNull(in unsigned long aIndex);
michael@0: 
michael@0:   /**
michael@0:    * Returns a shared string pointer
michael@0:    */
michael@0:   [noscript] void getSharedUTF8String(in unsigned long aIndex, out unsigned long aLength, [shared,retval] out string aResult);
michael@0:   [noscript] void getSharedString(in unsigned long aIndex, out unsigned long aLength, [shared,retval] out wstring aResult);
michael@0:   [noscript] void getSharedBlob(in unsigned long aIndex, out unsigned long aLength, [shared,retval] out octetPtr aResult);
michael@0: 
michael@0: %{C++
michael@0:   /**
michael@0:    * Getters for native code that return their values as
michael@0:    * the return type, for convenience and sanity.
michael@0:    *
michael@0:    * Not virtual; no vtable bloat.
michael@0:    */
michael@0: 
michael@0:   inline int32_t AsInt32(uint32_t idx) {
michael@0:     int32_t v = 0;
michael@0:     mozilla::DebugOnly<nsresult> rv = GetInt32(idx, &v);
michael@0:     NS_ABORT_IF_FALSE(NS_SUCCEEDED(rv) || IsNull(idx),
michael@0:                       "Getting value failed, wrong column index?");
michael@0:     return v;
michael@0:   }
michael@0: 
michael@0:   inline int64_t AsInt64(uint32_t idx) {
michael@0:     int64_t v = 0;
michael@0:     mozilla::DebugOnly<nsresult> rv = GetInt64(idx, &v);
michael@0:     NS_ABORT_IF_FALSE(NS_SUCCEEDED(rv) || IsNull(idx),
michael@0:                       "Getting value failed, wrong column index?");
michael@0:     return v;
michael@0:   }
michael@0: 
michael@0:   inline double AsDouble(uint32_t idx) {
michael@0:     double v = 0.0;
michael@0:     mozilla::DebugOnly<nsresult> rv = GetDouble(idx, &v);
michael@0:     NS_ABORT_IF_FALSE(NS_SUCCEEDED(rv) || IsNull(idx),
michael@0:                       "Getting value failed, wrong column index?");
michael@0:     return v;
michael@0:   }
michael@0: 
michael@0:   inline const char* AsSharedUTF8String(uint32_t idx, uint32_t *len) {
michael@0:     const char *str = nullptr;
michael@0:     *len = 0;
michael@0:     mozilla::DebugOnly<nsresult> rv = GetSharedUTF8String(idx, len, &str);
michael@0:     NS_ABORT_IF_FALSE(NS_SUCCEEDED(rv) || IsNull(idx),
michael@0:                       "Getting value failed, wrong column index?");
michael@0:     return str;
michael@0:   }
michael@0: 
michael@0:   inline const char16_t* AsSharedWString(uint32_t idx, uint32_t *len) {
michael@0:     const char16_t *str = nullptr;
michael@0:     *len = 0;
michael@0:     mozilla::DebugOnly<nsresult> rv = GetSharedString(idx, len, &str);
michael@0:     NS_ABORT_IF_FALSE(NS_SUCCEEDED(rv) || IsNull(idx),
michael@0:                       "Getting value failed, wrong column index?");
michael@0:     return str;
michael@0:   }
michael@0: 
michael@0:   inline const uint8_t* AsSharedBlob(uint32_t idx, uint32_t *len) {
michael@0:     const uint8_t *blob = nullptr;
michael@0:     *len = 0;
michael@0:     mozilla::DebugOnly<nsresult> rv = GetSharedBlob(idx, len, &blob);
michael@0:     NS_ABORT_IF_FALSE(NS_SUCCEEDED(rv) || IsNull(idx),
michael@0:                       "Getting value failed, wrong column index?");
michael@0:     return blob;
michael@0:   }
michael@0: 
michael@0:   inline bool IsNull(uint32_t idx) {
michael@0:     bool b = false;
michael@0:     mozilla::DebugOnly<nsresult> rv = GetIsNull(idx, &b);
michael@0:     NS_ABORT_IF_FALSE(NS_SUCCEEDED(rv),
michael@0:                       "Getting value failed, wrong column index?");
michael@0:     return b;
michael@0:   }
michael@0: 
michael@0: %}
michael@0: 
michael@0: };