This chapter describes the communication between components of the gateway. The connection between the bearer box and a WAP or SMS box is a TCP stream connection. The bearer box acts as a server and waits for the the WAP and SMS boxes to connect to the bearer box. This way, the bearer box does not have to have a static list of the other boxes. Instead, it starts with an empty list and waits for the others to register themselves. This design makes it trivial to add new WAP and SMS boxes on the fly: you just install a new one and configure it to connect to the appropriate bearer box. If the TCP stream between the bearer box and a WAP or SMS box breaks, the bearer box will notice this and remove that box from its list of clients. This makes for a simple fault tolerance design. Once the crashed box has been removed from the list of clients, packet from phones that were routed to that box will be treated as packets from new clients. This means that the WAP boxes need to be able to handle packets from the middle of a session and treat them as errors (silent, or preferably by responding with error messages to the phone). A box can also go catatonic: it is alive but is not responding to any messages. To detect this, the boxes within the gateway send heartbeat packets. Each box sends a message at regular intervals to the bearer box that says, essentially, I'm alive and well. If the bearer box does not receive such messages, it will assume that the other box in question has crashed, but not enough to make the TCP stream break. It then closes the stream and removes the box from its list of contents. When the other box is well again, it will re-open the connection. The heartbeat message includes the sender's load. The bearer box will use this for load balancing. Load balancing is not yet implemented. For communication between gateway components, we will use the same general message structure and implementation. This will make it easier to get things to work correctly and will make it easier to modify messages by minimizing the need to write tedious, repetitious, monotonous, error-prone code. The way we will do this is, however, a hack that is explained in (see bibliography for details). Messages always begin with a length (integer, see below) and a type field (integer). The other fields are either integers (signed 32 bits, network byte order) or variable length strings (integer giving length, then that many octets). There can be any number of fields, and they can come in any order (except that the type is always first). In main memory, messages are represented by the Msg structure. This structure contains the field type, which gives its type, and a separate struct field for each type of message, named after the type. The fields in the message are fields in the message type specific structure. For example, the heartbeat message contains one field giving the load of the sender, and this would be accessed like this: msg->heartbeat.load The file msg.h defines the following functions for manipulating Msg structures: msg_create Creates an empty Msg structure. The caller should fill in the message type specific fields manually. msg_destroy Destroys a Msg structure, including all fields. msg_pack Creates an Octstr from the fields of a Msg. The Octstr can easily be sent via the TCP stream to the receiving box. msg_unpack Unpacks an Octstr into a Msg. The Octstr can easily be read from a TCP stream. msg.h also declares the Msg type. The names and contents of messages are declared in the file msg-decl.h. This file obeys a special syntax so that the functions in msg.h can be implemented automatically. The code to, say, initialize each field in Msg is not written by hand. Instead, C preprocessor magic is employed to expand the declaration of the message to code that initializes the fields. It is not necessary to understand how the expansion is done to know how to use the functions or define new message types (and the magic isn't explained here). Each message is defined using the MSG command (implemented as a macro): MSG(sms, { OCTSTR(sender); OCTSTR(receiver); INTEGER(has_udh); OCTSTR(text); }) Here, sms is the type of the message. Each type is given a symbolic name that is a valid C identifier. The name is used everywhere in the code to refer to the message type. The fields of the message are declared as the second MSG argument. The second argument must be a C statement that calls OCTSTR and INTEGER for each field (depending on its type, of course) to define its type. C preprocessor magic turns the statements into code that, for example, destroy each field in the message. This implementation idea for messages is from Kenneth Oksanen and the HiBase project at the Helsinki University of Technology. Both the SMS and WAP boxes send heartbeat messages to the bearer box. The heartbeat informs the bearer box that the sender is alive and also its load. The message is simple: Load (integer) The load indicates the number of HTTP requests that the sending box has open at the time of sending the heartbeat message. The bearer box sends SMS messages to the SMS boxes and these reply with new SMS messages. SMS messages consist of the following pieces of information: Sender phone number (string) Receiver phone number (string) Contents of message (string) Phone numbers are normalized, meaning that whatever part of the gateway accepts a phone number from the world outside the gateway, it will make sure it is normalized to a global format. The bearer box will know from a normalized phone number via which SMS center it should be routed. SMS messages can contain so called User Data Headers. Whether they do is indicated in the message type. The bearer box sends WDP messages to the WAP boxes and these reply with new WDP messages. WDP messages consist of the following pieces of information: Source address (string) Source port (integer) Destination address (string) Destination port (integer) The data in the message (string) Addresses can be in any number of different formats (IP numbers, phone numbers, with more to come). The address may need to contain a prefix that specifies the type. The WAP box doesn't need to worry about the address, except for using it to identify the WTP and WSP state machine it needs to use; it just treats it as a black box and puts it in the proper place in the response message.