# Module Ocsigen_comet

    module Ocsigen_comet: sig .. end

Ocsigen_comet server extension : provides low-level server to client communication scheme.

    module Channels: sig .. end

    module Security: sig .. end

Usage:

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 client-to-server requests: * The content type header should be set to `application/x-ocsigen-comet` (without quotes) * A POST parameter is required. Its name should be `registration` and its content should be a list of channel identifiers separated by `\n` (newline) characters. * Name and content of the said POST parameter should be encoded according to the `escape` JavaScript primitive

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.
Usage:

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 client-to-server requests: * The content type header should be set to `application/x-ocsigen-comet` (without quotes) * A POST parameter is required. Its name should be `registration` and its content should be a list of channel identifiers separated by `\n` (newline) characters. * Name and content of the said POST parameter should be encoded according to the `escape` JavaScript primitive

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.
Conf-file options:

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.
Commands:

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.
Usage:

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 client-to-server requests: * The content type header should be set to `application/x-ocsigen-comet` (without quotes) * A POST parameter is required. Its name should be `registration` and its content should be a list of channel identifiers separated by `\n` (newline) characters. * Name and content of the said POST parameter should be encoded according to the `escape` JavaScript primitive

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.
Conf-file options:

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.
Commands:

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.

The low level Ocisgen server extension can however be used with classic Javascript clients (whereas the high level Eliom module requires Ocaml compatible unmarshalling which may be difficult to find in a non js_of_ocaml/O'browser based client). It may also be used to add your own high level wrapper with a custom communication protocol.