mirror of
https://github.com/vanitasvitae/Smack.git
synced 2024-11-27 14:32:06 +01:00
745d67a676
and rename documentation links from .html to .md, since markdown-gradle-plugin will now automatically transfer the links .md to .html. Now users can broswe the documentation in their markdown form (e.g. via github) and via html. Also add a symlink from README.md to index.md in documentation/.
94 lines
4.2 KiB
Markdown
94 lines
4.2 KiB
Markdown
Roster and Presence
|
|
===================
|
|
|
|
[Back](index.md)
|
|
|
|
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 `Roster.getInstanceFor(XMPPConnection)` method.
|
|
|
|
Roster Entries
|
|
--------------
|
|
|
|
Every user in a roster is represented by a RosterEntry, which consists of:
|
|
|
|
* An XMPP address (e.g. jsmith@example.com).
|
|
* A name you've assigned to the user (e.g. "Joe").
|
|
* The list of groups in the roster that the entry belongs to. If the roster entry belongs to no groups, it's called an "unfiled entry". The following code snippet prints all entries in the roster:
|
|
|
|
```
|
|
Roster roster = Roster.getInstanceFor(connection);
|
|
Collection<RosterEntry> entries = roster.getEntries();
|
|
for (RosterEntry entry : entries) {
|
|
System.out.println(entry);
|
|
}
|
|
```
|
|
|
|
Methods also exist to get individual entries, the list of unfiled entries, or
|
|
to get one or all roster groups.
|
|
|
|
Presence
|
|
|
|
|
|
|
|
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. To be informed about all
|
|
changes to the roster the RosterListener should be registered before logging
|
|
into the XMPP server. 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.
|
|
|
|
```
|
|
Roster roster = Roster.getInstanceFor(con);
|
|
roster.addRosterListener(new RosterListener() {
|
|
// Ignored events public void entriesAdded(Collection<String> addresses) {}
|
|
public void entriesDeleted(Collection<String> addresses) {}
|
|
public void entriesUpdated(Collection<String> addresses) {}
|
|
public void presenceChanged(Presence presence) {
|
|
System.out.println("Presence changed: " + presence.getFrom() + " " + presence);
|
|
}
|
|
});
|
|
```
|
|
|
|
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:
|
|
|
|
* Automatically accept all presence subscription requests.
|
|
* Automatically reject all presence subscription requests.
|
|
* Process presence subscription requests manually. The mode can be set using the `Roster.setSubscriptionMode(Roster.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`.
|
|
|
|
Copyright (C) Jive Software 2002-2008
|