diff --git a/documentation/roster.html b/documentation/roster.html index 7c88df07d..5f403be78 100644 --- a/documentation/roster.html +++ b/documentation/roster.html @@ -16,12 +16,104 @@ Roster and Presence

-The roster lets you keep track of the availability (presence) of other users. Users -can be organized into groups such as "Friends" and "Co-workers", and then you -discover whether each user is online or offline.

+The roster lets you keep track of the availability ("presence") of other users. +A roster also allows you to organize users into groups such as "Friends" and +"Co-workers". Other IM systems refer to the roster as the buddy list, contact list, +etc.

A Roster instance is obtained using the XMPPConnection.getRoster() -method, but only after +method, but only after successfully logging into a server. + +

Roster Entries

+ +

+Every user in a roster is represented by a RosterEntry, which consists of:

+ +The following code snippet prints all entries in the roster: + +
+Roster roster = con.getRoster();
+for (Iterator i=roster.getEntries(); i.hasNext(); ) {
+    System.out.println(i.next());
+}
+
+ +Methods also exist to get individual entries, the list of unfiled entries, or to get one or +all roster groups. + +

Presence

+ +Roster + +

Every entry in the roster has presence associated with it. The +Roster.getPresence(String user) method will return a Presence object with +the user's presence or null if the user is not online or you are not +subscribed to the user's presence. Note: typically, presence +subscription is always tied to the user being on the roster, but this is not +true in all cases.

+ +

A user either has a presence of online or offline. When a user is online, their +presence may contain extended information such as what they are currently doing, whether +they wish to be disturbed, etc. See the Presence class for further details.

+ +

Listening for Roster and Presence Changes

+ +

The typical use of the roster class is to display a tree view of groups and entries +along with the current presence value of each entry. As an example, see the image showing +a Roster in the Exodus XMPP client to the right.

+ +

The presence information will likely +change often, and it's also possible for the roster entries to change or be deleted. +To listen for changing roster and presence data, a RosterListener should be used. +The following code snippet registers a RosterListener with the Roster that prints +any presence changes in the roster to standard out. A normal client would use +similar code to update the roster UI with the changing information. + +
+ +

+final Roster roster = con.getRoster();
+roster.addRosterListener(new RosterListener() {
+    public void rosterModified() {
+        // Ignore event for this example.
+    }
+
+    public void presenceChanged(String user) {
+        // If the presence is unavailable then "null" will be printed,
+        // which is fine for this example.
+        System.out.println("Presence changed: " + roster.getPresence(user));
+    }
+});
+
+ +

Adding Entries to the Roster

+ +

Rosters and presence use a permissions-based model where users must give permission before +they are added to someone else's roster. This protects a user's privacy by +making sure that only approved users are able to view their presence information. +Therefore, when you add a new roster entry it will be in a pending state until +the other user accepts your request.

+ +If another user requests a presence subscription so they can add you to their roster, +you must accept or reject that request. Smack handles presence subscription requests +in one of three ways: + +The mode can be set using the Roster.setSubscriptionMode(int subscriptionMode) +method. Simple clients normally use one of the automated subscription modes, while +full-featured clients should manually process subscription requests and let the +end-user accept or reject each request. If using the manual mode, a PacketListener +should be registered that listens for Presence packets that have a type of +Presence.Type.SUBSCRIBE.