The SocketServer will start up the first time a Widget that uses it starts (such a Widget should use the SocketServer javascript object embedded in onload.js). When the SocketServer starts, it creates a TCP listener socket on port 15432 on localhost (127.0.0.1).

When an incoming connection is detected on that port, it analyzes the request to see if it is a special request, such as the request to shutdown, or to increment its internal counter of how many Widgets are using it. If it is one of these special requests, the server handles the request very quickly and goes back to listening on the socket.

If the request is not such a special request, the SocketServer forks a *new* process to handle the request, and goes back to listening for new requests. The SocketServer will not spawn more children if it already has MAX_CHILDREN children running -- MAX_CHILDREN is set to 25 in the file processmanagement.h. The newly created process is the Child.

When the Child process interprets the request, it expects it to look like an HTTP GET request. The general format it is expecting is: GET /command/host-header-if-URL/urlencoded-if-URL/serverip-to-contact/port-to-contact/?commanddata

To explain that a bit more fully, I have to tell you that the main thing that has to be true in this GET request is that there is a COMMAND sent between the first and second /. The main processing body in socketserver.c uses this command value to decide which of its internal processing functions to run against the remaining data (everything after the command). Thus, there is more-or-less a one-to-one correspondence of COMMANDS to C functions that implement the data handling and responses for those commands. That's why it's so easy to extend SocketServer.

Once a command has run, e.g. the XML RPC poster for blogger, it generates a response code which will be consumed by the error text handler in the SocketServer javascript object in onload.js. The child terminates after this point, and the parent will waitpid the child to clean up, and things will continue to repeat this lifecycle until the SocketServer is shutdown by the last Widget using it.

That's about it. Beyond this short introduction, there are the other pages to look at. Also, there should be documentation about every existing function already implemented in the SocketServer, and what it does, e.g. the XML RPC poster. I hope sometime to get around to that.