2 Client/Server Dispense Protocol
4 The protocol is ASCII based, similar to the FTP protocol
5 All server responses are on one line and are prefixed by a three digit response code.
8 <username> is a textual username unless the user does not have a username,
9 in which case the username is of the form '#<id>' where <id> is a unique
10 account number assigned by the server.
11 <card_id_hex> is the hexadecimal byte stream representation of a MIFARE card.
12 <item_id> is an item ID of the form '<type>:<id>', where <type> is an
13 alpha-numeric diriver identifier, and <id> is an non-negative integer assigned
15 <ammount> is an integer number of cents representing the size of a transactio.
16 Individual commands may restrict the range of the ammount to non-negative
22 200 Command succeeded, no extra information
23 201 Command succeeded, multiple lines follow (<length>)
24 202 Command succeeded, per-command format
26 401 Not Authenticated (or Authentication failure)
27 402 Balance insufficient
28 403 User not allowed to perform this action
29 404 Bad other username
32 500 Unknown Dispense Failure
36 <item_id> represents the item ID
37 Item IDs are allowed to contain any non-whitespace character, but in
38 general they will be limited to the standard alpha-numeric set
41 --- Untrusted Users ---
43 s 202 SALT <string>\n or 100 User Set\n (If no salt used)
44 c PASS <hash>\n (Hex-Encoded SHA-1 Hash of <username><salt><password>)
45 s 200 Auth OK\n or 401 Auth Failure\n
46 User is now authenticated
47 --- Alternate Method (Implicit Trust Authentication) ---
48 If the client is connecting from a trusted machine on a root port then
49 automatic authentication is allowed
50 c AUTOAUTH <username>\n
51 s 200 Auth OK\n or 404 Bad Username\n or 401 Untrusted\n
52 --- Alternate Method (MIFARE Authentication)
53 c MIFARE <card_id_hex>\n
54 s 200 Auth OK as <username>\n or 401 Untrusted\n or 404 Bad Card ID\n
56 --- Set effective user (User in `dispense -u`) ---
57 c SETEUSER <username>\n
58 s 200 User set\n or 403 Not in coke\n or 404 User not found\n
60 === Standard User Commands ===
61 --- Dispense an item ---
62 c DISPENSE <item_id>\n
63 s 200 Dispense OK\n or 402 Poor You\n or 406 Bad Item\n or 500 Dispense Error\n
64 --- Give to another user ---
65 c GIVE <user> <ammount> <reason>\n
66 s 200 Give OK\n or 402 Poor You\n or 404 Bad User\n
67 --- Donate to the club ---
68 c DONATE <ammount> <reason>\n
69 s 200 Give OK\n or 402 Poor You\n
71 === Coke Member Commands (Account Manipulation) ===
73 c ADD <user> <ammount> <reason>\n
74 s 200 Add OK\n or 402 No balance\n or 403 Not Coke\n or 404 Bad User\n
76 c SET <user> <balance> <reason>\n
77 s 200 Add OK\n or 402 No balance\n or 403 Not Coke\n or 404 Bad User\n
78 --- Refund a drink ---
79 c REFUND <user> <item>[ <price>]\n
80 s 200 Add OK\n or 403 Not Coke\n or 404 Bad User\n 406 Bad Item\n
87 s >> Response to ITEM_INFO
90 --- Get Item Information ---
91 c ITEM_INFO <item_id>\n
92 s 202 Item <item_id> <status> <price> <description>\n
93 <status> "avail", "sold", or "error"
94 --- Update an item ---
95 c UPDATE_ITEM <item_id> <price> <name>\n
99 --- Get Users' Balances ---
100 c ENUM_USERS[ min_balance:<balance>][ max_balance:<balance>][ flags:<flagset>][ last_seen_before:<unix_timestamp>][ last_seen_after:<unix_timestamp>][ sort:<field>[-desc]]\n
101 s 201 Users <count>\n
102 s 202 User <username> <balance> <flags>\n
105 <balance> Integer balance value (in cents)
106 <flagset> Flag values (same format as USER_FLAGS)
107 <unix_timestamp> Number of seconds since 1/Jan/1970
108 <field> Sort field (name,balance,lastseen)
109 --- Get a User's Balance ---
111 s 202 User <username> <balance> <flags>\n
113 === User Manipulation ===
114 --- Add a new user ---
115 c USER_ADD <username>\n
116 s 200 User Added\n or 403 Not Wheel\n or 404 User Exists\n
117 --- Set user flags ---
118 <flags> is a comma-separated list of flag values (optionally preceded by
119 - to remove the flag) Valid values are: user,coke,admin,internal,disabled,door
120 c USER_FLAGS <username> <flags>\n
121 s 200 User Updated\n or 403 Not Wheel\n or 404 Bad User\n or 407 Unknown Flags\n
122 --- Add MIFARE ID ---
123 c ADD_CARD <card id hex>\n
124 s 200 User Updated\n or 405 Card already registered\n