---

GenericDB.h

Go to the documentation of this file.

/** $Revision: 1.3 $
    Last updated: $Date: 2002/09/20 12:21:31 $

    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. */

#ifndef __GENERIC_DB_H__
#define __GENERIC_DB_H__

#include <PalmOS.h>
#include <FeatureMgr.h>
#include "MiscFunc.h" //for section definitions

/// Application Info Block
typedef struct {
    UInt16  renamedCategories;                  // bitfield of categories with a different name
    Char    categoryLabels [dmRecNumCategories] [dmCategoryLength];
    UInt8   categoryUniqIDs [dmRecNumCategories];
    UInt8   lastUniqID;                         // Uniq IDs generated by the device are between
                                                // 0 - 127.  Those from the PC are 128 - 255.
    UInt8   reserved1;                          // from the compiler word aligning things
    UInt16  reserved2;  
    UInt16  dirtyAppInfo;
    UInt8   sortOrder;
    UInt8   reserved3;
} appInfoType;

/** Generic Database class
    This contains the basic database functionality that does not depend
    on the record structre.
*/
class GenericDB
{
public:
    /// the currenct category
    UInt16      current_cat;

    /** get the pointer to the db (to use for calling PalmOS db functions directly)
        @return  pointer to the db (DmOpenRef)  */
    DmOpenRef getRef() DB_SECTION2;
    
    /// @return true if the constructor created the db instead of just opening it
    Boolean isNew() DB_SECTION2;
    
    /// @return the uid of the selected_record
    UInt32  getSelectedUid() DB_SECTION2; 

    /** Fetch the uid of a record
        @param id   the record id

        @return the record uid  */
    UInt32  getRecordUid(UInt16 id) DB_SECTION2;

    /** Fetch the uid of the current record
        @return the record uid  */
    UInt32  getRecordUid() DB_SECTION2;

    /** Fetch the uid of a record
        @param uid  the record uid

        @return the record id   */
    UInt16  getRecordId(UInt32 uid) DB_SECTION2;

    /** Returns the category of a given record
        @param id   the id of the record
        @return the record category */
    UInt16  getRecordCategory(UInt16 id) DB_SECTION2;

    /** Returns the category of a given record
        @param index    unique id of the record
        @return the record category */
    UInt16  getRecordCategory(UInt32 uid) DB_SECTION2;

    /** sets the category of a given record
        @param id   id of the record
        @param cat      the record category */
    void    setRecordCategory(UInt16 id, UInt16 cat) DB_SECTION2;

    /** sets the category of a given record
        @param uid  unique id of the record
        @param cat  the record category */
    void    setRecordCategory(UInt32 uid, UInt16 cat) DB_SECTION2;

    /** finds a category in this db by its name
        @param cat_name the name of the category to be found
        @return the category id */
    UInt16  findCategory(Char* cat_name) DB_SECTION2;

    /** fetches the name of a category in an allocated buffer
        @param cat_id the id of the category (in the current db only)
        @param cat_name allocated buffer to which the name will be written  */
    void    getCategoryName(UInt16 cat_id, Char* cat_name) DB_SECTION2;
    
    /** sets the selected_record to id and sets record_selected flag to false
        @param id id of the record to be selected   */
    void    selectRecord(UInt16 id) DB_SECTION2;

    /** sets the selected_record from an unique and sets record_selected flag to false
        @param id id of the record to be selected   */
    void    selectRecord(UInt32 uid) DB_SECTION2;

    /** if a record is selected this function unselects it (by setting the record_selected flag) */
    void    unselectRecord() DB_SECTION2;
    
    /** use this function to find out whether a record from the database is currently selected
        @return true if a record is selected, false otherwise   */
    Boolean isRecordSelected() DB_SECTION2;

    /** use this function to retrieve the currently selected record
        @return the index of the selected record    */
    UInt16  getSelectedRecord() DB_SECTION2;

    /** create a database using a reference to an already opened database */
    GenericDB(DmOpenRef db_open_ref) DB_SECTION2;
    /** create a database without using categories */
    GenericDB(UInt32 type, UInt32 creator, Char* db_name) DB_SECTION2;
    /** create a database with category support */
    GenericDB(UInt32 type, UInt32 creator, Char* db_name, UInt16 categ_string) DB_SECTION2;
    virtual ~GenericDB() DB_SECTION2;
    
    /** This function writes a given string into a structure; it is meant as a helper function for Database#packRecord. Also see 
        Database#writeAndAdvance.
        
        @note   I am actually amazed that C++ can handle polymorphism in this way...        
        
        @param s pointer to the start of the block where the str is to be written
        @param offset offset within the block. note that offset is changed by the function
        @param str string to be written */  
    void writeAndAdvance(MemPtr s, UInt32& offset, Char* str) DB_SECTION2;
    
    /** This is a helper function for pack record. Given a field from a structure together with a destination pointer and an offset
        it will write the field in the specified location. 
        @param s pointer to the start of the block where the str is to be written
        @param offset offset within the block. note that offset is changed by the function
        @param f a \b pointer to the field to be written. if it is a char* it will (hopefully) be handled by the other writeAndAdvance funcition    */
    template <class Field> void writeAndAdvance(MemPtr s, UInt32& offset, Field* f) DB_SECTION2;

    /** Deletes a record given by its id
        @param id the id of the record to be deleted
        @return true if deleted successfuly, false otherwise */
    virtual bool deleteRecord(UInt16 id) DB_SECTION2;

    /** Deletes a record given by its uid
        @param uid the unique id of the record to be deleted
        @return true if deleted successfuly, false otherwise */
    virtual bool deleteRecord(UInt32 uid) DB_SECTION2;

 protected: 
    /// reference to the database
    DmOpenRef   ref;
    /// total number of categories
    UInt32      num_cat;
    /// true if the db had to be created when it was opened
    Boolean     created;
    ///true if a record is selected, false otherwise
    Boolean     record_selected;
    /// the current record
    UInt16      selected_record;

    /** opens or creates a database
        @param type database type
        @param creator database creator
        @param mode mode in which to open the database
        @param name db name
        @param created on return is set to true if the db had to be created */
    Err     openOrCreate(UInt32 type, UInt32 creator, UInt16 mode, UInt16 cardNo, Char* name) DB_SECTION2;

    ///returns a pointer to the app info record
    MemPtr  getLockedAppInfo() DB_SECTION2;

    /** returns a pointer to the app info record
        @param categ_string the function will use this id to initialise the categories for the db   */
    MemPtr  getLockedAppInfo(UInt16 categ_string) DB_SECTION2;

    ///used by the func above to initialise the app info rec if it is empty
    MemPtr appInfoInit(LocalID dbID, UInt16 cardNo) DB_SECTION2;

    ///used by the func above to initialise the app info rec if it is empty
    MemPtr appInfoInit(LocalID dbID, UInt16 cardNo, UInt16 categ_string) DB_SECTION2;
};  

#endif

---