v1.0 commands - `\n' terminated v1.1 commands - `0x03' terminated Messages to the server: User level commands: (case is vital) STAT list users online returns MESG Send a message to a user. Only works with users who are online. uid 0 represents all users, exlicits a *CAST output. INFO Query the status of a user. Returns: QUIT Disconnect from the server User preferences commands: NICK Change your nickname. MAIL Change your email address. PASS Change your password. DISP Change your disposition. Currently, only `AWAY' and `ONLINE' are supported. Administrative commands: (only accessable by ADMIN users) AUTH KICK Kick a user off the system AUTH GROUP Set a users group. group: 0 = ADMIN, 1 = USER AUTH PASS Set a user's password. AUTH ADD Create a new user. group: 0 = ADMIN, 1 = USER AUTH DELE Permanently remove a user. AUTH FLUSH Flush the user database to disk. AUTH LOAD Reload the user database from disk. Messages to the client: The first character of a message indicates its type: `+': Ack response to a command. `-': Nak response to a command. `*': Unsolicited message. Exception: During the login challenge phase, the output is "USER> " and "PASS> ". Solicited messages: Login phase: USER> This is the user challenge presented upon connection. Note that there is a space (0x20) following the `>', and no . An will be transmitted after a client message is received. PASS> This is the pasword challenge, transmitted after a known user id is given. Note that there is a space (0x20) following the `>', and no . An will be transmitted after a client message is received. Errors: -ERR Invalid User That uid is unknown -ERR Invalid Password -ERR Invalid Login Returned if you are already logged in and the server is not set to boot duplicate logins. User phase: +STAT nick:uid:disp, nick:uid:disp, ..., Note trailing comma. -STAT +MESG -MESG Unknown user. User is offline or unknown. +NICK -NICK Invalid Nickname Nicknames cannot have spaces. +MAIL +PASS Password has been updated. -PASS Invalid Password Old password didn't match. +DISP -DISP Malformed Command Unknown disposition sent. +AUTH -AUTH Not Authorized For Command -AUTH Invalid Group Group must be 0 or 1 Notes: 1) All commands with the wrong aruments return: "- Malformed Command" 2) Unknown commands return: "-ERR Unknown Command" Unsolicited Messages: *MESG FROM <"msg"> Note that the message content is in quotes and may contain `\n' if using the v1.1 protocol. *CAST FROM <"msg"> A user has sent a message to all other users, including themselves *UPDT USER A user has either logged in (or set their disposition to ONLINE), or logged out of the system. *UPDT DISP A user has changed their dispositon. Currently, only `AWAY' is supported. *UPDT NICK A user has changed their nickname. Use the uid to change the proper entry in your internal indices. *MOTD This command is only sent immediately after a sucessful login. There may be several, but they will be sent consecutively without other message between. *UPDT SERV KICK You have been kicked off *UPDT SERV DOWN The server is going down *UPDT SERV DISCONNECT You have been disconnected The above SERV messages are transmitted immediately before the server closes the socket with a client. Notes: 1) You will receive messages regarding the user you are logged in as, i.e. If you change your disposition, then you will recieve a *UPDT message about yourself. Client Implementation Issues: Logging in: 1) Connect to the sever port, which is 5000 by default. There are two phases of client interaction, the login phase and the user phase. In the login phase, a connection is presented with the user and password challenges. After that, any user phase messages can be sent. These challenges must be honored or the connection will be dropped. 2) If connecting progammatically, there is no need to wait for the challenge/response scenario to play itself out. Simply send "uidpass" and check if a "-ERR ..." is returned. Otherwise, the login was successful. 3) Set up an event loop to handle user messages and server responses. Unsolicited server messages: These messages are the only tricky part of this protocol. The best solution seems to have either a thread, other process or equivalent for the platform, to always watch the incoming part of a socket or equivalent with a `select(3)' like statement. This thread would then activate a callback method to deal with the message. Caveats: Unfortunately, the server has no notion of identifiers for the transaction of a message and its result. Therefore, it is best for clients to remove a user from presentation as soon as they go offline. This way, a message to an offline user cannot be sent from the interface. This would not cause a problem except that if several messages are sent to offline or unknown users, then errors presented to the users could be ambiguous about which user in the interface presentation were causing these errors. The server also has no notion of sending a message to multiple users other than to all users. Client implementors should avoid sending messages to all users if possible, as this could be considered rude. The example TCL client has no ability to send a message to all users to avoid this issue completely. Sending messages to several users can be achieved by simply faking it with the client interface. Give the user the chance to pick several users for a message, and send the server a message command for each user selected. The example TCL client does this. The design philosophy for the server is flawed in some places, but the goal was to make a reasonably simple protocol that could be implemented in most languages with out creating complicated packet layouts. It was also designed to minimize the number of commands that the server dealt with, in the hopes that clients could build extra features on top of this protocol. Several additional features have been suggested to be added to the server, such as chat and shared markup. It is unlikely that these would be implemented however, since this server is being abandoned as a project in favor of a new design dubbed `v2.0'.