new SFSBuddyEvent()

Developers never istantiate the SFSBuddyEvent class: only use its static properties.

The constants contained in this class are used to register the event listeners; when an event is dispatched, an object containing event-specific parameters is passed to the listener. See the documentation below for a description of the parameters available for each event.

Example

This example shows the approach to be implemented to listen to events; please refer to the specific event types for the parameters object content.

function someMethod()
{
	sfs.addEventListener(SFS2X.SFSBuddyEvent.BUDDY_LIST_INIT, onBuddyListInitialized, this);
	sfs.addEventListener(SFS2X.SFSBuddyEvent.BUDDY_ERROR, onBuddyError, this)

	// Initialize the Buddy List system
	sfs.send(new SFS2X.InitBuddyListRequest());
}

function onBuddyListInitialized(evtParams)
{
	console.log("Buddy List system initialized successfully");

	// Retrieve my buddies list
	var buddies = evtParams.buddyList;

	// Display the online buddies in a list component in the application interface
	...
}

function onBuddyError(evtParams)
{
	console.log("The following error occurred while executing a buddy-related request: " + evtParams.errorMessage);
}

Properties

constant static

BUDDY_ADD  string

The buddyAdd event type, dispatched when a buddy is added successfully to the current user's buddy list.

This event is fired in response to the AddBuddyRequest request in case the operation is executed successfully.

The object passed to the listener contains the following parameters:
Property Type Description
buddy SFSBuddy The SFSBuddy object corresponding to the buddy that was added.

Example

This example sends a request to add a buddy.

function someMethod()
{
	sfs.addEventListener(SFS2X.SFSBuddyEvent.BUDDY_ADD, onBuddyAdded, this);
	sfs.addEventListener(SFS2X.SFSBuddyEvent.BUDDY_ERROR, onBuddyError, this);

	// Add Jack as a new buddy to my buddies list
	sfs.send(new SFS2X.AddBuddyRequest("Jack"));
}

function onBuddyAdded(evtParams)
{
	console.log("This buddy was added: " + evtParams.buddy.name);
}

function onBuddyError(evtParams)
{
	console.log("The following error occurred while executing a buddy-related request: " + evtParams.errorMessage);
}
See also
AddBuddyRequest
SFSBuddyEvent.BUDDY_ERROR
constant static

BUDDY_BLOCK  string

The buddyBlock event type, dispatched when a buddy is blocked or unblocked successfully by the current user.

This event is fired in response to the BlockBuddyRequest request in case the operation is executed successfully.

The object passed to the listener contains the following parameters:
Property Type Description
buddy SFSBuddy The SFSBuddy object corresponding to the buddy that was blocked/unblocked.

Example

This example handles the possible events caused by a request to block a buddy.

function someMethod()
{
	sfs.addEventListener(SFS2X.SFSBuddyEvent.BUDDY_BLOCK, onBuddyBlock, this);
	sfs.addEventListener(SFS2X.SFSBuddyEvent.BUDDY_ERROR, onBuddyError, this);

	// Block user "Jack" in my buddies list
	smartFox.send(new SFS2X.BlockBuddyRequest("Jack", true));
}

function onBuddyBlock(evtParams)
{
	var isBlocked = evtParams.buddy.isBlocked;
	console.log("Buddy " + evtParams.buddy.name + " is now " + (isBlocked ? "blocked" : "unblocked"));
}

function onBuddyError(evtParams)
{
	console.log("The following error occurred while executing a buddy-related request: " + evtParams.errorMessage);
}
See also
BlockBuddyRequest
SFSBuddyEvent.BUDDY_ERROR
constant static

BUDDY_ERROR  string

The buddyError event type, dispatched if an error occurs while executing a request related to the Buddy List system.

For example, this event is fired in response to the AddBuddyRequest request, the BlockBuddyRequest, etc.

The object passed to the listener contains the following parameters:
Property Type Description
errorMessage string A message containing the description of the error.
errorCode number The error code.

See the example provided in the BUDDY_ADD constant description.

See also
SFSBuddyEvent.BUDDY_ADD
constant static

BUDDY_LIST_INIT  string

The buddyListInit event type, dispatched if the Buddy List system is successfully initialized.

This event is fired in response to the InitBuddyListRequest request in case the operation is executed successfully.

After the Buddy List system initialization, the user returns to his previous custom state (if any - see SFSBuddyManager.getMyState() method). His online/offline state, his nickname and his persistent Buddy Variables are all loaded and broadcast in the system. In particular, the online state (see SFSBuddyManager.getMyOnlineState() method) determines if the user will appear online or not to other users who have him in their buddies list.

