LAFFER client-server protocol v.0.1 (aka horeMAG).
---------------------------------------------------------
Stage
1. Client Login
0. Allowed commands during this stage
VER, CAPS, USER, PASS, GOTO
1. Initial version nagotiation (VER command)
Client makes connection with the FrontServer(FS). To connect use TCP/IP
connection on SERVER:PORT. After the client is connected it sends:
(VER protocol_version(float)
client_name(char))
> VER 0.1 TEST_CLIENT
And the FS responds with
< VER OK
If client capabilities are ok, or
< VER NOK
<o> close connection
If the capabilities are not correct. For now the only valid protocol
version is 0.1
1.1 Sending client capabilities (CAPS command)
If the client program supports SSL, PGP or some other form of
encryption it should say this in the beginning. The command used for
this is:
> CAPS ssl pgp
Also the if the client supports compressing/decompressing it can send
to the server
> CAPS gz
For this version of the protocol all capabilities should be send
with only one CAPS command.
The server should respond with
< CAPS OK
or
<CAPS NOK
if there is something wrong with the capabilites send. Users can also
send user-defined capabilities.
Errors from this command should be silently escaped. No need to
terminate the connection.
2. Requesting client authorization (USER and PASS commands)
The client sends to FS request for entering into the IM system. It
sends:
> USER my_user_name
The server responds with
< USER my_user_name MD5
MD5_MESH_STRING
The client have to send his/her password, encrypted using the MD5
algorithm, for checking. The encrypted password = MD5(my_user_password
+
MD5_MESH_STRING). The client have to return something like this:
> PASS MD5(my_user_password +
MD5_MESH_STRING)
If the password is not correct the FS returns
< PASS NOK
<o> close connection
else
4. Redirecting the client to Message Server (GOTO command)
If everything is ready and setup then the server redirect the client to
the Message Server with command
< GOTO MessageServerX:Port
UNIQUE_CREDENTIALS
<o> close connection
or sends error message. If there was no error then the client have to
connect to the new MS server with the UNIQUE_CREDENTIALS
Stage 2.
Login to Message Server
1. Showing credentials to MS server (USER command)
The client tries to connect to MS server using the adress and port of
the MS server. When the client is connected it send:
> USER my_user_id MAGIC_COOKIE
The MS server checks if there is valid(if the client tried to
connect within 60 secs after the client credentials were saved)
MAGIC_COOKIE record for my_user_id in its database.
On invalid request the MS server sends back:
< USER my_user_id NOK
<o> close connection
otherwise the server sends back to
client
< USER my_user_id OK
2. Getting contact list from MS server (CGL, CLG and CLU
commands)
The next thing that the client has to do is to get the contact list.
the command to do this is
> GCL LOCAL_CONTACT_LIST_ID
The server compares LOCAL_CONTACT_LIST_ID with the contact_list stored
in the server and if they don't differ MS sends back
< GCL LOCAL_CONTACT_LIST_ID OK
else the server sends back
< GCL NEW_CONTACT_LIST_ID
ITEMS_TO_FOLLOW ENCODING
The encoding is the charset in which the items in the contact
list are writen. ITEMS_TO_FOLLOW is the total number of users + groups.
After this command the MS server sends info about the groups and users.
The GROUP_NAME and USER_NAME are URL encoded.
< CLG GROUP_ID GROU_NAME
Example: < CGL Test+Group
345
And the users are described with this command:
< CLU USER_NAME USER_ID GROUP_ID_1,GROUP_ID_2, ... ,GROUP_ID_X
The list of groups in which the user is included are separated by ",".
If you want to say/express that user is in your invisible list add to
the list ot groups the ID of special group 1.
Special groups "-1" - Awaiting Authorization
0 - Visible
1 InVisible
2 Ignore
3. Getting Presence information for the users in the contact List
(STAT command)
When the client receives all items in his/her contact list he/she has
to become ONLINE. This is done by sending this command to the MS server:
> STAT ONL
Valid statuses are:ONL(online), OFF(offline),IDL(idle),BSY(busy),
HDN(hidden)
The MS server tries to send this notification to all online users,
subscribed to see this client status.
The MS server asks the FS for the address of
the servers, serving the users in the contact list.
After that the MS server writes down the status in the local tables +
sends to the client
< STAT user_id_1 ONL
4. Messages (MSG command)
When the client tries to send instant message it sends something like
this to the MS server
> MSG TYPE ENCODING TO_USER_ID
LENGTH MESSAGE_CONTENT
Example: MSG text utf8
galfy@bgdate 10 1234567890
If the operation is successful the MS returns
< MSG OK
Otherwise it returns
< MSG NOK
TYPE can be text,
alert, invitation etc.
*May be we can add user-defined types also...
5. Adding new user to contact list (ADDU, REQ_AUTH, GRANT_AUTH,
REJ_AUTH and AUTH_OK commands)
If the client wants to add user X to his contact list he sends to the
server
> ADDU X_ID GROUP_ID
And the information is written down to the clients server contact list.
The server send this request for authorization to the user with X_ID
< REQ_AUTH client_id
And the client with X_ID can choose to grant authorization
> GRANT_AUTH client_id
or to reject authorization
> REJ_AUTH client_id
If the authorization is granted then the client with ID client_id
receives from server
> AUTH_OK X_ID
Otherwise it receives from the server
> REJ_AUTH X_ID
6. Adding new group to contact list (ADDG command)
When the client adds new group to his contact list, he sends to the
server
> ADDG GROUP_NAME
And the server responds with
< ADDG GROUP_NAME NEW_GROUP_ID
if everything is correct
or with error message
(-)* there is aleady group with such name
7. Changing user name (RENU command)
> RENU USER_ID NEW_NICK
< RENU USER_ID OK
or error
- no such user_id in your contact list
8. Changing group name (RENG command)
> RENG GROUP_ID NEW_GROUP_NAME
< RENG GROUP_ID OK
or error
- no such group_id in your contact list
9. Moving user in different group (MVU command)
> MVU USER_ID FROM_GROUP_ID TO_GROUP_ID
< MVU USER_ID OK
or error
- no such user_id in your contact list
- no such FROM_GROUP_ID in your contact list
- no such TO_GROUP_ID in your contact list
(-)* invalid TO_GROUP_ID - if the group id is special/reserved - 0,1,2
10. Deleting user from contact list (DELU command)
> DELU USER_ID
1. < DELU USER_ID OK
or error message
- no such user_id in your contact list
- invalid user_id - if the user id is the id of special user -
admin, support etc
11. Deleting group from contact list (DELG command)
DELG GROUP_ID
1. < DELG GROUP_ID OK
or error message
- no such group_id
- invalid group_id - if the group id is the id of special group -
example 0,1,2
12. Searching for user to
add (SRCH command)
> SRCH "URL_QUERY"
ToDo::
13. ..
16. Disconnecting (QUIT command)
if disconnection event occures - either the client sends
> QUIT
or the connection MS - Client is broken
or FS disconnects client with some reason