diff --git a/converse.js b/converse.js index 3a85cf28c..4416557e3 100644 --- a/converse.js +++ b/converse.js @@ -138,6 +138,7 @@ this.bosh_service_url = undefined; // The BOSH connection manager URL. this.cache_otr_key = false; this.debug = false; + this.expose_rid_and_sid = false; this.hide_muc_server = false; this.i18n = locales.en; this.prebind = false; @@ -165,6 +166,7 @@ 'cache_otr_key', 'connection', 'debug', + 'expose_rid_and_sid', 'fullname', 'hide_muc_server', 'i18n', @@ -3586,11 +3588,17 @@ converse.initialize(settings, callback); }, 'getRID': function () { - if (typeof converse.connection !== "undefined") { + if (converse.expose_rid_and_sid && typeof converse.connection !== "undefined") { return converse.connection.rid; } return null; }, + 'getSID': function () { + if (converse.expose_rid_and_sid && typeof converse.connection !== "undefined") { + return converse.connection.sid; + } + return null; + }, 'once': function(evt, handler) { converse.once(evt, handler); }, diff --git a/docs/CHANGES.rst b/docs/CHANGES.rst index 24b9103f9..2b59d3631 100644 --- a/docs/CHANGES.rst +++ b/docs/CHANGES.rst @@ -4,7 +4,8 @@ Changelog Unreleased ---------- -* Option to display a call button in the chatbox toolbar, to allow third-party libraries to provide a calling feature. [Aupajo] +* #93 Add API methods exposing the RID and SID values. Can be disabled. [jcbrand] +* #103 Option to display a call button in the chatbox toolbar, to allow third-party libraries to provide a calling feature. [Aupajo] * #108 Japanese Translations [mako09] * #111 OTR not working when using converse.js with prebinding. [jseidl, jcbrand] * #114 Hewbrew Translations [GreenLunar] diff --git a/docs/doctrees/index.doctree b/docs/doctrees/index.doctree index 3410f4be7..9b34c9735 100644 Binary files a/docs/doctrees/index.doctree and b/docs/doctrees/index.doctree differ diff --git a/docs/html/_sources/index.txt b/docs/html/_sources/index.txt index 58706f3dc..0682ab5a6 100644 --- a/docs/html/_sources/index.txt +++ b/docs/html/_sources/index.txt @@ -306,7 +306,6 @@ Facebook integration this myself. Feedback and patches from people who have succesfully done this will be appreciated. - Converse.js uses `Strophe.js `_ to connect and communicate with the XMPP server. One nice thing about Strophe.js is that it can be extended via `plugins `_. @@ -748,6 +747,14 @@ For each room on the server a query is made to fetch further details (e.g. features, number of occupants etc.), so on servers with many rooms this option will create lots of extra connection traffic. +auto_reconnect +-------------- + +Default = ``true`` + +Automatically reconnect to the XMPP server if the connection drops +unexpectedly. + auto_subscribe -------------- @@ -763,6 +770,30 @@ a middle man between HTTP and XMPP. See `here `_ for more information. +cache_otr_key +------------- + +Default = ``false`` + +Let the `OTR (Off-the-record encryption) `_ private +key be cached in your browser's session storage. + +The browser's session storage persists across page loads but is deleted once +the tab or window is closed. + +If this option is set to ``false``, a new OTR private key will be generated +for each page load. While more inconvenient, this is a much more secure option. + +This setting can only be used together with ``allow_otr = true``. + + +.. Note :: + A browser window's session storage is accessible by all javascript that + is served from the same domain. So if there is malicious javascript served by + the same server (or somehow injected via an attacker), then they will be able + to retrieve your private key and read your all the chat messages in your + current session. Previous sessions however cannot be decrypted. + debug ----- diff --git a/docs/html/index.html b/docs/html/index.html index 9321faef6..cf981d5a1 100644 --- a/docs/html/index.html +++ b/docs/html/index.html @@ -114,30 +114,32 @@
  • allow_muc
  • animate
  • auto_list_rooms
    • -
  • auto_subscribe
    • -
  • bosh_service_url
    • -
  • debug
    • -
  • fullname
    • -
  • hide_muc_server
    • -
  • i18n
    • -
  • prebind
    • -
  • show_controlbox_by_default
    • -
  • show_call_button
    • -
  • show_only_online_users
    • -
  • use_vcards
    • -
  • xhr_custom_status
    • -
  • xhr_custom_status_url
    • -
  • xhr_user_search
    • -
  • xhr_user_search_url
    • +
  • auto_reconnect
    • +
  • auto_subscribe
    • +
  • bosh_service_url
    • +
  • cache_otr_key
    • +
  • debug
    • +
  • fullname
    • +
  • hide_muc_server
    • +
  • i18n
    • +
  • prebind
    • +
  • show_controlbox_by_default
    • +
  • show_call_button
    • +
  • show_only_online_users
    • +
  • use_vcards
    • +
  • xhr_custom_status
    • +
  • xhr_custom_status_url
    • +
  • xhr_user_search
    • +
  • xhr_user_search_url
    • -
  • Minification
    @@ -182,7 +184,7 @@ practical.

    You’ll most likely want to implement some kind of single-signon solution for your website, where users authenticate once in your website and then stay logged into their XMPP session upon page reload.

    -

    For more info on this, read: `Pre-binding and Single Session Support`_.

    +

    For more info on this, read: `Pre-binding and Single Session Support`_.

    You might also want to have more fine-grained control of what gets included in the minified Javascript file. Read Configuration and Minification for more info on how to do that.

    @@ -729,41 +731,66 @@ multi-user chat, then a list of rooms on that server will be fetched.

    features, number of occupants etc.), so on servers with many rooms this option will create lots of extra connection traffic.

    +
    +

    auto_reconnect

    +

    Default = true

    +

    Automatically reconnect to the XMPP server if the connection drops +unexpectedly.

    +
    -

    auto_subscribe

    +

    auto_subscribe

    Default = false

    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 a middle man between HTTP and XMPP.

    See here for more information.

    +
    +

    cache_otr_key

    +

    Default = false

    +

    Let the OTR (Off-the-record encryption) private +key be cached in your browser’s session storage.

    +

    The browser’s session storage persists across page loads but is deleted once +the tab or window is closed.

    +

    If this option is set to false, a new OTR private key will be generated +for each page load. While more inconvenient, this is a much more secure option.

    +

    This setting can only be used together with allow_otr = true.

    +
    +

    Note

    +

    A browser window’s session storage is accessible by all javascript that +is served from the same domain. So if there is malicious javascript served by +the same server (or somehow injected via an attacker), then they will be able +to retrieve your private key and read your all the chat messages in your +current session. Previous sessions however cannot be decrypted.

    +
    +
    -

    debug

    +

    debug

    Default = false

    If set to true, debugging output will be logged to the browser console.

    -

    fullname

    +

    fullname

    If you are using prebinding, can specify the fullname of the currently logged in user, otherwise the user’s vCard will be fetched.

    -

    hide_muc_server

    +

    hide_muc_server

    Default = false

    Hide the server input field of the form inside the Room panel of the controlbox. Useful if you want to restrict users to a specific XMPP server of your choosing.

    -

    i18n

    +

    i18n

    Specify the locale/language. The language must be in the locales object. Refer to ./locale/locales.js to see which locales are supported.

    -

    prebind

    +

    prebind

    Default = false

    Use this option when you want to attach to an existing XMPP connection that was already authenticated (usually on the backend before page load).

    @@ -776,7 +803,7 @@ values as jid, Additionally, you have to specify bosh_service_url.

    -

    show_controlbox_by_default

    +

    show_controlbox_by_default

    Default = false

    The “controlbox” refers to the special chatbox containing your contacts roster, status widget, chatrooms and other controls.

    @@ -786,7 +813,7 @@ the page with class toggle-online-users.

    page load.

    -

    show_call_button

    +

    show_call_button

    Default = false

    Enable to display a call button on the chatbox toolbar.

    When the call button is pressed, it will emit an event that can be used by a third-party library to initiate a call.

    @@ -800,20 +827,20 @@ page load.

    -

    show_only_online_users

    +

    show_only_online_users

    Default = false

    If set to true, only online users will be shown in the contacts roster. Users with any other status (e.g. away, busy etc.) will not be shown.

    -

    use_vcards

    +

    use_vcards

    Default = true

    Determines whether the XMPP server will be queried for roster contacts’ VCards or not. VCards contain extra personal information such as your fullname and avatar image.

    -

    xhr_custom_status

    +

    xhr_custom_status

    Default = false

    Note

    @@ -823,7 +850,7 @@ avatar image.

    remote server.

    -

    xhr_custom_status_url

    +

    xhr_custom_status_url

    Note

    XHR stands for XMLHTTPRequest, and is meant here in the AJAX sense (Asynchronous Javascript and XML).

    @@ -835,7 +862,7 @@ message will be made.

    The message itself is sent in the request under the key msg.