Big cleanups, reworked CokeBank API

[tpg/opendispense2.git] / src / cokebank.h

diff --git a/src/cokebank.h b/src/cokebank.h
index 77ac110..30678c9 100644 (file)
--- a/src/cokebank.h
+++ b/src/cokebank.h
@@ -7,25 +7,65 @@
  * This file is licenced under the 3-clause BSD Licence. See the file COPYING
  * for full details.
  */
+/**
+ * \file cokebank.h
+ * \brief Coke Bank API Documentation
+ */
 #ifndef _COKEBANK_H_
 #define _COKEBANK_H_
 
 #define COKEBANK_SALES_ACCT    ">sales"        //!< Sales made into
 #define COKEBANK_DEBT_ACCT     ">liability"    //!< Credit taken out of
 
+/**
+ * \brief Account iterator opaque structure
+ *
+ * Opaque structure for account iterators returned by Bank_Iterator
+ * and used by Bank_IteratorNext and Bank_DelIterator
+ */
+typedef struct sAcctIterator   tAcctIterator;
+
+enum eBank_ItFlags
+{
+       BANK_ITFLAG_MINBALANCE  = 0x01,
+       BANK_ITFLAG_MAXBALANCE  = 0x02,
+       BANK_ITFLAG_SEENBEFORE  = 0x04,
+       BANK_ITFLAG_SEENAFTER   = 0x08,
+       
+       BANK_ITFLAG_SORT_NONE   = 0x000,
+       BANK_ITFLAG_SORT_NAME   = 0x100,
+       BANK_ITFLAG_SORT_BAL    = 0x200,
+       BANK_ITFLAG_SORT_UNIXID = 0x300,
+       BANK_ITFLAG_SORT_LASTSEEN       = 0x400,
+       BANK_ITFLAG_SORTMASK    = 0x700,
+       BANK_ITFLAG_REVSORT     = 0x800
+};
+
+/**
+ * \brief User flag values
+ *
+ * User flag values used by Bank_GetFlags and Bank_SetFlags
+ */
 enum eCokebank_Flags { 
-       USER_FLAG_COKE          = 0x01,
-       USER_FLAG_WHEEL         = 0x02,
-       USER_FLAG_DOORGROUP     = 0x04,
-       USER_FLAG_INTERNAL      = 0x40,
-       USER_FLAG_DISABLED      = 0x80
+       USER_FLAG_COKE          = 0x01, //!< User is a coke member (can do coke accounting)
+       USER_FLAG_WHEEL         = 0x02, //!< User is a wheel member (can create, delete and lock accounts)
+       USER_FLAG_DOORGROUP     = 0x04, //!< User is in the door group (can open the clubroom door)
+       USER_FLAG_INTERNAL      = 0x40, //!< Account is internal (cannot be authenticated, no lower balance limit)
+       USER_FLAG_DISABLED      = 0x80  //!< Account is disabled (no transactions allowed)
 };
 
 // --- Cokebank Functions ---
+/**
+ * \brief Initialise the cokebank
+ * \param Argument     Cokebank argument specified in the dispense config file (typically the database path)
+ * \return Boolean Failure
+ */
+extern int     Bank_Initialise(const char *Argument);
+
 /**
  * \brief Transfer money from one account to another
- * \param SourceUser   UID (from \a GetUserID) to take the money from
- * \param DestUser     UID (from \a GetUserID) give money to
+ * \param SourceUser   UID (from \a Bank_GetUserID) to take the money from
+ * \param DestUser     UID (from \a Bank_GetUserID) give money to
  * \param Ammount      Amount of money (in cents) to transfer
  * \param Reason       Reason for the transfer
  */
@@ -33,7 +73,7 @@ extern int    Bank_Transfer(int SourceUser, int DestUser, int Ammount, const char *
 /**
  * \brief Get flags on an account
  * \param User UID to get flags from
- * \see eCokebank_Flags
+ * \return Flag set as defined in eCokebank_Flags
  */
 extern int     Bank_GetFlags(int User);
 /**
@@ -59,19 +99,61 @@ extern char *Bank_GetUserName(int User);
 extern int     Bank_GetUserID(const char *Username);
 /**
  * \brief Create a new account
+ * \param Username     Name for the new account (if NULL, an anoymous account is created)
+ * \return User ID of the new account
  */
 extern int     Bank_CreateUser(const char *Username);
+
+/**
+ * \brief Create an account iterator
+ * \param FlagMask     Mask of account flags to check
+ * \param FlagValues   Wanted values for checked flags
+ * \param Flags        Specifies the operation of \a MinMaxBalance and \a Timestamp  (\see eBank_ItFlags)
+ * \param MinMaxBalance        Mininum/Maximum balance
+ * \param LastSeen     Latest/Earliest last seen time
+ * \return Pointer to an iterator across the selected data set
+ */
+extern tAcctIterator   *Bank_Iterator(int FlagMask, int FlagValues,
+       int Flags, int MinMaxBalance, time_t LastSeen);
+
+/**
+ * \brief Get the current entry in the iterator and move to the next
+ * \param It   Iterator returned by Bank_Iterator
+ * \return User ID or -1 for end of list
+ */
+extern int     Bank_IteratorNext(tAcctIterator *It);
+
 /**
- * \brief Get the maximum UID
- * \note Used for iterating accounts
+ * \brief Free an allocated iterator
+ * \param It   Iterator returned by Bank_Iterator
  */
-extern int     Bank_GetMaxID(void);
+extern void    Bank_DelIterator(tAcctIterator *It);
+
 /**
  * \brief Validates a user's authentication
  * \param Salt Salt given to the client for hashing the password
  * \param Username     Username used
  * \param Password     Password sent by the client
+ * \return User ID
  */
 extern int     Bank_GetUserAuth(const char *Salt, const char *Username, const char *Password);
 
+/**
+ * \brief Get a User ID from a MIFARE card ID
+ * \param CardID       MIFARE card ID
+ * \return User ID
+ */
+extern int     Bank_GetUserByCard(const char *CardID);
+
+/**
+ * \brief Add a card to a user's account
+ * \param User User ID
+ * \param CardID       MIFARE card ID
+ * \return Boolean failure
+ * \retval 0   Success
+ * \retval 1   Bad user ID
+ * \retval 2   Card in use
+ */
+extern int     Bank_AddUserCard(int User, const char *CardID);
+
 #endif