---

Database.h

Go to the documentation of this file.

/** $Revision: 1.15 $
    Last updated: $Date: 2002/09/20 12:21:30 $

    Copyright (C) 2000-2002 Vlad Mereuta <dizzy@users.sourceforge.net>

    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
    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 General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA */

#ifndef __DATABASE_H__
#define __DATABASE_H__

#include "GenericDB.h"
#include "FreeCoinsRsc.h"

/** interface to some of the PalmOS database functions
    Using this class:
    * derive a new database class as public from this one passing your packed/unpacked structures as parameters.
    * in your new class override the pure virtual function from this class and add anything you might thing useful  
*/
template <class recordStructure, class packedRecordStructure> class Database
: public GenericDB
{
 public:
    /** get the unpacked strucure of a given record
        @param id   id of the account record
        @param rec  pointer in which the unpacked data will be saved
        @return pointer to the record handler (of the packed record) or null if error */
    MemHandle getUnpackedRecord(UInt16 id,recordStructure* rec) DB_SECTION1;

    /** get the unpacked strucure of the current record
        @param rec  pointer in which the unpacked data will be saved
        @return pointer to the record handler (of the packed record) or null if error */
    MemHandle getUnpackedRecord(recordStructure* rec) DB_SECTION1;
    
    /** get the unpacked strucure of a given record
        @param uid  unique id of the account record
        @param rec  pointer in which the unpacked data will be saved
        @return pointer to the record handler (of the packed record) or NULL if error */
    MemHandle getUnpackedRecord(UInt32 uid,recordStructure* rec) DB_SECTION1;

    /** constructor
        use when in need to access functions like pack/unpack from a static function.
        @param db_open_ref reference to an *already* opened database */
    Database(DmOpenRef db_open_ref) : GenericDB(db_open_ref) {};

    /** initialize the databases
        @param creator database creator
        @param db_name name of the database 
        @param type type of the database (ex. 'DATA') */
    Database(UInt32 type, UInt32 creator, Char* db_name): GenericDB(type, creator, db_name) {};

    /** initialize the databases
        @param type type of the database (ex. 'DATA')
        @param creator database creator
        @param db_name - name of the database
        @param categ_string - id of the category resource to be used to initialise the categories for this database     */
    Database(UInt32 type, UInt32 creator, Char* db_name, UInt16 categ_string) : GenericDB(type, creator, db_name, categ_string) {};

    /// closes the database
    virtual ~Database() DB_SECTION1;

    /** unpacks a record
        @param rec the record pacxked_rec will be unpacked into this location
        @param packed_rec pointer to the record to be unpacked  */
    virtual void    unpackRecord (recordStructure* rec, packedRecordStructure* packed_rec)=0;

    /** packs an account record. This function should be overloaded by all database classes
        @param rec pointer to the record to be packed
        @param db_entry pointer to the newly allocated packed record */
    virtual void    packRecord (recordStructure* rec, MemHandle db_entry)=0;
    
        
    /** packs and writes the data from rec at the end of the database.
        @return the index to the record     */
    virtual UInt16  newRecord(recordStructure* rec) DB_SECTION1;
};

template <class recordStructure, class packedRecordStructure> MemHandle 
Database<recordStructure, packedRecordStructure>::		getUnpackedRecord(UInt32 uid,recordStructure* rec)
{
    return getUnpackedRecord(getRecordId(uid),rec);
}

template <class recordStructure, class packedRecordStructure> MemHandle 
Database<recordStructure, packedRecordStructure>::		getUnpackedRecord(UInt16 id,recordStructure* rec)
{
    MemHandle               rec_h;
    packedRecordStructure*  pac_rec;

    
    rec_h=DmQueryRecord(ref,id);
    if(!rec_h) {
        ErrFatalDisplay("Could not find record with given ID");
        return NULL;
    }

    pac_rec = (packedRecordStructure*) MemHandleLock(rec_h);
    if(!pac_rec){
        ErrFatalDisplay("Could not get lock on unpacked record");
        return NULL;
    }

    unpackRecord(rec,pac_rec);
    MemHandleUnlock(rec_h);
    return rec_h;
}

template <class recordStructure, class packedRecordStructure> MemHandle 
Database<recordStructure, packedRecordStructure>::		getUnpackedRecord(recordStructure* rec)
{
    if(!isRecordSelected()) ErrFatalDisplay("There is no record currently selected");
    return getUnpackedRecord(selected_record, rec); 
}

template <class recordStructure, class packedRecordStructure> UInt16    
Database<recordStructure, packedRecordStructure>::		newRecord(recordStructure* rec)
{
    MemHandle   h,p;
    UInt16              index=dmMaxRecordIndex;

    //set size to 1 - will be resized by overloading functions
    h=DmNewHandle(ref,1);
    if(!h) {
        MemHandle str_handle = DmGetResource (strRsc,NEW_REC_FAILED_STR);   
        ErrFatalDisplay(reinterpret_cast<char*> (MemHandleLock (str_handle)));
        MemHandleUnlock (str_handle);
        DmReleaseResource (str_handle);
    }

    packRecord(rec,h);

    p = (MemHandle) MemHandleLock(h);
    MemPtrUnlock(p);
    
    DmAttachRecord(ref,&index,h,0); //automatically sets the dirty bit  

    if(current_cat!=dmAllCategories) setRecordCategory(index, current_cat);
    return index;   
}

template <class recordStructure, class packedRecordStructure> Database<recordStructure, packedRecordStructure>::~Database()
{}

template <class Field> void GenericDB::writeAndAdvance(MemPtr s, UInt32& offset, Field* f)
{
    DmWrite(s, offset, (MemPtr) f, sizeof(Field));
    offset += sizeof(Field);
}

#endif

---