1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/storage/public/mozIStorageStatement.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,294 @@
1.4 +/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
1.5 + * vim: sw=2 ts=2 sts=2 expandtab
1.6 + * This Source Code Form is subject to the terms of the Mozilla Public
1.7 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.8 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.9 +
1.10 +#include "mozIStorageBaseStatement.idl"
1.11 +%{C++
1.12 +#include "mozilla/DebugOnly.h"
1.13 +%}
1.14 +
1.15 +[ptr] native octetPtr(uint8_t);
1.16 +
1.17 +/**
1.18 + * A SQL statement that can be used for both synchronous and asynchronous
1.19 + * purposes.
1.20 + */
1.21 +[scriptable, uuid(b3c4476e-c490-4e3b-9db1-e2d3a6f0287c)]
1.22 +interface mozIStorageStatement : mozIStorageBaseStatement {
1.23 + /**
1.24 + * Create a clone of this statement, by initializing a new statement
1.25 + * with the same connection and same SQL statement as this one. It
1.26 + * does not preserve statement state; that is, if a statement is
1.27 + * being executed when it is cloned, the new statement will not be
1.28 + * executing.
1.29 + */
1.30 + mozIStorageStatement clone();
1.31 +
1.32 + /*
1.33 + * Number of parameters
1.34 + */
1.35 + readonly attribute unsigned long parameterCount;
1.36 +
1.37 + /**
1.38 + * Name of nth parameter, if given
1.39 + */
1.40 + AUTF8String getParameterName(in unsigned long aParamIndex);
1.41 +
1.42 + /**
1.43 + * Returns the index of the named parameter.
1.44 + *
1.45 + * @param aName
1.46 + * The name of the parameter you want the index for. This does not
1.47 + * include the leading ':'.
1.48 + * @return the index of the named parameter.
1.49 + */
1.50 + unsigned long getParameterIndex(in AUTF8String aName);
1.51 +
1.52 + /**
1.53 + * Number of columns returned
1.54 + */
1.55 + readonly attribute unsigned long columnCount;
1.56 +
1.57 + /**
1.58 + * Name of nth column
1.59 + */
1.60 + AUTF8String getColumnName(in unsigned long aColumnIndex);
1.61 +
1.62 + /**
1.63 + * Obtains the index of the column with the specified name.
1.64 + *
1.65 + * @param aName
1.66 + * The name of the column.
1.67 + * @return The index of the column with the specified name.
1.68 + */
1.69 + unsigned long getColumnIndex(in AUTF8String aName);
1.70 +
1.71 + /**
1.72 + * Obtains the declared column type of a prepared statement.
1.73 + *
1.74 + * @param aParamIndex
1.75 + * The zero-based index of the column who's declared type we are
1.76 + * interested in.
1.77 + * @return the declared index type.
1.78 + */
1.79 + AUTF8String getColumnDecltype(in unsigned long aParamIndex);
1.80 +
1.81 + /**
1.82 + * Reset parameters/statement execution
1.83 + */
1.84 + void reset();
1.85 +
1.86 + /**
1.87 + * Execute the query, ignoring any results. This is accomplished by
1.88 + * calling executeStep() once, and then calling reset().
1.89 + *
1.90 + * Error and last insert info, etc. are available from
1.91 + * the mozStorageConnection.
1.92 + */
1.93 + void execute();
1.94 +
1.95 + /**
1.96 + * Execute a query, using any currently-bound parameters. Reset
1.97 + * must be called on the statement after the last call of
1.98 + * executeStep.
1.99 + *
1.100 + * @return a boolean indicating whether there are more rows or not;
1.101 + * row data may be accessed using mozIStorageValueArray methods on
1.102 + * the statement.
1.103 + */
1.104 + boolean executeStep();
1.105 +
1.106 + /**
1.107 + * Execute a query, using any currently-bound parameters. Reset is called
1.108 + * when no more data is returned. This method is only available to JavaScript
1.109 + * consumers.
1.110 + *
1.111 + * @deprecated As of Mozilla 1.9.2 in favor of executeStep().
1.112 + *
1.113 + * @return a boolean indicating whether there are more rows or not.
1.114 + *
1.115 + * [deprecated] boolean step();
1.116 + */
1.117 +
1.118 + /**
1.119 + * Obtains the current list of named parameters, which are settable. This
1.120 + * property is only available to JavaScript consumers.
1.121 + *
1.122 + * readonly attribute mozIStorageStatementParams params;
1.123 + */
1.124 +
1.125 + /**
1.126 + * Obtains the current row, with access to all the data members by name. This
1.127 + * property is only available to JavaScript consumers.
1.128 + *
1.129 + * readonly attribute mozIStorageStatementRow row;
1.130 + */
1.131 +
1.132 + //////////////////////////////////////////////////////////////////////////////
1.133 + //// Copied contents of mozIStorageValueArray
1.134 +
1.135 + /**
1.136 + * These type values are returned by getTypeOfIndex
1.137 + * to indicate what type of value is present at
1.138 + * a given column.
1.139 + */
1.140 + const long VALUE_TYPE_NULL = 0;
1.141 + const long VALUE_TYPE_INTEGER = 1;
1.142 + const long VALUE_TYPE_FLOAT = 2;
1.143 + const long VALUE_TYPE_TEXT = 3;
1.144 + const long VALUE_TYPE_BLOB = 4;
1.145 +
1.146 + /**
1.147 + * The number of entries in the array (each corresponding to a column in the
1.148 + * database row)
1.149 + */
1.150 + readonly attribute unsigned long numEntries;
1.151 +
1.152 + /**
1.153 + * Indicate the data type of the current result row for the the given column.
1.154 + * SQLite will perform type conversion if you ask for a value as a different
1.155 + * type than it is stored as.
1.156 + *
1.157 + * @param aIndex
1.158 + * 0-based column index.
1.159 + * @return The type of the value at the given column index; one of
1.160 + * VALUE_TYPE_NULL, VALUE_TYPE_INTEGER, VALUE_TYPE_FLOAT,
1.161 + * VALUE_TYPE_TEXT, VALUE_TYPE_BLOB.
1.162 + */
1.163 + long getTypeOfIndex(in unsigned long aIndex);
1.164 +
1.165 + /**
1.166 + * Retrieve the contents of a column from the current result row as an
1.167 + * integer.
1.168 + *
1.169 + * @param aIndex
1.170 + * 0-based colummn index.
1.171 + * @return Column value interpreted as an integer per type conversion rules.
1.172 + * @{
1.173 + */
1.174 + long getInt32(in unsigned long aIndex);
1.175 + long long getInt64(in unsigned long aIndex);
1.176 + /** @} */
1.177 + /**
1.178 + * Retrieve the contents of a column from the current result row as a
1.179 + * floating point double.
1.180 + *
1.181 + * @param aIndex
1.182 + * 0-based colummn index.
1.183 + * @return Column value interpreted as a double per type conversion rules.
1.184 + */
1.185 + double getDouble(in unsigned long aIndex);
1.186 + /**
1.187 + * Retrieve the contents of a column from the current result row as a
1.188 + * string.
1.189 + *
1.190 + * @param aIndex
1.191 + * 0-based colummn index.
1.192 + * @return The value for the result column interpreted as a string. If the
1.193 + * stored value was NULL, you will get an empty string with IsVoid set
1.194 + * to distinguish it from an explicitly set empty string.
1.195 + * @{
1.196 + */
1.197 + AUTF8String getUTF8String(in unsigned long aIndex);
1.198 + AString getString(in unsigned long aIndex);
1.199 + /** @} */
1.200 +
1.201 + /**
1.202 + * Retrieve the contents of a column from the current result row as a
1.203 + * blob.
1.204 + *
1.205 + * @param aIndex
1.206 + * 0-based colummn index.
1.207 + * @param[out] aDataSize
1.208 + * The number of bytes in the blob.
1.209 + * @param[out] aData
1.210 + * The contents of the BLOB. This will be NULL if aDataSize == 0.
1.211 + */
1.212 + void getBlob(in unsigned long aIndex, out unsigned long aDataSize, [array,size_is(aDataSize)] out octet aData);
1.213 + /**
1.214 + * Check whether the given column in the current result row is NULL.
1.215 + *
1.216 + * @param aIndex
1.217 + * 0-based colummn index.
1.218 + * @return true if the value for the result column is null.
1.219 + */
1.220 + boolean getIsNull(in unsigned long aIndex);
1.221 +
1.222 + /**
1.223 + * Returns a shared string pointer
1.224 + */
1.225 + [noscript] void getSharedUTF8String(in unsigned long aIndex, out unsigned long aLength, [shared,retval] out string aResult);
1.226 + [noscript] void getSharedString(in unsigned long aIndex, out unsigned long aLength, [shared,retval] out wstring aResult);
1.227 + [noscript] void getSharedBlob(in unsigned long aIndex, out unsigned long aLength, [shared,retval] out octetPtr aResult);
1.228 +
1.229 +%{C++
1.230 + /**
1.231 + * Getters for native code that return their values as
1.232 + * the return type, for convenience and sanity.
1.233 + *
1.234 + * Not virtual; no vtable bloat.
1.235 + */
1.236 +
1.237 + inline int32_t AsInt32(uint32_t idx) {
1.238 + int32_t v = 0;
1.239 + mozilla::DebugOnly<nsresult> rv = GetInt32(idx, &v);
1.240 + NS_ABORT_IF_FALSE(NS_SUCCEEDED(rv) || IsNull(idx),
1.241 + "Getting value failed, wrong column index?");
1.242 + return v;
1.243 + }
1.244 +
1.245 + inline int64_t AsInt64(uint32_t idx) {
1.246 + int64_t v = 0;
1.247 + mozilla::DebugOnly<nsresult> rv = GetInt64(idx, &v);
1.248 + NS_ABORT_IF_FALSE(NS_SUCCEEDED(rv) || IsNull(idx),
1.249 + "Getting value failed, wrong column index?");
1.250 + return v;
1.251 + }
1.252 +
1.253 + inline double AsDouble(uint32_t idx) {
1.254 + double v = 0.0;
1.255 + mozilla::DebugOnly<nsresult> rv = GetDouble(idx, &v);
1.256 + NS_ABORT_IF_FALSE(NS_SUCCEEDED(rv) || IsNull(idx),
1.257 + "Getting value failed, wrong column index?");
1.258 + return v;
1.259 + }
1.260 +
1.261 + inline const char* AsSharedUTF8String(uint32_t idx, uint32_t *len) {
1.262 + const char *str = nullptr;
1.263 + *len = 0;
1.264 + mozilla::DebugOnly<nsresult> rv = GetSharedUTF8String(idx, len, &str);
1.265 + NS_ABORT_IF_FALSE(NS_SUCCEEDED(rv) || IsNull(idx),
1.266 + "Getting value failed, wrong column index?");
1.267 + return str;
1.268 + }
1.269 +
1.270 + inline const char16_t* AsSharedWString(uint32_t idx, uint32_t *len) {
1.271 + const char16_t *str = nullptr;
1.272 + *len = 0;
1.273 + mozilla::DebugOnly<nsresult> rv = GetSharedString(idx, len, &str);
1.274 + NS_ABORT_IF_FALSE(NS_SUCCEEDED(rv) || IsNull(idx),
1.275 + "Getting value failed, wrong column index?");
1.276 + return str;
1.277 + }
1.278 +
1.279 + inline const uint8_t* AsSharedBlob(uint32_t idx, uint32_t *len) {
1.280 + const uint8_t *blob = nullptr;
1.281 + *len = 0;
1.282 + mozilla::DebugOnly<nsresult> rv = GetSharedBlob(idx, len, &blob);
1.283 + NS_ABORT_IF_FALSE(NS_SUCCEEDED(rv) || IsNull(idx),
1.284 + "Getting value failed, wrong column index?");
1.285 + return blob;
1.286 + }
1.287 +
1.288 + inline bool IsNull(uint32_t idx) {
1.289 + bool b = false;
1.290 + mozilla::DebugOnly<nsresult> rv = GetIsNull(idx, &b);
1.291 + NS_ABORT_IF_FALSE(NS_SUCCEEDED(rv),
1.292 + "Getting value failed, wrong column index?");
1.293 + return b;
1.294 + }
1.295 +
1.296 +%}
1.297 +};
