Class jabberwerx.RosterController

Controller class for roster functionality.

This class provides the following events:

jabberwerx.RosterController Events

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

Field Summary
Field Attributes	Field Name and Description
	autoaccept Indicates the behavior when receving presence subscriptions.
<static> <constant>	jabberwerx.RosterController.AUTOACCEPT_ALWAYS One of the possible values which jabberwerx.RosterController#autoaccept may be set to.
	autoaccept_in_domain Indicates if subscription requests will be automatically accepted if the sender's domain exactly matches the client's domain.
<static> <constant>	jabberwerx.RosterController.AUTOACCEPT_IN_ROSTER One of the possible values which jabberwerx.RosterController#autoaccept may be set to.
<static> <constant>	jabberwerx.RosterController.AUTOACCEPT_NEVER One of the possible values which jabberwerx.RosterController#autoaccept may be set to.
	autoremove Indicates if unsubscription requests will be automatically processed (removing the sending contact from this roster).
	autoSubscription Indicates the behavior when any subscription action is necessary.
	defaultGroup Specifies the default group to which contacts are added or updated to.

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

Method Summary
Method Attributes	Method Name and Description
	acceptSubscription(contact, nickname, groups) Accepts a subscription request from a contact See jabberwerx.RosterController#updateContact for details on nickname and groups.
	addContact(jid, nickname, groups, callback) DEPRECATED.
	cleanupEntity(entity) Cleanup RosterContact entity on behalf of an owning jabberwerx.EntitySet.
	deleteContact(jid, callback) Delete a contact from a user's roster
	denySubscription(contact) Denies (or cancels an existing) subscription from a contact.
	destroy() Destroys this RosterController and removes any event callbacks it registered.
	eachContact(op) Iterates over roster contacts
	fetch(callback) DEPRECATED.
	finishRendezvous()
	removeEntity(entity) Deletes the given entity.
	subscribe(jid) Sends out a subscribe request unless the current user is already subscribed to the passed in JID.
	unsubscribe(jid) Sends out an unsubscribe request when the current user is subscribed to the passed in JID.
	updateContact(jid, nickname, groups, callback) Update a contact in a user's roster.
	updateEntity(entity) Updates the given entity.

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

Creates a new RosterController with the given client.

Parameters:
{jabberwerx.Client} client: The client object to use for communicating to the server

Throws:
: TypeError If {client} is not an instance of jabberwerx.Client

Field Detail

{String} autoaccept

Indicates the behavior when receving presence subscriptions. The possible values are:

jabberwerx.RosterController.AUTOACCEPT_NEVER: never automatically accept subscription requests.
jabberwerx.RosterController.AUTOACCEPT_IN_ROSTER: only automatically accept if the sender is in the roster, with either [subscription='to'] or [ask='subscribe']. DEFAULT
jabberwerx.RosterController.AUTOACCEPT_ALWAYS: always automatically accept subscription requests.

The default value is jabberwerx.RosterController.AUTOACCEPT_IN_ROSTER.

<static> <constant> jabberwerx.RosterController.AUTOACCEPT_ALWAYS

One of the possible values which jabberwerx.RosterController#autoaccept may be set to.

{Boolean} autoaccept_in_domain

Indicates if subscription requests will be automatically accepted if the sender's domain exactly matches the client's domain. This behavior supercedes that indicated by jabberwerx.RosterController#autoaccept. In order to disable all possible automatic subscription acceptance, both this property and {autoaccept} must be set appropriately.

The default value is {true}, which is to accept in-domain subscription requests.

<static> <constant> jabberwerx.RosterController.AUTOACCEPT_IN_ROSTER

One of the possible values which jabberwerx.RosterController#autoaccept may be set to.

<static> <constant> jabberwerx.RosterController.AUTOACCEPT_NEVER

One of the possible values which jabberwerx.RosterController#autoaccept may be set to.

{Boolean} autoremove

Indicates if unsubscription requests will be automatically processed (removing the sending contact from this roster).

The default value if {true}, which is to automatically remove contacts when receiving unsubscribe requests.

{Boolean} autoSubscription

Indicates the behavior when any subscription action is necessary. When set to false, the RosterController will do nothing in the way of automatically sending subscribes or unsubscribes

The default value is {true} which allows jabberwerx.RosterController#autoaccept, jabberwerx.RosterController#autoaccept_in_domain and jabberwerx.RosterController#autoremove to determine the behavior of the RosterController when dealing with subscriptions.

{String} defaultGroup

Specifies the default group to which contacts are added or updated to. This property is only used when a groups parameter is not specified (or empty) in the add, update or accept subscription method call. It defaults to an empty string (i.e. no group). Modify this variable directly to set the default group.

This is not linked to jabberwerx.ui.RosterView#getDefaultGroupingName.

Method Detail

acceptSubscription(contact, nickname, groups)

Accepts a subscription request from a contact

See jabberwerx.RosterController#updateContact for details on nickname and groups.

Parameters:
{String|JID} contact: The contact to accept the subscription from
{String} nickname Optional: The nickname to apply to the contact in our roster
{String} groups Optional: The groups to apply to the contact in our roster

Throws:
{jabberwerx.Client.NotConnectedError}: If the jabberwerx.Client is not connected

