Chapter 2. The Protocol

Table of Contents
Lexical layer
Gramatical layer
Authorization

$Id: proto.docb,v 1.2 2001/03/26 13:49:20 malekith Exp $

Lexical layer

There are several types of packets sent. Each packet means one logical word. So most actual RPCs are expressed by several packets. First byte contains packet type. Possible types:

Example packet, client-server conversation might look like this:

                    # ...
                    client> 
                    	'c' 3 
                    	'k' "goto" 
                    	'i' 10 
                    	'i' 10
                    server> 
                    	'r' 1 
                    	'k' "ok"
                    # ...
                    client>
                    	'v' 3 
                    	'k' "goto" 
                    	'i' 10 
                    	'i' 10
                    # server doesn't reply here
                    # ...
                    server> 
                    	'v' 3 
                    	'k' "mouse_moved" 
                    	'i' -1 
                    	'i' 2
                    # ...
   

Some words about encoding. After first byte designating type, second byte designating packet length follows. E.g. the actual 'k' "goto" message would look like this in C:

     { 'k', 4, 'g', 'o', 't', 'o' }
    
(6 bytes, there is no NUL terminator).

As there can be (rare) packets bigger then 255 bytes, special version of 's' and 'b' packets are provided. If packets starts with uppercase letter then there are 4 bytes describing length. They are in network byte order (big endian). Otherwise meaning is the same as with lowercase letters. Note that using this makes sense only for 's' and 'b' packets, at the moment. Conforming implementation shall not send other uppercase packets.

Numbers encoding: numbers are encoded as 32 bit (4 byte) signed integers in network byte order. So actual packet 'i' -1 has form:

     { 'i', 4, 0xff, 0xff, 0xff, 0xff }
    
and 'i' 1 has form:

     { 'i', 4, 0, 0, 0, 1 }
    

Strings encoding: they are sent as 32 bit wide unsigned integers in network byte order to be interpreted as unicode. So 's' "foo" is:

     { 's', 12, 0, 0, 0, 'f', 0, 0, 0, 'o', 0, 0, 0, 'o' } 
    

Calls lengths are same as regular numbers, 'v' 5 is:

     { 'v', 4, 0, 0, 0, 5 }
    
hipotetical 'r' 16273 is:

     { 'r', 4, 0, 0, 63, 145 }