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 == Response Codes ==
   8 100     Information
   9 200     Command succeeded, no extra information
  10 201     Command succeeded, array follows (<length> <items> <items> ...)
  11 202     Command succeeded, per-command format
  12 400     Unknown Command
  13 401     Not Authenticated (or Authentication failure)
  14 402     Balance insufficient
  15 403     User not allowed to perform this action
  16 404     Bad other username
  17 406     Bad Item ID
  18 500     Unknown Dispense Failure
  19
  20 == Item IDs ==
  21 <item_id> represents the item ID
  22 Item IDs are allowed to contain any non-whitespace character, but in
  23 general they will be limited to the standard alpha-numeric set
  24
  25 === User Auth ===
  26 c       USER <username>\n
  27 s       100 SALT <string>\n or 100 User Set\n   (If no salt used)
  28 c       PASS <hash>\n   (Hex-Encoded SHA-512 Hash of <username><salt><password>)
  29 s       200 Auth OK\n or 401 Auth Failure\n
  30 User is now authenticated
  31 --- Alternate Method (Implicit Trust Authentication) ---
  32 If the client is connecting from a trusted machine on a root port then
  33 automatic authentication is allowed
  34 c       AUTOAUTH <username>\n
  35 s       200 Auth OK\n or 401 Auth Failure\n or 401 Untrusted\n
  36
  37 === Commands ===
  38 --- Get Item list ---
  39 c       ENUM_ITEMS\n
  40 s       201 Items <count> <item_id> <item_id> ...\n
  41 --- Get Item Information ---
  42 c       ITEM_INFO <item_id>\n
  43 s       202 Item <item_id> <price> <description>\n
  44 --- Dispense an item ---
  45 c       DISPENSE <item_id>\n
  46 s       200 Dispense OK\n or 402 Poor You\n or 500 Dispense Error\n or 406 Bad Item\n
  47 --- Give to another user ---
  48 c       GIVE <user> <ammount> <reason>\n
  49 s       200 Give OK\n or 402 Poor You\n or 404 Bad User\n
  50 --- Update balance ---
  51 c       ADD <user> <ammount> <reason>\n
  52 s       200 Add OK\n or 403 Not Coke\n or 404 Bad User\n
  53 --- Set Balance ---
  54 c       SET <user> <balance> <reason>\n
  55 s       200 Set OK\n or 403 Not allowed\n or 404 Bad User\n
  56 --- Get Users Balances ---
  57 c       ENUM_USERS[ <max balance>]\n
  58 s       201 Users <count> <username> <username> ...\n
  59 --- Get a User's Balance ---
  60 c       USERINFO\n
  61 s       202 User <username> <balance>\n