---

TransactionsDB.h

Go to the documentation of this file.

/** Code to access the database containing the Transaction information

    $Revision: 1.38 $
    Last updated: $Date: 2002/12/17 22:52:00 $

    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 __TRANSACTIONS_DB__
#define __TRANSACTIONS_DB__

#include "Database.h"
#include "CoinsPref.h"

/// type of the Transaction database
#define TRANSACTIONSDB_TYPE 'DATA'
/// db name
#define TRANSACTIONSDB_NAME "FreeCoins-Transactions"

/// intervals at which scheduled transactions can be repeated   
typedef enum { rep_day, rep_week, rep_month, rep_year } Repeat_interval;


///unpacked structure of an scheduled scheduled
typedef struct {
   ///interval at which the transaction will repeat (day,week,etc.)
    Repeat_interval repeat_interval;
    /// day of the week/month on which transaction will repeat
    UInt16 repeat_on;
    ///frequency of the repetition (i.e. every n days)
    UInt16 frequency;
    ///number of times the transaction will be repeated (-1 - forever)
    Int16 repeat_times;
    ///the last date at which the transaction can be repeated (start date is stored in the transaction itself)
    DateType end_date;
    /// if true, the transaction is going to be recorded as cleared
    Boolean to_be_cleared;
    ///if true, end_date defines the end of this repeat transaction; otherwise repeat_times defines it.
    Boolean end_by_date;
    /** if true, recording of the transaction is paused (i.e. the actual date is still updated as usual, but no
        new transactions are created */
    Boolean paused;
} scheduledStructure;

/// data specific to scheduled transactions
typedef struct {
    /// day of the week/month on which transaction will repeat
    UInt16 repeat_on;
    ///frequency of the repetition (i.e. every n days)
    UInt16 frequency;
    ///number of times the transaction will be repeated (-1 - forever)
    Int16 repeat_times;
    ///the last date at which the transaction can be repeated (start date is stored in the transaction itself)
    DateType end_date;
    ///true if newly created transactions are cleared
    unsigned to_be_cleared :1;
    ///if true, end_date defines the end of this repeat transaction; otherwise repeat_times defines it.
    unsigned end_by_date :1;
    /** if true, recording of the transaction is paused (i.e. the actual date is still updated as usual, but no
        new transactions are created */
    unsigned paused :1;
    /// saved for future fields to keep binary compatibility
    unsigned reserved :13;
    ///interval at which the transaction will repeat (day,week,etc.)
    Repeat_interval repeat_interval;
} packedScheduleStructure;

///the packed structure of a transaction - see the unpacked struct for explanations
typedef struct {
    ///date on which the transaction was made
    DateType date;
    /// number of splits assigned to this transaction
    UInt8 num_splits;
    ///the method of payment
    UInt8 method;
    ///per-transaction exchange rate (if another currency is involved). The rate relates 1st split to second split (order matters)
    double exchange_rate;
    /// indicates if the transaction is scheduled
    unsigned is_scheduled   :1;
    /// saved for future fields to keep binary compatibility
    unsigned reserved       :15;
} packedTransactionStructure;

/** unpacked structure of an Transaction
    \note the fields related to scheduling should only be considered if the transaction itself is marked as 
    schduled (i.e. is in the scheduled category) */
typedef struct {
    ///date on which the transaction was made
    DateType        date;
    ///the method of payment
    Payment_method  method;
    ///per-transaction exchange rate (if another currency is involved). The rate relates 1st split to second split (order matters)
    double exchange_rate;
    /// indicates if the transaction is scheduled
    Boolean is_scheduled;
    /// number of splits assigned to this transaction
    UInt8           num_splits;
    ///contains scheduling information
    scheduledStructure sched;
    /// person/company 
    Char*           payee;
    ///optional number to id this transaction (cheque number, order number, etc.)
    Char*           num;
    /// note on the transaction 
    Char*           note;
} transactionStructure;

