diff options
Diffstat (limited to 'storage/mozIStorageStatement.idl')
| -rw-r--r-- | storage/mozIStorageStatement.idl | 326 |
1 files changed, 326 insertions, 0 deletions
diff --git a/storage/mozIStorageStatement.idl b/storage/mozIStorageStatement.idl new file mode 100644 index 0000000000..ad2821bb6c --- /dev/null +++ b/storage/mozIStorageStatement.idl @@ -0,0 +1,326 @@ +/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- + * vim: sw=2 ts=2 sts=2 expandtab + * This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ + +#include "mozIStorageBaseStatement.idl" +%{C++ +#include "mozilla/DebugOnly.h" +%} + +[ptr] native octetPtr(uint8_t); + +/** + * A SQL statement that can be used for both synchronous and asynchronous + * purposes. + */ +[scriptable, builtinclass, uuid(5f567c35-6c32-4140-828c-683ea49cfd3a)] +interface mozIStorageStatement : mozIStorageBaseStatement { + /** + * Create a clone of this statement, by initializing a new statement + * with the same connection and same SQL statement as this one. It + * does not preserve statement state; that is, if a statement is + * being executed when it is cloned, the new statement will not be + * executing. + */ + mozIStorageStatement clone(); + + /* + * Number of parameters + */ + readonly attribute unsigned long parameterCount; + + /** + * Name of nth parameter, if given + */ + AUTF8String getParameterName(in unsigned long aParamIndex); + + /** + * Returns the index of the named parameter. + * + * @param aName + * The name of the parameter you want the index for. This does not + * include the leading ':'. + * @return the index of the named parameter. + */ + unsigned long getParameterIndex(in AUTF8String aName); + + /** + * Number of columns returned + */ + readonly attribute unsigned long columnCount; + + /** + * Name of nth column + */ + AUTF8String getColumnName(in unsigned long aColumnIndex); + + /** + * Obtains the index of the column with the specified name. + * + * @param aName + * The name of the column. + * @return The index of the column with the specified name. + */ + unsigned long getColumnIndex(in AUTF8String aName); + + /** + * Reset parameters/statement execution + */ + void reset(); + + /** + * Execute the query, ignoring any results. This is accomplished by + * calling executeStep() once, and then calling reset(). + * + * Error and last insert info, etc. are available from + * the mozStorageConnection. + */ + void execute(); + + /** + * Execute a query, using any currently-bound parameters. Reset + * must be called on the statement after the last call of + * executeStep. + * + * @return a boolean indicating whether there are more rows or not; + * row data may be accessed using mozIStorageValueArray methods on + * the statement. + */ + boolean executeStep(); + + /** + * Execute a query, using any currently-bound parameters. Reset is called + * when no more data is returned. This method is only available to JavaScript + * consumers. + * + * @deprecated As of Mozilla 1.9.2 in favor of executeStep(). + * + * @return a boolean indicating whether there are more rows or not. + * + * [deprecated] boolean step(); + */ + + /** + * Obtains the current list of named parameters, which are settable. This + * property is only available to JavaScript consumers. + * + * readonly attribute mozIStorageStatementParams params; + */ + + /** + * Obtains the current row, with access to all the data members by name. This + * property is only available to JavaScript consumers. + * + * readonly attribute mozIStorageStatementRow row; + */ + + ////////////////////////////////////////////////////////////////////////////// + //// Copied contents of mozIStorageValueArray + + /** + * These type values are returned by getTypeOfIndex + * to indicate what type of value is present at + * a given column. + */ + const long VALUE_TYPE_NULL = 0; + const long VALUE_TYPE_INTEGER = 1; + const long VALUE_TYPE_FLOAT = 2; + const long VALUE_TYPE_TEXT = 3; + const long VALUE_TYPE_BLOB = 4; + + /** + * The number of entries in the array (each corresponding to a column in the + * database row) + */ + readonly attribute unsigned long numEntries; + + /** + * Indicate the data type of the current result row for the the given column. + * SQLite will perform type conversion if you ask for a value as a different + * type than it is stored as. + * + * @param aIndex + * 0-based column index. + * @return The type of the value at the given column index; one of + * VALUE_TYPE_NULL, VALUE_TYPE_INTEGER, VALUE_TYPE_FLOAT, + * VALUE_TYPE_TEXT, VALUE_TYPE_BLOB. + */ + long getTypeOfIndex(in unsigned long aIndex); + + /** + * Retrieve the contents of a column from the current result row as a + * variant. + * + * @param aIndex + * 0-based colummn index. + * @return A variant with the type of the column value. + */ + nsIVariant getVariant(in unsigned long aIndex); + + /** + * Retrieve the contents of a column from the current result row as an + * integer. + * + * @param aIndex + * 0-based colummn index. + * @return Column value interpreted as an integer per type conversion rules. + * @{ + */ + long getInt32(in unsigned long aIndex); + long long getInt64(in unsigned long aIndex); + /** @} */ + /** + * Retrieve the contents of a column from the current result row as a + * floating point double. + * + * @param aIndex + * 0-based colummn index. + * @return Column value interpreted as a double per type conversion rules. + */ + double getDouble(in unsigned long aIndex); + /** + * Retrieve the contents of a column from the current result row as a + * string. + * + * @param aIndex + * 0-based colummn index. + * @return The value for the result column interpreted as a string. If the + * stored value was NULL, you will get an empty string with IsVoid set + * to distinguish it from an explicitly set empty string. + * @{ + */ + AUTF8String getUTF8String(in unsigned long aIndex); + AString getString(in unsigned long aIndex); + /** @} */ + + /** + * Retrieve the contents of a column from the current result row as a + * blob. + * + * @param aIndex + * 0-based colummn index. + * @param[out] aDataSize + * The number of bytes in the blob. + * @param[out] aData + * The contents of the BLOB. This will be NULL if aDataSize == 0. + */ + void getBlob(in unsigned long aIndex, out unsigned long aDataSize, [array,size_is(aDataSize)] out octet aData); + + /** + * Retrieve the contents of a Blob column from the current result row as a + * string. + * + * @param aIndex + * 0-based colummn index. + * @return The value for the result Blob column interpreted as a String. + * No encoding conversion is performed. + */ + AString getBlobAsString(in unsigned long aIndex); + + /** + * Retrieve the contents of a Blob column from the current result row as a + * UTF8 string. + * + * @param aIndex + * 0-based colummn index. + * @return The value for the result Blob column interpreted as a UTF8 String. + * No encoding conversion is performed. + */ + AUTF8String getBlobAsUTF8String(in unsigned long aIndex); + + /** + * Check whether the given column in the current result row is NULL. + * + * @param aIndex + * 0-based colummn index. + * @return true if the value for the result column is null. + */ + boolean getIsNull(in unsigned long aIndex); + + /** + * Returns a shared string pointer. + * + * @param aIndex + * 0-based colummn index. + * @param aByteLength + * The number of bytes in the string or blob. This is the same as the + * number of characters for UTF-8 strings, and twice the number of + * characters for UTF-16 strings. + * @param aResult + * A pointer to the string or blob. + */ + [noscript] void getSharedUTF8String(in unsigned long aIndex, out unsigned long aByteLength, [shared,retval] out string aResult); + [noscript] void getSharedString(in unsigned long aIndex, out unsigned long aByteLength, [shared,retval] out wstring aResult); + [noscript] void getSharedBlob(in unsigned long aIndex, out unsigned long aByteLength, [shared,retval] out octetPtr aResult); + + /** + * Getters for native code that return their values as + * the return type, for convenience and sanity. + * + * Not virtual; no vtable bloat. + */ + +%{C++ + inline int32_t AsInt32(uint32_t idx) { + int32_t v = 0; + mozilla::DebugOnly<nsresult> rv = GetInt32(idx, &v); + MOZ_ASSERT(NS_SUCCEEDED(rv) || IsNull(idx), + "Getting value failed, wrong column index?"); + return v; + } + + inline int64_t AsInt64(uint32_t idx) { + int64_t v = 0; + mozilla::DebugOnly<nsresult> rv = GetInt64(idx, &v); + MOZ_ASSERT(NS_SUCCEEDED(rv) || IsNull(idx), + "Getting value failed, wrong column index?"); + return v; + } + + inline double AsDouble(uint32_t idx) { + double v = 0.0; + mozilla::DebugOnly<nsresult> rv = GetDouble(idx, &v); + MOZ_ASSERT(NS_SUCCEEDED(rv) || IsNull(idx), + "Getting value failed, wrong column index?"); + return v; + } + + inline const char* AsSharedUTF8String(uint32_t idx, uint32_t *len) { + const char *str = nullptr; + *len = 0; + mozilla::DebugOnly<nsresult> rv = GetSharedUTF8String(idx, len, &str); + MOZ_ASSERT(NS_SUCCEEDED(rv) || IsNull(idx), + "Getting value failed, wrong column index?"); + return str; + } + + inline const char16_t* AsSharedWString(uint32_t idx, uint32_t *len) { + const char16_t *str = nullptr; + *len = 0; + mozilla::DebugOnly<nsresult> rv = GetSharedString(idx, len, &str); + MOZ_ASSERT(NS_SUCCEEDED(rv) || IsNull(idx), + "Getting value failed, wrong column index?"); + return str; + } + + inline const uint8_t* AsSharedBlob(uint32_t idx, uint32_t *len) { + const uint8_t *blob = nullptr; + *len = 0; + mozilla::DebugOnly<nsresult> rv = GetSharedBlob(idx, len, &blob); + MOZ_ASSERT(NS_SUCCEEDED(rv) || IsNull(idx), + "Getting value failed, wrong column index?"); + return blob; + } + + inline bool IsNull(uint32_t idx) { + bool b = false; + mozilla::DebugOnly<nsresult> rv = GetIsNull(idx, &b); + MOZ_ASSERT(NS_SUCCEEDED(rv), + "Getting value failed, wrong column index?"); + return b; + } + +%} +}; |