The object passed to the listener contains the following parameters:
Property Type Description
buddyList Array of SFSBuddyA list of SFSBuddy objects representing all the buddies in the current user's buddy list.
myVariablesArray of SFSBuddyVariableA list of all the Buddy Variables associated with the current user.

Example

This example initializes the Buddy List system.

function someMethod()
{
	sfs.addEventListener(SFS2X.SFSBuddyEvent.BUDDY_LIST_INIT, onBuddyListInitialized, this);
	sfs.addEventListener(SFS2X.SFSBuddyEvent.BUDDY_ERROR, onBuddyError, this)

	// Initialize the Buddy List system
	sfs.send(new SFS2X.InitBuddyListRequest());
}

function onBuddyListInitialized(evtParams)
{
	console.log("Buddy List system initialized successfully");

	// Retrieve my buddies list
	var buddies = evtParams.buddyList;

	// Display the online buddies in a list component in the application interface
	...
}

function onBuddyError(evtParams)
{
	console.log("The following error occurred while executing a buddy-related request: " + evtParams.errorMessage);
}
See also
InitBuddyListRequest
SFSBuddyManager
SFSBuddyEvent.BUDDY_ERROR
constant static

BUDDY_MESSAGE  string

The buddyMessage event type, dispatched when a message from a buddy is received by the current user.

This event is fired in response to the BuddyMessageRequest request.

NOTE: the same event is fired by the sender's client too, so that the user is aware that the message was delivered successfully to the recipient, and it can be displayed in the chat area keeping the correct message ordering. As in this case the value of the buddy parameter is null (because, being the sender, the user is not buddy to himself of course), there is no default way to know who the message was originally sent to. As this information can be useful in scenarios where the sender is chatting with more than one buddy at the same time in separate windows or tabs (and we need to write his own message in the proper one), the data parameter can be used to store, for example, the id of the recipient buddy.

The object passed to the listener contains the following parameters:
Property Type Description
buddy SFSBuddy The SFSBuddy object representing the message sender. If the isItMe parameter is true, the value of this parameter is null (because a user is not buddy to himself).
isItMe boolean true if the message sender is the current user himself (in this case this event is a sort of message delivery confirmation).
message string The message text.
data SFSObject A SFSObject containing additional custom parameters (e.g. the message color, an emoticon id, etc).

Example

This example sends a message to a buddy and handles the related event.

function someMethod()
{
	sfs.addEventListener(SFS2X.SFSBuddyEvent.BUDDY_MESSAGE, onBuddyMessage, this);

	// Get the recipient of the message, in this case my buddy Jack
	var buddy = sfs.buddyManager.getBuddyByName("Jack");

	// Send a message to Jack
	sfs.send(new SFS2X.BuddyMessageRequest("Hello Jack!", buddy));
}

function onBuddyMessage(evtParams)
{
	// As messages are forwarded to the sender too,
	// I have to check if I am the sender

	var isItMe = evtParams.isItMe;
	var sender = evtParams.buddy;

	if (isItMe)
		console.log("I said: " + evtParams.message);
	else
		console.log("My buddy " + sender.name + " said: " + evtParams.message);
}
See also
BuddyMessageRequest
constant static

BUDDY_ONLINE_STATE_CHANGE  string

The buddyOnlineStateChange event type, dispatched when a buddy in the current user's buddy list changes his online state in the Buddy List system.

This event is fired in response to the GoOnlineRequest request.

NOTE: this event is dispatched to those who have the user as a buddy, but also to the user himself. As in this case the value of the buddy parameter is null (because the user is not buddy to himself of course), the isItMe parameter should be used to check if the current user is the one who changed his own online state.

The object passed to the listener contains the following parameters:
Property Type Description
buddy SFSBuddy The SFSBuddy object representing the buddy who changed his own online state. If the isItMe parameter is true, the value of this parameter is null (because a user is not buddy to himself).
isItMe boolean true if the online state was changed by the current user himself (in this case this event is a sort of state change confirmation).

Example

This example changes the online state of the user in the Buddy List system.

function someMethod()
{
	sfs.addEventListener(SFS2X.SFSBuddyEvent.BUDDY_ONLINE_STATE_CHANGE, onBuddyOnlineStateChanged, this);

	// Put myself offline in the Buddy List system
	sfs.send(new SFS2X.GoOnlineRequest(false));
}

