Examples (iOS)
Examples (Android)

 

» 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 in Actionscript 3. We chose this language because it is commonly used and very similar to C# and Java. Transposing the examples to any of the other API languagse requires almost no effort.

Using Variables on the Server side is equally straightforward and uses the same interface and logic.

Finally Buddy Variables are 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 hanlde 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

The following examples demonstrate how to work with User and Room Variables in your server side Extensions, written in Java.

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 set a look 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 section.