/** class to manipulate the transactions database.
   \note Transactions can belong to one of the three categories:
      -# cleared
      -# uncleared
      -# scheduled
   Cleared/uncleared transaction should be treated (\em mostly)  the same. The scheduled transactions
   contain the information for the transaction <b> to be scheduled </b>in the transaction body, and information
   about how this is to be done in the scheduled structure */

class TransactionsDB : public Database <transactionStructure, packedTransactionStructure>
{
 public:
    /// unpacks an Transaction record
    void    unpackRecord (transactionStructure* trans, packedTransactionStructure* packed_trans) DB_SECTION2;

    /** packs an Transaction record
        \todo we should be able to pack the scheduled structure to 0 or 1 bytes. I am not sure how 
        viable this is (as we do not always know whether the transaction is scheduled or not when packing it ) but if it
        can be done it would save about 14 bytes for each transaction   */
    void    packRecord (transactionStructure* trans, MemHandle db_entry) DB_SECTION2;

    /** get the date of the transaction
        @param id record index
        @param pDate pointer to allocated date structure that will receive the date */
    void    getDate(UInt16 id, DateType * pDate) DB_SECTION2;

    /** @return the value of the Cleared category */
    UInt16  getClearedCategory() DB_SECTION2;

    /** @return the value of the Cl/Uncl category */
    UInt16  getClUnclCategory() DB_SECTION2;
  
    /** @return the value of the Uncleared category */
    UInt16  getUnclearedCategory() DB_SECTION2;

    /** @return the value of the Scheduled category */
    UInt16  getScheduledCategory() DB_SECTION2;

    /** determine if the transaction is balanced
        @param trans_uid UID of the transaction
        @return true if the transaction is balanced, false otherwise */
    Boolean isBalanced(UInt32 trans_uid) DB_SECTION2;

    /** get the amount by which the transaction affects the given account
        @param trans_uid UID of the transaction
        @param acc_uid UID of the account
        @return signed amount   */
    Int32 getAmount(UInt32 trans_uid, UInt32 acc_uid) DB_SECTION2;

    /** get the peer account in the given transaction from the point of view
        of the given account. Only makes sense for transactions that are
        split two ways, i.e. simple transfers.
        @param trans_uid UID of the transaction
        @param acc_uid UID of the account
        @return UID of the peer account     */
    UInt32 getPeerAcc(UInt32 trans_uid, UInt32 acc_uid) DB_SECTION2;

    /** checks whether a record is cleared or not
        @param id id of the record to be checked
        @return true if the record is cleared, false otherwise  */
    Boolean isCleared(UInt16 id) DB_SECTION2;

    /** checks whether a record is to be cleared or not
        @param id id of the record to be checked
        @return true if the record is set to be cleared in the future, false otherwise  */
    Boolean willBeCleared(UInt16 id) DB_SECTION2;

   /**  checks whether a transaction is scheduled or not by checking the record category
        @param id the id of the transaction to be checked
        @return true if it is scheduled, false othewise   */
   Boolean  isScheduled(UInt16 id) DB_SECTION2;

    /** set a record category to cleared
        @param id id of the record to be set    */
    void    clearRecord(UInt16 id) DB_SECTION2;

    /** set a record category to uncleared
        @param id id of the record to be set    */
    void    unclearRecord(UInt16 id) DB_SECTION2;

    /// initialize the database
    TransactionsDB() DB_SECTION2;

    ///init the Transactions DB with some default records
    void    initializeTransactions() DB_SECTION2;

    /** creates a new record and update the balances of the two involved accounts
        @param s pointer to the structure containing the transaction data
        @param cleared boolean which indicates the status of the record. The function will place the record in the right category
        @param scheduled (which defaults to false if no value is given) indicates whether the transaction is scheduled or not. the 
            cateogry will be set to the right one
        @return id of the newly created record  */
    UInt16  newRecord(transactionStructure* s, Boolean cleared, Boolean scheduled = false) DB_SECTION2;
    
