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

 

» Server Variables

The SmartFoxServer 2X framework provides different types of Server Variables that can be used to maintain synchronized state across users, Rooms and buddies inside a Buddy List.

Server Variables, in general, allow the client or server logic to create custom values that are automatically updated within their scope. There are three main types of Server Variables with different scope:

» General architecture

The following diagram illustrates a simplified hierarchy of the different types of server variables. At the top we have the Variable interface defining the basic properties such as name and value. Below we find different sub-classes that extend the basic features and add new properties such as private, persistent, etc.

variables-diag

Let's take a more in depth look at each property:

Static Room Variables
While User Variables and Buddy Variables can only be created dynamically via code, Room Variables can also be created statically at configuration time. You can learn more about this by consulting the documentation about the AdminTool's Zone Configurator.

» Examples of usage

Below you will find a few examples of how to use Room and User Variables from the client API using the ActionScript 3 language.

Buddy Variables will be treated separately in the largest context of the Buddy List API.

User Variables

This is an example of how a user can store his profile using Variables and automatically update all other clients in the same Room(s)

var avatarPic:UserVariable = new SFSUserVariable("avt", "MissPiggy.png");
var occupation:UserVariable = new SFSUserVariable("occ", "Acting and singing");
var location:UserVariable = new SFSUserVariable("loc", "Muppet's Show");

sfs.send( new SetUserVariablesRequest( [avatarPics, occupation, location] ));

To receive the update, clients must be listening to the SFSEvent.USER_VARIABLES_UPDATE event:

sfs.addEventListener(SFSEvent.USER_VARIABLES_UPDATE, onUserVarsUpdate);

// ...

private function onUserVarsUpdate(evt:SFSEvent):void
{      
    // The User that changed his variables
    var user:User = evt.params.user as User;
    
    // Do something with these values...
    trace("Location: " + user.getVariable("loc").getValue());
    trace("Occupation: " + user.getVariable("occ").getValue());
    
    // etc...
}

Room Variables

The following is a quick example of how to set a private Room Variable from client side:

var chatRoomTopic:RoomVariable = new SFSRoomVariable("topic", "Multiplayer Game Development");
chatRoomTopic.isPrivate = true;

sfs.send( new SetRoomVariablesRequest( [chatRoomTopic] ));

The other clients must be listening to the SFSEvent.ROOM_VARIABLES_UPDATE event and handle it like this:

sfs.addEventListener(SFSEvent.ROOM_VARIABLES_UPDATE, onRoomVarsUpdate);

// ...

private function onRoomVarsUpdate(evt:SFSEvent):void
{
    // An array of variable names that were updated for the Room
    var changedVars:Array = evt.params.changedVars as Array;
    
    // Obtain the variable and show the new value
    var topicRV:RoomVariable = sfs.lastJoinedRoom.getVariable("topic");
    
    trace("The Room topic is now set to: " + topicRV.getValue());
}

» Variables on the server-side

Using Variables on the server side is equally straightforward and uses the same interface and logic. Even if you still have to learn how to develop your own custom server side Extensions (see the Extensions Development sections), here you will find a couple of examples showing the principles of working with User and Room Variables in a Java Extension.

User Variables

Let's set a couple of User Variables. One of them will be exclusively server side, using the hidden property.

private void setUserProfile(User user, int databaseId)
{
    // public user var
    UserVariable avatarPic = new SFSUserVariable("pic", "GonzoTheGreat.jpg");
    
    // private user var
    UserVariable dbId = new SFSUserVariable("dbId", databaseId);
    dbId.setHidden(true);
    
    // Set variables via the server side API
    getApi().setUserVariables(user, Arrays.asList(avatarPic, dbId));
}

Room Variables

Let's take a look at Room Variables now. The interesting thing about creating them on the server side is that their "creator" will be the server itself. Just like from client side the creator is the user who sends the request.

This means that server-created Room Variables will never expire, in contrast to those generated with the client API. This can be used to maintain fully persistent values in any Room that requires it.

private void setupRoomVariables(Room room)
{
    // Private Global Room variable, no one will be able to overwrite this value
    // The topic will be visible from outside the Room
    RoomVariable chatTopic = new SFSRoomVariable("topic", "Multiplayer Game Development");
    chatTopic.setPrivate(true);
    chatTopic.setGlobal(true);
    
    // Secret variable, only accessible from server side
    RoomVariable isModerated = new SFSRoomVariable("isMod", true);
    isModerated.setHidden(true);
    
    // Set variables via the server side API
    // Passing null as the User parameter sets the ownership of the variables to the Server itself
    getApi().setRoomVariables(null, room, Arrays.asList(chatTopic, isModerated));
}

» Learning more

In order to learn more about Server Variables we recommend to check the specific server and client side API for your platform of choice. You find all the links on the left side menu under the API Documentation sections.