一 Roster对象介绍
将其翻译成中文为"花名册",用来表示一个用户的所有好友清单以及申请加好友的用户清单,为了便于管理,Roster中的用户分组进行管理。当其他用户想申请加好友时,需要向该用户发出一个subcription请求,处理请求的模式有三种:
accept_all: 接收所有请求;
reject_all: 拒绝所有请求;
manual: 手工处理所有请求
二 常用方法
getDefaultSubscriptionMode
public static Roster.SubscriptionModegetDefaultSubscriptionMode()
-
Returns the default subscription processing mode to use when a new Roster is created. The subscription processing mode dictates what action Smack will take when subscription requests from other users are made. The default subscription mode is
Roster.SubscriptionMode.accept_all
. -
-
Returns:
- the default subscription mode to use for new Rosters
setDefaultSubscriptionMode
public static void setDefaultSubscriptionMode(Roster.SubscriptionMode subscriptionMode)
-
Sets the default subscription processing mode to use when a new Roster is created. The subscription processing mode dictates what action Smack will take when subscription requests from other users are made. The default subscription mode is
Roster.SubscriptionMode.accept_all
. -
-
Parameters:
-
subscriptionMode
- the default subscription mode to use for new Rosters.
-
getSubscriptionMode
public Roster.SubscriptionMode getSubscriptionMode()
-
Returns the subscription processing mode, which dictates what action Smack will take when subscription requests from other users are made. The default subscription mode is
Roster.SubscriptionMode.accept_all
.If using the manual mode, a PacketListener should be registered that listens for Presence packets that have a type of
Presence.Type.subscribe
. -
-
Returns:
- the subscription mode.
setSubscriptionMode
public void setSubscriptionMode(Roster.SubscriptionMode subscriptionMode)
-
Sets the subscription processing mode, which dictates what action Smack will take when subscription requests from other users are made. The default subscription mode is
Roster.SubscriptionMode.accept_all
.If using the manual mode, a PacketListener should be registered that listens for Presence packets that have a type of
Presence.Type.subscribe
. -
-
Parameters:
-
subscriptionMode
- the subscription mode.
-
reload
public void reload()
- Reloads the entire roster from the server. This is an asynchronous operation, which means the method will return immediately, and the roster will be reloaded at a later point when the server responds to the reload request.
-
-
Throws:
-
IllegalStateException
- if connection is not logged in or logged in anonymously
-
addRosterListener
public void addRosterListener(RosterListener rosterListener)
- Adds a listener to this roster. The listener will be fired anytime one or more changes to the roster are pushed from the server.
-
-
Parameters:
-
rosterListener
- a roster listener.
-
removeRosterListener
public void removeRosterListener(RosterListener rosterListener)
- Removes a listener from this roster. The listener will be fired anytime one or more changes to the roster are pushed from the server.
-
-
Parameters:
-
rosterListener
- a roster listener.
-
createGroup
public RosterGroup createGroup(String name)
-
Creates a new group.
Note: you must add at least one entry to the group for the group to be kept after a logout/login. This is due to the way that XMPP stores group information.
-
-
Parameters:
-
name
- the name of the group.
Returns:
- a new group. Throws:
-
IllegalStateException
- if connection is not logged in or logged in anonymously
-
createEntry
public void createEntry(String user, String name, String[] groups) throws XMPPException
- Creates a new roster entry and presence subscription. The server will asynchronously update the roster with the subscription status.
-
-
Parameters:
-
user
- the user. (e.g. johndoe@jabber.org) -
name
- the nickname of the user. -
groups
- the list of group names the entry will belong to, ornull if the the roster entry won't belong to a group.
Throws:
-
XMPPException
- if an XMPP exception occurs. -
IllegalStateException
- if connection is not logged in or logged in anonymously
-
removeEntry
public void removeEntry(RosterEntry entry) throws XMPPException
- Removes a roster entry from the roster. The roster entry will also be removed from the unfiled entries or from any roster group where it could belong and will no longer be part of the roster. Note that this is an asynchronous call -- Smack must wait for the server to send an updated subscription status.
-
-
Parameters:
-
entry
- a roster entry.
Throws:
-
XMPPException
- if an XMPP error occurs. -
IllegalStateException
- if connection is not logged in or logged in anonymously
-
getEntryCount
public int getEntryCount()
- Returns a count of the entries in the roster.
-
-
Returns:
- the number of entries in the roster.
getEntries
public Collection<RosterEntry> getEntries()
- Returns an unmodifiable collection of all entries in the roster, including entries that don't belong to any groups.
-
-
Returns:
- all entries in the roster.
getUnfiledEntryCount
public int getUnfiledEntryCount()
- Returns a count of the unfiled entries in the roster. An unfiled entry is an entry that doesn't belong to any groups.
-
-
Returns:
- the number of unfiled entries in the roster.
getUnfiledEntries
public Collection<RosterEntry> getUnfiledEntries()
- Returns an unmodifiable collection for the unfiled roster entries. An unfiled entry is an entry that doesn't belong to any groups.
-
-
Returns:
- the unfiled roster entries.
getEntry
public RosterEntry getEntry(String user)
- Returns the roster entry associated with the given XMPP address ornull if the user is not an entry in the roster.
-
-
Parameters:
-
user
- the XMPP address of the user (eg "jsmith@example.com"). The address could be in any valid format (e.g. "domain/resource", "user@domain" or "user@domain/resource").
Returns:
- the roster entry or null if it does not exist.
-
contains
public boolean contains(String user)
- Returns true if the specified XMPP address is an entry in the roster.
-
-
Parameters:
-
user
- the XMPP address of the user (eg "jsmith@example.com"). The address could be in any valid format (e.g. "domain/resource", "user@domain" or "user@domain/resource").
Returns:
- true if the XMPP address is an entry in the roster.
-
getGroup
public RosterGroup getGroup(String name)
- Returns the roster group with the specified name, ornull if the group doesn't exist.
-
-
Parameters:
-
name
- the name of the group.
Returns:
- the roster group with the specified name.
-
getGroupCount
public int getGroupCount()
- Returns the number of the groups in the roster.
-
-
Returns:
- the number of groups in the roster.
getGroups
public Collection<RosterGroup> getGroups()
- Returns an unmodifiable collections of all the roster groups.
-
-
Returns:
- an iterator for all roster groups.
getPresence
public Presence getPresence(String user)
-
Returns the presence info for a particular user. If the user is offline, or if no presence data is available (such as when you are not subscribed to the user's presence updates), unavailable presence will be returned.
If the user has several presences (one for each resource), then the presence with highest priority will be returned. If multiple presences have the same priority, the one with the "most available" presence mode will be returned. In order, that's
free to chat
,available
,away
,extended away
, anddo not disturb
.Note that presence information is received asynchronously. So, just after logging in to the server, presence values for users in the roster may be unavailable even if they are actually online. In other words, the value returned by this method should only be treated as a snapshot in time, and may not accurately reflect other user's presence instant by instant. If you need to track presence over time, such as when showing a visual representation of the roster, consider using a
RosterListener
. -
-
Parameters:
-
user
- an XMPP ID. The address could be in any valid format (e.g. "domain/resource", "user@domain" or "user@domain/resource"). Any resource information that's part of the ID will be discarded.
Returns:
- the user's current presence, or unavailable presence if the user is offline or if no presence information is available..
-
getPresenceResource
public Presence getPresenceResource(String userWithResource)
- Returns the presence info for a particular user's resource, or unavailable presence if the user is offline or if no presence information is available, such as when you are not subscribed to the user's presence updates.
-
-
Parameters:
-
userWithResource
- a fully qualified XMPP ID including a resource (user@domain/resource).
Returns:
- the user's current presence, or unavailable presence if the user is offline or if no presence information is available.
-
getPresences
public Iterator<Presence> getPresences(String user)
- Returns an iterator (of Presence objects) for all of a user's current presences or an unavailable presence if the user is unavailable (offline) or if no presence information is available, such as when you are not subscribed to the user's presence updates.
-
-
Parameters:
-
user
- a XMPP ID, e.g. jdoe@example.com.
Returns:
- an iterator (of Presence objects) for all the user's current presences, or an unavailable presence if the user is offline or if no presence information is available.
-
三 Roster对象的获取
使用Connection.getRoster()方法来获取一个用户的Roster实例,需要注意的是:无论用户是否登录、或是否匿名登录,该方法返回的Roster对象都不会为空,不过在上述情况下,不能使用Roster对象的大部分方法,否则会抛出异常