Classes

Classes

Class SFS2X.SmartFox

The SmartFoxServer 2X JavaScript API main class.

Class Summary
Constructor Attributes Constructor Name and Description
 
SFS2X.SmartFox(configObj)
Creates a new SmartFox instance.

Field Summary

Method Summary

Class Detail

SFS2X.SmartFox(configObj)
Creates a new SmartFox instance.

The SmartFox class is responsible for connecting the client to a SmartFoxServer instance and for dispatching all asynchronous events. Developers always interact with SmartFoxServer through this class.
For detailed informations please check our website: http://www.smartfoxserver.com.

The SmartFox instance can be configured through a configuration object with the following properties (all optional):

PropertyTypeDescription
host{String}The IP address or host name of the SmartFoxServer 2X instance to connect to.
port{Number}The TCP port of the SmartFoxServer 2X instance to connect to.
useSSL{Boolean}Use an encrypted SSL connection.
zone{String}The Zone of the SmartFoxServer 2X instance to join during the login process.
debug{Boolean}Indicates whether the client-server messages console debug should be enabled or not.

The following example instantiates the SmartFox class passing a configuration object; please notice that in the examples provided throughout the documentation, sfs always indicates a SmartFox instance:

function init()
{
	// Create configuration object
	var config = {};
	config.host = "127.0.0.1";
	config.port = 8888;
	config.useSSL = false;
	config.zone = "BasicExamples";
	config.debug = false;

	// Create SmartFox client instance
	sfs = new SmartFox(config);
}
Parameters:
{Object} configObj Optional
The client configuration data.

Field Detail

{BuddyManager} buddyManager
Returns a reference to the Buddy Manager.

This manager is used internally by the SmartFoxServer 2X API; the reference returned by this property gives access to the buddies list, allowing interaction with Buddy and BuddyVariable objects and access to user properties in the Buddy List system.

See also:
SFS2X.Managers.BuddyManager
{Object} config
Returns the client configuration object passed during the SmartFox instance creation.
{Boolean} debug
Indicates whether the client-server messages console debug is enabled or not.

If set to true, detailed debugging informations for all the incoming and outgoing messages are provided in the browser's debug console (if available).
Debugging can be enabled when instantiating the SmartFox class too by means of the configuration object.

{SFSRoom} lastJoinedRoom
Returns the object representing the last Room joined by the client, if any.

This property is null if no Room was joined.

NOTE: setting the lastJoinedRoom property manually can disrupt the API functioning. Use the JoinRoomRequest request to join a new Room instead.

See also:
#getJoinedRooms
SFS2X.Requests.System.JoinRoomRequest
{Logger} logger
Returns a reference to the internal Logger instance used by SmartFoxServer 2X.
See also:
SFS2X.Logger
{SFSUser} mySelf
Returns the SFSUser object representing the client itself when connected to a SmartFoxServer 2X instance.

This object is generated upon successful login only, so it is null if login was not performed yet.

NOTE: setting the mySelf property manually can disrupt the API functioning.

See also:
SFS2X.Entities.SFSUser#isItMe
SFS2X.Requests.System.LoginRequest
{RoomManager} roomManager
Returns a reference to the Room Manager.

This manager is used internally by the SmartFoxServer 2X API; the reference returned by this property gives access to the Rooms list and Groups, allowing interaction with SFSRoom objects.

See also:
SFS2X.Managers.RoomManager
{String} sessionToken
Returns the unique session token of the client.

The session token is a string sent by the server to the client after the initial handshake.
It is required as mean of identification when uploading files to the server (see specific documentation).

{UserManager} userManager
Returns a reference to the User Manager.

This manager is used internally by the SmartFoxServer 2X API; the reference returned by this property gives access to the users list, allowing interaction with SFSUser objects.

See also:
SFS2X.Managers.UserManager
{String} version
Returns the current version of the SmartFoxServer 2X JavaScript API.

