---

CurrencyDB.h

Go to the documentation of this file.

/** $Revision: 1.7 $
    Last updated: $Date: 2002/12/17 22:51:59 $
    
    Copyright (C) 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 __CURRENCY_DB__
#define __CURRENCY_DB__

#include "Database.h"

/// type of the Currency database
#define CURRENCYDB_TYPE 'DATA'
/// db name
#define CURRENCYDB_NAME "FreeCoins-Currency"

///the packed structure for a currency entry
typedef struct {
    /// exchange rate, relative to the default currency (one unit of this currency = 1 unit of default currency  * exchange_rate)
    double exchange_rate;
    /// text containing the code and description of the currency (will be resized to fit)
    Char text[1];
} packedCurrencyStructure;

///unpacked structure for a currency entry
typedef struct {
    /** exchange rate is value of 1 unit of default currency in this currency (if you get £2 for $1 and £ is default,
        £ exchange rate is 1 and $ exchange rate is 0.5) */
    double exchange_rate;
    ///user defined currency code (i.e. USD, GBP, etc)
    Char* code;
    ///long textual description for this currency entry
    Char* description;
} currencyStructure;

///class to manipulate the currency database
class CurrencyDB : public Database <currencyStructure, packedCurrencyStructure>
{
 public:
    /// unpacks a currency record
    void    unpackRecord (currencyStructure* currency, packedCurrencyStructure* packed_currency) DB_SECTION1;
    /// packs a currency record
    void    packRecord (currencyStructure* currency, MemHandle db_entry) DB_SECTION1;
    /// initialize the database
    CurrencyDB() DB_SECTION1;
    /** creates a new record; if this is the only currency the default currency for the application is
        automatically set to the uid for this new record; the exchange rate is automatically set to 1. Otherwise
        the record is simply created without any further manipulation
        The code names have to be unique, so giving an existing code name will result in a warning a refusal to create
        @param c pointer to the structure containing the currency data
        @return id of the newly created record  */
    UInt16 newRecord(currencyStructure* c) DB_SECTION1;
    /** deletes a currency, given its id. The process fails if the given currency is set as default, or if there are
        any accounts which use the currency
        @param id the id of the record to be deleted */
    bool deleteRecord(UInt16 id) DB_SECTION1;

    /**  check whether there is any kind of dependency on the given currency 
         @return true if there is such a dependency, false otherwise*/
    bool checkCurrencyDependency (UInt16 id) DB_SECTION1;
    /**  checks if a given code already exists in the database
         @return true if a currency with the given code exists in the database, false othewise
         @param code currency code to look for 
         @param ignore_uid if not 0 (default value) the given uid is going to be ignored in the search. This is useful when 
         updating an existing record */
    bool checkForExistingCode (Char* code, UInt32 ignore_uid = 0) DB_SECTION1;
    /**  This method can be used to obtain the exchange rate between any two currencies. The calculation
         will make use of the exchange rate w.r.t the default currency 
         @param currency1 UID of the first currency (source currency)
         @param currency2 UID of the destination currency
         @return a fraction x such that:
         one unit of currency1 * x = value of 1 unit currency1 in currency2  */
    double getExchangeRate (UInt32 currency1, UInt32 currency2) DB_SECTION1;
    /**  modifies the exchange rate in between the given currency to match some given rate.
         @note the operation fails if none of the given currencies is the default currency. This is because
         we would have to set the exchange rate of both give currencies w.r.t. the default currency. We cannot do this 
         without more information
         @param src_currency UID for the source currency
         @param dest_currency UID for the destination currency
         @param rate new exchange rate between src_currency and dest_currency */
    void adjustExchangeRate (UInt32 src_currency, UInt32 dest_currency, double rate) DB_SECTION1;
    /**  Update all exchange rates so that they correspond to a new given default currency
         @param currency the UID of the new default currency
         @note this method does not change the actual currency, as it is stored in the application preferences */
    void newDefaultCurrency (UInt32 currency) DB_SECTION1;

    /**  creates a description for a given currency and puts it in a (preallocated) buffer
         @param uid the uid of the currency to be described
         @param width maximum width of generated text (if generated text is longer will be truncated)
         @param buffer buffer where the new text is going to be generated */
    void getDescriptionTruncLeftToFit(UInt32 uid, Int16 width, Char* buffer) DB_SECTION1;
    
    /** Compares two packed currency structures. The currency database is sorted by code
        For parameters see the PalmOS reference     */
    static Int16    compareRecords(packedCurrencyStructure* rec1,packedCurrencyStructure* rec2,Int16 other,SortRecordInfoPtr sr1,SortRecordInfoPtr sr2,MemHandle app_info) DB_SECTION1;
};

extern CurrencyDB* currency_db;

#endif

---