src/cokebank.h

   1 /*
   2  * OpenDispense 2
   3  * UCC (University [of WA] Computer Club) Electronic Accounting System
   4  *
   5  * cokebank.h - Coke-Bank common definitions
   6  *
   7  * This file is licenced under the 3-clause BSD Licence. See the file COPYING
   8  * for full details.
   9  */
  10 /**
  11  * \file cokebank.h
  12  * \brief Coke Bank API Documentation
  13  */
  14 #ifndef _COKEBANK_H_
  15 #define _COKEBANK_H_
  16
  17 #include <stdlib.h>
  18
  19 #define COKEBANK_SALES_ACCT     ">sales"        //!< Sales made into
  20 #define COKEBANK_DEBT_ACCT      ">liability"    //!< Credit taken out of
  21 #define COKEBANK_FREE_ACCT      ">freeitems"    //!< ODay drink costs taken out of
  22
  23 /**
  24  * \brief Account iterator opaque structure
  25  *
  26  * Opaque structure for account iterators returned by Bank_Iterator
  27  * and used by Bank_IteratorNext and Bank_DelIterator
  28  */
  29 typedef struct sAcctIterator    tAcctIterator;
  30
  31 enum eBank_ItFlags
  32 {
  33         BANK_ITFLAG_MINBALANCE  = 0x01,
  34         BANK_ITFLAG_MAXBALANCE  = 0x02,
  35         BANK_ITFLAG_SEENBEFORE  = 0x04,
  36         BANK_ITFLAG_SEENAFTER   = 0x08,
  37
  38         BANK_ITFLAG_SORT_NONE   = 0x000,
  39         BANK_ITFLAG_SORT_NAME   = 0x100,
  40         BANK_ITFLAG_SORT_BAL    = 0x200,
  41         BANK_ITFLAG_SORT_UNIXID = 0x300,
  42         BANK_ITFLAG_SORT_LASTSEEN       = 0x400,
  43         BANK_ITFLAG_SORTMASK    = 0x700,
  44         BANK_ITFLAG_REVSORT     = 0x800
  45 };
  46
  47 /**
  48  * \brief User flag values
  49  *
  50  * User flag values used by Bank_GetFlags and Bank_SetFlags
  51  */
  52 enum eCokebank_Flags {
  53         USER_FLAG_COKE          = 0x01, //!< User is a coke member (can do coke accounting)
  54         USER_FLAG_ADMIN         = 0x02, //!< User is a administrator (can create, delete and lock accounts)
  55         USER_FLAG_DOORGROUP     = 0x04, //!< User is in the door group (can open the clubroom door)
  56         USER_FLAG_INTERNAL      = 0x40, //!< Account is internal (cannot be authenticated, no lower balance limit)
  57         USER_FLAG_DISABLED      = 0x80  //!< Account is disabled (no transactions allowed)
  58 };
  59
  60 // --- Cokebank Functions ---
  61 /**
  62  * \brief Initialise the cokebank
  63  * \param Argument      Cokebank argument specified in the dispense config file (typically the database path)
  64  * \return Boolean Failure
  65  */
  66 extern int      Bank_Initialise(const char *Argument);
  67
  68 /**
  69  * \brief Transfer money from one account to another
  70  * \param SourceUser    UID (from \a Bank_GetUserID) to take the money from
  71  * \param DestUser      UID (from \a Bank_GetUserID) give money to
  72  * \param Ammount       Amount of money (in cents) to transfer
  73  * \param Reason        Reason for the transfer
  74  */
  75 extern int      Bank_Transfer(int SourceAcct, int DestAcct, int Ammount, const char *Reason);
  76 /**
  77  * \brief Get flags on an account
  78  * \param AcctID        UID to get flags from
  79  * \return Flag set as defined in eCokebank_Flags
  80  */
  81 extern int      Bank_GetFlags(int AcctID);
  82 /**
  83  * \brief Set an account's flags
  84  * \param AcctID        UID to set flags on
  85  * \param Mask  Mask of flags changed
  86  * \param Value Final value of changed flags
  87  */
  88 extern int      Bank_SetFlags(int AcctID, int Mask, int Value);
  89 /**
  90  * \brief Get an account's balance
  91  * \param AcctID        Account to query
  92  */
  93 extern int      Bank_GetBalance(int AcctID);
  94 /**
  95  * \brief Get the name associated with an account
  96  * \return Heap string
  97  */
  98 extern char     *Bank_GetAcctName(int AcctID);
  99 /**
 100  * \brief Get an account ID from a passed name
 101  */
 102 extern int      Bank_GetAcctByName(const char *Name);
 103 /**
 104  * \brief Create a new account
 105  * \param Username      Name for the new account (if NULL, an anoymous account is created)
 106  * \return ID of the new account
 107  */
 108 extern int      Bank_CreateAcct(const char *Name);
 109
 110 /**
 111  * \brief Create an account iterator
 112  * \param FlagMask      Mask of account flags to check
 113  * \param FlagValues    Wanted values for checked flags
 114  * \param Flags Specifies the operation of \a MinMaxBalance and \a Timestamp  (\see eBank_ItFlags)
 115  * \param MinMaxBalance Mininum/Maximum balance
 116  * \param LastSeen      Latest/Earliest last seen time
 117  * \return Pointer to an iterator across the selected data set
 118  */
 119 extern tAcctIterator    *Bank_Iterator(int FlagMask, int FlagValues,
 120         int Flags, int MinMaxBalance, time_t LastSeen);
 121
 122 /**
 123  * \brief Get the current entry in the iterator and move to the next
 124  * \param It    Iterator returned by Bank_Iterator
 125  * \return Accoun ID, or -1 for end of list
 126  */
 127 extern int      Bank_IteratorNext(tAcctIterator *It);
 128
 129 /**
 130  * \brief Free an allocated iterator
 131  * \param It    Iterator returned by Bank_Iterator
 132  */
 133 extern void     Bank_DelIterator(tAcctIterator *It);
 134
 135 /**
 136  * \brief Validates a user's authentication
 137  * \param Salt  Salt given to the client for hashing the password
 138  * \param Username      Username used
 139  * \param Password      Password sent by the client
 140  * \return User ID
 141  */
 142 extern int      Bank_GetUserAuth(const char *Salt, const char *Username, const char *Password);
 143
 144 /**
 145  * \brief Get an account ID from a MIFARE card ID
 146  * \param CardID        MIFARE card ID
 147  * \return Account ID
 148  */
 149 extern int      Bank_GetAcctByCard(const char *CardID);
 150
 151 /**
 152  * \brief Add a card to an account
 153  * \param AcctID        Account ID
 154  * \param CardID        MIFARE card ID
 155  * \return Boolean failure
 156  * \retval 0    Success
 157  * \retval 1    Bad account ID
 158  * \retval 2    Card in use
 159  */
 160 extern int      Bank_AddAcctCard(int AcctID, const char *CardID);
 161
 162 // ---
 163 // Server provided helper functions
 164 // ---
 165 /**
 166  * \brief Create a formatted string on the heap
 167  * \param Format        Format string
 168  * \return Heap string
 169  */
 170 extern char     *mkstr(const char *Format, ...);
 171
 172 #endif