3 * UCC (University [of WA] Computer Club) Electronic Accounting System
5 * cokebank.h - Coke-Bank common definitions
7 * This file is licenced under the 3-clause BSD Licence. See the file COPYING
12 * \brief Coke Bank API Documentation
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
24 * \brief Account iterator opaque structure
26 * Opaque structure for account iterators returned by Bank_Iterator
27 * and used by Bank_IteratorNext and Bank_DelIterator
29 typedef struct sAcctIterator tAcctIterator;
33 BANK_ITFLAG_MINBALANCE = 0x01,
34 BANK_ITFLAG_MAXBALANCE = 0x02,
35 BANK_ITFLAG_SEENBEFORE = 0x04,
36 BANK_ITFLAG_SEENAFTER = 0x08,
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
48 * \brief User flag values
50 * User flag values used by Bank_GetFlags and Bank_SetFlags
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)
60 // --- Cokebank Functions ---
62 * \brief Initialise the cokebank
63 * \param Argument Cokebank argument specified in the dispense config file (typically the database path)
64 * \return Boolean Failure
66 extern int Bank_Initialise(const char *Argument);
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
75 extern int Bank_Transfer(int SourceAcct, int DestAcct, int Ammount, const char *Reason);
77 * \brief Get flags on an account
78 * \param AcctID UID to get flags from
79 * \return Flag set as defined in eCokebank_Flags
81 extern int Bank_GetFlags(int AcctID);
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
88 extern int Bank_SetFlags(int AcctID, int Mask, int Value);
90 * \brief Get an account's balance
91 * \param AcctID Account to query
93 extern int Bank_GetBalance(int AcctID);
95 * \brief Get the name associated with an account
98 extern char *Bank_GetAcctName(int AcctID);
100 * \brief Get an account ID from a passed name
102 extern int Bank_GetAcctByName(const char *Name);
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
108 extern int Bank_CreateAcct(const char *Name);
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
119 extern tAcctIterator *Bank_Iterator(int FlagMask, int FlagValues,
120 int Flags, int MinMaxBalance, time_t LastSeen);
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
127 extern int Bank_IteratorNext(tAcctIterator *It);
130 * \brief Free an allocated iterator
131 * \param It Iterator returned by Bank_Iterator
133 extern void Bank_DelIterator(tAcctIterator *It);
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
142 extern int Bank_GetUserAuth(const char *Salt, const char *Username, const char *Password);
145 * \brief Get an account ID from a MIFARE card ID
146 * \param CardID MIFARE card ID
149 extern int Bank_GetAcctByCard(const char *CardID);
152 * \brief Add a card to an account
153 * \param AcctID Account ID
154 * \param CardID MIFARE card ID
155 * \return Boolean failure
157 * \retval 1 Bad account ID
158 * \retval 2 Card in use
160 extern int Bank_AddAcctCard(int AcctID, const char *CardID);
163 // Server provided helper functions
166 * \brief Create a formatted string on the heap
167 * \param Format Format string
168 * \return Heap string
170 extern char *mkstr(const char *Format, ...);