Packageorg.igniterealtime.xiff.im
Classpublic class Roster
InheritanceRoster Inheritance ArrayCollection Inheritance flash.utils.Proxy
ImplementsIRoster

Manages a user's server-side instant messaging roster (or "buddy list"). By default, this class uses an internal data provider to keep track of roster data locally and provides a "read-only" form of the Data Provider API for external use. Non-read operations are performed using alternative, roster-specific methods.



Public Properties
 PropertyDefined by
  connection : IXMPPConnection
The instance of the XMPPConnection class to use for the roster to use for sending and receiving data.
Roster
 Inheritedlength : int
The number of items in the ArrayCollection.
ArrayCollection
 Inheritedsource : Array
The source of data in the ArrayCollection.
ArrayCollection
Protected Properties
 PropertyDefined by
 InheritedeventDispatcher : EventDispatcher
ArrayCollection
 Inherited_source : Array
ArrayCollection
Public Methods
 MethodDefined by
  
Roster(aConnection:IXMPPConnection = null)
Roster
  
addContact(id:UnescapedJID, displayName:String, groupName:String = null, requestSubscription:Boolean = true):void
Adds a contact to the roster.
Roster
  
addContact_result(resultIQ:IQ):void
Roster
 Inherited
addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void
Registers an event listener object with an EventDispatcher object so that the listener receives notification of an event.
ArrayCollection
 Inherited
addItem(item:*):void
Add the specified item to the end of the list.
ArrayCollection
 Inherited
addItemAt(item:*, index:int):void
Add the specified item at the specified index.
ArrayCollection
 Inherited
clearSource():void
Remove all items from the ArrayCollection without dispatching a RESET event.
ArrayCollection
 Inherited
contains(item:*):Boolean
Returns whether the ArrayCollection contains the specified item.
ArrayCollection
  
Revokes an existing presence subscription or denies a subscription request.
Roster
 Inherited
dispatchEvent(event:Event):Boolean
Dispatches an event into the event flow.
ArrayCollection
  
fetchRoster():void
Fetches the roster data from the server.
Roster
  
fetchRoster_result(resultIQ:IQ):void
Roster
  
Roster
  
getGroup(name:String):IRosterGroup
Get a group by given name
Roster
 Inherited
getItemAt(index:int):*
Get the item at the specified index.
ArrayCollection
 Inherited
getItemIndex(item:*):int
Get the index of the item if it is in the ArrayCollection such that getItemAt( index ) == item.
ArrayCollection
  
Get the Presence of the given user if any.
Roster
  
grantSubscription(tojid:UnescapedJID, requestAfterGrant:Boolean = true):void
Grants a user or service authorization for subscribing to your presence.
Roster
 Inherited
hasEventListener(type:String):Boolean
Checks whether the EventDispatcher object has any listeners registered for a specific type of event.
ArrayCollection
 Inherited
itemUpdated(item:*):void
Notifies the view that an item has been updated.
ArrayCollection
 Inherited
removeAll():void
Remove all items from the ArrayCollection.
ArrayCollection
  
removeContact(rosterItem:IRosterItemVO):void
Removes a contact from the roster and revokes all presence subscriptions for that contact.
Roster
 Inherited
removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void
Removes a listener from the EventDispatcher object.
ArrayCollection
 Inherited
removeItem(item:*):Boolean
Remove the specified item from this list, should it exist.
ArrayCollection
 Inherited
removeItemAt(index:int):*
Removes the item at the specified index and returns it.
ArrayCollection
  
requestSubscription(id:UnescapedJID, isResponse:Boolean = false):void
Requests subscription authorization with a user or service.
Roster
 Inherited
setItemAt(item:*, index:int):*
Places the item at the specified index.
ArrayCollection
  
setPresence(show:String, status:String, priority:int):void
Sets your current presence status.
Roster
 Inherited
toArray():Array
Return an Array that is populated in the same order as the ArrayCollection.
ArrayCollection
 Inherited
toString():String
Pretty prints the contents of the ArrayCollection to a string and returns it.
ArrayCollection
  
