• Examples (iOS)
• Examples (Java/Android)
• Examples (C++)
Server API Documentation


» The Buddy List API

SmartFoxServer 2X provides a new set of client and server API specifically designed for managing Buddies and Buddy Lists including persistence, custom states, ability to go online/offline in the Buddy system, runtime and persistent Buddy Variables, server side events and more. The new Buddy API (version 3.0) are loosely based on the previous SFS 1.x Buddy List framework, although we now provide a more simplified approach, better flexibility and more advanced features.

If you are familiar with the previous system you will notice the following differences:

» New features

The following is a rapid overview of the new features and improvements added in the framework:

» Buddy List Client API

Adding Buddies

Adding a new buddy to the current User is pretty straightforward:

// 'sfs' is our SmartFox class instance
sfs.addEventListener(SFSBuddyEvent.BUDDY_ERROR, onBuddyError)
sfs.addEventListener(SFSBuddyEvent.BUDDY_ADD, onBuddyListUpdate)

// The server will send a BUDDY_ADD event in response to this
sfs.send(new AddBuddyRequest("Kermit")); 

public function onBuddyListUpdate(evt:SFSEvent)
	// Populate the visual buddy list
	for each (var buddy:Buddy in sfs.buddyManager.buddyList)
    	// Do something with the objects in the list of buddies

private function onBuddyError(evt:SFSBuddyEvent):void
    trace("BuddyError: " + evt.params.errorMessage)

Setting Buddy Variables

sfs.addEventListener(SFSBuddyEvent.BUDDY_VARIABLES_UPDATE, onBuddyListUpdate)

// Setting one or more buddy variables
sfs.send(new SetBuddyVariablesRequest([ new SFSBuddyVariable("avatarPic", "kermit-avatar,jpg") ]) 

public function onBuddyListUpdate(evt:SFSEvent)
    // Populate the visual buddy list
    for each (var buddy:Buddy in sfs.buddyManager.buddyList)
        // Do something with the objects in the list of buddies

» Buddy List Server API

The server side API offer a very similar interface to manipulate buddy lists. All Buddy List-related commands are found in the ISFSBuddyApi object.

Getting the Buddy API

SmartFoxServer sfs = SmartFoxServer.getInstance();
ISFSBuddyApi buddyApi = sfs.getAPIManager().getBuddyApi()

Adding Buddies to a User

// This will add the User "Piggy" in the list of buddies for User "Kermit"
buddyApi.addBuddy(getParentZone(), "Kermit", "Piggy");

Setting Buddy Variables

The simple example will add the Buddy to the User and notify the client. Now let's see how to set a Buddy Variable:

// 1. Get a reference to the Owner of the BuddyList
User owner = getParentZone().getUserByName("Kermit");

// 2. Create a list of variables
List<BuddyVariable> vars = new ArrayList<BuddyVariable>();
vars.add( new SFSBuddyVariable("$avatarPic", "kermit-avatar.jpg") );
vars.add( new SFSBuddyVariable("color", "green") );

// 3. Set the variables and disptach a client side event
buddyApi.setBuddyVariables(owner, vars);

Notice how the first variable name starts with a dollar sign ($) marking the variable persistent. This means that "$avatarPic" is stored locally and available across multiple sessions while the "color" variable exists only until the current user session ends (i.e. upon disconnection).

For more details about the BuddyAPI we recommend consulting the server side javadoc.

» Buddy List persistence

The Buddy List persistence is delegated to an implementation of the BuddyStorage interface found under the com.smartfoxserver.v2.buddylist.storage package. This is the skeleton of the interface:
void init();
void destroy();
BuddyList loadList(String ownerName) throws SFSBuddyListNotFoundException, IOException;
void saveList(BuddyList buddyList) throws IOException;
List<BuddyVariable> getOfflineVariables(String buddyName) throws IOException;
BuddyListManager getBuddyListManager();
void setBuddyListManager(BuddyListManager buddyListManager);

The init() and destroy() method are called upon creation and destruction of the class, while the BuddyListManager getter/setter is used to maintain a reference to the BuddyListManager object that governs the Buddy Lists in the current Zone. The remaining methods represent the core of the persistence mechanism, which is very simple.

You will be able to provide your custom implementation by simply dropping your .jar file in the SFS2X lib/ folder and specifying the fully qualified name of the storage class in the AdminTool (Zone Configurator -> Buddy List tab).

Zone Configurator's Buddy List tab

>> DOWNLOAD the the default BuddyStorage source code <<