mozIStorageValueArray.idl (5270B)
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 };