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

UCC git Repository :: git.ucc.asn.au