function onBuddyOnlineStateChanged(evtParams)
{
	// As the state change event is dispatched to me too,
	// I have to check if I am the one who changed his state

	var isItMe = evtParams.isItMe;

	if (isItMe)
		console.log("I'm now " + (sfs.buddyManager.getMyOnlineState() ? "online" : "offline"));
	else
		console.log("My buddy " + evtParams.buddy.name + " is now " + (evtParams.buddy.isOnline ? "online" : "offline"));
}
See also
GoOnlineRequest
constant static

BUDDY_REMOVE  string

The buddyRemove event type, dispatched when a buddy is removed successfully from the current user's buddy list.

This event is fired in response to the RemoveBuddyRequest request in case the operation is executed successfully.

The object passed to the listener contains the following parameters:
Property Type Description
buddy SFSBuddy The SFSBuddy object corresponding to the buddy that was removed.

Example

This example sends a request to remove a buddy.

function someMethod()
{
	sfs.addEventListener(SFS2X.SFSBuddyEvent.BUDDY_REMOVE, onBuddyRemoved, this);
	sfs.addEventListener(SFS2X.SFSBuddyEvent.BUDDY_ERROR, onBuddyError, this);

	// Remove Jack from my buddies list
	sfs.send(new SFS2X.RemoveBuddyRequest("Jack"));
}

function onBuddyRemoved(evtParams)
{
	console.log("This buddy was removed: " + evtParams.buddy.name);
}

function onBuddyError(evtParams)
{
	console.log("The following error occurred while executing a buddy-related request: " + evtParams.errorMessage);
}
See also
RemoveBuddyRequest
SFSBuddyEvent.BUDDY_ERROR
constant static

BUDDY_VARIABLES_UPDATE  string

The buddyVariablesUpdate event type, dispatched when a buddy in the current user's buddies list updates one or more Buddy Variables.

This event is fired in response to the SetBuddyVariablesRequest request.

NOTE: this event is dispatched to those who have the user as a buddy, but also to the user himself. As in this case the value of the buddy parameter is null (because the user is not buddy to himself of course) and the isItMe parameter should be used to check if the current user is the one who updated his own Buddy Variables.

The object passed to the listener contains the following parameters:
Property Type Description
buddy SFSBuddy The SFSBuddy object representing the buddy who updated his own Buddy Variables. If the isItMe parameter is true, the value of this parameter is null (because a user is not buddy to himself).
isItMe boolean true if the Buddy Variables were updated by the current user himself (in this case this event is a sort of update confirmation).
changedVars Array of string The list of names of the Buddy Variables that were changed (or created for the first time).

Example

This example sets some Buddy Variables for the current user, one of which is persistent and another one is the reserved variable used to set the nickname; the example also handles changes made by the user or by his buddies.

function someMethod()
{
	sfs.addEventListener(SFS2X.SFSBuddyEvent.BUDDY_VARIABLES_UPDATE, onBuddyVarsUpdate, this);

	// Create two Buddy Variables containing the title and artist of the song I'm listening to
	var songTitle = new SFS2X.SFSBuddyVariable("songTitle", "Ascension");
	var songAuthor = new SFS2X.SFSBuddyVariable("songAuthor", "Mike Oldfield");

	// Create a persistent Buddy Variable containing my mood message
	var mood = new SFS2X.SFSBuddyVariable(SFS2X.SFSBuddyVariable.OFFLINE_PREFIX + "mood", "SFS2X rocks!");

	// Set my nickname
	var nick = new SFS2X.SFSBuddyVariable(SFS2X.ReservedBuddyVariables.BV_NICKNAME, "Bax");

	// Set my Buddy Variables
	var vars = [songTitle, songAuthor, mood, nick];
	sfs.send(new SFS2X.SetBuddyVariablesRequest(vars));
}

function onBuddyVarsUpdate(evtParams)
{
	// As the update event is dispatched to me too,
	// I have to check if I am the one who changed his Buddy Variables

	var isItMe = evtParams.isItMe;

	if (isItMe)
	{
		console.log("I've updated the following Buddy Variables:");

		for (var i = 0; i < evtParams.changedVars.length; i++)
		{
			var bVarName = evtParams.changedVars[i];
			console.log(bVarName + " -->; " + sfs.buddyManager.getMyVariable(bVarName).value);
		}
	}
	else
	{
		var buddyName = evtParams.buddy.name;

		console.log("My buddy " + buddyName + " updated the following Buddy Variables:");

		for (var i = 0; i < evtParams.changedVars.length; i++)
		{
			var bVarName = evtParams.changedVars[i];
			console.log(bVarName + " --> " + sfs.buddyManager.getBuddyByName(buddyName).getVariable(bVarName).value);
		}
	}
}
See also
SetBuddyVariablesRequest
SFSBuddyVariable