/***************************************************************************
    copyright     : (C) 1999 by Edwin Glaser
    email         : edwin@pannenleiter.de
    version       : $Id: dbrecord.h,v 1.1.1.1 2000/02/07 21:42:04 ege Exp $
 ***************************************************************************/

/***************************************************************************
 *                                                                         *
 *   This program is free software; you can redistribute it and/or modify  *
 *   it under the terms of the GNU General Public License as published by  *
 *   the Free Software Foundation; either version 2 of the License, or     *
 *   (at your option) any later version.                                   * 
 *                                                                         *
 ***************************************************************************/


#ifndef DBRECORD_H
#define DBRECORD_H


/** Database specific part of the manager.
  *  
  * The manager consists of two classes. 
  * DBDatasource keeps track of the state and emits the signals.
  * A class derrived from DBRecord handles the database connection.
  * 
  * @author Edwin Glaser
  * @version $Name:  $ $Date: 2000/02/07 21:42:04 $
  */

class DBField;
class QString;

class DBRecord {

public:
  /* These values are returned by getCursor
  */
  static const int BOFCursor = -1;
  static const int EOFCursor = -2;
  static const int InsertCursor = -3;
  static const int InitCursor = -4;

  /* Flags for validate
  */
  static const int SetCopy = 1;
  static const int SetZero = 2;
  static const int SetNull = 4;
  static const int SetAutoNull = 8;

public: 
/** Constructor does nothing
  */
  DBRecord();

/** Destructor does nothing
  */
  virtual ~DBRecord();

/** Is update, insert or delete possible ?
  */
  virtual bool isReadOnly() = 0; 

/** Returns a description of the last error 
  */
  virtual const QString &getErrorInfo() = 0;

/** Defines the query string.
  * 
  * @param str The query eg. "select * from table where id = ?" 
  * @param removeTables Remove table definitions set by addTable()
  */
  virtual void setQuery(const QString &str, bool removeTables = false) = 0;

/** Defines a table, the primary keys and the columns.
  * If you want to update the table, you have to define the primary keys.
  * 
  * @param table The name of the database table.
  * @param primaries Pairs of name=position sperated by blanks eg. "id=0 mid=1"
  * @param columns The names of the columns seperated by blanks. 
  *        It defaults to all columns if the string is 0 or "".
  */
  virtual void addTable(const char *table, const char *primaries, const char *columns) = 0;

/** Opens the database connection.
  */
  virtual bool open() = 0;

/** Closes the database connection. 
  */
  virtual void close() = 0;

/** Refreshes the dataset after a write operation. 
  * If you don't call refresh, the data is undefined.
  */
  virtual bool refresh() = 0;

/** Go to the first record.
  * 
  * @return False if error or if the record does not exist.
  * @param invalid Will become true if the record does not exist.
  */
  virtual bool first(bool *invalid) = 0;

/** Go to the previous record.
  * 
  * @return False if error or if the record does not exist.
  * @param invalid Will become true if the record does not exist.
  */
  virtual bool prior(bool *invalid) = 0;

/** Go to the next record.
  * 
  * @return False if error or if the record does not exist.
  * @param invalid Will become true if the record does not exist.
  */
  virtual bool next(bool *invalid) = 0;

/** Go to the last record.
  * 
  * @return False if error or if the record does not exist.
  * @param invalid Will become true if the record does not exist.
  */
  virtual bool last(bool *invalid) = 0;

/** Go to the given record.
  * 
  * @return False if error or if the record does not exist.
  * @param offset Number of records to move.
  * @param invalid Will become true if the record does not exist.
  */
  virtual bool moveBy(bool *invalid, long offset) = 0;

/** Go to the given record.
  * 
  * @return False if error or if the record does not exist.
  * @param position Index of the record, zero based.
  * @param invalid Will become true if the record does not exist.
  */
  virtual bool moveTo(bool *invalid, long position) = 0;

/** Returns the position of the record [zero based] or BOFCursor, EOFCursor, InsertCursor, InitCursor.
  */
  virtual long getCursor() = 0;

/** Cancels append and setValue, restores the old values.
  */
  virtual bool cancel() = 0;


/** Is an insert/update necessary
  */
  virtual bool isDirty() = 0;

/** Updates the Database if the values had been changed. 
  * 
  * @return False if an error occured.
  * @param done Becomes true if the update was performd.
  * @param force Update even if no field had been changed.
  */
  virtual bool update(bool *done = 0, bool force = false) = 0;

/** Insert into the Database if the values had been changed. 
  * 
  * @return False if an error occured.
  * @param done Becomes true if the insert was performd.
  * @param force Insert even if no field had been changed.
  */
  virtual bool insert(bool *done = 0, bool force = false) = 0;

/** Prepare working area for an insert. 
  * 
  * @param todo SetCopy fetches the values from the current record.<br>
  *             SetZero init to 0 or "".<br>
  *             SetNull init null values<br>
  *             SetAutoNull init autoincrement columns for generating a new value
  */
  virtual bool append(int todo) = 0;

/** Deletes the current record from the database.
  */
  virtual bool remove() = 0;

/** Saves the current state, the cursor and the curernt values of the fields.
  */
  virtual void backup() = 0;

/** Restores the state from the last backup.
  */
  virtual bool restore() = 0;

/** Returns the number of columns;
  */
  virtual int getNumCols() = 0;

/** Returns the name or alias of the column, zero based.
  */
  virtual const char *getColumnName(int col) = 0;

/** Returns the name or alias of the table, zero based.
  */
  virtual const char *getColumnQualifierName(int col) = 0;

/** Returns the type of the column, zero based.
  *
  * @return  DBTypes::TypeLong DBTypes::TypeDouble DBTypes::TypeDate DBTypes::TypeTime DBTypes::TypeDateTime DBTypes::TypeBinary DBTypes::TypeString
  */
  virtual int getColumnType(int col) = 0;

/** Returns the type of the column, zero based.
  */
  virtual const char *getColumnTypeName(int col) = 0;

/** Returns the size of the column, zero based.
  */
  virtual long getColumnLength(int col) = 0;

/** Returns the precision of the column, zero based.
  */
  virtual int getColumnPrecision(int col) = 0;

/** Returns the scale of the column, zero based.
  */
  virtual int getColumnScale(int ) = 0;

/** Returns the display size of the column, zero based.
  */
  virtual long getColumnDisplaySize(int col) = 0;

/** Is the column nullable, zero based.
  */
  virtual int getColumnNullable(int col) = 0;

/** Is the column unsigned, zero based.
  */
  virtual int getColumnUnsigned(int col) = 0;

/** Is the column a money value, zero based.
  */
  virtual int getColumnMoney(int col) = 0;

/** Is the column updateable, zero based.
  */
  virtual int getColumnUpdatable(int col) = 0;

/** Is it a auto increment column, zero based.
  */
  virtual int getColumnAutoIncrement(int col) = 0;

/** Returns the number of rows of query.
  */
  virtual long getNumRows() = 0;

/** Changes the value in the working area.
  * 
  * @param field The new value
  * @param column The index of the column, zero based.
  * @param markDirty An insert() or update() will do nothing if there was no markDirty call.
  */
  virtual bool setValue(const DBField *field, int column, bool markDirty = true) = 0;

/** Changes the parameter of the select statement.
  * 
  * @param field The new value
  * @param column The index of the column, zero based.
  */
  virtual bool setParameter(const DBField *field, int column) = 0;

/** Returns the value from the working area.
  * If the working area was not initialzed with append() and the value had not been set with setValue(),
  * the value is fetched from the database.
  */
  virtual const DBField *getValue(int pos) = 0;

/** If setParameter was called, the method returns the old value.
  * Otherwise it creates a DBField with a proper type.
  */
  virtual const DBField *getParameter(int pos) = 0;
};

#endif