module Ocsigen_comet:sig
..end
module Channels:sig
..end
module Security:sig
..end
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.