com.zion.jbuddy
Interface IBuddyList

public interface IBuddyList

This interface provides access to the Buddy List, Permit List, and Deny Lists. These lists are maintained for the user by the IClient instance, but may be queried for the online presence of the users or for other administrative reasons.

Field Summary

static int	BUDDY_LIST The list type for users we wish to see the status of.
static int	DENY_ALL A permit mode which denies all users.
static int	DENY_LIST The list type for users we do not allow to send us messages.
static int	DENY_SOME A permit mode which denies all users in the Deny List.
static int	IGNORE_IN_LIST Deprecated. Since version 2.4, this permit mode is no longer used.
static int	IGNORE_NOT_IN_LIST Deprecated. Since version 2.4, this permit mode is no longer used.
static int	PERMIT_ALL A permit mode which permits all users.
static int	PERMIT_LIST The list type for users we allow to send us messages.
static int	PERMIT_SOME A permit mode which permits only users in the Permit List.
static int	REVERSE_LIST The list type for users watching our status.

Method Summary

boolean	addBuddyGroup(String name) Adds a buddy group to this buddy list.
boolean	addBuddyToList(String username, String nickname, String groupName) Adds a buddy to the specified group in the list.
Enumeration	getAllGroupsForBuddy(IBuddy buddy) Returns the names of the groups that the specified buddy is a member of.
Enumeration	getAllGroupsForBuddy(String buddyName) Returns the names of the groups that the specified buddy is a member of.
IBuddy[]	getBuddies() Returns the buddies contained in this buddy list.
Enumeration	getBuddiesInGroup(String groupName) Returns the buddies contained in the specified group.
IBuddy	getBuddyInGroup(String groupName, String buddyName) Returns a reference to the IBuddy object for the specified buddy.
int	getGroupCountForBuddyName(String buddyName) Returns the number of groups that the specified buddy is a member of.
Enumeration	getListOfGroups() Returns the names of the groups that are contained in this list.
int	getListType() Returns this list's type.
String	getName() Returns this list's name.
int	getNumberOfBuddiesInGroup(String groupName) Returns the number of buddies contained in the specified group.
int	getNumberOfGroups() Returns the number of groups in this list.
int	getTotalNumberOfBuddiesInList() Returns the total number of buddies in the list.
int	getVersion() Returns the current version number associated with this Buddy List.
boolean	removeBuddyGroup(String name) Removes the specified buddy group (and the buddies it contains) from this buddy list.
boolean	renameBuddyGroup(String name, String newName) Renames the specified buddy group.
void	setName(String name) Sets this list's name.
void	setVersion(int listVersion) Sets the version number for this Buddy List.

Field Detail

DENY_ALL

static final int DENY_ALL

A permit mode which denies all users.

No users are allowed to send messages to this client or receive presence updates from this client. Other side effects may occur depending on the protocol. See setPermitMode for details.

Valid on AIM, JABBER, JSC.

See Also:

IClient.setPermitMode(int), Constant Field Values

PERMIT_ALL

static final int PERMIT_ALL

A permit mode which permits all users.

All users are allowed to send messages to this client or receive presence updates from this client.

Valid on AIM, JABBER, JSC.

See Also:

IClient.setPermitMode(int), Constant Field Values

PERMIT_SOME

static final int PERMIT_SOME

A permit mode which permits only users in the Permit List.

Only users in the Permit List are allowed to send messages to this client or receive presence updates from this client. All other users are denied. Other side effects may occur depending on the protocol. See setPermitMode for details.

Valid on AIM, JABBER, JSC, MSN, SAMETIME.

See Also:

IClient.setPermitMode(int), Constant Field Values

DENY_SOME

static final int DENY_SOME

A permit mode which denies all users in the Deny List.

Users in the Deny List are not allowed to send messages to this client or receive presence updates from this client. Other side effects may occur depending on the protocol. See setPermitMode for details.

Valid on all protocols.

See Also:

IClient.setPermitMode(int), Constant Field Values

IGNORE_IN_LIST

static final int IGNORE_IN_LIST

Deprecated. Since version 2.4, this permit mode is no longer used.

A permit mode which prevents all users in our Deny List from being aware of our online presence and state.

See Also:

IClient.setPermitMode(int), Constant Field Values

IGNORE_NOT_IN_LIST

static final int IGNORE_NOT_IN_LIST

Deprecated. Since version 2.4, this permit mode is no longer used.

A permit mode which permits all users in our Deny List to be aware of our online presence and state.

See Also:

IClient.setPermitMode(int), Constant Field Values

BUDDY_LIST

static final int BUDDY_LIST

The list type for users we wish to see the status of.

See Also:

getListType(), Constant Field Values

PERMIT_LIST

static final int PERMIT_LIST

The list type for users we allow to send us messages.

See Also:

getListType(), Constant Field Values

DENY_LIST

static final int DENY_LIST

The list type for users we do not allow to send us messages.

See Also:

getListType(), Constant Field Values

REVERSE_LIST

static final int REVERSE_LIST

The list type for users watching our status.

See Also:

getListType(), Constant Field Values

Method Detail

getListType

int getListType()

Returns this list's type.

See Also:

BUDDY_LIST, REVERSE_LIST, PERMIT_LIST, DENY_LIST

getVersion

