strophe.js

A JavaScript library for XMPP BOSH.

This is the JavaScript version of the Strophe library. Since JavaScript has no facilities for persistent TCP connections, this library uses Bidirectional-streams Over Synchronous HTTP (BOSH) to emulate a persistent, stateful, two-way connection to an XMPP server. More information on BOSH can be found in XEP 124.

Summary

strophe.js	A JavaScript library for XMPP BOSH.
Functions
$build	Create a Strophe.Builder.
$msg	Create a Strophe.Builder with a <message/> element as the root.
$iq	Create a Strophe.Builder with an <iq/> element as the root.
$pres	Create a Strophe.Builder with a <presence/> element as the root.
Strophe	An object container for all Strophe library functions.
Constants
VERSION	The version of the Strophe library.
XMPP Namespace Constants	Common namespace constants from the XMPP RFCs and XEPs.
Functions
addNamespace	This function is used to extend the current namespaces in Strophe.NS.
Constants
Connection Status Constants	Connection status constants for use by the connection handler callback.
Log Level Constants	Logging level indicators.
Functions
forEachChild	Map a function over some or all child elements of a given element.
isTagEqual	Compare an element’s tag name with a string.
xmlElement	Create an XML DOM element.
xmlescape	Excapes invalid xml characters.
xmlTextNode	Creates an XML DOM text node.
getText	Get the concatenation of all text children of an element.
copyElement	Copy an XML DOM element.
escapeNode	Escape the node part (also called local part) of a JID.
unescapeNode	Unescape a node part (also called local part) of a JID.
getNodeFromJid	Get the node portion of a JID String.
getDomainFromJid	Get the domain portion of a JID String.
getResourceFromJid	Get the resource portion of a JID String.
getBareJidFromJid	Get the bare JID from a JID String.
log	User overrideable logging function.
debug	Log a message at the Strophe.LogLevel.DEBUG level.
info	Log a message at the Strophe.LogLevel.INFO level.
warn	Log a message at the Strophe.LogLevel.WARN level.
error	Log a message at the Strophe.LogLevel.ERROR level.
fatal	Log a message at the Strophe.LogLevel.FATAL level.
serialize	Render a DOM element and all descendants to a String.
addConnectionPlugin	Extends the Strophe.Connection object with the given plugin.
Strophe.Builder	XML DOM builder.
Functions
Strophe.Builder	Create a Strophe.Builder object.
tree	Return the DOM tree.
toString	Serialize the DOM tree to a String.
up	Make the current parent element the new current element.
attrs	Add or modify attributes of the current element.
c	Add a child to the current element and make it the new current element.
cnode	Add a child to the current element and make it the new current element.
t	Add a child text element.
Strophe.Connection	XMPP Connection manager.
Functions
Strophe.Connection	Create and initialize a Strophe.Connection object.
reset	Reset the connection.
pause	Pause the request manager.
resume	Resume the request manager.
getUniqueId	Generate a unique ID for use in <iq/> elements.
connect	Starts the connection process.
attach	Attach to an already created and authenticated BOSH session.
xmlInput	User overrideable function that receives XML data coming into the connection.
xmlOutput	User overrideable function that receives XML data sent to the connection.
rawInput	User overrideable function that receives raw data coming into the connection.
rawOutput	User overrideable function that receives raw data sent to the connection.
send	Send a stanza.
flush	Immediately send any pending outgoing data.
sendIQ	Helper function to send IQ stanzas.
addTimedHandler	Add a timed handler to the connection.
deleteTimedHandler	Delete a timed handler for a connection.
addHandler	Add a stanza handler for the connection.
deleteHandler	Delete a stanza handler for a connection.
disconnect	Start the graceful disconnection process.

Functions

$build

function $build( name,
attrs )

Create a Strophe.Builder. This is an alias for ‘new Strophe.Builder(name, attrs)’.

Parameters

(String) name	The root element name.
(Object) attrs	The attributes for the root element in object notation.

Returns

A new Strophe.Builder object.

$msg

function $msg( attrs )

Create a Strophe.Builder with a <message/> element as the root.

Parmaeters

(Object) attrs

The <message/> element attributes in object notation.

Returns

A new Strophe.Builder object.

$iq

function $iq( attrs )

Create a Strophe.Builder with an <iq/> element as the root.

Parameters

(Object) attrs

The <iq/> element attributes in object notation.

Returns

A new Strophe.Builder object.

$pres

function $pres( attrs )

