/* ***** 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 nsIVariant;

/**
 * This interface is used to get the results from an SQL query.
 * The enumerator uses a row pointer which can be adjusted with
 * the next and previous methods. Other methods operate only on
 * the row selected by the pointer.
 *
 * The row pointer starts just before the first row, so you should
 * always call the next method once before attempting to read row
 * data.
 *
 * @status UNDER_DEVELOPMENT
 */

[scriptable, uuid(dcc0d29e-2b44-460e-b39f-89121ff8b963)]
interface mozISqlResultEnumerator : nsISupports
{
  /**
   * The most recent error message.
   */
  readonly attribute AString errorMessage;

  /**
   * Moves the row pointer to the next row in the results.
   * Returns true if there is a next row and false if there are
   * no more rows.
   *
   * @return               false if there are no more rows
   */
  boolean next();

  /**
   * Moves the row pointer to the previous row in the results.
   * Returns true if there is a previous row.
   *
   * @return               false if there are no previous rows
   */
  boolean previous();

  /**
   * Moves the row pointer to just before the first row.
   */
  void beforeFirst();

  /**
   * Moves the row pointer to the first row.
   */
  void first();

  /**
   * Moves the row pointer to the last row.
   */
  void last();

  /**
   * Moves the row pointer by a number relative to the current row.
   * An error occurs if this causes the row pointer to extend past
   * the last row. This method may also be used to move the row pointer
   * back by using a negative value.
   *
   * @param aRowIndex      aRowIndex the number of rows to move by
   */
  void relative(in long aRows);

  /**
   * Moves the row pointer to a specific row. An error occurs if the index
   * is after the last row.
   *
   * @param aRowIndex      the index of the row to move to
   */
  void absolute(in long aRowIndex);


  /**
   * Returns true if the value at the specified column in the current row
   * is null.
   *
   * @param aColumnIndex   the column to retrieve
   * @return               true if the value is null
   */
  boolean isNull(in long aColumnIndex);

  /**
   * Returns the value at the specified column in the current row as a variant.
   *
   * @param aColumnIndex   the column to retrieve
   * @return               the value as a variant
   */
  nsIVariant getVariant(in long aColumnIndex);

  /**
   * Returns the value at the specified column in the current row as a string.
   * An error occurs if the value is not a string type.
   *
   * @param aColumnIndex   the column to retrieve
   * @return               the string value
   */
  AString getString(in long aColumnIndex);

  /**
   * Returns the value at the specified column in the current row as an
   * integer. An error occurs if the value is not a integer type.
   *
   * @param aColumnIndex   the column to retrieve
   * @return               the integer value
   */
  long getInt(in long aColumnIndex);

  /**
   * Returns the value at the specified column in the current row as a
   * float. An error occurs if the value is not a float type.
   *
   * @param aColumnIndex   the column to retrieve
   * @return               the float value
   */
  float getFloat(in long aColumnIndex);

  /**
   * Returns the value at the specified column in the current row as a
   * decimal. An error occurs if the value is not a decimal type.
   *
   * @param aColumnIndex   the column to retrieve
   * @return               the decimal value
   */
  float getDecimal(in long aColumnIndex);

  /**
   * Returns the value at the specified column in the current row as a date.
   * An error occurs if the value is not a date type.
   *
   * @param aColumnIndex   the column to retrieve
   * @return               the date value
   */
  long long getDate(in long aColumnIndex);

  /**
   * Returns the value at the specified column in the current row as a
   * boolean. An error occurs if the value is not a boolean type.
   *
   * @param aColumnIndex   the column to retrieve
   * @return               the boolean value
   */
  boolean getBool(in long aColumnIndex);


  /**
   * Sets the value at the specified column in the current row to null.
   * Changes are not committed until either the insertRow or updateRow method
   * is called.
   *
   * @param aColumnIndex   the column to modify
   */
  void setNull(in long aColumnIndex);

  /**
   * Sets the value at the specified column in the current row to the
   * default value for that column. Changes are not committed until either the
   * insertRow or updateRow method is called.
   *
   * @param aColumnIndex   the column to modify
   */
  void setDefault(in long aColumnIndex);

