notes/proto.txt

   1 OpenDispense^2
   2 Client/Server Dispense Protocol
   3
   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.
   6
   7 == Paramaters ===
   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
  14 by the driver.
  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
  17 numbers.
  18
  19
  20 == Response Codes ==
  21 100     Information
  22 200     Command succeeded, no extra information
  23 201     Command succeeded, multiple lines follow (<length>)
  24 202     Command succeeded, per-command format
  25 400     Unknown Command
  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
  30 406     Bad Item ID
  31 407     Invalid arguments
  32 500     Unknown Dispense Failure
  33 501     Action Rejected
  34
  35 == Item IDs ==
  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
  39
  40 === User Auth ===
  41 --- Untrusted Users ---
  42 c       USER <username>\n
  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
  55
  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
  59
  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
  70
  71 === Coke Member Commands (Account Manipulation) ===
  72 --- Alter balance ---
  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
  75 --- Set balance ---
  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
  81
  82
  83 === Items ===
  84 --- Get Item list ---
  85 c       ENUM_ITEMS\n
  86 s       201 Items <count>\n
  87 s       >> Response to ITEM_INFO
  88     ...
  89 s       200 List End\n
  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
  96 s       200 Item updated
  97
  98 === Users ===
  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
 103     ...
 104 s       200 List End\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 ---
 110 c       USER_INFO\n
 111 s       202 User <username> <balance> <flags>\n
 112
 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