Create and initialize a Connection object.
The transport-protocol for this connection will be chosen automatically based on the given service parameter. URLs starting with "ws://" or "wss://" will use WebSockets, URLs starting with "http://", "https://" or without a protocol will use BOSH.
To make Strophe connect to the current host you can leave out the protocol and host part and just pass the path:
const conn = new Strophe.Connection("/http-bind/");
The BOSH or WebSocket service URL.
A object containing configuration options
OptionalroleThis connection's role in a shared-worker setup: the 'primary' tab drives the stream, 'secondary' tabs share it. undefined outside worker mode. Assigned by the worker (see Connection#onRoleChanged).
OptionalsmThe XEP-0198 Stream Management engine. Only present when the
enableStreamManagement option is set on a websocket connection.
Under the worker option this is a StreamManagementMirror:
the engine itself lives inside the shared worker and the mirror only
reflects the session state. Typed against the shared
StreamManagementController interface so the two are
interchangeable here.
Private function to add a system level stanza handler.
This function is used to add a Handler for the library code. System stanza handlers are allowed to run before authentication is complete.
The callback function.
The namespace to match.
The stanza name to match.
The stanza type attribute to match.
The stanza id attribute to match.
Private function to add a system level timed handler.
This function is used to add a TimedHandler for the library code. System timed handlers are allowed to run before authentication is complete.
The period of the handler.
The callback function.
Private helper function that makes sure plugins and the user's callback are notified of connection status changes.
the new connection status, one of the values in Strophe.Status
Optionalcondition: string
the error condition
Optionalelem: Element
The triggering stanza.
Private handler for initial connection request.
This handler is used to process the initial connection request response from the BOSH server. It is used to set up authentication handlers and start the authentication process.
SASL authentication will be attempted if available, otherwise the code will fall back to legacy authentication.
The current request.
Optional_callback: ConnectCallback
low level (xmpp) connect callback function. Useful for plugins with their own xmpp connect callback (when they want to do something special).
Optionalraw: string
The stanza as raw string.
Private handler to processes incoming data from the the connection.
Except for _connect_cb handling the initial connection request, this function handles the incoming data for all requests. This function also fires stanza handlers that match each incoming stanza.
The request that has data ready.
Optionalraw: string
The stanza as raw string.
Private function to disconnect.
This is the last piece of the disconnection logic. This resets the connection and alerts the user's connection callback.
Optionalcondition: string
the error condition
Private timeout handler for handling non-graceful disconnection.
If the graceful disconnect process does not complete within the time allotted, this handler finishes the disconnect anyway.
false to remove the handler.
Private handler to process events during idle cycle.
This handler is called every 100ms to fire timed handlers that are ready and keep poll requests going.
Called at the CONNECTED-emission points of the connect flow, just before CONNECTED is emitted i.e. once the full JID is final (resource bound, legacy session established, or legacy auth completed).
Under the worker option the bound JID is always reported to the
shared worker — with or without Stream Management — so it can hand the
right JID to attaching tabs, release joins parked on the handshake,
and (when this stream's features advertised SM) start a fresh SM
session itself (it answers with _smEnabled, which updates the mirror).
Otherwise, if the server supports XEP-0198 and nothing was resumed,
a fresh SM session is started from here. The XEP allows
Private handler for a successful XEP-0198 stream resumption.
The engine reconciles the server's 'h' and re-sends whatever the server didn't acknowledge.
The connection state is restored, this.jid is set back to the JID that
was bound when the SM session was established, before CONNECTED is emitted,
so no stanza can ever be stamped with a resource the server doesn't know.
The
true to keep the handler.
Private handler for a failed
The engine resets its state; after a failed resumption it also
salvages the unacked queue (re-sent once a fresh session reaches
The
true to keep the handler.
Continue the connect flow with resource binding, once it is clear no
XEP-0198 resumption will happen (no SM support, no resumable state, a
failed
Register the XEP-0198 nonza handlers (idempotently) They are system handlers, so they run before authentication completes, which the resume flow requires.
Private handler for SASL authentication failure.
The matching stanza.
false to remove the handler.
Checks whether sessionStorage and JSON are supported and whether we're using BOSH.
Add a stanza handler for the connection.
This function adds a stanza handler to the connection. The handler callback will be called for any stanza that matches the parameters. Note that if multiple parameters are supplied, they must all match for the handler to be invoked.
The handler will receive the stanza that triggered it as its argument. The handler should return true if it is to be invoked again; returning false will remove the handler after it returns.
As a convenience, the ns parameters applies to the top level element and also any of its immediate children. This is primarily to make matching /iq/query elements easy.
With the options argument, you can specify boolean flags that affect how matches are being done.
Currently two flags exist:
matchBareFromJid: When set to true, the from parameter and the from attribute on the stanza will be matched as bare JIDs instead of full JIDs. To use this, pass {matchBareFromJid: true} as the value of options. The default value for matchBareFromJid is false.
ignoreNamespaceFragment: When set to true, a fragment specified on the stanza's namespace URL will be ignored when it's matched with the one configured for the handler.
This means that if you register like this:
connection.addHandler( handler, 'http://jabber.org/protocol/muc', null, null, null, null, {'ignoreNamespaceFragment': true} );
Then a stanza with XML namespace of 'http://jabber.org/protocol/muc#user' will also be matched. If 'ignoreNamespaceFragment' is false, then only stanzas with 'http://jabber.org/protocol/muc' will be matched.
The return value should be saved if you wish to remove the handler
with deleteHandler().
The user callback.
The namespace to match.
The stanza name to match.
The stanza type (or types if an array) to match.
Optionalid: string
The stanza id attribute to match.
Optionalfrom: string
The stanza from attribute to match.
Optionaloptions: HandlerOptions
The handler options
A reference to the handler that can be used to remove it.
Register a handler function for when a protocol (websocker or HTTP) error occurs.
NOTE: Currently only HTTP errors for BOSH requests are handled. Patches that handle websocket errors would be very welcome.
'HTTP' or 'websocket'
Error status code (e.g 500, 400 or 404)
Function that will fire on Http error
Add a timed handler to the connection.
This function adds a timed handler. The provided handler will be called every period milliseconds until it returns false, the connection is terminated, or the handler is removed. Handlers that wish to continue being invoked should return true.
Because of method binding it is necessary to save the result of this function if you wish to remove a handler with deleteTimedHandler().
Note that user handlers are not active until authentication is successful.
The period of the handler.
The callback function.
A reference to the handler that can be used to remove it.
Attach to an already created and authenticated BOSH session.
This function is provided to allow Strophe to attach to BOSH sessions which have been created externally, perhaps by a Web application. This is often used to support auto-login type features without putting user credentials into the page.
The full JID that is bound by the session.
Optionalsid: string
The SID of the BOSH session.
Optionalrid: number
The current RID of the BOSH session. This RID will be used by the next request.
Optionalcallback: ConnectCallback
The connect callback function.
Optionalwait: number
The optional HTTPBIND wait value. This is the time the server will wait before returning an empty result for a request. The default setting of 60 seconds is recommended. Other settings will require tweaks to the Strophe.TIMEOUT value.
Optionalhold: number
The optional HTTPBIND hold value. This is the number of connections the server will hold at one time. This should almost always be set to 1 (the default).
Optionalwind: number
The optional HTTBIND window value. This is the allowed range of request ids that are valid. The default is 5.
Set up authentication
Continues the initial connection request by setting up authentication handlers and starting the authentication process.
SASL authentication will be attempted if available, otherwise the code will fall back to legacy authentication.
Array of SASL mechanisms supported.
Sends an IQ to the XMPP server to bind a JID resource for this session.
https://tools.ietf.org/html/rfc6120#section-7.5
If explicitResourceBinding was set to a truthy value in the options
passed to the Connection constructor, then this function needs
to be called explicitly by the client author.
Otherwise it'll be called automatically as soon as the XMPP server advertises the "urn:ietf:params:xml:ns:xmpp-bind" stream feature.
Starts the connection process.
As the connection process proceeds, the user supplied callback will be triggered multiple times with status updates. The callback should take two arguments - the status code and the error condition.
The status code will be one of the values in the Strophe.Status constants. The error condition will be one of the conditions defined in RFC 3920 or the condition 'strophe-parsererror'.
The Parameters wait, hold and route are optional and only relevant for BOSH connections. Please see XEP 124 for a more detailed explanation of the optional parameters.
The user's JID. This may be a bare JID, or a full JID. If a node is not supplied, SASL OAUTHBEARER or SASL ANONYMOUS authentication will be attempted (OAUTHBEARER will process the provided password value as an access token). (String or Object) pass - The user's password, or an object containing the users SCRAM client and server keys, in a fashion described as follows:
{ name: String, representing the hash used (eg. SHA-1),
salt: String, base64 encoded salt used to derive the client key,
iter: Int, the iteration count used to derive the client key,
ck: String, the base64 encoding of the SCRAM client key
sk: String, the base64 encoding of the SCRAM server key
}
The user password
Optionalcallback: ConnectCallback
The connect callback function.
Optionalwait: number
The optional HTTPBIND wait value. This is the time the server will wait before returning an empty result for a request. The default setting of 60 seconds is recommended.
Optionalhold: number
The optional HTTPBIND hold value. This is the number of connections the server will hold at one time. This should almost always be set to 1 (the default).
Optionalroute: string
The optional route value.
Optionalauthcid: string
The optional alternative authentication identity (username) if intending to impersonate another user. When using the SASL-EXTERNAL authentication mechanism, for example with client certificates, then the authcid value is used to determine whether an authorization JID (authzid) should be sent to the server. The authzid should NOT be sent to the server if the authzid and authcid are the same. So to prevent it from being sent (for example when the JID is already contained in the client certificate), set authcid to that same JID. See XEP-178 for more details.
The optional disconnection timeout in milliseconds before _doDisconnect will be called.
Delete a stanza handler for a connection.
This function removes a stanza handler from the connection. The handRef parameter is not the function passed to addHandler(), but is the reference returned from addHandler().
The handler reference.
Delete a timed handler for a connection.
This function removes a timed handler from the connection. The handRef parameter is not the function passed to addTimedHandler(), but is the reference returned from addTimedHandler().
The handler reference.
Start the graceful disconnection process.
This function starts the disconnection process. This process starts by sending unavailable presence and sending BOSH body of type terminate. A timeout handler makes sure that disconnection happens even if the BOSH server does not respond. If the Connection object isn't connected, at least tries to abort all pending requests so the connection object won't generate successful requests (which were already opened).
The user supplied connection callback will be notified of the progress as this process happens.
Optionalreason: string
The reason the disconnect is occuring.
Immediately send any pending outgoing data.
Normally send() queues outgoing data until the next idle period (100ms), which optimizes network use in the common cases when several send()s are called in succession. flush() can be used to immediately send all pending data.
Generate a unique ID for use in
All
Suffixes are used to make debugging easier when reading the stream data, and their use is recommended. The counter resets to 0 for every new connection for the same reason. For connections to the same server that authenticate the same way, all the ids should be the same, which makes it easy to see changes. This is useful for automated testing as well.
Optionalsuffix: string | number
A optional suffix to append to the id.
A unique string to be used for the id attribute.
true if the current session was established by resuming a previous one via XEP-0198 Stream Management (in which case the previously bound resource is still valid and roster/presence state was retained by the server).
true if a XEP-0198 Stream Management session is currently
active (i.e.
User overrideable function that receives the new valid rid.
The next valid rid
User overrideable function that receives message and presence stanzas
sent by another tab sharing this connection (via the worker
option), so every tab can render what any tab sent.
Deliberately separate from the inbound handler pipeline: these stanzas were sent, not received, so they must not trigger stanza handlers. IQs are not reflected — they are request/response traffic private to the sending tab.
The sent stanza.
User overrideable function that receives the new role of this connection in a shared-worker setup.
Called when the shared worker assigns or changes this tab's role, for example when this tab is promoted to 'primary' after the previous primary tab went away.
The new role ('primary' or 'secondary')
Pause the request manager.
This will prevent Strophe from sending any more requests to the server. This is very useful for temporarily pausing BOSH-Connections while a lot of send() calls are happening quickly. This causes Strophe to send the data in a single request, saving many request trips.
User overrideable function that receives raw data coming into the connection.
The data received by the connection.
User overrideable function that receives raw data sent to the connection.
The data sent by the connection.
Register a single SASL mechanism, to be supported by this client.
Object with a Strophe.SASLMechanism prototype
Register the SASL mechanisms which will be supported by this instance of Connection (i.e. which this XMPP client will support).
Optionalmechanisms: (new (...args: any[]) => default)[]
Array of objects with SASLMechanism prototypes
Reset the connection.
This function should be called after a connection is disconnected before that connection is reused.
Attempt to restore a cached BOSH session.
This function is only useful in conjunction with providing the "keepalive":true option when instantiating a new Connection.
When "keepalive" is set to true, Strophe will cache the BOSH tokens RID (Request ID) and SID (Session ID) and then when this function is called, it will attempt to restore the session from those cached tokens.
This function must therefore be called instead of connect or attach.
For an example on how to use it, please see examples/restore.js
Optionaljid: string
The user's JID. This may be a bare JID or a full JID.
Optionalcallback: ConnectCallback
The connect callback function.
Optionalwait: number
The optional HTTPBIND wait value. This is the time the server will wait before returning an empty result for a request. The default setting of 60 seconds is recommended.
Optionalhold: number
The optional HTTPBIND hold value. This is the number of connections the server will hold at one time. This should almost always be set to 1 (the default).
Optionalwind: number
The optional HTTBIND window value. This is the allowed range of request ids that are valid. The default is 5.
Resume the request manager.
This resumes after pause() has been called.
Helper function to send IQ stanzas.
The stanza to send.
Optionalcallback: (stanza: Element) => void
The callback function for a successful request.
Optionalerrback: (stanza: Element) => void
The callback function for a failed or timed out request. On timeout, the stanza will be null.
Optionaltimeout: number
The time specified in milliseconds for a timeout to occur.
The id used to send the IQ.
Helper function to send presence stanzas. The main benefit is for sending presence stanzas for which you expect a responding presence stanza with the same id (for example when leaving a chat room).
The stanza to send.
Optionalcallback: (stanza: Element) => void
The callback function for a successful request.
Optionalerrback: (stanza: Element) => void
The callback function for a failed or timed out request. On timeout, the stanza will be null.
Optionaltimeout: number
The time specified in milliseconds for a timeout to occur.
The id used to send the presence.
Select protocal based on this.options or this.service
User overrideable function that receives XML data coming into the connection.
Due to limitations of current Browsers' XML-Parsers the opening and closing
BOSH-Connections will have all stanzas wrapped in a
tag. See <Bosh.strip> if you want to strip this tag.The XML data received by the connection.
User overrideable function that receives XML data sent to the connection.
Due to limitations of current Browsers' XML-Parsers the opening and closing
BOSH-Connections will have all stanzas wrapped in a
tag. See <Bosh.strip> if you want to strip this tag.The XMLdata sent by the connection.
StaticaddExtends the Connection object with the given plugin.
The name of the extension.
The plugin's prototype.
StaticaddRegister an optional transport, selectable via the protocol connection
option. Used to plug in environment-specific transports (such as the
Node-only XEP-0114 component transport) without the core browser build
depending on them.
XMPP Connection manager
This class is the main part of Strophe. It manages a BOSH or websocket connection to an XMPP server and dispatches events to the user callbacks as data arrives.
It supports various authentication mechanisms (e.g. SASL PLAIN, SASL SCRAM), and more can be added via registerSASLMechanisms().
After creating a Connection object, the user will typically call connect() with a user supplied callback to handle connection level events like authentication failure, disconnection, or connection complete.
The user will also have several event handlers defined by using addHandler() and addTimedHandler(). These will allow the user code to respond to interesting stanzas or do something periodically with the connection. These handlers will be active once authentication is finished.
To send data to the connection, use send().
Memberof
Strophe