  /**
   * Sets the value at the specified column in the current row to its original
   * value. The row may be changed with the various setX methods and then
   * commited with updateRow.
   *
   * @param aColumnIndex   the column to modify
   */
  void copy(in long aColumnIndex);

  /**
   * Sets the value at the specified column in the current row to a variant.
   * Changes are not committed until either the insertRow or updateRow method
   * is called.
   *
   * @param aColumnIndex   the column to modify
   * @param aValue         the value to assign
   */
  void setVariant(in long aColumnIndex, in nsIVariant aValue);

  /**
   * Sets the value at the specified column in the current row to a string.
   * Changes are not committed until either the insertRow or updateRow method
   * is called.
   *
   * @param aColumnIndex   the column to modify
   * @param aValue         the value to assign
   */
  void setString(in long aColumnIndex, in AString aValue);

  /**
   * Sets the value at the specified column in the current row to an integer.
   * Changes are not committed until either the insertRow or updateRow method
   * is called.
   *
   * @param aColumnIndex   the column to modify
   * @param aValue         the value to assign
   */
  void setInt(in long aColumnIndex, in long aValue);

  /**
   * Sets the value at the specified column in the current row to a float.
   * Changes are not committed until either the insertRow or updateRow method
   * is called.
   *
   * @param aColumnIndex   the column to modify
   * @param aValue         the value to assign
   */
  void setFloat(in long aColumnIndex, in float aValue);

  /**
   * Sets the value at the specified column in the current row to a decimal.
   * Changes are not committed until either the insertRow or updateRow method
   * is called.
   *
   * @param aColumnIndex   the column to modify
   * @param aValue         the value to assign
   */
  void setDecimal(in long aColumnIndex, in float aValue);

  /**
   * Sets the value at the specified column in the current row to a date.
   * Changes are not committed until either the insertRow or updateRow method
   * is called.
   *
   * @param aColumnIndex   the column to modify
   * @param aValue         the value to assign
   */
  void setDate(in long aColumnIndex, in long long aValue);

  /**
   * Sets the value at the specified column in the current row to a boolean.
   * Changes are not committed until either the insertRow or updateRow method
   * is called.
   *
   * @param aColumnIndex   the column to modify
   * @param aValue         the value to assign
   */
  void setBool(in long aColumnIndex, in boolean aValue);


  /**
   * Sets the value of the cells in all columns in the current row to null.
   * This is equivalent to calling setNullValue for every column.
   */
  void setNullValues();

  /**
   * Sets the value of the cells in all columns in the current row to the
   * default values for the columns. This is equivalent to calling
   * setDefaultValue for every column.
   */
  void setDefaultValues();

  /**
   * Sets the values of all of the cells in the current row to their original
   * values. The row may be changed with the various set methods and then
   * commited with updateRow. This method is equivalent to calling the copy
   * method for each column.
   */
  void copyValues();


  /**
   * Returns true if inserts are allowed.
   *
   * @return               true if inserts are allowed
   */
  boolean canInsert();

  /**
   * Returns true if updates are allowed.
   *
   * @return               true if updates are allowed
   */
  boolean canUpdate();

  /**
   * Returns true if deletes are allowed.
   *
   * @return               true if deletes are allowed
   */
  boolean canDelete();

  /**
   * Inserts a row using the data assigned using the various setX methods.
   * The row was inserted successfully if 0 or 1 is returned, however if 0
   * is returned, the row does not satisfy the where condition of the result
   * (that is, it doesn't belong in the result enumerator) and does not need
   * to be displayed.
   *
   * @return               1 if the row was inserted, 0 if the row was
   *                       inserted but does not fit the condition, or -1
   *                       if an error occured.
   */
  long insertRow();
  
  /**
   * Updates the current row using the data assigned using the various setX
   * methods. The row was inserted successfully if 0 or 1 is returned, however
   * if 0 is returned, the row does not satisfy the where condition of the
   * result and does not need to be displayed.
   *
   * @return               1 if the row was updated, 0 if the row was updated
   *                       but does not fit the condition, or -1 if an error
   *                       occured.
   */
  long updateRow();

  /**
   * Deletes the current row.
   *
   * @return               1 if the row was deleted or -1 if an error occured.
   */
  long deleteRow();

  /**
   * Holds the SQL condition clause.
   */
  readonly attribute AString currentCondition;

};