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_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
28 * \brief Account iterator opaque structure
30 * Opaque structure for account iterators returned by Bank_Iterator
31 * and used by Bank_IteratorNext and Bank_DelIterator
33 typedef struct sAcctIterator tAcctIterator;
37 * \brief Iterator for a collection of items
39 typedef struct sItemIterator tItemIterator;
42 * \brief Item structure
54 * \brief Flag values for the \a Flags parameter to Bank_Iterator
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)
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
72 * \brief Flag values for the \a Flags parameter to Items_Iterator
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
86 * \brief User flag values
88 * User flag values used by Bank_GetFlags and Bank_SetFlags
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)
98 // --- Cokebank Functions ---
100 * \brief Initialise the cokebank
101 * \param Argument Cokebank argument specified in the dispense config file (typically the database path)
102 * \return Boolean Failure
104 extern int Bank_Initialise(const char *Argument);
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
113 extern int Bank_Transfer(int SourceAcct, int DestAcct, int Ammount, const char *Reason);
115 * \brief Get flags on an account
116 * \param AcctID UID to get flags from
117 * \return Flag set as defined in eCokebank_Flags
119 extern int Bank_GetFlags(int AcctID);
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
126 extern int Bank_SetFlags(int AcctID, int Mask, int Value);
128 * \brief Get an account's balance
129 * \param AcctID Account to query
131 extern int Bank_GetBalance(int AcctID);
133 * \brief Get the name associated with an account
134 * \return Heap string
136 extern char *Bank_GetAcctName(int AcctID);
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
142 extern int Bank_GetAcctByName(const char *Name, int bCreate);
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
148 extern int Bank_CreateAcct(const char *Name);
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
159 extern tAcctIterator *Bank_Iterator(int FlagMask, int FlagValues,
160 int Flags, int MinMaxBalance, time_t LastSeen);
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
167 extern int Bank_IteratorNext(tAcctIterator *It);
170 * \brief Free an allocated iterator
171 * \param It Iterator returned by Bank_Iterator
173 extern void Bank_DelIterator(tAcctIterator *It);
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
182 extern int Bank_GetUserAuth(const char *Salt, const char *Username, const char *Password);
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
190 extern int Bank_IsPinValid(int AcctID, int Pin);
193 * \brief Update a user's pin
194 * \param AcctID Account ID
195 * \param NewPin New pin for the account
197 extern void Bank_SetPin(int AcctID, int NewPin);
200 * \brief Get an account ID from a MIFARE card ID
201 * \param CardID MIFARE card ID
204 extern int Bank_GetAcctByCard(const char *CardID);
207 * \brief Add a card to an account
208 * \param AcctID Account ID
209 * \param CardID MIFARE card ID
210 * \return Boolean failure
212 * \retval 1 Bad account ID
213 * \retval 2 Card in use
215 extern int Bank_AddAcctCard(int AcctID, const char *CardID);
217 // === Item Manipulation ===
219 extern tItem *Items_GetItem(char *Handler, int ID);
221 * \brief Create an item iterator
222 * \return Pointer to an iterator across the selected data set
224 extern tItemIterator *Items_Iterator(int Flags, char *Handler, int MaxPrice);
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
231 extern tItem *Items_IteratorNext(tItemIterator *It);
234 * \brief Free an allocated iterator
235 * \param It Iterator returned by Items_Iterator
237 extern void Items_DelIterator(tItemIterator *It);
241 // Server provided helper functions
244 * \brief Create a formatted string on the heap
245 * \param Format Format string
246 * \return Heap string
248 extern char *mkstr(const char *Format, ...);
251 * \brief Dispense log access
252 * \note Try not to over-use, only stuff that matters should go in here
254 extern void Log_Info(const char *Format, ...);