OpenDispense^2 Client/Server Dispense Protocol The protocol is ASCII based, similar to the FTP protocol All server responses are on one line and are prefixed by a three digit response code. == Paramaters === is a textual username unless the user does not have a username, in which case the username is of the form '#' where is a unique account number assigned by the server. is the hexadecimal byte stream representation of a MIFARE card. is an item ID of the form ':', where is an alpha-numeric diriver identifier, and is an non-negative integer assigned by the driver. is an integer number of cents representing the size of a transactio. Individual commands may restrict the range of the ammount to non-negative numbers. == Response Codes == 100 Information 200 Command succeeded, no extra information 201 Command succeeded, multiple lines follow () 202 Command succeeded, per-command format 400 Unknown Command 401 Not Authenticated (or Authentication failure) 402 Balance insufficient 403 User not allowed to perform this action 404 Bad other username 406 Bad Item ID 407 Invalid arguments 408 Already exists 500 Unknown Dispense Failure 501 Action Rejected == Item IDs == represents the item ID Item IDs are allowed to contain any non-whitespace character, but in general they will be limited to the standard alpha-numeric set === User Auth === --- Untrusted Users --- c USER \n s 202 SALT \n or 100 User Set\n (If no salt used) c PASS \n (Hex-Encoded SHA-1 Hash of ) s 200 Auth OK\n or 401 Auth Failure\n User is now authenticated --- Alternate Method (Implicit Trust Authentication) --- If the client is connecting from a trusted machine on a root port then automatic authentication is allowed c AUTOAUTH \n s 200 Auth OK\n or 404 Bad Username\n or 401 Untrusted\n --- Alternate Method (MIFARE Authentication) c MIFARE \n s 200 Auth OK as \n or 401 Untrusted\n or 404 Bad Card ID\n --- Set effective user (User in `dispense -u`) --- c SETEUSER \n s 200 User set\n or 403 Not in coke\n or 404 User not found\n === Standard User Commands === --- Dispense an item --- c DISPENSE \n s 200 Dispense OK\n or 402 Poor You\n or 406 Bad Item\n or 500 Dispense Error\n --- Give to another user --- c GIVE \n s 200 Give OK\n or 402 Poor You\n or 404 Bad User\n --- Donate to the club --- c DONATE \n s 200 Give OK\n or 402 Poor You\n === Coke Member Commands (Account Manipulation) === --- Alter balance --- c ADD \n s 200 Add OK\n or 402 No balance\n or 403 Not Coke\n or 404 Bad User\n --- Set balance --- c SET \n s 200 Add OK\n or 402 No balance\n or 403 Not Coke\n or 404 Bad User\n --- Refund a drink --- c REFUND [ ]\n s 200 Add OK\n or 403 Not Coke\n or 404 Bad User\n 406 Bad Item\n === Items === --- Get Item list --- c ENUM_ITEMS\n s 201 Items \n s >> Response to ITEM_INFO ... s 200 List End\n --- Get Item Information --- c ITEM_INFO \n s 202 Item \n "avail", "sold", or "error" --- Update an item --- c UPDATE_ITEM \n s 200 Item updated === Users === --- Get Users' Balances --- c ENUM_USERS[ min_balance:][ max_balance:][ flags:][ last_seen_before:][ last_seen_after:][ sort:[-desc]]\n s 201 Users \n s 202 User \n ... s 200 List End\n Integer balance value (in cents) Flag values (same format as USER_FLAGS) Number of seconds since 1/Jan/1970 Sort field (name,balance,lastseen) --- Get a User's Balance --- c USER_INFO\n s 202 User \n === User Manipulation === --- Add a new user --- c USER_ADD \n s 200 User Added\n or 403 Not Wheel\n or 404 User Exists\n --- Set user flags --- is a comma-separated list of flag values (optionally preceded by - to remove the flag) Valid values are: user,coke,admin,internal,disabled,door c USER_FLAGS \n s 200 User Updated\n or 403 Not Wheel\n or 404 Bad User\n or 407 Unknown Flags\n --- Add MIFARE ID --- c ADD_CARD \n s 200 User Updated\n or 405 Card already registered\n