1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
2 * vim: sw=2 ts=2 sts=2 expandtab
3 * This Source Code Form is subject to the terms of the Mozilla Public
4 * License, v. 2.0. If a copy of the MPL was not distributed with this
5 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
7 #include
"mozIStorageBaseStatement.idl"
9 #include
"mozilla/DebugOnly.h"
12 [ptr] native octetPtr
(uint8_t
);
15 * A SQL statement that can be used for both synchronous and asynchronous
18 [scriptable
, uuid(5f567c35
-6c32
-4140-828c
-683ea49cfd3a
)]
19 interface mozIStorageStatement
: mozIStorageBaseStatement
{
21 * Create a clone of this statement, by initializing a new statement
22 * with the same connection and same SQL statement as this one. It
23 * does not preserve statement state; that is, if a statement is
24 * being executed when it is cloned, the new statement will not be
27 mozIStorageStatement clone
();
30 * Number of parameters
32 readonly attribute
unsigned long parameterCount
;
35 * Name of nth parameter, if given
37 AUTF8String getParameterName
(in unsigned long aParamIndex
);
40 * Returns the index of the named parameter.
43 * The name of the parameter you want the index for. This does not
44 * include the leading ':'.
45 * @return the index of the named parameter.
47 unsigned long getParameterIndex
(in AUTF8String aName
);
50 * Number of columns returned
52 readonly attribute
unsigned long columnCount
;
57 AUTF8String getColumnName
(in unsigned long aColumnIndex
);
60 * Obtains the index of the column with the specified name.
63 * The name of the column.
64 * @return The index of the column with the specified name.
66 unsigned long getColumnIndex
(in AUTF8String aName
);
69 * Reset parameters/statement execution
74 * Execute the query, ignoring any results. This is accomplished by
75 * calling executeStep() once, and then calling reset().
77 * Error and last insert info, etc. are available from
78 * the mozStorageConnection.
83 * Execute a query, using any currently-bound parameters. Reset
84 * must be called on the statement after the last call of
87 * @return a boolean indicating whether there are more rows or not;
88 * row data may be accessed using mozIStorageValueArray methods on
91 boolean executeStep
();
94 * Execute a query, using any currently-bound parameters. Reset is called
95 * when no more data is returned. This method is only available to JavaScript
98 * @deprecated As of Mozilla 1.9.2 in favor of executeStep().
100 * @return a boolean indicating whether there are more rows or not.
102 * [deprecated] boolean step();
106 * Obtains the current list of named parameters, which are settable. This
107 * property is only available to JavaScript consumers.
109 * readonly attribute mozIStorageStatementParams params;
113 * Obtains the current row, with access to all the data members by name. This
114 * property is only available to JavaScript consumers.
116 * readonly attribute mozIStorageStatementRow row;
119 //////////////////////////////////////////////////////////////////////////////
120 //// Copied contents of mozIStorageValueArray
123 * These type values are returned by getTypeOfIndex
124 * to indicate what type of value is present at
127 const long VALUE_TYPE_NULL
= 0;
128 const long VALUE_TYPE_INTEGER
= 1;
129 const long VALUE_TYPE_FLOAT
= 2;
130 const long VALUE_TYPE_TEXT
= 3;
131 const long VALUE_TYPE_BLOB
= 4;
134 * The number of entries in the array (each corresponding to a column in the
137 readonly attribute
unsigned long numEntries
;
140 * Indicate the data type of the current result row for the the given column.
141 * SQLite will perform type conversion if you ask for a value as a different
142 * type than it is stored as.
145 * 0-based column index.
146 * @return The type of the value at the given column index; one of
147 * VALUE_TYPE_NULL, VALUE_TYPE_INTEGER, VALUE_TYPE_FLOAT,
148 * VALUE_TYPE_TEXT, VALUE_TYPE_BLOB.
150 long getTypeOfIndex
(in unsigned long aIndex
);
153 * Retrieve the contents of a column from the current result row as an
157 * 0-based colummn index.
158 * @return Column value interpreted as an integer per type conversion rules.
161 long getInt32
(in unsigned long aIndex
);
162 long long getInt64
(in unsigned long aIndex
);
165 * Retrieve the contents of a column from the current result row as a
166 * floating point double.
169 * 0-based colummn index.
170 * @return Column value interpreted as a double per type conversion rules.
172 double getDouble
(in unsigned long aIndex
);
174 * Retrieve the contents of a column from the current result row as a
178 * 0-based colummn index.
179 * @return The value for the result column interpreted as a string. If the
180 * stored value was NULL, you will get an empty string with IsVoid set
181 * to distinguish it from an explicitly set empty string.
184 AUTF8String getUTF8String
(in unsigned long aIndex
);
185 AString getString
(in unsigned long aIndex
);
189 * Retrieve the contents of a column from the current result row as a
193 * 0-based colummn index.
194 * @param[out] aDataSize
195 * The number of bytes in the blob.
197 * The contents of the BLOB. This will be NULL if aDataSize == 0.
199 void getBlob
(in unsigned long aIndex
, out unsigned long aDataSize
, [array
,size_is(aDataSize
)] out octet aData
);
202 * Retrieve the contents of a Blob column from the current result row as a
206 * 0-based colummn index.
207 * @return The value for the result Blob column interpreted as a String.
208 * No encoding conversion is performed.
210 AString getBlobAsString
(in unsigned long aIndex
);
213 * Retrieve the contents of a Blob column from the current result row as a
217 * 0-based colummn index.
218 * @return The value for the result Blob column interpreted as a UTF8 String.
219 * No encoding conversion is performed.
221 AUTF8String getBlobAsUTF8String
(in unsigned long aIndex
);
224 * Check whether the given column in the current result row is NULL.
227 * 0-based colummn index.
228 * @return true if the value for the result column is null.
230 boolean getIsNull
(in unsigned long aIndex
);
233 * Returns a shared string pointer
235 [noscript
] void getSharedUTF8String
(in unsigned long aIndex
, out unsigned long aLength
, [shared
,retval] out string aResult
);
236 [noscript
] void getSharedString
(in unsigned long aIndex
, out unsigned long aLength
, [shared
,retval] out wstring aResult
);
237 [noscript
] void getSharedBlob
(in unsigned long aIndex
, out unsigned long aLength
, [shared
,retval] out octetPtr aResult
);
241 * Getters for native code that return their values as
242 * the return type, for convenience and sanity.
244 * Not virtual; no vtable bloat.
247 inline int32_t AsInt32
(uint32_t idx
) {
249 mozilla
::DebugOnly
<nsresult
> rv
= GetInt32
(idx
, &v
);
250 MOZ_ASSERT
(NS_SUCCEEDED
(rv
) || IsNull
(idx
),
251 "Getting value failed, wrong column index?");
255 inline int64_t AsInt64
(uint32_t idx
) {
257 mozilla
::DebugOnly
<nsresult
> rv
= GetInt64
(idx
, &v
);
258 MOZ_ASSERT
(NS_SUCCEEDED
(rv
) || IsNull
(idx
),
259 "Getting value failed, wrong column index?");
263 inline
double AsDouble
(uint32_t idx
) {
265 mozilla
::DebugOnly
<nsresult
> rv
= GetDouble
(idx
, &v
);
266 MOZ_ASSERT
(NS_SUCCEEDED
(rv
) || IsNull
(idx
),
267 "Getting value failed, wrong column index?");
271 inline
const char* AsSharedUTF8String
(uint32_t idx
, uint32_t
*len
) {
272 const char *str
= nullptr
;
274 mozilla
::DebugOnly
<nsresult
> rv
= GetSharedUTF8String
(idx
, len
, &str
);
275 MOZ_ASSERT
(NS_SUCCEEDED
(rv
) || IsNull
(idx
),
276 "Getting value failed, wrong column index?");
280 inline
const char16_t
* AsSharedWString
(uint32_t idx
, uint32_t
*len
) {
281 const char16_t
*str
= nullptr
;
283 mozilla
::DebugOnly
<nsresult
> rv
= GetSharedString
(idx
, len
, &str
);
284 MOZ_ASSERT
(NS_SUCCEEDED
(rv
) || IsNull
(idx
),
285 "Getting value failed, wrong column index?");
289 inline
const uint8_t
* AsSharedBlob
(uint32_t idx
, uint32_t
*len
) {
290 const uint8_t
*blob
= nullptr
;
292 mozilla
::DebugOnly
<nsresult
> rv
= GetSharedBlob
(idx
, len
, &blob
);
293 MOZ_ASSERT
(NS_SUCCEEDED
(rv
) || IsNull
(idx
),
294 "Getting value failed, wrong column index?");
298 inline bool IsNull
(uint32_t idx
) {
300 mozilla
::DebugOnly
<nsresult
> rv
= GetIsNull
(idx
, &b
);
301 MOZ_ASSERT
(NS_SUCCEEDED
(rv
),
302 "Getting value failed, wrong column index?");