---

AccountsDB.h

Go to the documentation of this file.

/** $Revision: 1.45 $
    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 __ACCOUNTS_DB__
#define __ACCOUNTS_DB__


#include "Database.h"

/// type of the account database
#define ACCOUNTSDB_TYPE 'DATA'
/// db name
#define ACCOUNTSDB_NAME "FreeCoins-Accounts"

///this structure contains the overall totals for all the selected accounts
typedef struct {
    ///current balance total (all transactions regardless of the cleared state)
    Int32 total;
    ///the total of cleared transactions
    Int32 cleared_total;
    ///total available (total+overdrafts)
    Int32 available_total;
} totalsStruct;

/// sort order type
typedef enum { soName, soAmount, soDate } sortOrder;

/// account flags for tight packing
typedef struct {
    /// indicates whether the account is collapsed or not
    unsigned collapsed      :1;
    /// if true, the program will credit money to this account when spending them and subtract from the balance when paying money into it
    unsigned credit_account :1;
    ///reserved for future fields
    unsigned reserved       :14;
} AccountFlags;

///the packed structure of an account
typedef struct {
    /// account balance
    Int32       balance;
    /** total of cleared trasactions (splits) for this account */
    Int32       cleared_balance;
    ///the credit limit for creditcards/overdraft for other accounts
    Int32       credit_limit;
    /// uid of the parent of this account. if the account is a root one this field should be ignored
    UInt32      parent_uid;
    ///currency used by this account (UID from currency database)
    UInt32      currency;
    /// overall balance of the children of this account
    Int32       children_total;
    /// total cleared balance of the children of this account
    Int32       children_cleared_total;
    /// total available (inc overdraft) in children accounts
    Int32       children_available_total;
    ///various account flags, packed
    AccountFlags flags;
    /// account type (Bank, CC, etc.)
    UInt8       type;
    /// depth at which this account is situated (0 for root accounts, >0 for the others)
    UInt8       depth;
    /// total number of children owned by this account. this should facilitate things like sorting
    UInt8       children_no;
    ///all strings associated with the account
    Char        description[1]; // actually may be longer than 1
} packedAccountStructure;

///possible account types
enum AccountType { BANK=0, CREDIT=1, INCOME=2, EXPENSE=3, EQUITY=4 };

///unpacked structure of an account
typedef struct {
    /// account balance
    Int32       balance;
    /** total of cleared trasactions (splits) for this account */
    Int32       cleared_balance;
    ///the credit limit for creditcards/overdraft for other accounts
    Int32       credit_limit;   
    /// uid of the parent of this account. if the account is a root one this field should be ignored
    UInt32      parent_uid;
    ///currency used by this account (UID from currency database)
    UInt32      currency;
    /// overall balance of the children of this account
    Int32       children_total;
    /// total cleared balance of the children of this account
    Int32       children_cleared_total;
    /// total available (inc overdraft) in children accounts
    Int32       children_available_total;
    /// account type (Bank, CC, etc.)
    AccountType type;
    /// depth at which this account is situated (0 for root accounts, >0 for the others)
    UInt8       depth;
    /// total number of children owned by this account. this should facilitate things like sorting
    UInt8       children_no;    
    /// indicates whether the account is collapsed or not
    UInt8       collapsed;
    /// if true, the program will credit money to this account when spending them and subtract from the balance when paying money into it
    UInt8       credit_account;
    ///account desciption
    Char*       description;
    ///the name of the account - this will show up throughout the program
    Char*       name;
    ///optional note attached to the account
    Char*       note;
} accountStructure;

/** class to manipulate the accounts database.
    The category field is used to split the accounts into visible and invisible.
    Onely the visible accounts will be displayed by AccountsTable */
class AccountsDB : public Database <accountStructure, packedAccountStructure>
{
private:
    /** creates a new account
        @param name account name
        @param parent_uid the uid of the parent for the new account
        @param acc_type the type of the account */
    UInt32 createAccount(char *name, UInt32 parent_uid, AccountType acc_type);

 public:
    ///structure containing the totals
    totalsStruct    totals;
        
    /** default constructor
        opens or creates the database (if created populates it with sample records)     */
    AccountsDB() DB_SECTION1;
    
