SmartFoxServer 2X JavaScript server API

Class: BuddyApi

BuddyApi

The BuddyApi class provides all the features to manage the users' Buddy Lists. It contains methods to initialize the Buddy List of a user, add and remove buddies, set the online status and more.

See also

new BuddyApi()

Developers never istantiate the BuddyApi class: this is done internally by the SmartFoxServer 2X API; get a reference to it using the Extension's getBuddyApi method.

Methods

addBuddy(owner, buddyName, isTemp [, fireClientEvent] [, fireServerEvent])

Adds a new buddy to the Buddy List of the passed user.
Parameters:
Name Type Argument Default Description
owner SFSUser The SFSUser object representing the owner of the Buddy List to add a new buddy to.
buddyName string The name of the user to add as a buddy.
isTemp boolean If true, the buddy is only temporary and will be removed when the owner logs out of the system.
fireClientEvent boolean <optional>
 false If true, a client-side BUDDY_ADD event will be fired to notify the action.
fireServerEvent boolean <optional>
 false If true, a server-side event of type SFSEventType.BUDDY_ADD will be fired to notify the action.
Throws:
A SFSBuddyListException exception if the Buddy List of the user is full or the buddy is already in the Buddy List.

blockBuddy(owner, buddyName, isBlocked [, fireClientEvent] [, fireServerEvent])

Blocks/unblocks a buddy in the Buddy List of a user.

Blocked buddies won't be able to see the user online status and send him messages or Buddy Variables updates.

Parameters:
Name Type Argument Default Description
owner SFSUser The SFSUser object representing the owner of the Buddy List in which the buddy should be blocked/unblocked.
buddyName string The name of the buddy to block/unblock.
isBlocked boolean If true, the buddy will be blocked in the Buddy List of the user; if false, the block will be removed.
fireClientEvent boolean <optional>
 false If true, a client-side BUDDY_BLOCK event will be fired to notify the change.
fireServerEvent boolean <optional>
 false If true, a server-side event of type SFSEventType.BUDDY_BLOCK will be fired to notify the change.

goOnline(user, online [, fireServerEvent])

Activates/deactivates the ONLINE status of the user in the Buddy List system.

All clients who have the user as their Buddy will see him as online or offline respectively.

Parameters:
Name Type Argument Default Description
user SFSUser The SFSUser object representing the user to set online/offline in the Buddy List system.
online boolean If true, the user is set as online in the Buddy List system; if false, he is set as offline.
fireServerEvent boolean <optional>
 false If true, a server-side event of type SFSEventType.BUDDY_ONLINE_STATE_UPDATE will be fired to notify the user's online state change.

initBuddyList(user [, fireServerEvent])

Initializes the Buddy List for the passed user.

This causes saved data (the list of buddies and their persistent Buddy Variables) to be loaded from the Buddy List storage.

Parameters:
Name Type Argument Default Description
user SFSUser The SFSUser object representing the user whose Buddy List should be loaded.
fireServerEvent boolean <optional>
 false If true, a server-side event of type SFSEventType.BUDDY_LIST_INIT will be fired to notify the Buddy List initialization success.
Throws:
An IOException Java exception if the Buddy List data couldn't be retrieved from the storage.
Returns:
A SFSBuddyList class instance representing the usere's Buddy List.
Type
SFSBuddyList

removeBuddy(owner, buddyName [, fireClientEvent] [, fireServerEvent])

Removes a buddy from the Buddy List of the passed user.
Parameters:
Name Type Argument Default Description
owner SFSUser The SFSUser object representing the owner of the Buddy List to remove a buddy from.
buddyName string The name of the buddy to remove.
fireClientEvent boolean <optional>
 false If true, a client-side BUDDY_REMOVE event will be fired to notify the buddy removal.
fireServerEvent boolean <optional>
 false If true, a server-side event of type SFSEventType.BUDDY_REMOVE will be fired to notify the buddy removal.

sendBuddyMessage(sender, recipient, message, params)

Sends a Buddy Message from a user to one of his buddies.

A Buddy Message is similar to a regular private chat message, but it is meant to work with the Buddy List system, taking into account the buddy blocked state, online presence, etc.
The message is sent to both the sender and the receiver. The recipient must be in the sender's Buddy List.

Parameters:
Name Type Description
sender SFSUser The SFSUser object representing the user sending the message.
recipient SFSUser The SFSUser object representing the message recipient (must be a buddy in the sender's Buddy List).
message string The chat message to send.
params SFSObject A SFSObject containing custom parameters to be attached to the message (e.g. text color, font size, etc).
Throws:
A SFSBuddyListException exception if the recipient is not in the sender's Buddy List or if the recipient has blocked the sender.

setBuddyVariables(owner, variables [, fireClientEvent] [, fireServerEvent])

Sets the Buddy Variables for the passed user.

Only new/updated variables are broadcast to the users that have the owner in their Buddy list. A variable can also be deleted by setting it to null.

Parameters:
Name Type Argument Default Description
owner SFSUser The SFSUser object representing the user to set the Buddy Variables for.
variables Array.<SFSBuddyVariable> An array of SFSBuddyVariable objects to set.
fireClientEvent boolean <optional>
 false If true, a client-side BUDDY_VARIABLES_UPDATE event will be fired to notify the Buddy Variables creation/update.
fireServerEvent boolean <optional>
 false If true, a server-side event of type SFSEventType.BUDDY_VARIABLES_UPDATE will be fired to notify the Buddy Variables creation/update.
Throws:
A SFSBuddyListException exception if the limit on the number of allowed Buddy Variables is exceeded.