Location: PHPKode > projects > Laffer > modules/server/docs/horeMAG.html
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
  <meta http-equiv="content-type"
 content="text/html; charset=ISO-8859-1">
<table cellpadding="2" cellspacing="2" border="0"
 style="text-align: left; width: 50%;" align="left">
      <td style="vertical-align: top;"><img src="message_server.jpeg"
 title="MS 1" alt="" style="width: 88px; height: 89px;"><br>
Message Server 1<br>
      <td style="vertical-align: top;"><br>
      <td style="vertical-align: top;"><img src="message_server.jpeg"
 title="MS 2" alt="" style="width: 88px; height: 89px;"><br>
Message Server 2<br>
      <td style="vertical-align: top;"><br>
      <td style="vertical-align: top;"><img src="forn_server.jpeg"
 title="" alt="FS" style="width: 83px; height: 98px;"><br>
      <td style="vertical-align: top;"><br>
      <td style="vertical-align: top;"><br>
      <td style="vertical-align: top;">Front Server<br>
      <td style="vertical-align: top;"><br>
      <td style="vertical-align: top;"><br>
      <td style="vertical-align: top;"><img src="client.jpeg" title=""
 alt="CL" style="width: 73px; height: 94px;"><br>
      <td style="vertical-align: top;"><br>
<h2> 1. Client Login</h2>
<h3>0. Allowed commands during this stage<br>
<h3>1. Initial version nagotiation </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)
<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>
<h3>2. Requesting client authorization</h3>
The client sends to FS request for entering into the IM system. It
<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
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 +
</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>3. Deciding which server is most convinient for the client.</h3>
The server gets the Contact List for the user. The contact list
contains users, groups and which user in which group is situated. Every
user in&nbsp; contact list has XBIT which can be -1, 0, 1, 2 - awaiting
authorization, visible, invisible, ignore list. This information is
added as user_in_group information. For example if user X is in groups
120,130,45,0 that means that the user belongs to groups with ids -
120,130,45 and also this user is can see my presence status. <br>
After the contact list, the FS tries to figure out which Message
Server(MS) is most convinient to server the client and the system. <br>
Some criterias for choosing most convinient MS server:<br>
- it is UP, and isn't overloded with people<br>
- most ot the users in the contact list for this client are in MS
server X. Local messages are faster then relayed messages.<br>
- #ToDo:: add additional criterias<br>
The desicion making process should be quite fast.<br>
After the desicion is taken the FS sends to MessageServer (MS) X <br>
<span style="font-weight: bold;"> FS &gt; SRV_ADD_CREDENTIALS
sceenname contact_list_str protocol client_name UNIQUE_CREDENTIALS</span><br>
If the server responds with<br>
<span style="font-weight: bold;">MSX &lt; SRV_ADD_CREDENTIALS
my_user_id OK<br>
</span>then the MSX server writes down the information in the
IM_USER_CREDENTIALS table and the FS writes down the information about
the user in its IM_USER_IN_SERVER table. <br>
<h3>4. Redirecting the client to Message Server</h3>
After that it responds to the client&nbsp; with <span
 style="font-weight: bold;"></span><br>
<span style="font-weight: bold;">&gt; GOTO MessageServerX:Port&nbsp;
</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>
<h2>2. Login to Message Server</h2>
<h3>1. Showing credentials to MS server</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
<span style="font-weight: bold;">&lt; USER my_user_id OK<br>
</span>The MS server send to FS server reply that the my_user_id has
logged in it.<br>
<span style="font-weight: bold;">MS &gt; SRV_USER_STAT my_user_id LOGGED</span><br>
And the front server updates it records and sets the client status to
LOGGED/Before that it was LOGGING/<br>
<span style="font-weight: bold;">FS &lt; SRV_USER_STAT my_user_id OK</span></span></span><br>
<h3>2. Getting contact list from MS server</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
</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
</span>And the users are described with this command:<span
 style="font-weight: bold;"><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>