    /** deletes a record, given its id
        @param id the id of the record to be deleted
        @param keep_balance if true then the balances of the accounts involved in the transaction will *not* be changed */
    bool deleteRecord(UInt16 id, Boolean keep_balance = false) DB_SECTION2;

    /** Compares two packed transaction structures.
        For parameters see the PalmOS reference */
    static Int16    compareRecords(packedTransactionStructure* rec1,packedTransactionStructure* rec2,Int16 other,SortRecordInfoPtr sr1,SortRecordInfoPtr sr2,MemHandle app_info) DB_SECTION2;

    /** This function deletes all the transactions earlier than the given date. 
        This should not change the existing balances for the accounts involved. Both cleared and uncleared transactions are removed, but
        the scheduled ones are kept
        \todo message informing the operation is being performed while this function runs
        \warning should probably set the archived bit on deletion rather than removing the records. this is true for all the destructive operations, but
        there is really no point in doing so before the conduit reaches a working state
        \note scheduled transaction are not deleted on purging
        @param last_date the last date up to which the transactions are to be deleted   */
    void purgeTransactions(DateType last_date) DB_SECTION2;
  
    /** records the next date in the associated transaction (in relation to the date already recorded)
        if we have repeated the record enought times, the record is deleted
        @param id id of the record for which to find the next date
        @return true if the record has been deleted, false otherwise    */
    Boolean calculateNextDate(UInt16 id) DB_SECTION2;
    
    /** scans through all the scheduled transactions, and if there are any due they are recorded and their next occurance date
        is updated
        @param force if true then the current date is ignored the update is perfomed anyway
        @return true if updates were made, false otherwise  */
    Boolean schedule(Boolean force=false) DB_SECTION2;

    /** schedule the first scheduled record that is due */
    Boolean scheduleNextRecord() DB_SECTION2;
   
    /** returns the total for the scheduled transactions in a given account
        @param account_uid uid of the account to be checked
        @return the sum of the amounts of all scheduled transaction for that account   */
    Int32 getScheduledTotal(UInt32 account_uid) DB_SECTION2;

    /**  creates a new (unscheduled) record from a scheduled one, leaving the original scheduled transaction unaltered
         @param record_uid uid of the scheduled transaction to be recorded
         @param mod_date if true, the date of the new record is going to be set to today. Otherwise the date is left 
         unaltered
         @return uid of the new record that has been created */
    UInt32 recordScheduledRecord(UInt32 record_uid, bool mod_date) DB_SECTION2;

    /** Returns the first transaction with an id equal or higher than the given one which has a payee string which starts the same (case insensitive) as the given string and
        has as source account the account which is currently used
        @param p start of the payee string which is to be mached by an existing transaction
        @param start_id id from where to start looking for matching transactions; it defaults to 0. Note that the given ID is checked aswell!
        @return the UInt16 id of the first matched transaction or -1 if no such transaction was found */
    Int32 getTransactionByPayeeAndAcc(Char* p, UInt16 start_id) DB_SECTION2;
    
    /** Returns the first transaction with an id equal or higher than the given one which has a payee string which starts the same (case insensitive) as the given string
        @param p start of the payee string which is to be mached by an existing transaction
        @param start_id id from where to start looking for matching transactions; it defaults to 0. Note that the given ID is checked aswell!
        @return the UInt16 id of the first matched transaction or -1 if no such transaction was found
        @param want_cur_acc if true, the function will attempt to return a transaction with the same source account as the current account. If it fails to find such a transaction it
        returns the first transaction from any acount which matches the given payee */
    Int32 getTransactionByPayee(Char* p, UInt16 start_id = 0, Boolean want_cur_acc = false) DB_SECTION2;
};

extern TransactionsDB* transactions_db;

#endif

---