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