Location: PHPKode > projects > Laffer > modules/server/docs/horeMAG-client-server.html
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
  <meta http-equiv="content-type"
 content="text/html; charset=ISO-8859-1">
  <title>horeMAG</title>
</head>
<body>
<h2>LAFFER client-server protocol v.0.1 (aka horeMAG).</h2>
<h2>---------------------------------------------------------<br>
<span style="color: rgb(0, 0, 102); text-decoration: underline;">Stage
1. Client Login</span></h2>
<h3>0. Allowed commands during this stage<br>
</h3>
VER, CAPS, USER, PASS, GOTO<br>
<br>
<h3>1. Initial version nagotiation (VER command)<br>
</h3>
Client makes connection with the FrontServer(FS). To connect use TCP/IP
connection on SERVER:PORT. After the client is connected it sends: <br>
(<span style="font-weight: bold;">VER</span> protocol_version(float)
client_name(char))<br>
<span style="font-weight: bold;">&gt; VER 0.1 TEST_CLIENT</span><br>
And the FS responds with <br>
<span style="font-weight: bold;">&lt; VER OK<br>
</span>If client capabilities are ok, or<br>
<span style="font-weight: bold;">&lt; VER NOK</span><br>
<span style="color: rgb(204, 0, 0);">&lt;o&gt; close connection</span><br>
If the capabilities are not correct. For now the only valid protocol
version is 0.1<br>
<br>
<h3>1.1 Sending client capabilities (CAPS command)<br>
</h3>
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:<br>
&gt; CAPS ssl pgp<br>
Also the if the client supports compressing/decompressing it can send
to the server<br>
&gt; CAPS gz <br>
For this version of the protocol&nbsp; all capabilities should be send
with only one CAPS command.<br>
The server should respond with<br>
&lt; CAPS OK<br>
or <br>
&lt;CAPS NOK<br>
if there is something wrong with the capabilites send. Users can also
send user-defined capabilities.<br>
Errors from this command should be silently escaped. No need to
terminate the connection. <br>
<br>
<br>
<h3>2. Requesting client authorization (USER and PASS commands)<br>
</h3>
The client sends to FS request for entering into the IM system. It
sends:<br>
<span style="font-weight: bold;">&gt; USER my_user_name</span><br>
The server responds with <br>
<span style="font-weight: bold;">&lt; USER my_user_name MD5
MD5_MESH_STRING</span><br>
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:<br>
<span style="font-weight: bold;">&gt; PASS MD5(my_user_password +
MD5_MESH_STRING)<br>
</span>If the password is not correct the FS returns<span
 style="font-weight: bold;"><br>
&lt; PASS NOK<br>
</span><span style="color: rgb(204, 0, 0);">&lt;o&gt; close connection<br>
</span> else <br>
<h3>4. Redirecting the client to Message Server (GOTO command)<br>
</h3>
If everything is ready and setup then the server redirect the client to
the Message Server with command<br>
<span style="font-weight: bold;">&lt; GOTO MessageServerX:Port&nbsp;
UNIQUE_CREDENTIALS<br>
</span><span style="color: rgb(204, 0, 0);">&lt;o&gt; close connection</span><br>
or sends error message. If there was no error then the client have to
connect to the new MS server with the UNIQUE_CREDENTIALS<br>
<br>
<h2 style="color: rgb(0, 0, 102); text-decoration: underline;">Stage 2.
Login to Message Server</h2>
<h3>1. Showing credentials to MS server (USER command)<br>
</h3>
The client tries to connect to MS server using the adress and port of
the MS server. When the client is connected it send:<br>
&gt; <span style="font-weight: bold;">USER my_user_id MAGIC_COOKIE<br>
</span>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. <br>
On invalid request the MS server sends back:<br>
<span style="font-weight: bold;">&lt; USER my_user_id NOK</span><br>
<span style="color: rgb(204, 0, 0);">&lt;o&gt; close connection<br>
<span style="color: rgb(0, 0, 0);">otherwise the server sends back to
client<br>
<span style="font-weight: bold;">&lt; USER my_user_id OK</span><br>
</span></span>
<h3>2. Getting contact list from MS server (CGL, CLG&nbsp; and CLU
commands)<br>
</h3>
The next thing that the client has to do is to get the contact list.
the command to do this is<br>
<span style="font-weight: bold;">&gt; GCL LOCAL_CONTACT_LIST_ID</span><br>
The server compares LOCAL_CONTACT_LIST_ID with the contact_list stored
in the server and if they don't differ MS sends back<br>
<span style="font-weight: bold;">&lt; GCL LOCAL_CONTACT_LIST_ID OK<br>
</span>else the server sends back<br>
<span style="font-weight: bold;">&lt; GCL NEW_CONTACT_LIST_ID
ITEMS_TO_FOLLOW ENCODING<br>
</span>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.<br>
After this command the MS server sends info about the groups and users.
The GROUP_NAME and USER_NAME are URL encoded. <br>
<span style="font-weight: bold;">&lt; CLG </span><span
 style="font-weight: bold;">GROUP_ID </span><span
 style="font-weight: bold;">GROU_NAME<br>