Create a Strophe.Builder with a <presence/> element as the root.

Parameters

(Object) attrs

The <presence/> element attributes in object notation.

Returns

A new Strophe.Builder object.

Strophe

An object container for all Strophe library functions.

This class is just a container for all the objects and constants used in the library. It is not meant to be instantiated, but to provide a namespace for library objects, constants, and functions.

Summary

Constants
VERSION	The version of the Strophe library.
XMPP Namespace Constants	Common namespace constants from the XMPP RFCs and XEPs.
Functions
addNamespace	This function is used to extend the current namespaces in Strophe.NS.
Constants
Connection Status Constants	Connection status constants for use by the connection handler callback.
Log Level Constants	Logging level indicators.
Functions
forEachChild	Map a function over some or all child elements of a given element.
isTagEqual	Compare an element’s tag name with a string.
xmlElement	Create an XML DOM element.
xmlescape	Excapes invalid xml characters.
xmlTextNode	Creates an XML DOM text node.
getText	Get the concatenation of all text children of an element.
copyElement	Copy an XML DOM element.
escapeNode	Escape the node part (also called local part) of a JID.
unescapeNode	Unescape a node part (also called local part) of a JID.
getNodeFromJid	Get the node portion of a JID String.
getDomainFromJid	Get the domain portion of a JID String.
getResourceFromJid	Get the resource portion of a JID String.
getBareJidFromJid	Get the bare JID from a JID String.
log	User overrideable logging function.
debug	Log a message at the Strophe.LogLevel.DEBUG level.
info	Log a message at the Strophe.LogLevel.INFO level.
warn	Log a message at the Strophe.LogLevel.WARN level.
error	Log a message at the Strophe.LogLevel.ERROR level.
fatal	Log a message at the Strophe.LogLevel.FATAL level.
serialize	Render a DOM element and all descendants to a String.
addConnectionPlugin	Extends the Strophe.Connection object with the given plugin.

Constants

VERSION

The version of the Strophe library. Unreleased builds will have a version of head-HASH where HASH is a partial revision.

XMPP Namespace Constants

Common namespace constants from the XMPP RFCs and XEPs.

NS.HTTPBIND	HTTP BIND namespace from XEP 124.
NS.BOSH	BOSH namespace from XEP 206.
NS.CLIENT	Main XMPP client namespace.
NS.AUTH	Legacy authentication namespace.
NS.ROSTER	Roster operations namespace.
NS.PROFILE	Profile namespace.
NS.DISCO_INFO	Service discovery info namespace from XEP 30.
NS.DISCO_ITEMS	Service discovery items namespace from XEP 30.
NS.MUC	Multi-User Chat namespace from XEP 45.
NS.SASL	XMPP SASL namespace from RFC 3920.
NS.STREAM	XMPP Streams namespace from RFC 3920.
NS.BIND	XMPP Binding namespace from RFC 3920.
NS.SESSION	XMPP Session namespace from RFC 3920.

Functions

addNamespace

addNamespace: function ( name,
value )

This function is used to extend the current namespaces in Strophe.NS. It takes a key and a value with the key being the name of the new namespace, with its actual value. For example: Strophe.addNamespace(‘PUBSUB’, “http://jabber.org/protocol/pubsub”);

Parameters

(String) name	The name under which the namespace will be referenced under Strophe.NS
(String) value	The actual namespace.

Constants

Connection Status Constants

Connection status constants for use by the connection handler callback.

Status.ERROR	An error has occurred
Status.CONNECTING	The connection is currently being made
Status.CONNFAIL	The connection attempt failed
Status.AUTHENTICATING	The connection is authenticating
Status.AUTHFAIL	The authentication attempt failed
Status.CONNECTED	The connection has succeeded
Status.DISCONNECTED	The connection has been terminated
Status.DISCONNECTING	The connection is currently being terminated
Status.ATTACHED	The connection has been attached

Log Level Constants

Logging level indicators.

LogLevel.DEBUG	Debug output
LogLevel.INFO	Informational output
LogLevel.WARN	Warnings
LogLevel.ERROR	Errors
LogLevel.FATAL	Fatal errors

Functions

forEachChild

forEachChild: function ( elem,
elemName,
func )

Map a function over some or all child elements of a given element.

This is a small convenience function for mapping a function over some or all of the children of an element. If elemName is null, all children will be passed to the function, otherwise only children whose tag names match elemName will be passed.

Parameters

(XMLElement) elem	The element to operate on.
(String) elemName	The child element tag name filter.
(Function) func	The function to apply to each child. This function should take a single argument, a DOM element.

isTagEqual

isTagEqual: function ( el,
name )

Compare an element’s tag name with a string.

This function is case insensitive.

Parameters

(XMLElement) el	A DOM element.
(String) name	The element name.

Returns

true if the element’s tag name matches el, and false otherwise.

xmlElement

xmlElement: function ( name )

Create an XML DOM element.

This function creates an XML DOM element correctly across all implementations. Specifically the Microsoft implementation of document.createElement makes DOM elements with 43+ default attributes unless elements are created with the ActiveX object Microsoft.XMLDOM.

Most DOMs force element names to lowercase, so we use the _realname attribute on the created element to store the case sensitive name. This is required to generate proper XML for things like vCard avatars (XEP 153). This attribute is stripped out before being sent over the wire or serialized, but you may notice it during debugging.

Parameters

(String) name	The name for the element.
(Array) attrs	An optional array of key/value pairs to use as element attributes in the following format [[‘key1’, ‘value1’], [‘key2’, ‘value2’]]
(String) text	The text child data for the element.

Returns

A new XML DOM element.

xmlescape

xmlescape: function( text )

Excapes invalid xml characters.

Parameters

(String) text

text to escape.

Returns

Escaped text.

xmlTextNode

xmlTextNode: function ( text )

Creates an XML DOM text node.

Provides a cross implementation version of document.createTextNode.

Parameters

(String) text

The content of the text node.

Returns

A new XML DOM text node.

getText

getText: function ( elem )

Get the concatenation of all text children of an element.

Parameters

(XMLElement) elem

A DOM element.

Returns

A String with the concatenated text of all text element children.

copyElement

copyElement: function ( elem )

log: function ( level,
msg )

User overrideable logging function.

This function is called whenever the Strophe library calls any of the logging functions. The default implementation of this function does nothing. If client code wishes to handle the logging messages, it should override this with

Strophe.log = function (level, msg) {
  (user code here)
};

Please note that data sent and received over the wire is logged via Strophe.Connection.rawInput() and Strophe.Connection.rawOutput().

The different levels and their meanings are

DEBUG	Messages useful for debugging purposes.
INFO	Informational messages. This is mostly information like ‘disconnect was called’ or ‘SASL auth succeeded’.
WARN	Warnings about potential problems. This is mostly used to report transient connection errors like request timeouts.
ERROR	Some error occurred.
FATAL	A non-recoverable fatal error occurred.

Parameters

(Integer) level	The log level of the log message. This will be one of the values in Strophe.LogLevel.
(String) msg	The log message.

debug

debug: function( msg )

Log a message at the Strophe.LogLevel.DEBUG level.

Parameters

(String) msg

The log message.

info

info: function ( msg )

Log a message at the Strophe.LogLevel.INFO level.

Parameters

(String) msg

The log message.

warn

warn: function ( msg )

Log a message at the Strophe.LogLevel.WARN level.

Parameters

(String) msg

The log message.

error

error: function ( msg )

Log a message at the Strophe.LogLevel.ERROR level.

Parameters

(String) msg

The log message.

fatal

fatal: function ( msg )

Log a message at the Strophe.LogLevel.FATAL level.

Parameters

(String) msg

The log message.

serialize

serialize: function ( elem )

Render a DOM element and all descendants to a String.

Parameters

(XMLElement) elem

A DOM element.

Returns

The serialized element tree as a String.

addConnectionPlugin

addConnectionPlugin: function ( name,
ptype )

Extends the Strophe.Connection object with the given plugin.

Paramaters

(String) name	The name of the extension.
(Object) ptype	The plugin’s prototype.

Strophe.Builder

XML DOM builder.

This object provides an interface similar to JQuery but for building DOM element easily and rapidly. All the functions except for toString() and tree() return the object, so calls can be chained. Here’s an example using the $iq() builder helper.

$iq({to: 'you': from: 'me': type: 'get', id: '1'})
    .c('query', {xmlns: 'strophe:example'})
    .c('example')
    .toString()

The above generates this XML fragment

<iq to='you' from='me' type='get' id='1'>
  <query xmlns='strophe:example'>
    <example/>
  </query>
</iq>

The corresponding DOM manipulations to get a similar fragment would be a lot more tedious and probably involve several helper variables.

Since adding children makes new operations operate on the child, up() is provided to traverse up the tree. To add two children, do

builder.c('child1', ...).up().c('child2', ...)

The next operation on the Builder will be relative to the second child.

Summary

Functions
Strophe.Builder	Create a Strophe.Builder object.
tree	Return the DOM tree.
toString	Serialize the DOM tree to a String.
up	Make the current parent element the new current element.
attrs	Add or modify attributes of the current element.
c	Add a child to the current element and make it the new current element.
cnode	Add a child to the current element and make it the new current element.
t	Add a child text element.

Functions

Strophe.Builder

Strophe.Builder = function ( name,
attrs )

Create a Strophe.Builder object.

The attributes should be passed in object notation. For example

var b = new Builder('message', {to: 'you', from: 'me'});

var b = new Builder('messsage', {'xml:lang': 'en'});

Parameters

(String) name	The name of the root element.
(Object) attrs	The attributes for the root element in object notation.

Returns

A new Strophe.Builder.

tree

tree: function ()

Return the DOM tree.

This function returns the current DOM tree as an element object. This is suitable for passing to functions like Strophe.Connection.send().

Returns

The DOM tree as a element object.

toString

toString: function ()

Serialize the DOM tree to a String.

This function returns a string serialization of the current DOM tree. It is often used internally to pass data to a Strophe.Request object.

Returns

The serialized DOM tree in a String.

up

up: function ()

Make the current parent element the new current element.

This function is often used after c() to traverse back up the tree. For example, to add two children to the same element

builder.c('child1', {}).up().c('child2', {});

Returns

The Stophe.Builder object.

attrs

attrs: function ( moreattrs )

Add or modify attributes of the current element.

The attributes should be passed in object notation. This function does not move the current element pointer.

Parameters

(Object) moreattrs

The attributes to add/modify in object notation.

Returns

The Strophe.Builder object.

c

c: function ( name,
attrs )

Add a child to the current element and make it the new current element.

This function moves the current element pointer to the child. If you need to add another child, it is necessary to use up() to go back to the parent in the tree.

Parameters

(String) name	The name of the child.
(Object) attrs	The attributes of the child in object notation.

Returns

The Strophe.Builder object.

cnode

cnode: function ( elem )

Add a child to the current element and make it the new current element.

This function is the same as c() except that instead of using a name and an attributes object to create the child it uses an existing DOM element object.

Parameters

(XMLElement) elem

A DOM element.

Returns

The Strophe.Builder object.

t

t: function ( text )

Add a child text element.

This does not make the child the new current element since there are no children of text elements.

Parameters

(String) text

The text data to append to the current element.

Returns

The Strophe.Builder object.

Strophe.Connection

XMPP Connection manager.

Thie class is the main part of Strophe. It manages a BOSH connection to an XMPP server and dispatches events to the user callbacks as data arrives. It supports SASL PLAIN, SASL DIGEST-MD5, and legacy authentication.

After creating a Strophe.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().

Summary

Functions
Strophe.Connection	Create and initialize a Strophe.Connection object.
reset	Reset the connection.
pause	Pause the request manager.
resume	Resume the request manager.
getUniqueId	Generate a unique ID for use in <iq/> elements.
connect	Starts the connection process.
attach	Attach to an already created and authenticated BOSH session.
xmlInput	User overrideable function that receives XML data coming into the connection.
xmlOutput	User overrideable function that receives XML data sent to the connection.
rawInput	User overrideable function that receives raw data coming into the connection.
rawOutput	User overrideable function that receives raw data sent to the connection.
send	Send a stanza.
flush	Immediately send any pending outgoing data.
sendIQ	Helper function to send IQ stanzas.
addTimedHandler	Add a timed handler to the connection.
deleteTimedHandler	Delete a timed handler for a connection.
addHandler	Add a stanza handler for the connection.
deleteHandler	Delete a stanza handler for a connection.
disconnect	Start the graceful disconnection process.

Functions

Strophe.Connection

Strophe.Connection = function ( service )

Create and initialize a Strophe.Connection object.

Parameters

(String) service

The BOSH service URL.

Returns

A new Strophe.Connection object.

reset

reset: function ()

Reset the connection.

This function should be called after a connection is disconnected before that connection is reused.

pause

pause: function ()

Pause the request manager.

This will prevent Strophe from sending any more requests to the server. This is very useful for temporarily pausing while a lot of send() calls are happening quickly. This causes Strophe to send the data in a single request, saving many request trips.

resume

resume: function ()

Resume the request manager.

This resumes after pause() has been called.

getUniqueId

getUniqueId: function ( suffix )

Generate a unique ID for use in <iq/> elements.

All <iq/> stanzas are required to have unique id attributes. This function makes creating these easy. Each connection instance has a counter which starts from zero, and the value of this counter plus a colon followed by the suffix becomes the unique id. If no suffix is supplied, the counter is used as the unique id.

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.

Parameters

(String) suffix

A optional suffix to append to the id.

Returns

A unique string to be used for the id attribute.

connect

connect: function ( jid,
pass,
callback,
wait,
hold )

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’.

Please see XEP 124 for a more detailed explanation of the optional parameters below.

Parameters

(String) jid	The user’s JID. This may be a bare JID, or a full JID. If a node is not supplied, SASL ANONYMOUS authentication will be attempted.
(String) pass	The user’s password. (Function) callback The connect callback function.
(Integer) wait	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.
(Integer) hold	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).

attach

attach: function ( jid,
sid,
rid,
callback,
wait,
hold,
wind )

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.

Parameters

(String) jid	The full JID that is bound by the session.
(String) sid	The SID of the BOSH session.
(String) rid	The current RID of the BOSH session. This RID will be used by the next request. (Function) callback The connect callback function.
(Integer) wait	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.
(Integer) hold	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).
(Integer) wind	The optional HTTBIND window value. This is the allowed range of request ids that are valid. The default is 5.

xmlInput

xmlInput: function ( elem )

User overrideable function that receives XML data coming into the connection.

The default function does nothing. User code can override this with

Strophe.Connection.xmlInput = function (elem) {
  (user code)
};

Parameters

(XMLElement) elem

The XML data received by the connection.

xmlOutput

xmlOutput: function ( elem )

User overrideable function that receives XML data sent to the connection.

The default function does nothing. User code can override this with

Strophe.Connection.xmlOutput = function (elem) {
  (user code)
};

Parameters

(XMLElement) elem

The XMLdata sent by the connection.

rawInput

rawInput: function ( data )

User overrideable function that receives raw data coming into the connection.

The default function does nothing. User code can override this with

Strophe.Connection.rawInput = function (data) {
  (user code)
};

Parameters

(String) data

The data received by the connection.

