<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<link rel="stylesheet" href="style.css" type="text/css">
<meta content="text/html; charset=iso-8859-1" http-equiv="Content-Type">
<link rel="Start" href="index.html">
<link rel="previous" href="Ocsigen_server.html">
<link rel="next" href="Accesscontrol.html">
<link rel="Up" href="index.html">
<link title="Index of types" rel=Appendix href="index_types.html">
<link title="Index of exceptions" rel=Appendix href="index_exceptions.html">
<link title="Index of values" rel=Appendix href="index_values.html">
<link title="Index of class methods" rel=Appendix href="index_methods.html">
<link title="Index of classes" rel=Appendix href="index_classes.html">
<link title="Index of modules" rel=Appendix href="index_modules.html">
<link title="Index of module types" rel=Appendix href="index_module_types.html">
<link title="Ocsigen_cache" rel="Chapter" href="Ocsigen_cache.html">
<link title="Ocsigen_lib_base" rel="Chapter" href="Ocsigen_lib_base.html">
<link title="Ocsigen_lib" rel="Chapter" href="Ocsigen_lib.html">
<link title="Ocsigen_config" rel="Chapter" href="Ocsigen_config.html">
<link title="Ocsigen_getcommandline" rel="Chapter" href="Ocsigen_getcommandline.html">
<link title="Ocsigen_messages" rel="Chapter" href="Ocsigen_messages.html">
<link title="Ocsigen_stream" rel="Chapter" href="Ocsigen_stream.html">
<link title="Ocsigen_loader" rel="Chapter" href="Ocsigen_loader.html">
<link title="Polytables" rel="Chapter" href="Polytables.html">
<link title="Http_headers" rel="Chapter" href="Http_headers.html">
<link title="Ocsigen_http_frame" rel="Chapter" href="Ocsigen_http_frame.html">
<link title="Ocsigen_headers" rel="Chapter" href="Ocsigen_headers.html">
<link title="Framepp" rel="Chapter" href="Framepp.html">
<link title="Ocsigen_http_com" rel="Chapter" href="Ocsigen_http_com.html">
<link title="Ocsigen_charset_mime" rel="Chapter" href="Ocsigen_charset_mime.html">
<link title="Ocsigen_senders" rel="Chapter" href="Ocsigen_senders.html">
<link title="Ocsigen_cookies" rel="Chapter" href="Ocsigen_cookies.html">
<link title="Ocsigen_extensions" rel="Chapter" href="Ocsigen_extensions.html">
<link title="Ocsigen_parseconfig" rel="Chapter" href="Ocsigen_parseconfig.html">
<link title="Ocsigen_http_client" rel="Chapter" href="Ocsigen_http_client.html">
<link title="Ocsigen_local_files" rel="Chapter" href="Ocsigen_local_files.html">
<link title="Ocsigen_server" rel="Chapter" href="Ocsigen_server.html">
<link title="Ocsigen_comet" rel="Chapter" href="Ocsigen_comet.html">
<link title="Accesscontrol" rel="Chapter" href="Accesscontrol.html">
<link title="Authbasic" rel="Chapter" href="Authbasic.html">
<link title="Ocsipersist" rel="Chapter" href="Ocsipersist.html"><title>Ocsigen_comet</title>
</head>
<body>
<div class="navbar"><a class="pre" href="Ocsigen_server.html" title="Ocsigen_server">Previous</a>
<a class="up" href="index.html" title="Index">Up</a>
<a class="post" href="Accesscontrol.html" title="Accesscontrol">Next</a>
</div>
<h1>Module <a href="type_Ocsigen_comet.html">Ocsigen_comet</a></h1>
<pre><span class="keyword">module</span> Ocsigen_comet: <code class="code">sig</code> <a href="Ocsigen_comet.html">..</a> <code class="code">end</code></pre><div class="info module top">
Ocsigen_comet server extension : provides low-level server to client communication
scheme.<br>
</div>
<hr width="100%">
<pre><span class="keyword">module</span> <a href="Ocsigen_comet.Channels.html">Channels</a>: <code class="code">sig</code> <a href="Ocsigen_comet.Channels.html">..</a> <code class="code">end</code></pre>
<pre><span class="keyword">module</span> <a href="Ocsigen_comet.Security.html">Security</a>: <code class="code">sig</code> <a href="Ocsigen_comet.Security.html">..</a> <code class="code">end</code></pre><br>
Usage:
<p>
On the server side :
1) create needed channels
2) transmit their identifiers to clients
3) write when appropriate (using the outcome mechanism if necessary
<p>
On the client :
1) make a XmlHttpRequest (XHR) with a list of channel identifiers.
2) wait for the reply
3) GOTO 1
<p>
Encoding for client-to-server requests:
* The content type header should be set to <code class="code">application/x-ocsigen-comet</code>
(without quotes)
* A POST parameter is required. Its name should be <code class="code">registration</code> and its
content should be a list of channel identifiers separated by <code class="code">\n</code>
(newline) characters.
* Name and content of the said POST parameter should be encoded according to
the <code class="code">escape</code> JavaScript primitive
<p>
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 <code class="code">:</code> (colon) while the list elements are
separated by <code class="code">\n</code> (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 <code class="code">ENDED_CHANNEL</code>.
When receiving such a message, the client should lose hope of ever
connecting to that particular channel ever again.<br>
<br>
Conf-file options:
<p>
One can use the configuration file to tweak Ocsigen_comet settings. The supported
options are:
<p>
* max_virtual_channels:
* default: <code class="code">None</code>
* syntax: "" is for <code class="code">None</code>, "i" is for <code class="code">Some (int_of_string i)</code>
* <code class="code">max_virtual_channels</code> 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 <code class="code">Ocsigen_comet.Channels.t</code> that can be used simultaneously. If
one calls <code class="code">Ocsigen_comet.Channels.create</code> while the number of channels is
already maxed out, the exception
<code class="code">Ocsigen_comet.Channels.Too_many_virtual_channels</code> is raised.<br>
<br>
Commands:
<p>
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).
<p>
* deactivate:
* deactivate is a command that stops all Comet activity. It is equivalent
to a call to <code class="code">Ocsigen_comet.Security.deactivate</code>.
<p>
* 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 <code class="code">Ocsigen_comet.Security.activate</code> would have.
<p>
* set_timeout:
* parameter: f (float)
* optional parameter: s ("KILL")
* set_timeout allows one to dynamically change the value of Comet
connections timeout to <code class="code">f</code>. Previously activated connections are closed
if the second optional parameter is used. If not, connections are
carried out with their old timeout unchanged.<br>
<br>
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.
<p>
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.<br>
</body></html>