Method Detail

  • addEventListener(evtType, listener, scope)
    Registers an event listener function that will receive notification of an event.

    If you no longer need an event listener, remove it by calling the removeEventListener() method, or memory problems could result. In fact event listeners are not automatically removed from memory.

    The following example shows how to add a number of common event listeners to the SmartFox instance, usually during initialization:

    function init()
{
	sfs = new SmartFox();
	
	sfs.addEventListener(SFS2X.SFSEvent.CONNECTION, onConnection, this);
	sfs.addEventListener(SFS2X.SFSEvent.CONNECTION_LOST, onConnectionLost, this);
	sfs.addEventListener(SFS2X.SFSEvent.LOGIN_ERROR, onLoginError, this);
	sfs.addEventListener(SFS2X.SFSEvent.LOGIN, onLogin, this);
	sfs.addEventListener(SFS2X.SFSEvent.LOGOUT, onLogout, this);
	sfs.addEventListener(SFS2X.SFSEvent.ROOM_JOIN_ERROR, onRoomJoinError, this);
	sfs.addEventListener(SFS2X.SFSEvent.ROOM_JOIN, onRoomJoin, this);
}
    Parameters:
    {String} evtType
    The type of event to listen to, among those available in the SFSevent and SFSBuddyEvent classes.
    {Function} listener
    The listener function that processes the event. This function should accept an object as its only parameter, which in turn contains the event parameters.
    {Number} scope
    The object that acts as a context for the event listener: it is the object that acts as a "parent scope" for the callback function, thus providing context (i.e. access to variables and other mehtods) to the function itself.
    See also:
    SFS2X.SFSEvent
    SFS2X.SFSBuddyEvent
    #removeEventListener
  • connect(host, port, useSSL)
    Establishes a connection between the client and a SmartFoxServer 2X instance.

    If no argument is passed, the client will use the settings passed during the SmartFox class instantiation.

    The following example connects to a local SmartFoxServer 2X instance:

    function someMethod()
{
	sfs = new SmartFox();
	sfs.addEventListener(SFS2X.SFSEvent.CONNECTION, onConnection, this);
	
	// Connect
	sfs.connect(127.0.0.1, 9933);
}

function onConnection(evtParams)
{
	if (evtParams.success)
		console.log("Connection established");
	else
		console.log("Connection failed");
}
    Parameters:
    {String} host Optional
    The address of the server to connect to.
    {Number} port Optional
    The TCP port to connect to.
    {Boolean} useSSL Optional
    Use an encrypted SSL connection.
    See also:
    #disconnect
    SFS2X.SFSEvent.CONNECTION
  • disconnect()
    Closes the connection between the client and the SmartFoxServer 2X instance.
    See also:
    #connect
    SFS2X.SFSEvent.CONNECTION_LOST
  • enableLagMonitor(enabled, interval, queueSize)
    Enables the automatic realtime monitoring of the lag between the client and the server (round robin).

    When turned on, the pingPong event type is dispatched continuously, providing the average of the last ten measured lag values. The lag monitoring is automatically halted when the user logs out of a Zone or gets disconnected.

    NOTE: the lag monitoring can be enabled after the login has been performed successfully only.

    Parameters:
    {Boolean} enabled
    The lag monitoring status: true to start the monitoring, false to stop it.
    {Number} interval Optional, Default: 4
    The amount of seconds to wait between each query (recommended 3-4s).
    {Number} queueSize Optional, Default: 10
    The amount of values stored temporarily and used to calculate the average lag.
    See also:
    SFS2X.SFSEvent.PING_PONG
  • {Array} getJoinedRooms()
    Returns a list of SFSRoom objects representing the Rooms currently joined by the client.

    NOTE: the same list is returned by the RoomManager.getJoinedRooms() method, accessible through the roomManager property; this was replicated on the SmartFox class for handy access due to its usually frequent usage.

    Returns:
    {Array} The list of SFSRoom objects representing the Rooms joined by the client.
    See also:
    #lastJoinedRoom
    #roomManager
    SFS2X.Entities.SFSRoom
    SFS2X.Requests.System.JoinRoomRequest
  • {Number} getMaxMessageSize()
    Returns the maximum size of messages allowed by the server.

    Any request exceeding this size will not be sent. The value is determined by the server configuration.

    Returns:
    {Number} The maximum size of messages allowed by the server.
  • {SFSRoom} getRoomById(id)
    Retrieves a SFSRoom object from its id.

    NOTE: the same object is returned by the RoomManager.getRoomById() method, accessible through the roomManager property; this was replicated on the SmartFox class for handy access due to its usually frequent usage.

    The following example retrieves a SFSRoom object and traces its name:

    var roomId = 3;