unsubscribe_result(resultIQ:IQ):void
Roster
  
updateContactGroups(rosterItem:IRosterItemVO, newGroupNames:Array):void
Updates the groups associated with an existing contact.
Roster
  
updateContactName(rosterItem:IRosterItemVO, newName:String):void
Updates the display name for an existing contact.
Roster
 Inherited
willTrigger(type:String):Boolean
Checks whether an event listener is registered with this EventDispatcher object or any of its ancestors for the specified event type.
ArrayCollection
Protected Methods
 MethodDefined by
 Inherited
internalDispatchEvent(kind:String, item:int = null, location:* = -1):void
Dispatches a collection event with the specified information.
ArrayCollection
Events
 EventSummaryDefined by
    Roster
   Broadcast whenever a subscription request that you make (via the addContact() or requestSubscription() methods) is denied.Roster
   Broadcast whenever someone requests to subscribe to your presence.Roster
   Broadcast whenever someone revokes your presence subscription.Roster
   Broadcast whenever a contact in the roster becomes available.Roster
   Broadcast whenever a contact in the roster becomes unavailable.Roster
    Roster
    Roster
    Roster
Protected Constants
 ConstantDefined by
 InheritedOUT_OF_BOUNDS_MESSAGE : String = "The supplied index is out of bounds."
ArrayCollection
Property detail
connectionproperty
connection:IXMPPConnection  [read-write]

The instance of the XMPPConnection class to use for the roster to use for sending and receiving data.

Implementation
    public function get connection():IXMPPConnection
    public function set connection(value:IXMPPConnection):void
Constructor detail
Roster()constructor
public function Roster(aConnection:IXMPPConnection = null)

Parameters
aConnection:IXMPPConnection (default = null) — A reference to an XMPPConnection class instance
Method detail
addContact()method
public function addContact(id:UnescapedJID, displayName:String, groupName:String = null, requestSubscription:Boolean = true):void

Adds a contact to the roster. Remember: All roster data is managed on the server-side, so this contact is added to the server-side roster first, and upon successful addition, reflected in the local client-side copy of the roster.

Parameters
id:UnescapedJID — The JID of the contact to add
 
displayName:String — A friendly name for use when displaying this contact in the roster
 