addContact(jid, nickname, groups, callback)

DEPRECATED. Update a contact in a user's roster. Invoking this method is the same as invoking jabberwerx.RosterController#updateContact NOTE: If the given contact is not in our roster the contact is added. If we are not receiving the contact's presence, we subscribe to it.

Parameters:

{jabberwerx.JID|String} jid

The JID of the contact to be added

{String} nickname Optional

The nickname to associate with the contact. The contact's nickname is only updated if supplied a non-empty string value. If value is null or undefined the nickname is left unchanged. If value is an empty string the contact's nickname is cleared.

{String|String[]} groups Optional

The name of the group or array of groups names to associate with the contact The contact's groups are only updated if supplied a non-empty string or array. If groups is null or undefined the groups are left unchanged. If value is an empty string or an empty array, the contact's groups are reset to the default group.

{function} callback Optional

The function called after the server response is processed. If a server error occurs, the function will be passed the error stanza response.

The signature of the function is callback(errorStanza).

The callback will be invoked in the context of the RosterController e.g. callback.call(this, errorStanza). Therefore in the callback method this will refer to the instance of RosterController and so this.client will retrieve the jabberwerx.Client object.

Deprecated:
Since version 2012.06

Throws:
{jabberwerx.Client.NotConnectedError}: If the jabberwerx.Client is not connected
{jabberwerx.JID.InvalidJIDError}: If the JID argument is undefined, null or an empty string

cleanupEntity(entity)

Cleanup RosterContact entity on behalf of an owning jabberwerx.EntitySet.

Parameters:
{jabberwerx.Entity} entity: The entity to destroy

deleteContact(jid, callback)

Delete a contact from a user's roster

Parameters:

{jabberwerx.JID|String} jid

The JID of the contact to be deleted

{function} callback Optional

The function called after the server response is processed. If a server error occurs, the function will be passed the error stanza response.

The signature of the function is callback(errorStanza).

Throws:
{jabberwerx.Client.NotConnectedError}: If the jabberwerx.Client is not connected
{jabberwerx.JID.InvalidJIDError}: If {jid} is undefined, null or an empty string

denySubscription(contact)

Denies (or cancels an existing) subscription from a contact.

Parameters:
{String|jabberwerx.JID} contact: The contact to deny the subscription from

Throws:
{jabberwerx.Client.NotConnectedError}: If the jabberwerx.Client is not connected

destroy()

Destroys this RosterController and removes any event callbacks it registered.

eachContact(op)

Iterates over roster contacts

Parameters:
{function} op: The function called for each contact. Can return false to cancel iteration.

fetch(callback)

DEPRECATED. This function is called on the users behalf. Fetch a user's roster and adds the contacts to the jabberwerx.Client#entitySet

Parameters:

{function} callback Optional

The function called after the server response is processed. If a server error occurs, the function will be passed the error stanza response.

The signature of the function is callback(errorStanza).

Deprecated:
Since version 2011.08

Throws:
{jabberwerx.Client.NotConnectedError}: If the jabberwerx.Client is not connected

finishRendezvous()

removeEntity(entity)

Deletes the given entity. This method calls #deleteContact with the displayName and groups from the given entity.

Parameters:
{jabberwerx.RosterContact} entity: The entity to delete

Throws:
{TypeError}: if {entity} is not a Contact

subscribe(jid)

Sends out a subscribe request unless the current user is already subscribed to the passed in JID.

Parameters:
{jabberwerx.JID|String} jid: The JID of the contact to be updated

Throws:
{jabberwerx.Client.NotConnectedError}: If the jabberwerx.Client is not connected
{jabberwerx.JID.InvalidJIDError}: If {jid} is an invalid JID.

unsubscribe(jid)

Sends out an unsubscribe request when the current user is subscribed to the passed in JID.

Parameters:
{jabberwerx.JID|String} jid: The JID of the contact to be updated

Throws:
{jabberwerx.Client.NotConnectedError}: If the jabberwerx.Client is not connected
{jabberwerx.JID.InvalidJIDError}: If {jid} is an invalid JID.

updateContact(jid, nickname, groups, callback)

Update a contact in a user's roster. Invoking this method is the same as invoking jabberwerx.RosterController#addContact NOTE: If the given contact is not in our roster the contact is added. If we are not receiving the contact's presence, we subscribe to it.

Parameters:

{jabberwerx.JID|String} jid

The JID of the contact to be added

{String} nickname Optional

{String|String[]} groups Optional

The name of the group or array of groups names to associate with the contact The contact's groups are only updated if supplied a non-empty string or array. If groups is null or undefined the groups are left unchanged. If value is an empty string or empty array, the contact's groups are reset to the default group.

{function} callback Optional

The function called after the server response is processed. If a server error occurs, the function will be passed the error stanza response.

The signature of the function is callback(errorStanza).

Throws:
{jabberwerx.Client.NotConnectedError}: If the jabberwerx.Client is not connected
{jabberwerx.JID.InvalidJIDError}: If the JID argument is undefined, null or an empty string

updateEntity(entity)

Updates the given entity.

Parameters:
{jabberwerx.RosterContact} entity: The entity to update

Throws:
{TypeError}: if {entity} is not a Contact

Classes

Class jabberwerx.RosterController