var room = sfs.getRoomById(roomId);
console.log("The name of Room " + roomId + " is " + room.name);
    Parameters:
    {Number} id
    The id of the Room.
    Returns:
    {SFSRoom} The object representing the requested Room; null if no SFSRoom object with the passed id exists in the Rooms list.
    See also:
    #getRoomByName
    SFS2X.Managers.RoomManager#getRoomById
    SFS2X.Entities.SFSRoom
  • {SFSRoom} getRoomByName(name)
    Retrieves a SFSRoom object from its name.

    NOTE: the same object is returned by the RoomManager.getRoomByName() method, accessible through the roomManager property; this was replicated on the SmartFox class for handy access due to its usually frequent usage.

    The following example retrieves a SFSRoom object and traces its id:

    var roomName = "The Lobby";
var room = sfs.getRoomByName(roomName);
console.log("The ID of Room '" + roomName + "' is " + room.id);
    Parameters:
    {String} name
    The name of the Room.
    Returns:
    {SFSRoom} The object representing the requested Room; null if no SFSRoom object with the passed name exists in the Rooms list.
    See also:
    #getRoomById
    SFS2X.Managers.RoomManager#getRoomByName
    SFS2X.Entities.SFSRoom
  • {Array} getRoomList()
    Returns the list of SFSRoom objects representing the Rooms currently "watched" by the client.

    The list contains all the Rooms that are currently joined and all the Rooms belonging to the Room Groups that have been subscribed by the client.

    NOTE 1: at login time, the client automatically subscribes all the Room Groups specified in the Zone's Default Room Groups setting.

    NOTE 2: the same list is returned by the RoomManager.getRoomList() method, accessible through the roomManager property; this was replicated on the SmartFox class for handy access due to its usually frequent usage.

    Returns:
    {Array} The list of SFSRoom objects representing the Rooms available on the client.
    See also:
    #roomManager
    SFS2X.Requests.System.JoinRoomRequest
    SFS2X.Requests.System.SubscribeRoomGroupRequest
    SFS2X.Requests.System.UnsubscribeRoomGroupRequest
  • {Array} getRoomListFromGroup(groupId)
    Retrieves the list of Rooms which are part of the specified Room Group.

    NOTE: the same list is returned by the RoomManager.getRoomListFromGroup() method, accessible through the roomManager property; this was replicated on the SmartFox class for handy access due to its usually frequent usage.

    Parameters:
    {String} groupId
    The name of the Group.
    Returns:
    {Array} The list of SFSRoom objects belonging to the passed Group.
    See also:
    SFS2X.Managers.RoomManager#getRoomListFromGroup
    SFS2X.Entities.SFSRoom
  • {Boolean} isConnected()
    Indicates whether the client is connected to the server or not.

    The following example checks the connection status:

    console.log("Am I connected? " + sfs.isConnected());
    Returns:
    {Boolean} true if the client is connected.
  • removeEventListener(evtType, listener)
    Removes an event listener.
    Parameters:
    {String} evtType
    The type of event to remove, among those available in the SFSevent and SFSBuddyEvent classes.
    {Function} listener
    The listener function to be removed.
    See also:
    SFS2X.SFSEvent
    SFS2X.SFSBuddyEvent
    #addEventListener
  • send(request)
    Sends a request to the server.

    All the available request objects can be found under the SFS2X.Requests namespace.

    Example #1 below shows how to sends a login request.

    Example #2 sends a "join room" request.

    Example #3 creates an object containing some parameters and sends it to the server-side Extension.

    // Example 1
sfs.send(new SFS2X.Requests.System.LoginRequest("KermitTheFrog", "kermitPwd", null, "TheMuppetZone"));

// Example 2
sfs.send(new SFS2X.Requests.System.JoinRoomRequest("Lobby"));

// Example 3
var params = {};
params.x = 10;
params.y = 37;

sfs.send(new SFS2X.Requests.System.ExtensionRequest("setPosition", params));
    Parameters:
    {<any>Request} request
    A request object.
  • setClientDetails(platformId, version)
    Allows to specify custom client details that will be used to gather statistics about the client platform via the AdminTool's Analytics Module.

    By default no details are sent and the client type is the generic "JavaScript".

    NOTE: this method must be called before the connection is started. The length of the two strings combined must be less than 512 characters.

    Parameters:
    {String} platformId
    An identification string for the client, like the browser name for example.
    {String} version
    An additional string to describe the client version, like the browser version for example.