Commit 04078260 authored by JC Brand's avatar JC Brand

Two websocket related changes. updates #204

* Handle case where no websocket url is specified.
* Update the documentation w.r.t. websockets
parent 95f83834
...@@ -5100,10 +5100,12 @@ ...@@ -5100,10 +5100,12 @@
if (!this.bosh_service_url && ! this.websocket_url) { if (!this.bosh_service_url && ! this.websocket_url) {
throw("Error: you must supply a value for the bosh_service_url or websocket_url"); throw("Error: you must supply a value for the bosh_service_url or websocket_url");
} }
if ('WebSocket' in window || 'MozWebSocket' in window) { if (('WebSocket' in window || 'MozWebSocket' in window) && this.websocket_url) {
this.connection = new Strophe.Connection(this.websocket_url); this.connection = new Strophe.Connection(this.websocket_url);
} else { } else if (this.bosh_service_url) {
this.connection = new Strophe.Connection(this.bosh_service_url); this.connection = new Strophe.Connection(this.bosh_service_url);
} else {
throw("Error: this browser does not support websockets and no bosh_service_url specified.");
} }
this.setUpXMLLogging(); this.setUpXMLLogging();
......
...@@ -103,11 +103,20 @@ If true, the user will automatically subscribe back to any contact requests. ...@@ -103,11 +103,20 @@ If true, the user will automatically subscribe back to any contact requests.
bosh_service_url bosh_service_url
---------------- ----------------
Connections to an XMPP server depend on a BOSH connection manager which acts as Default: ``undefined``
a middle man between HTTP and XMPP.
To connect to an XMPP server over HTTP you need a `BOSH <https://en.wikipedia.org/wiki/BOSH>`_
connection manager which acts as a middle man between the HTTP and XMPP
protocols.
The bosh_service_url setting takes the URL of a BOSH connection manager.
Please refer to your XMPP server's documentation on how to enable BOSH.
For more information, read this blog post: `Which BOSH server do you need? <http://metajack.im/2008/09/08/which-bosh-server-do-you-need>`_ For more information, read this blog post: `Which BOSH server do you need? <http://metajack.im/2008/09/08/which-bosh-server-do-you-need>`_
A more modern alternative to BOSH is to use `websockets <https://developer.mozilla.org/en/docs/WebSockets>`_.
Please see the :ref:`websocket-url` configuration setting.
cache_otr_key cache_otr_key
------------- -------------
...@@ -145,6 +154,8 @@ Default: ``e.g. conversejs.org`` ...@@ -145,6 +154,8 @@ Default: ``e.g. conversejs.org``
The placeholder text shown in the domain input on the registration form. The placeholder text shown in the domain input on the registration form.
.. _`keepalive`:
keepalive keepalive
--------- ---------
...@@ -158,6 +169,13 @@ See also: ...@@ -158,6 +169,13 @@ See also:
* :ref:`session-support` * :ref:`session-support`
* `Using prebind in connection with keepalive`_ * `Using prebind in connection with keepalive`_
.. note::
Currently the "keepalive" setting only works with BOSH and not with
websockets. This is because XMPP over websocket does not use the same
session token as with BOSH. A possible solution for this is to implement
`XEP-0198 <http://xmpp.org/extensions/xep-0198.html>`_, specifically
with regards to "stream resumption".
message_carbons message_carbons
--------------- ---------------
...@@ -257,6 +275,8 @@ it in both formats as ``http://yoursite.com/sounds/msg_received.mp3`` and ...@@ -257,6 +275,8 @@ it in both formats as ``http://yoursite.com/sounds/msg_received.mp3`` and
``http://yoursite.com`` should of course be your site's URL. ``http://yoursite.com`` should of course be your site's URL.
.. _`prebind`:
prebind prebind
-------- --------
...@@ -452,6 +472,33 @@ Allows you to show or hide buttons on the chat boxes' toolbars. ...@@ -452,6 +472,33 @@ Allows you to show or hide buttons on the chat boxes' toolbars.
* toggle_participants: * toggle_participants:
Shows a button for toggling (i.e. showing/hiding) the list of participants in a chat room. Shows a button for toggling (i.e. showing/hiding) the list of participants in a chat room.
.. _`websocket-url`:
websocket_url
-------------
Default: ``undefined``
This option is used to specify a
`websocket <https://developer.mozilla.org/en/docs/WebSockets>`_ URI to which
converse.js can connect to.
Websockets provide a more modern and effective two-way communication protocol
between the browser and a server, effectively emulating TCP at the application
layer and therefore overcoming many of the problems with existing long-polling
techniques for bidirectional HTTP (such as `BOSH <https://en.wikipedia.org/wiki/BOSH>`_).
Please refer to your XMPP server's documentation on how to enable websocket
support.
.. note::
Please note that not older browsers do not support websockets. For older
browsers you'll want to specify a BOSH URL. See the :ref:`bosh-service-url`
configuration setting).
.. note::
Converse.js does not yet support "keepalive" with websockets.
xhr_custom_status xhr_custom_status
----------------- -----------------
......
...@@ -120,15 +120,15 @@ Apache ...@@ -120,15 +120,15 @@ Apache
Single Session Support Single Session Support
---------------------- ----------------------
Server-side authentication Server-side authentication (prebind)
========================== ====================================
It's possible to enable single-site login, whereby users already It's possible to enable shared sessions whereby users already
authenticated in your website will also automatically be logged in on the chat server, authenticated in your website will also automatically be logged in on the XMPP server,
This session should also persist across page loads. In other words, we don't This session can be made to persist across page loads. In other words, we want
want the user to have to give their chat credentials every time they reload the a user to automatically be logged in to chat when they log in to the website,
page. and we want their chat session to persist across page loads.
To do this you will require a `BOSH server <http://xmpp.org/about-xmpp/technology-overview/bosh/>`_ To do this you will require a `BOSH server <http://xmpp.org/about-xmpp/technology-overview/bosh/>`_
for converse.js to connect to (see the :ref:`bosh-service-url` under :ref:`configuration-variables`) for converse.js to connect to (see the :ref:`bosh-service-url` under :ref:`configuration-variables`)
...@@ -193,6 +193,12 @@ These values are then passed to converse.js's ``initialize`` method. ...@@ -193,6 +193,12 @@ These values are then passed to converse.js's ``initialize`` method.
Additionally you need to pass in valid **jid**, **sid**, **rid** and Additionally you need to pass in valid **jid**, **sid**, **rid** and
**bosh_service_url** values. **bosh_service_url** values.
The :ref:`prebind` configuration setting can be used together with the
:ref:`keepalive` setting. This means you only have to prebind once for the
first page the user loads and not anymore for subsequent pages.
For more info, please refer to the :ref:`configuration-variables` section.
Example code for server-side prebinding Example code for server-side prebinding
======================================= =======================================
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment