Class jabberwerx.CapabilitiesController

Extends jabberwerx.Controller.

Controller class for capability functionality. This class is responsible for attaching the capabilities element to all outgoing presence stanzas. It also registers for disco info iq messages and responds with the identity and list of supported capabilities of this client. The feature set for this client can be modified using the add and remove Feature methods, or by modifying the jabberwerx_config option before loading the library. This is referred to as "Outgoing Caps."

Any incoming caps information from a presence packet will be stored in this controller. If the hash referred to in the caps portion of the presence is not known, a disco#info iq will be sent out to the owner of the unknown hash. The caps hash will have a list of associated JIDs and a list of the capabilities associated with the hash. This is referred to as "Incoming Caps."

All methods that are Incoming Caps will not wait for the disco#info request before returning. They return the current information for that particular JID at the time of the method call. It is best to call the Incoming Caps methods in the "entityUpdated" event callback.

Class Summary
Constructor Attributes	Constructor Name and Description
	jabberwerx.CapabilitiesController(client) Creates a new CapabilitiesController with the given client.

Field Summary
Field Attributes	Field Name and Description
	identity This simple object defines the identity to use in disco#info messages.
	node This is the node value sent out as part of the capabilities of this client.

Fields borrowed from class jabberwerx.Controller:: client, name

Method Summary
Method Attributes	Method Name and Description
	addFeature(feature) Add a feature to the feature set.
	addFeatureToJid(jid, feature) Add a feature to the feature set for the given jid.
	containsFeature(feature) Returns true if the feature is in the feature set, or false if not present.
	containsFeatureForJid(jid, feature) Checks to see if the given feature is in the list for the given jid.
	destroy() Destroys this CapabilitiesController.
	generateVerificationString(features) Generate the verification string according to XEP-0115 Section 5.
	getFeatures(jid) Get Features for the given JID.
	getFeatureSet() Get the alphabetically sorted array of features in the feature set This is an Outgoing Caps method.
	getFeaturesForVerificationString(ver) This function returns set of features for the given verification string.
	getIdentities(jid) Get Identities for the given JID.
	getSupportedResources(jid, feature) Fetch all resources of the given jid that support the requested feature.
	getVerificationString(nodeVal) This functions returns verification string based on node value passed.
	getVerificationStringForJid(jid) Helper function used in unit tests which returns verification string for the given jid.
	isSupportedFeature(jid, feature) Checks capablility information of given JID for requested feature.
	removeFeature(feature) Remove feature from the feature set.
	removeFeatureFromJid(jid, feature) Remove feature from the feature set for the given jid.

Methods borrowed from class jabberwerx.Controller:: cleanupEntity, removeEntity, updateEntity
Methods borrowed from class jabberwerx.JWModel:: applyEvent, event, shouldBeSavedWithGraph
Methods borrowed from class jabberwerx.JWBase:: getClassName, graphUnserialized, init, invocation, shouldBeSerializedInline, toString, wasUnserialized, willBeSerialized

Class Detail

jabberwerx.CapabilitiesController(client)

Creates a new CapabilitiesController with the given client.

Parameters:
{jabberwerx.Client} client: The owning client

Throws:
{TypeError}: If {client} is not valid

Field Detail

identity

This simple object defines the identity to use in disco#info messages. It defaults to: <identity category='client' type='pc' name='Cisco AJAX XMPP Library'/> and can be changed using CapabilitiesController.identity.property = value Do not replace this identity property directy. Example: CapabilitiesController.identity = {category: 'cat', name: 'name', type: 'type'}; as this will cause undefined behaviour of this class. Calling identity.toString() returns a string in the format: category/type/xmlLang/name Note: No support for the xml:lang attribute in this release

This is an Outgoing Caps property.

{String} node

This is the node value sent out as part of the capabilities of this client. It defaults to 'http://jabber.cisco.com/caxl'. Most clients will want to change this value. It can be modified directly via jabberwerx.client.controller['capabilities'].node, or through the jabberwerx_config object.

This is an Outgoing Caps property.

Method Detail

{Boolean} addFeature(feature)

Add a feature to the feature set. If the feature already exists within the set then it will not be added again and false will be returned.

This is an Outgoing Caps method.

Parameters:
{String} feature: Feature to add to feature set

Returns:: {Boolean} true if successfully added, false if unsuccessful

{Boolean} addFeatureToJid(jid, feature)

Add a feature to the feature set for the given jid. If the feature already exists within the set then it will not be added again and false will be returned.

This is an Outgoing Caps method.

Parameters:
{String|jabberwerx.JID} jid: The jid for which to add feature
{String} feature: Feature to add to feature set

Throws:
{TypeError}: If feature is not a non empty string.
{jabberwerx.JID.InvalidJIDError}: If {jid} could not be converted into a JID

Returns:: {Boolean} true if successfully added, false if unsuccessful

{Boolean} containsFeature(feature)

Returns true if the feature is in the feature set, or false if not present.

This is an Outgoing Caps method.

Parameters:
{String} feature: for which to check for

Returns:: {Boolean} true if present, otherwise false

{Boolean} containsFeatureForJid(jid, feature)

Checks to see if the given feature is in the list for the given jid.

This is an Outgoing Caps method.

Parameters:
{String|jabberwerx.JID} jid: The jid for which to lookup a feature
{String} feature: Feature to look up

Throws:
{TypeError}: If feature is not a non empty string.
{jabberwerx.JID.InvalidJIDError}: If {jid} could not be converted into a JID

Returns:: {Boolean} true if found, false otherwise

destroy()

Destroys this CapabilitiesController. This method unbinds all registered callbacks.

{String} generateVerificationString(features)

Generate the verification string according to XEP-0115 Section 5. Uses the SHA-1 algorithm. Uses the feature set and identity to determine the verification string.

This is an Outgoing Caps method.

Parameters:
{Array} features Optional: Array of features

Returns:: {String} the verification string

{Array} getFeatures(jid)

Get Features for the given JID. Returns an array of feature Strings for the given JID. A bare JID will return a union of features for all resources while a full JID will return only features that match exactly.

This is an Incomming Caps method.

Parameters:
{jabberwerx.JID|String} jid: the bare or full JID to query

Throws:
{TypeError}: if jid is not a valid jabberwerx.JID

Returns:: {Array} unique feature strings, may be empty if no matches or features were found.

See:: http://xmpp.org/extensions/xep-0030.html for complete discussion of entity features.

{String[]} getFeatureSet()

Get the alphabetically sorted array of features in the feature set

This is an Outgoing Caps method.

Returns:: {String[]} Alphabetically sorted set of features

{String[]} getFeaturesForVerificationString(ver)

This function returns set of features for the given verification string.

This is an Outgoing Caps method.

Parameters:
{String} ver: Verification string for which to return the set of features for.

Throws:
{TypeError}: if ver is not a non empty String.

Returns:: {String[]} Alphabetically sorted set of features

{Array} getIdentities(jid)

Get Identities for the given JID. Returns an array of Identity objects for the given JID. A bare JID will return a union of entity identities for all resources while a full JID will return only identities that match exactly.

The returned identity object is defined

 {
     category {String}   The identity category.
     type     {String}   The category's type
     name     {String}   The human readable name for this identity
     xmlLang  {String}   The language code for the name property.
 }

All properties will exist but their value may be an empty String.

This is an Incomming Caps method.

Parameters:
{jabberwerx.JID|String} jid: the bare or full JID to query

Throws:
{TypeError}: if jid is not a valid jabberwerx.JID

Returns:: {Array} Identity array, may be empty if no matches were found.

See:: http://xmpp.org/extensions/xep-0030.html for complete discussion of entity identities.; http://xmpp.org/registrar/disco-categories.html for registered categories and corresponding types.

{JID[]} getSupportedResources(jid, feature)

Fetch all resources of the given jid that support the requested feature. Given JID is coerced to bare.

This is an Incoming Caps method.

Parameters:
{String|jabberwerx.JID} jid: base jid for resource search
{String} feature: Supported feature

Throws:
{TypeError}: if given feature is not a non-empty string
{TypeError}: if given jid is not valid

Returns:: {JID[]} of supporting resources. may be empty

{String} getVerificationString(nodeVal)

This functions returns verification string based on node value passed.

This is an Outgoing Caps method.

Parameters:
{String} nodeVal: for which to return the verification string for

Returns:: {String} Returns null if match is not found, otherwise returns verification string

{String} getVerificationStringForJid(jid)

Helper function used in unit tests which returns verification string for the given jid.

This is an Outgoing Caps method.

Parameters:
{jabberwerx.JID|String} jid: The jid for which to return the verification string for.

Throws:
{jabberwerx.JID.InvalidJIDError}: If {jid} could not be converted into a JID

Returns:: {String} Returns null if match is not found, otherwise returns verification string

{Boolean} isSupportedFeature(jid, feature)

Checks capablility information of given JID for requested feature. All resources of a given bare jid are checked until one supports the feature. A full jid selects at most one caps info.

This is an Incoming Caps method.

Parameters:
{String|jabberwerx.JID} jid: entity to check for features
{String} feature: requested feature to search jid's capsinfo for

Throws:
{TypeError}: if feature is not a non empty string.

Returns:: {Boolean} true if jid's capsinfo has the given feature

{Boolean} removeFeature(feature)

Remove feature from the feature set.

This is an Outgoing Caps method.

Parameters:
{String} feature: The feature in the feature set to remove

Returns:: {Boolean} true if successfully removed feature, false if unsuccessful

{Boolean} removeFeatureFromJid(jid, feature)

Remove feature from the feature set for the given jid.

This is an Outgoing Caps method.

Parameters:
{String|jabberwerx.JID} jid: The jid for which to lookup a feature
{String} feature: The feature in the feature set to remove

Throws:
{TypeError}: If feature is not a non empty string.
{jabberwerx.JID.InvalidJIDError}: If {jid} could not be converted into a JID

Returns:: {Boolean} true if successfully removed feature, false otherwise

Classes

Class jabberwerx.CapabilitiesController