<span style="font-weight: bold;"></span> <br>
<h3>3. Getting Presence information for the users in the contact List</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),
The MS server tries to send this notification to all online users in
the client contact list. The MS server asks the FS for the address of
the servers, serving the users in the contact list. The MS tries to see
if there is local record for user X server by Y and if there is no such
record it adds USER_ID_X to the list of users. <br>
<span style="font-weight: bold;">MS &gt; SRV_WHEREIS_USER
FS read the information in its database. After that it&nbsp; sends
addresses of the servers for each user in the list. <br>
<span style="font-weight: bold;">FS &gt; SRV_USER_SERVED_BY
USER_ID_1,USER_ID2,...,USER_ID_N server1:port1,server:port,...<br>
</span>If user is not logged it send 0 as corresponding server
MS asks every server for the status of the clients they are serving,
that are online and are in his/her contact list<br>
<span style="font-weight: bold;">MS &gt; SRV_GET_USER_STAT user_id_1</span><br>
MS1 responds with<br>
<span style="font-weight: bold;">MS1 &lt; SRV_SET_USER_STAT user_id ONL</span><br>
And MS writes down the status in the local tables + sends to the client<br>
<span style="font-weight: bold;">&gt; STAT user_id_1 ONL</span><br>
<span style="font-weight: bold;"></span>
<h3>4. Remembering which user by which server is served</h3>
The MS server writes locally information about the users and servers
that serve them. <br>
<h3>5. Send initial&nbsp; presence status</h3>
After that the MS server can determine which user in the contact list
is online. Therefore it resends to every online(not in the invisible,
ignore, or awaiting authorization list) user (to the other
MessageServer (MS2) in fact) this message.<br>
<span style="font-weight: bold;">MS &gt; SRV_USR_MSG user_id_1&nbsp;
STAT&nbsp; my_user_id ONL <br>
</span>The MS2 redirect locally this message to user with id user_id_1<br>
<h3>6. Messages</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
</span>Example:<span style="font-weight: bold;"> MSG text utf8
hide@address.com 10 1234567890<br>
The MS server checks if <span style="font-weight: bold;">TO_USER_ID</span>
is local user for this server <br>
If <span style="font-weight: bold;">TO_USER_ID</span> is local user MS
writes down the message in the <span style="font-weight: bold;">IM_EVENT</span>
else if the <span style="font-weight: bold;">TO_USER_ID </span>has
record in the <span style="font-weight: bold;">USER_LOCATION</span>
table MS server sends to the other MS server:<br>
MS &gt; <span style="font-weight: bold;">SRV_USR_MSG TO_USER_ID </span><span
 style="font-weight: bold;">MSG text utf8 my_user_id 10 1234567890<br>
</span>And the other MS server saves it in its<span
 style="font-weight: bold;"> IM_EVENT</span> table. The thread that is
serving our client gets this message, check if the FROM_USER_ID is not
in ignore list, and send it to the client<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</span><br>
<h3>7. Adding new user to contact list</h3>
<h3>8. Adding new group to contact list</h3>
<h3>9. Changing user name and groups he/she takes part in</h3>
<h3>10. Changing group name</h3>
<h3>11. Moving user in different group</h3>
<h3>12. Deleting user from contact list</h3>
<h3>13. Deleting group from contact list</h3>
<h3><span style="font-weight: bold;"></span>14. Searching for user to
<h3>15. ..</h3>
<h3>16. Disconnecting</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<br>
<span style="font-weight: bold;">FS &gt; SRV_QUIT my_user_is REASON_CODE<br>
</span>1. The MS server deletes his local records with credentials<span
 style="font-weight: bold;"><br>
</span>2. The MS server send to every MS server, that is serving online
users from his/her contact list:<br>
<span style="font-weight: bold;">MS &gt; SRV_USR_MSG user_id_1&nbsp;
STAT&nbsp; my_user_id ONL <br>
</span>3. .. And then&nbsp; MS sends <span style="font-weight: bold;"><br>
</span><span style="font-weight: bold;">MS &gt; SRV_USR_DISCONNECTED
</span>4. And the other MS server deletes his record in the local
USER_LOCATION table <br>
5. And finally MS sends to FS<br>
<span style="font-weight: bold;">MS &gt; SRV_USER_DISCONNECTED
my_user_id</span><span style="font-weight: bold;"></span><span
 style="font-weight: bold;"></span><span style="font-weight: bold;"></span><br>
Return current item: Laffer