Class SFS2X.SFSBuddyEvent
The Buddy List related event types dispatched by the SmartFoxServer 2X JavaScript API.
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.
The following 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.Requests.BuddyList.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);
}
Field Summary
Field Detail
This event is fired in response to the AddBuddyRequest request in case the operation is executed successfully.
| Property | Type | Description |
|---|---|---|
| buddy | {SFSBuddy} | The SFSBuddy object corresponding to the buddy that was added. |
The following 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.Requests.BuddyList.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:
- SFS2X.Requests.BuddyList.AddBuddyRequest
- SFS2X.Entities.SFSBuddy
- SFS2X.SFSBuddyEvent.BUDDY_ERROR
This event is fired in response to the BlockBuddyRequest request in case the operation is executed successfully.
| Property | Type | Description |
|---|---|---|
| buddy | {SFSBuddy} | The SFSBuddy object corresponding to the buddy that was blocked/unblocked. |
The following 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.Requests.BuddyList.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:
- SFS2X.Requests.BuddyList.BlockBuddyRequest
- SFS2X.Entities.SFSBuddy
- SFS2X.SFSBuddyEvent.BUDDY_ERROR
For example, this event is fired in response to the AddBuddyRequest request, the BlockBuddyRequest, etc.
| 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:
- SFS2X.SFSBuddyEvent.BUDDY_ADD
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 BuddyManager.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 BuddyManager.getMyOnlineState method) determines if the user will appear online or not to other users who have him in their buddies list.
| Property | Type | Description |
|---|---|---|
| buddyList | {Array} | A list of SFSBuddy objects representing all the buddies in the current user's buddy list. |
| myVariables | {Array} | A list of all the Buddy Variables associated with the current user. |
The following 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.Requests.BuddyList.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:
- SFS2X.Requests.BuddyList.InitBuddyListRequest
- SFS2X.Managers.BuddyManager
- SFS2X.Entities.SFSBuddy
- SFS2X.Entities.Variables.SFSBuddyVariable
- SFS2X.SFSBuddyEvent.BUDDY_ERROR
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.
| 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 | {Object} | An object containing additional custom parameters (e.g. the message color, an emoticon id, etc). |
The following 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.Requests.BuddyList.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);
}
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.
| 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). |
The following 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.Requests.BuddyList.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"));
}
This event is fired in response to the RemoveBuddyRequest request in case the operation is executed successfully.
| Property | Type | Description |
|---|---|---|
| buddy | {SFSBuddy} | The SFSBuddy object corresponding to the buddy that was removed. |
The following 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.Requests.BuddyList.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:
- SFS2X.Requests.BuddyList.RemoveBuddyRequest
- SFS2X.Entities.SFSBuddy
- SFS2X.SFSBuddyEvent.BUDDY_ERROR
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.
| 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} | The list of names of the Buddy Variables that were changed (or created for the first time). |
The following 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.Entities.Variables.SFSBuddyVariable("songTitle", "Ascension");
var songAuthor = new SFS2X.Entities.Variables.SFSBuddyVariable("songAuthor", "Mike Oldfield");
// Create a persistent Buddy Variable containing my mood message
var mood = new SFS2X.Entities.Variables.SFSBuddyVariable(SFS2X.Entities.Variables.SFSBuddyVariable.OFFLINE_PREFIX + "mood", "SFS2X rocks!");
// Set my nickname
var nick = new SFS2X.Entities.Variables.SFSBuddyVariable(SFS2X.Entities.Variables.ReservedBuddyVariables.BV_NICKNAME, "Bax");
// Set my Buddy Variables
var vars = [songTitle, songAuthor, mood, nick];
sfs.send(new SFS2X.Requests.BuddyList.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);
}
}
}