    /** constructor
        @param db_open_ref reference to an *already* opened database */
    AccountsDB(DmOpenRef db_open_ref) DB_SECTION1;
     
    /** @param n name of the account to be found
        @param categ category of the account
        @return unique id of the account or 0 if the account could not be found     */
    UInt32  findAccountByName(char* n, UInt16 categ) DB_SECTION1;
    
    /** returns a formated account name in buf
        @param acc account to get the name for
        @param buf an *allocated* buffer in which the name is to be copied!     */
    void    getAccountName(UInt32 acc, Char* buf) DB_SECTION1;

    /** returns the currency used by an account
        @param acc UID of the account to get the currency for
        @return UID of the currency used by the account */
    UInt32  getAccountCurrency(UInt32 acc) DB_SECTION1;

    /** Build the account's full path name, truncating the beginning if
        necessary to fit the given number of pixels.
        @param acc The account's UID
        @param width number of pixels
        @param dest allocated buffer to receive the result. I figure that it
            should be able to store width/2 characters in the worst case.   */
    void    getFullNameTruncLeftToFit(UInt32 acc, Int16 width, Char *dest) DB_SECTION1;

    /// unpacks an account record
    void    unpackRecord (accountStructure* account, packedAccountStructure* packedAccount) DB_SECTION1;

    /// packs an account record
    void    packRecord (accountStructure* account, MemHandle accountDBEntry) DB_SECTION1;
    
    /** Increment the account's balances by specified amounts, notifying the
        ancestors about the change as well.
        This is a 'lowlevel' function that modifies the account balance
        directly.
        @param uid uid of the account to be affected
        @param clr_amt amount to be added to the cleared balance
        @param amount amount to be added to the (total) balance
        @param is_parent true if the uid is the parent of an account whose
            balance has already changed. In this case, only the children totals
            of the given account and its ancestors are updated. */
    void incrementBalance(UInt32 uid, Int32 clr_amt, Int32 amount, Boolean is_parent = false)  DB_SECTION1;

    /** Updates the balance for an account. This is a 'highlevel' function
        that affects the balance by inserting a cleared balance adjustment
        transaction.
        @param uid unique id
        @param newbal the new balance
        @param payee optional payee description */
    void updateBalance(UInt32 uid,Int32 newbal,char *payee=NULL) DB_SECTION1;

    /** fetch the balance of a given account
        @param uid  the unique id of the account record
        @return the balance in pence */
    Int32   getBalance(UInt32 uid) DB_SECTION1;

    /** fetch the cleared balance of a given account
        @param uid  the unique id of the account record
        @return the expected balance in pence   */
    Int32   getClearedBalance(UInt32 uid) DB_SECTION1;

    /** checks if a parent of the current account is collapsed
        @acc account id
        @return true if no parrent is collapsed, false otherwise */
    Boolean isDisplayable(UInt16 acc) DB_SECTION1;
    
    /** packs and writes the data from s into the database
        @note: after calling this function the record has to be released
        @param s pointer to an allocated account which is to be saved
        @return the index to the record */
    UInt16  newRecord(accountStructure* s) DB_SECTION1;

    /** Deletes an account given by its id
        The function scans through all the transactions and removes the ones which
        have as source/destinations the account to be deleted and as dest/src an account
        in the Income or Expense categories.

        All the transaction involving user defined account will be updated so that the 
        reference to the account to be deleted is replaced with a reference to a Income/Expense
        account

        @param id the id of the account to be deleted   */
    bool    deleteRecord(UInt16 id) DB_SECTION1;

    /** Compares two records (by the account name)  */
    static Int16    compareRecords(packedAccountStructure* rec1,packedAccountStructure* rec2,Int16 other,SortRecordInfoPtr sr1,SortRecordInfoPtr
            sr2,MemHandle app_info) DB_SECTION1;

    /// recategorize accounts as visible/invisible depending on user's choice
    void updateVisibility(void);
};

/** unfortunatelly this is a bit messy :(. We need to be able to access this db from anywhere in the program (including the compareRecords function).
    The best solution I managed to come up with is defining the pointer in .c file, and exporting it in .h (tried defining it as static in .h only but
    did not work. Next we need to instatntiate the class (this is done in palmcoins.c) and set the pointer to a valid address */
extern AccountsDB* accounts_db;

#endif

---