cursor.h

/* This file is part of the KDE project
   Copyright (C) 2003-2006 Jaroslaw Staniek <js@iidea.pl>
 
   This program is free software; you can redistribute it and/or
   modify it under the terms of the GNU Library General Public
   License as published by the Free Software Foundation; either
   version 2 of the License, or (at your option) any later version.
 
   This program is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
   Library General Public License for more details.
 
   You should have received a copy of the GNU Library General Public License
   along with this program; see the file COPYING.  If not, write to
   the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
 * Boston, MA 02110-1301, USA.
*/
 
#ifndef KEXIDB_CURSOR_H
#define KEXIDB_CURSOR_H
 
#include <tqstring.h>
#include <tqvariant.h>
#include <tqptrvector.h>
#include <tqvaluevector.h>
 
#include <kexidb/connection.h>
#include <kexidb/object.h>
 
namespace KexiDB {
 
class RowEditBuffer;


class KEXI_DB_EXPORT Cursor: public TQObject, public Object
{
    TQ_OBJECT
  
 
    public:
        enum Options {
            NoOptions = 0,
            Buffered = 1
        };
 
        virtual ~Cursor();

        inline Connection* connection() const { return m_conn; }

        bool open();

        bool reopen();
 
//      /*! Opens the cursor using \a statement. 
//       Omit \a statement if cursor is already initialized with statement 
//       at creation time. If \a statement is not empty, existing statement
//       (if any) is overwritten. */
//      bool open( const TQString& statement = TQString() );

        virtual bool close();

        inline QuerySchema *query() const { return m_query; }

        TQValueList<TQVariant> queryParameters() const;

        void setQueryParameters(const TQValueList<TQVariant>& params);

        inline TQString rawStatement() const { return m_rawStatement; }

        inline uint options() const { return m_options; }

        inline bool isOpened() const { return m_opened; }

        bool isBuffered() const;

        void setBuffered(bool buffered);

        bool moveFirst();

        virtual bool moveLast();

        virtual bool moveNext();

        virtual bool movePrev();

        bool eof() const;

        bool bof() const;

        TQ_LLONG at() const;

        inline uint fieldCount() const { return m_query ? m_logicalFieldCount : m_fieldCount; }

        inline bool containsROWIDInfo() const { return m_containsROWIDInfo; }

        virtual TQVariant value(uint i) = 0;

        virtual const char ** rowData() const = 0;

        void setOrderByColumnList(const TQStringList& columnNames);

        void setOrderByColumnList(const TQString& column1, const TQString& column2 = TQString(), 
            const TQString& column3 = TQString(), const TQString& column4 = TQString(), 
            const TQString& column5 = TQString());

        QueryColumnInfo::Vector orderByColumnList() const;

        virtual void storeCurrentRow(RowData &data) const = 0;
 
        bool updateRow(RowData& data, RowEditBuffer& buf, bool useROWID = false);
 
        bool insertRow(RowData& data, RowEditBuffer& buf, bool getROWID = false);
 
        bool deleteRow(RowData& data, bool useROWID = false);
 
        bool deleteAllRows();

        virtual int serverResult() { return 0; }
        
        virtual TQString serverResultName() { return TQString(); }

        virtual TQString serverErrorMsg() { return TQString(); }
    
        TQString debugString() const;
        
        void debug() const;
 
    protected:
        enum FetchResult { FetchError=0, FetchOK=1, FetchEnd=2 };

        Cursor(Connection* conn, const TQString& statement, uint options = NoOptions );

        Cursor(Connection* conn, QuerySchema& query, uint options = NoOptions );
 
        void init();

        bool getNextRecord();
 
        /* Note for driver developers: this method should initialize engine-specific cursor's
         resources using m_sql statement. It is not required to store \a statement somewhere
         in your Cursor subclass (it is already stored in m_query or m_rawStatement, 
         depending query type) - only pass it to proper engine's function. */
        virtual bool drv_open() = 0;
 
        virtual bool drv_close() = 0;
//      virtual bool drv_moveFirst() = 0;
        virtual void drv_getNextRecord() = 0;
//unused        virtual bool drv_getPrevRecord() = 0;

        virtual void drv_appendCurrentRecordToBuffer() = 0;
        virtual void drv_bufferMovePointerNext() = 0;
        virtual void drv_bufferMovePointerPrev() = 0;
        virtual void drv_bufferMovePointerTo(TQ_LLONG at) = 0;
 
        /*DISABLED: ! This is called only once in open(), after successful drv_open().
            Reimplement this if you need (or not) to do get the first record after drv_open(),
            eg. to know if there are any records in table. Value returned by this method
            will be assigned to m_readAhead.
            Default implementation just calls drv_getNextRecord(). */

        virtual void drv_clearBuffer() {}

        void clearBuffer();

        virtual void drv_clearServerResult() = 0;
 
        TQGuardedPtr<Connection> m_conn;
        QuerySchema *m_query;
//      CursorData *m_data;
        TQString m_rawStatement;
        bool m_opened : 1;
//js (m_at==0 is enough)        bool m_beforeFirst : 1;
        bool m_atLast : 1;
        bool m_afterLast : 1;
//      bool m_atLast;
        bool m_validRecord : 1; 
        bool m_containsROWIDInfo : 1;
        TQ_LLONG m_at;
        uint m_fieldCount; 
        uint m_logicalFieldCount;  
        uint m_options; 
        char m_result; 
        
        //<members related to buffering>
        int m_records_in_buf;          
        bool m_buffering_completed : 1;   
        //</members related to buffering>

        QueryColumnInfo::Vector* m_fieldsExpanded;

        QueryColumnInfo::Vector* m_orderByColumnList;
 
        TQValueList<TQVariant>* m_queryParameters;
 
    private:
        bool m_readAhead : 1;
        
        //<members related to buffering>
        bool m_at_buffer : 1;             
        //</members related to buffering>
 
 
        class Private;
        Private *d;
};
 
} //namespace KexiDB
 
#endif