The Tor Browser / file revision

 /* -*- 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, uuid(b3c4476e-c490-4e3b-9db1-e2d3a6f0287c)]

 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);

   /**

    * Obtains the declared column type of a prepared statement.

    *

    * @param aParamIndex

    *        The zero-based index of the column who's declared type we are

    *        interested in.

    * @return the declared index type.

    */

   AUTF8String getColumnDecltype(in unsigned long aParamIndex);

   /**

    * 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 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);

   /**

    * 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

    */

   [noscript] void getSharedUTF8String(in unsigned long aIndex, out unsigned long aLength, [shared,retval] out string aResult);

   [noscript] void getSharedString(in unsigned long aIndex, out unsigned long aLength, [shared,retval] out wstring aResult);

   [noscript] void getSharedBlob(in unsigned long aIndex, out unsigned long aLength, [shared,retval] out octetPtr aResult);

 %{C++

   /**

    * Getters for native code that return their values as

    * the return type, for convenience and sanity.

    *

    * Not virtual; no vtable bloat.

    */

   inline int32_t AsInt32(uint32_t idx) {

     int32_t v = 0;

     mozilla::DebugOnly<nsresult> rv = GetInt32(idx, &v);

     NS_ABORT_IF_FALSE(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);

     NS_ABORT_IF_FALSE(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);

     NS_ABORT_IF_FALSE(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);

     NS_ABORT_IF_FALSE(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);

     NS_ABORT_IF_FALSE(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);

     NS_ABORT_IF_FALSE(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);

     NS_ABORT_IF_FALSE(NS_SUCCEEDED(rv),

                       "Getting value failed, wrong column index?");

     return b;

   }

 %}

 };