rawOutput

rawOutput: function ( data )

User overrideable function that receives raw data sent to the connection.

The default function does nothing. User code can override this with

Strophe.Connection.rawOutput = function (data) {
  (user code)
};

Parameters

(String) data

The data sent by the connection.

send

send: function ( elem )

Send a stanza.

This function is called to push data onto the send queue to go out over the wire. Whenever a request is sent to the BOSH server, all pending data is sent and the queue is flushed.

Parameters

(XMLElement | [XMLElement] | Strophe.Builder) elem - The stanza to send.

flush

flush: function ()

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.

sendIQ

sendIQ: function( elem,
callback,
errback,
timeout )

Helper function to send IQ stanzas.

Parameters

(XMLElement) elem	The stanza to send.
(Function) callback	The callback function for a successful request.
(Function) errback	The callback function for a failed or timed out request. On timeout, the stanza will be null.
(Integer) timeout	The time specified in milliseconds for a timeout to occur.

Returns

The id used to send the IQ.

addTimedHandler

addTimedHandler: function ( period,
handler )

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.

Parameters

(Integer) period	The period of the handler.
(Function) handler	The callback function.

Returns

A reference to the handler that can be used to remove it.

deleteTimedHandler

deleteTimedHandler: function ( handRef )

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().

Parameters

(Strophe.TimedHandler) handRef

The handler reference.

addHandler

addHandler: function ( handler,
ns,
name,
type,
id,
from,
options )

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.

The options argument contains handler matching flags that affect how matches are determined. Currently the only flag is matchBare (a boolean). When matchBare is 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 {matchBare: true} as the value of options. The default value for matchBare is false.

The return value should be saved if you wish to remove the handler with deleteHandler().

Parameters

(Function) handler	The user callback.
(String) ns	The namespace to match.
(String) name	The stanza name to match.
(String) type	The stanza type attribute to match.
(String) id	The stanza id attribute to match.
(String) from	The stanza from attribute to match.
(String) options	The handler options

Returns

A reference to the handler that can be used to remove it.

deleteHandler

deleteHandler: function ( handRef )

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().

Parameters

(Strophe.Handler) handRef

The handler reference.

disconnect

disconnect: function ( reason )

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.

The user supplied connection callback will be notified of the progress as this process happens.

Parameters

(String) reason

The reason the disconnect is occuring.