module Ocsigen_comet : sig..end
Ocsigen_comet server extension : provides low-level server to client communication scheme.
On the server side : 1) create needed channels 2) transmit their identifiers to clients 3) write when appropriate (using the outcome mechanism if necessary
On the client : 1) make a XmlHttpRequest (XHR) with a list of channel identifiers. 2) wait for the reply 3) GOTO 1
Encoding for server-to-client answer: * The server answer is either empty (when no channel was written upon before timeout) or a list of pairs of channel identifiers and message content. The pairs are separated by : (colon) while the list elements are separated by \n (newline) characters. * In the list, channels that no longer exists on the server side are marked as pairs of channel identifier and the special string ENDED_CHANNEL. When receiving such a message, the client should lose hope of ever connecting to that particular channel ever again.
One can use the configuration file to tweak Ocsigen_comet settings. The supported options are:
* max_virtual_channels: * default: None * syntax: "" is for None, "i" is for Some (int_of_string i) * max_virtual_channels is an upper limit to the number of active channels. It does not limit the number of connections but the number of values of type Ocsigen_comet.Channels.t that can be used simultaneously. If one calls Ocsigen_comet.Channels.create while the number of channels is already maxed out, the exception Ocsigen_comet.Channels.Too_many_virtual_channels is raised.
Comet provides commands (to be piped into Ocsigen's command pipe). The complete list of commands is described here. Don't forget to use the Comet prefix: each command is to be prefixed by "comet:" (without quotes).
* deactivate: * deactivate is a command that stops all Comet activity. It is equivalent to a call to Ocsigen_comet.Security.deactivate.
* activate: * activate is the dual command to deactivate. It resumes Comet activity (or do nothing is Comet is already activated) with exactly the same effect as a call to Ocsigen_comet.Security.activate would have.
* set_timeout: * parameter: f (float) * optional parameter: s ("KILL") * set_timeout allows one to dynamically change the value of Comet connections timeout to f. Previously activated connections are closed if the second optional parameter is used. If not, connections are carried out with their old timeout unchanged.
Note to Eliom users: Although it is possible to use Ocsigen_comet as an extension to the Ocsigen Server, it is recommended to use the higher level Eliom modules, namely Eliom_comet (for server side) and Eliom_client_comet (for client side). The former provides typed channels (with automatic marshaling) and channel wrapping, the later automates decoding and demarshaling and manages channel registration and deregistration.