= Comet =

//Available from Ocsigen server version 1.90//

This extension provides an easy way for the server to send messages to the connected clients. It can be used as such or wrapped in a high-level module. Such a wrapping is provided in Eliom. The whole implementation is in the {{{extensions/comet.ml}}} file, the corresponding interface is in the associated mli file.

==User interface==

The user interface for the extension is quite simple. It is divided into two distinct modules, namely {{{Channels}}} and {{{Security}}}. The former allow channel creation and tampering while the latter gives a few functions to interrupt normal execution flow. The interfaces of both modules are pretty straight forward. Documentation is provided for each function in the mli file.

The {{{Channels}}} module important functions are: {{{create}}} for channel creation, {{{write}}} to actually send a message and {{{get_id}}} to get a channel identifier. Detailed description is available in the mli file.

The {{{Security}}} module is accessible from Ocsigen's command pipe. The different commands are{{{deactivate}}}, {{{activate}}} and {{{set_timeout}}}, the meaning of each of them along with their arguments are given in the mli file.

==Specifications and client implementation==

If not used with the Eliom high-level wrap, it is up to the developer to create a compatible client code. This task requires one to know the protocol used by the extension.

It is the client's responsibility to open a connection indicating the channels it want to be registered to. This is acheived by making an Xml Http Request (XHR) with the following characteristics: the content-type header field must read {{{application/x-ocsigen-comet}}}, the {{{registration}}} POST parameter must be included with a list of channel as value. The said list should be made of channel identifiers separated by newline ({{{\n}}}) character and encoded according to the escape Javascript primitive. Following is an example of list for registration:

{{{
randomstringblahblahtotofoocoucoubardfhkqjsdkjdfgqf
nicely%20encoded%20channel%20identifier
foooobaarfoofoo
}}}

When the server receives an XHR with a comet specific content-type it decodes the registration list, and waits for one of them to be written upon. Then it either times out sending an empty answer or answers with a list of values written on channels. The said list is newline separated and contains channel identifier-value tuples. The reserved value {{{"ENDED_CHANNEL"}}} marks channels that no longer exists on the server (their identifier is no longer relevant). An example of answer the server can make to the example client XHR is:

{{{
randomstringblahblahtotofoocoucoubardfhkqjsdkjdfgqf:ENDED_CHANNEL
nicely%20encoded%20channel%20identifier:42%2043%2044
}}}

In this example, the first channel identifier is no longer associated to any channel on the server, the second channel receives the encoded string value {{{"42 43 44"}}} and the third channel hasn't been written upon.