</span>Example: <span style="font-weight: bold;">&lt; CGL Test+Group
345<br>
</span>And the users are described with this command:<span
 style="font-weight: bold;"><br>
&lt; CLU USER_NAME USER_ID GROUP_ID_1,GROUP_ID_2, ... ,GROUP_ID_X </span><br>
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. <br>
Special groups&nbsp; "-1" - Awaiting Authorization<br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp; 0 - Visible<br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp; 1 InVisible<br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp; 2 Ignore<br>
<br>
<br>
<h3>3. Getting Presence information for the users in the contact List
(STAT command)<br>
</h3>
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:<br>
<span style="font-weight: bold;">&gt; STAT ONL</span><br>
Valid statuses are:ONL(online), OFF(offline),IDL(idle),BSY(busy),
HDN(hidden)<br>
The MS server tries to send this notification to all online users,
subscribed to see this client status.<br>
The MS server asks the FS for the address of
the servers, serving the users in the contact list. <br>
After that the MS server writes down the status in the local tables +
sends to the client<br>
<span style="font-weight: bold;">&lt; STAT user_id_1 ONL</span><br>
<h3>4. Messages (MSG command)</h3>
When the client tries to send instant message it sends something like
this to the MS server<br>
&gt; <span style="font-weight: bold;">MSG TYPE ENCODING TO_USER_ID
LENGTH MESSAGE_CONTENT <br>
</span>Example:<span style="font-weight: bold;"> MSG text utf8
hide@address.com 10 1234567890</span><br>
<br>
If the operation is successful the MS returns<br>
<span style="font-weight: bold;">&lt; MSG OK</span><br>
Otherwise it returns<br>
<span style="font-weight: bold;">&lt; MSG NOK<br>
<br>
</span><span style="font-weight: bold;">TYPE </span>can be text,
alert, invitation etc. <br>
*May be we can add user-defined types also...<br>
<h3>5. Adding new user to contact list (ADDU, REQ_AUTH, GRANT_AUTH,
REJ_AUTH and AUTH_OK commands)<br>
</h3>
If the client wants to add user X to his contact list he sends to the
server<br>
&gt; ADDU X_ID GROUP_ID<br>
And the information is written down to the clients server contact list.<br>
The server send this request for authorization to the user with X_ID<br>
&lt; REQ_AUTH client_id<br>
And the client with X_ID can choose to grant authorization<br>
&gt; GRANT_AUTH client_id<br>
or to reject authorization <br>
&gt; REJ_AUTH client_id<br>
<br>
If the authorization is granted then the client with ID client_id
receives from server<br>
&gt;&nbsp; AUTH_OK X_ID<br>
Otherwise it receives from the server<br>
&gt; REJ_AUTH X_ID<br>
<h3>6. Adding new group to contact list (ADDG command)<br>
</h3>
When the client adds new group to his contact list, he sends to the
server <br>
&gt; ADDG GROUP_NAME<br>
And the server responds with<br>
&lt; ADDG GROUP_NAME NEW_GROUP_ID<br>
if everything is correct<br>
or with error message<br>
(-)* there is aleady group with such name<br>
<h3>7. Changing user name (RENU command)<br>
</h3>
&gt; RENU USER_ID NEW_NICK<br>
&lt; RENU USER_ID OK<br>
or error<br>
- no such user_id in your contact list<br>
<h3>8. Changing group name (RENG command)<br>
</h3>
&gt; RENG GROUP_ID NEW_GROUP_NAME<br>
&lt; RENG GROUP_ID OK<br>
or error<br>
- no such group_id in your contact list<br>
<h3>9. Moving user in different group (MVU command)<br>
</h3>
&gt; MVU USER_ID FROM_GROUP_ID TO_GROUP_ID <br>
&lt; MVU USER_ID OK<br>
or error<br>
- no such user_id in your contact list<br>
- no such FROM_GROUP_ID in your contact list<br>
- no such TO_GROUP_ID in your contact list<br>
(-)* invalid TO_GROUP_ID - if the group id is special/reserved - 0,1,2<br>
<h3>10. Deleting user from contact list (DELU command)<br>
</h3>
&gt; DELU USER_ID<br>
1. &lt; DELU USER_ID OK<br>
or error message<br>
- no such user_id in your contact list<br>
- invalid user_id - if the user id is the id of special&nbsp; user -
admin, support etc<br>
<h3>11. Deleting group from contact list (DELG command)<br>
</h3>
DELG GROUP_ID<br>
1. &lt; DELG GROUP_ID OK<br>
or error message<br>
- no such group_id<br>
- invalid group_id - if the group id is the id of special group -
example 0,1,2<br>
<h3>12. Searching for user to
add (SRCH command)<br>
</h3>
&gt; SRCH "URL_QUERY"<br>
ToDo::<br>
<br>
<h3>13. ..</h3>
<h3>16. Disconnecting (QUIT command)<br>
</h3>
if disconnection event occures - either the client sends<br>
<span style="font-weight: bold;">&gt; QUIT</span><br>
or the connection MS - Client is broken<br>
or FS disconnects client with some reason<span
 style="font-weight: bold;"></span><br>
</body>
</html>
Return current item: Laffer