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