groupName:String (default = null) — (Optional) The name of the group that this contact should be added to. (Used for organization in the roster listing.
 
requestSubscription:Boolean (default = true) — (Optional) Determines whether a subscription request should be sent to this user. Most of the time you will want this parameter to be true. You will be unable to view the contacts presence status until a subscription request is granted.

Example
This example adds a contact to the roster and simultaneously requests a presence subscription with the new contact.
myRoster.addContact( "homer

addContact_result()method 
public function addContact_result(resultIQ:IQ):void

Parameters
resultIQ:IQ
denySubscription()method 
public function denySubscription(tojid:UnescapedJID):void

Revokes an existing presence subscription or denies a subscription request. If a user has sent you a subscription request you can use this method to deny that request. Otherwise, if a user already has a granted presence subscription, you can use this method to revoke that subscription.

Parameters
tojid:UnescapedJID — The JID of the user or service that you are denying subscription
fetchRoster()method 
public function fetchRoster():void

Fetches the roster data from the server. Once the data has been fetched, the Roster's data provider is populated appropriately. If the Roster-XMPPConnection class dependency has been set up before logging in, then this method will be called automatically because the Roster listens for "login" events from the XMPPConnection.

fetchRoster_result()method 
public function fetchRoster_result(resultIQ:IQ):void

Parameters
resultIQ:IQ
getContainingGroups()method 
public function getContainingGroups(item:IRosterItemVO):Array

Parameters
item:IRosterItemVO

Returns
Array
getGroup()method 
public function getGroup(name:String):IRosterGroup

Get a group by given name

Parameters
name:String

Returns
IRosterGroup
getPresence()method 
public function getPresence(jid:UnescapedJID):IPresence

Get the Presence of the given user if any.

Parameters
jid:UnescapedJID

Returns
IPresence
grantSubscription()method 
public function grantSubscription(tojid:UnescapedJID, requestAfterGrant:Boolean = true):void

Grants a user or service authorization for subscribing to your presence. Once authorization is granted, the user can see whether you are offline, online, away, etc. Subscriptions can be revoked at any time using the denySubscription() method.

Parameters
tojid:UnescapedJID — The JID of the user or service to grant subscription to
 
requestAfterGrant:Boolean (default = true) — Whether or not a reciprocal subscription request should be sent to the grantee, so that you may, in turn, subscribe to his/her/its presence.
removeContact()method 
public function removeContact(rosterItem:IRosterItemVO):void

Removes a contact from the roster and revokes all presence subscriptions for that contact. This method will only attempt action if the contact you are trying to remove is currently on the roster in the first place.

Parameters
rosterItem:IRosterItemVO — The value object which is to be removed
requestSubscription()method 
public function requestSubscription(id:UnescapedJID, isResponse:Boolean = false):void

Requests subscription authorization with a user or service. In the XMPP-world, you cannot receive notifications on changes to a contact's presence until that contact has authorized you to subscribe to his/her/its presence.

Parameters
id:UnescapedJID — The JID of the user or service that you wish to subscribe to
 
isResponse:Boolean (default = false)

See also

setPresence()method 
public function setPresence(show:String, status:String, priority:int):void

Sets your current presence status. Calling this method notifies others who are subscribed to your presence of a presence change. You should use this to change your status to away, extended-away, etc. There are static variables that you can use defined in the presence class for the show parameter:

Parameters
show:String — The show type for your presence. This represents what others should see - whether you are offline, online, away, etc.
 
status:String — The status message associated with the show value
 
priority:int — (Optional) A priority integer for the presence

See also

unsubscribe_result()method 
public function unsubscribe_result(resultIQ:IQ):void

Parameters
resultIQ:IQ
updateContactGroups()method 
public function updateContactGroups(rosterItem:IRosterItemVO, newGroupNames:Array):void

Updates the groups associated with an existing contact.

Parameters
rosterItem:IRosterItemVO — The value object of the contact to update
 
newGroupNames:Array — The new groups to associate the contact with
updateContactName()method 
public function updateContactName(rosterItem:IRosterItemVO, newName:String):void

Updates the display name for an existing contact.

Parameters
rosterItem:IRosterItemVO — The value object of the contact to update
 
newName:String — The new display name for this contact
Event detail
rosterLoadedevent 
Event object type: org.igniterealtime.xiff.events.RosterEvent

subscriptionDenialevent  
Event object type: org.igniterealtime.xiff.events.RosterEvent

Broadcast whenever a subscription request that you make (via the addContact() or requestSubscription() methods) is denied. The event object contains an attribute jid with the JID of the user who denied the request.

subscriptionRequestevent  
Event object type: org.igniterealtime.xiff.events.RosterEvent

Broadcast whenever someone requests to subscribe to your presence. The event object contains an attribute jid with the JID of the user who is requesting a presence subscription.

subscriptionRevocationevent  
Event object type: org.igniterealtime.xiff.events.RosterEvent

Broadcast whenever someone revokes your presence subscription. This is not an event that is fired when you revoke a subscription, but rather when one of your contacts decides that he/she/it no longer wants you to know about their presence status. The event object contains an attribute jid with the JID of the user who revoked your subscription.

userAvailableevent  
Event object type: org.igniterealtime.xiff.events.RosterEvent

Broadcast whenever a contact in the roster becomes available. (Goes from offline to online.) The event object contains an attribute jid with the JID of the user who became available.

userAvailableevent  
Event object type: org.igniterealtime.xiff.events.RosterEvent

Broadcast whenever a contact in the roster becomes unavailable. (Goes from online to offline.) The event object contains an attribute jid with the JID of the user who became unavailable.

userPresenceUpdatedevent  
Event object type: org.igniterealtime.xiff.events.RosterEvent

userRemovedevent  
Event object type: org.igniterealtime.xiff.events.RosterEvent

userSubscriptionUpdatedevent  
Event object type: org.igniterealtime.xiff.events.RosterEvent