/* ***** BEGIN LICENSE BLOCK *****
 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
 *
 * The contents of this file are subject to the Mozilla Public License Version
 * 1.1 (the "License"); you may not use this file except in compliance with
 * the License. You may obtain a copy of the License at
 * http://www.mozilla.org/MPL/
 *
 * Software distributed under the License is distributed on an "AS IS" basis,
 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
 * for the specific language governing rights and limitations under the
 * License.
 *
 * The Original Code is mozilla.org code.
 *
 * The Initial Developer of the Original Code is Jan Varga
 * Portions created by the Initial Developer are Copyright (C) 2003
 * the Initial Developer. All Rights Reserved.
 *
 * Contributor(s):
 *   Neil Deakin <enndeakin@sympatico.ca>
 *
 * Alternatively, the contents of this file may be used under the terms of
 * either the GNU General Public License Version 2 or later (the "GPL"), or
 * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
 * in which case the provisions of the GPL or the LGPL are applicable instead
 * of those above. If you wish to allow use of your version of this file only
 * under the terms of either the GPL or the LGPL, and not to allow others to
 * use your version of this file under the terms of the MPL, indicate your
 * decision by deleting the provisions above and replace them with the notice
 * and other provisions required by the GPL or the LGPL. If you do not delete
 * the provisions above, a recipient may use your version of this file under
 * the terms of any one of the MPL, the GPL or the LGPL.
 *
 * ***** END LICENSE BLOCK ***** */

#include "nsISupports.idl"

interface mozISqlConnection;
interface mozISqlResultEnumerator;
interface mozISqlInputStream;

/**
 * The result of an SQL query. Use the enumerate method to retrieve each
 * row.
 *
 * @status UNDER_DEVELOPMENT
 */

[scriptable, uuid(08c220b0-7140-456a-89e9-c94609a7392d)]
interface mozISqlResult : nsISupports
{
  /**
   * By default, this value is false.
   */
  attribute boolean displayNullAsText;

  /**
   * The connection used to execute the query
   */
  readonly attribute mozISqlConnection connection;

  /**
   * The SQL query
   */
  readonly attribute AString query;

  /**
   * The table that was used in the query. If more than one table was used,
   * only the first is returned. 
   */
  readonly attribute AString tableName;

  /**
   * The number of rows in the result
   */
  readonly attribute long rowCount;

  /**
   * The number of columns in the result
   */
  readonly attribute long columnCount;

  /**
   * Retrieves the name of a column given its index. Indicies start at zero.
   *
   * @param aColumnIndex   the index of the column to return
   * @return               the column name
   */
  AString getColumnName(in long aColumnIndex);

  /**
   * Retrieves the index of a column given its name. If the column does not
   * exist, -1 is returned.
   *
   * @param aColumnName    the column name to return
   * @return               the column index
   */
  long getColumnIndex(in AString aColumnName);

  /**
   * column type constants used by |getColumnType|.
   */
  const long TYPE_STRING        = 1;
  const long TYPE_INT           = 2;
  const long TYPE_FLOAT         = 3;
  const long TYPE_DECIMAL       = 4;
  const long TYPE_DATE	        = 5;
  const long TYPE_TIME	        = 6;
  const long TYPE_DATETIME      = 7;
  const long TYPE_BOOL	        = 8;

  /**
   * Returns the type of the data in a given column.
   *
   * @param aColumnIndex   the index of the column to return the type of
   * @return               the column type
   */
  long getColumnType(in long aColumnIndex);

  /**
   * Returns the type of the data in a given column as a string. This is used
   * as an alternative to using the constants and will return either
   * string, int, float, decimal, date, time, datetime or bool.
   *
   * @param aColumnIndex   the index of the column to return the type of
   * @return               the column type
   */
  AString getColumnTypeAsString(in long aColumnIndex);

  /**
   * Returns the maximum number of bytes that are needed to hold a value in a
   * particular column.
   *
   * @param aColumnIndex   the index of the column to return the size of
   * @return               the column size
   */
  long getColumnDisplaySize(in long aColumnIndex);

  /**
   * Returns an enumerator to enumerator over the returned rows.
   *
   * @return               the row enumerator
   */
  mozISqlResultEnumerator enumerate();

  /**
   * Returns a stream which may be used to return the rows as XML.
   *
   * The XML format is:
   * <?xml version="1.0"?>
   * <document>
   *   <body>
   *     <row>
   *       <cell>value11</cell>
   *       <cell>value12</cell>
   *       ...
   *     </row>
   *   </body>
   * </document>
   *
   * @return               the input stream
   */
  mozISqlInputStream open();

  /**
   * Re-executes the query.
   */
  void reload();

};