X-Git-Url: https://git.ucc.asn.au/?a=blobdiff_plain;f=notes%2Fproto.txt;h=dc11783ad527da8606d96b2006b1cac6ce2bd2b3;hb=f8ff5876b5787375fe629450d0c5d088965720d0;hp=c27ff06ccc98643ba060e4255797bc7380f33dce;hpb=6b194d420f1554ace61a251f2c416712d68ab633;p=tpg%2Fopendispense2.git

diff --git a/notes/proto.txt b/notes/proto.txt
index c27ff06..dc11783 100644
--- a/notes/proto.txt
+++ b/notes/proto.txt
@@ -4,6 +4,19 @@ 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 ===
+<username> is a textual username unless the user does not have a username,
+in which case the username is of the form '#<id>' where <id> is a unique
+account number assigned by the server.
+<card_id_hex> is the hexadecimal byte stream representation of a MIFARE card.
+<item_id> is an item ID of the form '<type>:<id>', where <type> is an
+alpha-numeric diriver identifier, and <id> is an non-negative integer assigned
+by the driver.
+<ammount> 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
@@ -25,8 +38,9 @@ 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 <username>\n
-s	100 SALT <string>\n or 100 User Set\n	(If no salt used)
+s	202 SALT <string>\n or 100 User Set\n	(If no salt used)
 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
@@ -35,6 +49,10 @@ 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 404 Bad Username\n or 401 Untrusted\n
+--- Alternate Method (MIFARE Authentication)
+c	MIFARE <card_id_hex>\n
+s	200 Auth OK as <username>\n or 401 Untrusted\n or 404 Bad Card ID\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
@@ -42,10 +60,13 @@ s	200 User set\n or 403 Not in coke\n or 404 User not found\n
 === Commands ===
 --- 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
+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 <user> <ammount> <reason>\n
 s	200 Give OK\n or 402 Poor You\n or 404 Bad User\n
+--- Donate to the club ---
+c	DONATE <ammount> <reason>\n
+s	200 Give OK\n or 402 Poor You\n
 --- Alter balance ---
 c	ADD <user> <ammount> <reason>\n
 s	200 Add OK\n or 402 No balance\n or 403 Not Coke\n or 404 Bad User\n
@@ -61,12 +82,15 @@ 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
+c	ENUM_USERS[ min:<balance>][ max:<balance>][ flags:<flagset>][ lastseen:<unix_timestamp>][ sort:<field>[-desc]]\n
 s	201 Users <count>\n
 s	202 User <username> <balance> <flags>\n
     ...
 s	200 List End\n
+<balance>	Integer balance value (in cents)
+<flagset>	Flag values (same format as USER_FLAGS)
+<unix_timestamp>	Number of seconds since 1/Jan/1970
+<field>	Sort field (name,balance,lastseen)
 --- Get a User's Balance ---
 c	USER_INFO\n
 s	202 User <username> <balance> <flags>\n
@@ -76,6 +100,9 @@ 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
+ - to remove the flag) Valid values are: user,coke,admin,internal,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
+--- Add MIFARE ID ---
+c	ADD_CARD <card id hex>\n
+s	200 User Updated\n or 405 Card already registered\n