int getVersion()

Returns the current version number associated with this Buddy List.

Valid on MSN.

setVersion

void setVersion(int listVersion)

Sets the version number for this Buddy List.

This is currently valid for the MSN protocol only. Microsoft Network developers have indicated that good MSN Messenger citizens cache the Buddy Lists locally and set the version prior to connecting. MSN developers don't like to see this ignored because it means their servers must resend the full buddy lists each time your client signs on. Store the version number and lists in a local store such as a database to reduce the volume of messages received with the MSN protocol. Set the version before connecting to the IM server, and MSN will only send the Buddy List information if the server has a more up-to-date version of the Buddy List.

Note: If you avoid having the server send your buddy list, you may not be able to modify it further. Some buddy group information is lost in the process, because it is expected by the server but not supported in this API. Therefore, modifying the buddy list may lead to unspecified results.

getName

String getName()

Returns this list's name.

setName

void setName(String name)

Sets this list's name. This can be helpful in multiple user applications.

Parameters:

name - the name you wish to assign to this list

addBuddyToList

boolean addBuddyToList(String username,
                       String nickname,
                       String groupName)

Adds a buddy to the specified group in the list.

This method should only be used to populate a client buddy list before calling connect().

Parameters:

username - the buddy's unique name

nickname - the buddy's nickname

groupName - The name of the group in this list where you wish to add the buddy. The group is created if it does not exist, and it may be null.

Returns:

true if the buddy was successfully added to this list; false if the buddy was already in this list

See Also:

IClient.addBuddy(String, String, String)

getGroupCountForBuddyName

int getGroupCountForBuddyName(String buddyName)

Returns the number of groups that the specified buddy is a member of.

Parameters:

buddyName - the buddy's unique name

getAllGroupsForBuddy

Enumeration getAllGroupsForBuddy(String buddyName)

Returns the names of the groups that the specified buddy is a member of.

Parameters:

buddyName - the buddy's unique name

Returns:

an Enumeration of String objects representing the group names

getAllGroupsForBuddy

Enumeration getAllGroupsForBuddy(IBuddy buddy)

Returns the names of the groups that the specified buddy is a member of.

Returns:

an Enumeration of String objects representing the group names

getBuddies

IBuddy[] getBuddies()

Returns the buddies contained in this buddy list.

Buddies are added to the array in the order in which they are encountered in this buddy list. Each buddy that is contained in more than one buddy group appears only once (it is unique).

Since:

2.4

getBuddiesInGroup

Enumeration getBuddiesInGroup(String groupName)

Returns the buddies contained in the specified group.

Parameters:

groupName - the group's name

Returns:

an enumeration of IBuddy objects

getBuddyInGroup

IBuddy getBuddyInGroup(String groupName,
                       String buddyName)

Returns a reference to the IBuddy object for the specified buddy.

Parameters:

groupName - the name of the group which contains the buddy

buddyName - the buddy's unique name

getListOfGroups

Enumeration getListOfGroups()

Returns the names of the groups that are contained in this list.

Returns:

an Enumeration of String objects representing the group names

getNumberOfBuddiesInGroup

int getNumberOfBuddiesInGroup(String groupName)

Returns the number of buddies contained in the specified group.

Parameters:

groupName - the group's name

getNumberOfGroups

int getNumberOfGroups()

Returns the number of groups in this list.

getTotalNumberOfBuddiesInList

int getTotalNumberOfBuddiesInList()

Returns the total number of buddies in the list. Buddies with equal usernames found in separate groups are counted separately.

addBuddyGroup

boolean addBuddyGroup(String name)
                      throws IOException

Adds a buddy group to this buddy list.

AIM and ICQ clients must call sendConfigToServer() for the changes to be saved to the server.

JABBER, JSC, and YIM don't currently save buddy groups on the server unless the groups contain at least one buddy.

Parameters:

name - the buddy group's name

Returns:

true if the operation was successful, false otherwise (if the group could not be created, or already exists)

Throws:

IOException - if there is a problem communicating with the server

Since:

2.4

See Also:

IClient.sendConfigToServer()

removeBuddyGroup

boolean removeBuddyGroup(String name)
                         throws IOException

Removes the specified buddy group (and the buddies it contains) from this buddy list.

AIM and ICQ clients must call sendConfigToServer() for the changes to be saved to the server.

Parameters:

name - the buddy group's name

Returns:

true if the operation was successful, false otherwise (if the group and the buddies it contains could not be removed, or the group does not exist)

Throws:

IOException - if there is a problem communicating with the server

Since:

2.4

See Also:

IClient.sendConfigToServer()

renameBuddyGroup

boolean renameBuddyGroup(String name,
                         String newName)
                         throws IOException

Renames the specified buddy group.

AIM and ICQ clients must call sendConfigToServer() for the changes to be saved to the server.

JSC does not support renaming groups on the buddy list.

Parameters:

name - the buddy group's current name

newName - the buddy group's new name. This must not be equal to another buddy group's name in this buddy list.

Returns:

true if the operation was successful, false otherwise (if the group doesn't exist, a group with the same name as the new name already exists, or the protocol doesn't support renaming buddy groups)

Throws:

IOException - if there is a problem communicating with the server

Since:

2.4

See Also:

IClient.sendConfigToServer()