Documentation cleanups

[tpg/opendispense2.git] / proto.txt

diff --git a/proto.txt b/proto.txt
index e8d235c..18a5416 100644 (file)
--- a/proto.txt
+++ b/proto.txt
@@ -7,7 +7,7 @@ All server responses are on one line and are prefixed by a three digit response
 == Response Codes ==
 100    Information
 200    Command succeeded, no extra information
 == Response Codes ==
 100    Information
 200    Command succeeded, no extra information

-201    Command succeeded, array follows (<length> <items> <items> ...)
+201    Command succeeded, multiple lines follow (<length>)

 202    Command succeeded, per-command format
 400    Unknown Command
 401    Not Authenticated (or Authentication failure)
 202    Command succeeded, per-command format
 400    Unknown Command
 401    Not Authenticated (or Authentication failure)


@@ -15,7 +15,9 @@ All server responses are on one line and are prefixed by a three digit response
 403    User not allowed to perform this action
 404    Bad other username
 406    Bad Item ID
 403    User not allowed to perform this action
 404    Bad other username
 406    Bad Item ID

+407    Invalid arguments

 500    Unknown Dispense Failure
 500    Unknown Dispense Failure

+501    Action Rejected

 
 == Item IDs ==
 <item_id> represents the item ID
 
 == Item IDs ==
 <item_id> represents the item ID


@@ -25,37 +27,58 @@ general they will be limited to the standard alpha-numeric set
 === User Auth ===
 c      USER <username>\n
 s      100 SALT <string>\n or 100 User Set\n   (If no salt used)
 === User Auth ===
 c      USER <username>\n
 s      100 SALT <string>\n or 100 User Set\n   (If no salt used)

-c      PASS <hash>\n   (Hex-Encoded SHA-512 Hash of <username><salt><password>)
+c      PASS <hash>\n   (Hex-Encoded SHA-1 Hash of <username><salt><password>)

 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 <username>\n
 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 <username>\n

-s      200 Auth OK\n or 401 Auth Failure\n or 401 Untrusted\n
+s      200 Auth OK\n or 404 Bad Username\n or 401 Untrusted\n
+--- Set effective user (User in `dispense -u`) ---
+c      SETEUSER <username>\n
+s      200 User set\n or 403 Not in coke\n or 404 User not found\n

 
 === Commands ===
 
 === Commands ===

---- Get Item list ---
-c      ENUM_ITEMS\n
-s      201 Items <count> <item_id> <item_id> ...\n
---- Get Item Information ---
-c      ITEM_INFO <item_id>\n
-s      202 Item <item_id> <price> <description>\n

 --- Dispense an item ---
 c      DISPENSE <item_id>\n
 s      200 Dispense OK\n or 402 Poor You\n or 500 Dispense Error\n or 406 Bad Item\n
 --- Give to another user ---
 c      GIVE <user> <ammount> <reason>\n
 s      200 Give OK\n or 402 Poor You\n or 404 Bad User\n
 --- Dispense an item ---
 c      DISPENSE <item_id>\n
 s      200 Dispense OK\n or 402 Poor You\n or 500 Dispense Error\n or 406 Bad Item\n
 --- Give to another user ---
 c      GIVE <user> <ammount> <reason>\n
 s      200 Give OK\n or 402 Poor You\n or 404 Bad User\n

---- Update balance ---
+--- Alter balance ---

 c      ADD <user> <ammount> <reason>\n
 c      ADD <user> <ammount> <reason>\n

-s      200 Add OK\n or 403 Not Coke\n or 404 Bad User\n
---- Set Balance ---
-c      SET <user> <balance> <reason>\n
-s      200 Set OK\n or 403 Not allowed\n or 404 Bad User\n
---- Get Users Balances ---
-c      ENUM_USERS[ <max balance>]\n
-s      201 Users <count> <username> <username> ...\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 <user> <ammount> <reason>\n
+s      200 Set OK\n or 403 Not Coke\n or 404 Bad User\n
+
+--- Get Item list ---
+c      ENUM_ITEMS\n
+s      201 Items <count>\n
+s      202 Item <item_id> <price> <description>\n
+    ...
+s      200 List End\n
+--- Get Item Information ---
+c      ITEM_INFO <item_id>\n
+s      202 Item <item_id> <price> <description>\n
+
+--- Get Users' Balances ---
+ <max balance> and <min balance> can be '-' to indicate "none"
+c      ENUM_USERS[ <min balance> [<max balance>]]\n
+s      201 Users <count>\n
+s      202 User <username> <balance> <flags>\n
+    ...
+s      200 List End\n

 --- Get a User's Balance ---
 --- Get a User's Balance ---

-c      USERINFO\n
-s      202 User <username> <balance>\n
+c      USER_INFO\n
+s      202 User <username> <balance> <flags>\n
+
+--- Add a new user ---
+c      USER_ADD <username>\n
+s      200 User Added\n or 403 Not Wheel\n or 404 User Exists\n
+--- Set user flags ---
+ <flags> is a comma-separated list of flag values (optionally preceded by
+ - to remove the flag) Valid values are: user,coke,wheel,meta,disabled,door
+c      USER_FLAGS <username> <flags>\n
+s      200 User Updated\n or 403 Not Wheel\n or 404 Bad User\n or 407 Unknown Flags\n