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 #if 0
  32 /**
  33  * \brief Iterator for a collection of items
  34  */
  35 typedef struct sItemIterator    tItemIterator;
  36
  37 /**
  38  * \brief Item structure
  39  */
  40 typedef struct
  41 {
  42         char    *Handler;
  43          int    ID;
  44          int    Price;
  45         char    Name[];
  46 }       tItem;
  47 #endif
  48
  49 /**
  50  * \brief Flag values for the \a Flags parameter to Bank_Iterator
  51  */
  52 enum eBank_ItFlags
  53 {
  54         BANK_ITFLAG_MINBALANCE  = 0x01, //!< Balance value is Minium Balance
  55         BANK_ITFLAG_MAXBALANCE  = 0x02, //!< Balance value is Maximum Balance (higher priority)
  56         BANK_ITFLAG_SEENAFTER   = 0x04, //!< Last seen value is lower bound
  57         BANK_ITFLAG_SEENBEFORE  = 0x08, //!< Last seen value is upper bound (higher priority)
  58
  59         BANK_ITFLAG_SORT_NONE   = 0x000,        //!< No sorting (up to the implementation)
  60         BANK_ITFLAG_SORT_NAME   = 0x100,        //!< Sort alphabetically ascending by name
  61         BANK_ITFLAG_SORT_BAL    = 0x200,        //!< Sort by balance, ascending
  62         BANK_ITFLAG_SORT_UNIXID = 0x300,        //!< Sort by UnixUID (TODO: Needed?)
  63         BANK_ITFLAG_SORT_LASTSEEN = 0x400,      //!< Sort by last seen time (ascending)
  64         BANK_ITFLAG_SORTMASK    = 0x700,        //!< Sort type mask
  65         BANK_ITFLAG_REVSORT     = 0x800 //!< Sort descending instead
  66 };
  67 /**
  68  * \brief Flag values for the \a Flags parameter to Items_Iterator
  69  */
  70 enum eItems_ItFlags
  71 {
  72         ITEMS_ITFLAG_SHOWDISABLED = 0x001,      //!< Show disabled items
  73         ITEMS_ITFLAG_SORT_NONE  = 0x000,        //!< No sorting (up to the implementation)
  74         ITEMS_ITFLAG_SORT_NAME  = 0x100,        //!< Sort alphabetically ascending by name
  75         ITEMS_ITFLAG_SORT_PRICE = 0x200,        //!< Sort by price, ascending
  76         ITEMS_ITFLAG_SORT_IDENT = 0x300,        //!< Sort by Identifier (handler:id)
  77         ITEMS_ITFLAG_SORTMASK   = 0x700,        //!< Sort type mask
  78         ITEMS_ITFLAG_REVSORT    = 0x800 //!< Sort descending instead
  79 };
  80
  81 /**
  82  * \brief User flag values
  83  *
  84  * User flag values used by Bank_GetFlags and Bank_SetFlags
  85  */
  86 enum eCokebank_Flags {
  87         USER_FLAG_COKE          = 0x01, //!< User is a coke member (can do coke accounting)
  88         USER_FLAG_ADMIN         = 0x02, //!< User is a administrator (can create, delete and lock accounts)
  89         USER_FLAG_DOORGROUP     = 0x04, //!< User is in the door group (can open the clubroom door)
  90         USER_FLAG_INTERNAL      = 0x40, //!< Account is internal (cannot be authenticated, no lower balance limit)
  91         USER_FLAG_DISABLED      = 0x80  //!< Account is disabled (no transactions allowed)
  92 };
  93
  94 // --- Cokebank Functions ---
  95 /**
  96  * \brief Initialise the cokebank
  97  * \param Argument      Cokebank argument specified in the dispense config file (typically the database path)
  98  * \return Boolean Failure
  99  */
 100 extern int      Bank_Initialise(const char *Argument);
 101
 102 /**
 103  * \brief Transfer money from one account to another
 104  * \param SourceAcct    UID (from \a Bank_GetUserID) to take the money from
 105  * \param DestAcct      UID (from \a Bank_GetUserID) give money to
 106  * \param Ammount       Amount of money (in cents) to transfer
 107  * \param Reason        Reason for the transfer
 108  */
 109 extern int      Bank_Transfer(int SourceAcct, int DestAcct, int Ammount, const char *Reason);
 110 /**
 111  * \brief Get flags on an account
 112  * \param AcctID        UID to get flags from
 113  * \return Flag set as defined in eCokebank_Flags
 114  */
 115 extern int      Bank_GetFlags(int AcctID);
 116 /**
 117  * \brief Set an account's flags
 118  * \param AcctID        UID to set flags on
 119  * \param Mask  Mask of flags changed
 120  * \param Value Final value of changed flags
 121  */
 122 extern int      Bank_SetFlags(int AcctID, int Mask, int Value);
 123 /**
 124  * \brief Get an account's balance
 125  * \param AcctID        Account to query
 126  */
 127 extern int      Bank_GetBalance(int AcctID);
 128 /**
 129  * \brief Get the name associated with an account
 130  * \return Heap string
 131  */
 132 extern char     *Bank_GetAcctName(int AcctID);
 133 /**
 134  * \brief Get an account ID from a passed name
 135  * \param Name  Name to search for
 136  * \return ID of the account, or -1 if not found
 137  */
 138 extern int      Bank_GetAcctByName(const char *Name);
 139 /**
 140  * \brief Create a new account
 141  * \param Name  Name for the new account (if NULL, an anoymous account is created)
 142  * \return ID of the new account
 143  */
 144 extern int      Bank_CreateAcct(const char *Name);
 145
 146 /**
 147  * \brief Create an account iterator
 148  * \param FlagMask      Mask of account flags to check
 149  * \param FlagValues    Wanted values for checked flags
 150  * \param Flags Specifies the operation of \a MinMaxBalance and \a Timestamp  (\see eBank_ItFlags)
 151  * \param MinMaxBalance Mininum/Maximum balance
 152  * \param LastSeen      Latest/Earliest last seen time
 153  * \return Pointer to an iterator across the selected data set
 154  */
 155 extern tAcctIterator    *Bank_Iterator(int FlagMask, int FlagValues,
 156         int Flags, int MinMaxBalance, time_t LastSeen);
 157
 158 /**
 159  * \brief Get the current entry in the iterator and move to the next
 160  * \param It    Iterator returned by Bank_Iterator
 161  * \return Accoun ID, or -1 for end of list
 162  */
 163 extern int      Bank_IteratorNext(tAcctIterator *It);
 164
 165 /**
 166  * \brief Free an allocated iterator
 167  * \param It    Iterator returned by Bank_Iterator
 168  */
 169 extern void     Bank_DelIterator(tAcctIterator *It);
 170
 171 /**
 172  * \brief Validates a user's authentication
 173  * \param Salt  Salt given to the client for hashing the password
 174  * \param Username      Username used
 175  * \param Password      Password sent by the client
 176  * \return User ID
 177  */
 178 extern int      Bank_GetUserAuth(const char *Salt, const char *Username, const char *Password);
 179
 180 /**
 181  * \brief Get an account ID from a MIFARE card ID
 182  * \param CardID        MIFARE card ID
 183  * \return Account ID
 184  */
 185 extern int      Bank_GetAcctByCard(const char *CardID);
 186
 187 /**
 188  * \brief Add a card to an account
 189  * \param AcctID        Account ID
 190  * \param CardID        MIFARE card ID
 191  * \return Boolean failure
 192  * \retval 0    Success
 193  * \retval 1    Bad account ID
 194  * \retval 2    Card in use
 195  */
 196 extern int      Bank_AddAcctCard(int AcctID, const char *CardID);
 197
 198 // === Item Manipulation ===
 199 #if 0
 200 extern tItem    *Items_GetItem(char *Handler, int ID);
 201 /**
 202  * \brief Create an item iterator
 203  * \return Pointer to an iterator across the selected data set
 204  */
 205 extern tItemIterator    *Items_Iterator(int Flags, char *Handler, int MaxPrice);
 206
 207 /**
 208  * \brief Get the current entry in the iterator and move to the next
 209  * \param It    Iterator returned by Items_Iterator
 210  * \return Item ID, or -1 for end of list
 211  */
 212 extern tItem    *Items_IteratorNext(tItemIterator *It);
 213
 214 /**
 215  * \brief Free an allocated iterator
 216  * \param It    Iterator returned by Items_Iterator
 217  */
 218 extern void     Items_DelIterator(tItemIterator *It);
 219 #endif
 220
 221 // ---
 222 // Server provided helper functions
 223 // ---
 224 /**
 225  * \brief Create a formatted string on the heap
 226  * \param Format        Format string
 227  * \return Heap string
 228  */
 229 extern char     *mkstr(const char *Format, ...);
 230
 231 /**
 232  * \brief Dispense log access
 233  * \note Try not to over-use, only stuff that matters should go in here
 234  */
 235 extern void     Log_Info(const char *Format, ...);
 236
 237 #endif