package it.gotoandplay.smartfoxclient;

import it.gotoandplay.smartfoxclient.data.Room;
import it.gotoandplay.smartfoxclient.data.SFSObject;

/**
 * <p>
 * {@code SFSEvent} is the class representing all events dispatched by the {@link SmartFoxClient} instance.
 * The SFSEvent class provides a public method called {@link #getParams} that returns object
 * of type {@link SFSObject} that can contain any number of parameters.
 * In the rest of the documentation this object is refered as {@code params} object.
 * </p>
 * 
 * <p>
 * The following example show a generic usage of a SFSEvent.
 * Please refer to the specific events for the {@code params} object content.
 * 
 * <pre>
 * package sfsTest;
 * 
 * import it.gotoandplay.smartfoxclient.ISFSEventListener;
 * import it.gotoandplay.smartfoxserver.SmartFoxClient;
 * import it.gotoandplay.smartfoxserver.SFSEvent;
 * 
 * public class MyTest implements ISFSEventListener
 * {
 *     private SmartFoxClient smartFox;
 *
 *     public MyTest()
 *     {
 *         // Create instance
 *         smartFox = new SmartFoxClient();
 *
 *         // Add event handler for connection 
 *         smartFox.addEventListener(SFSEvent.onConnection, this);
 *
 *         // Connect to server
 *         smartFox.connect("127.0.0.1", 9339);	
 *     }
 *
 *     // Handle SFS events 
 *     public void handleEvent(SFSEvent event)
 *     {
 *         // Handle connection event
 *         if(event.getName().equals(SFSEvent.onConnection))
 *         {
 *             if(event.getParams().getBool("success"))
 *             {
 *                 System.out.println("Great, successfully connected!");
 *             }
 *             else
 *             {
 *                 System.out.println("Ouch, connection failed!");
 *             }
 *         }
 *     }
 * }
 * </pre>
 * </p>
 * <p>
 * <b>NOTE</b>: In the following examples, {@code smartFox} always indicates a SmartFoxClient instance.
 * </p>
 * 
 * @version 1.1.0
 * 
 * @author The gotoAndPlay() Team<br>
 * 
 *         <a href="http://www.smartfoxserver.com">http://www.smartfoxserver.com</a><br>
 *         <a href="http://www.gotoandplay.it">http://www.gotoandplay.it</a><br>
 */
public class SFSEvent
{
    /**
     * <p>
     * Dispatched when a message from the Administrator is received.
     * </p>
     * 
     * <p>
     * Admin messages are special messages that can be sent by an Administrator to a user or group of users.
     * All client applications should handle this event,
     * or users won't be be able to receive important admin notifications!
     * </p>
     * 
     * <p>
     * The {@code params} object contains the following parameters.
     * </p>
     * <ul>
     * <li>
     * message ({@code String}): the Administrator's message.
     * </li>
     * </ul>
     * 
     * <p>
     * The following example shows how to handle a message coming from the Administrator.
     * <pre>
     * smartFox.addEventListener(SFSEvent.onAdminMessage, this);
     * 			
     * public void handleEvent(SFSEvent event)
     * {
     *     if(event.getName().equals(SFSEvent.onAdminMessage))
     *     {
     *         System.out.println(getParams().getString("message"));
     *     }
     * }
     * </pre>
     * </p>
     * 
     * @see #onModeratorMessage
     * 
     * @since SmartFoxServer Basic / Pro v1.x.x
     */
    public static final String onAdminMessage = "onAdminMessage";


    /**
     * Dispatched when the buddy list for the current user is received or a buddy is added/removed.
     * 
     * <p>
     * The {@code params} object contains the following parameters.
     * </p>
     * <ul>
     * <li>
     * list ({@code List<Buddy>}): the buddy list.
     * </li>
     * </ul>
     * 
     * <p>
     * The following example shows how to retrieve the properties of each buddy when the buddy list is received.
     * <pre>
     * smartFox.addEventListener(SFSEvent.onBuddyList, new ISFSEventHandler()
     *   {
     *       public void handleEvent(SFSEvent evt)
     *       {
     *           for(Buddy buddy : smartFox.buddyList)
     *           {
     * 
     *               // Trace buddy properties
     *               System.out.println("Buddy id: " + buddy.getId());
     *               System.out.println("Buddy name: " + buddy.getName());
     *               System.out.println("Is buddy online? " + (buddy.isOnline() ? "Yes" : "No"));
     *               System.out.println("Is buddy blocked? " + (buddy.isBlocked() ? "Yes" : "No"));
     * 
     *               // Trace all Buddy Variables
     *               for(String key : buddy.getVariables().keySet())
     *               {
     *                   System.out.println("\t" + key + " --> " + buddy.getVariables().get(key));
     *               }
     *           }
     *       }
     *   });
     * smartFox.loadBuddyList();
     * </pre>
     * </p>
     * 
     * @see #onBuddyListError
     * @see #onBuddyListUpdate
     * @see #onBuddyRoom
     * @see SmartFoxClient#buddyList
     * @see SmartFoxClient#loadBuddyList
     * @see SmartFoxClient#addBuddy
     * @see SmartFoxClient#removeBuddy
     * 
     * @since SmartFoxServer Basic / Pro v1.x.x
     */
    public static final String onBuddyList = "onBuddyList";

    /**
     * Dispatched when an error occurs while loading the buddy list.
     * 
     * <p>
     * The {@code params} object contains the following parameters.
     * </p>
     * <ul>
     * <li>
     * error ({@code String}): the error message.
     * </li>
     * </ul>
     * 
     * <p>
     * The following example shows how to handle a potential error in buddy list loading.
     * <pre>
     * smartFox.addEventListener(SFSEvent.onBuddyListError, new ISFSEventHandler()
     *   {
     *       public void handleEvent(SFSEvent evt)
     *       {
     *           System.out.println("An error occurred while loading the buddy list: " + evt.getParams().getString("error"));
     *       }
     *   });
     * smartFox.loadBuddyList();
     * </pre>
     * </p>
     * 
     * @see #onBuddyList
     * 
     * @since SmartFoxServer Basic / Pro v1.x.x
     */
    public static final String onBuddyListError = "onBuddyListError";


    /**
     * Dispatched when the status or variables of a buddy in the buddy list change.
     * 
     * <p>
     * The {@code params} object contains the following parameters.
     * </p>
     * <ul>
     * <li>
     * buddy ({@code Buddy}): the buddy whose status or Buddy Variables have changed.
     * </li>
     * </ul>
     * 
     * <p>
     * The following example shows how to handle the online status change of a buddy.
     * <pre>
     * smartFox.addEventListener(SFSEvent.onBuddyListUpdate, new ISFSEventHandler()
     *   {
     *       public void handleEvent(SFSEvent evt)
     *       {
     *           Buddy buddy = (Buddy)evt.getParams().get("buddy");
     *           String name = buddy.getName();
     *           String status = (buddy.isOnline()) ? "online" : "offline";
     * 		 System.out.println("Buddy " + name + " is currently " + status);
     *       }
     *   });
     * </pre>
     * </p>
     * 
     * @see #onBuddyList
     * @see SmartFoxClient#buddyList
     * @see SmartFoxClient#setBuddyBlockStatus
     * @see SmartFoxClient#setBuddyVariables
     * 
     * @since SmartFoxServer Basic / Pro v1.x.x
     */
    public static final String onBuddyListUpdate = "onBuddyListUpdate";


    /**
     * Dispatched when the current user receives a request to be added to the buddy list of another user.
     * 
     * <p>
     * The {@code params} object contains the following parameters.
     * </p>
     * <ul>
     * <li>
     * sender ({@code String}): the name of the user requesting to add the current user to his/her buddy list.
     * </li>
     * <li>
     * message ({@code String}): a message accompaining the permission request.
     *                           This message can't be sent from the client-side, but it's part of the
     *                           advanced server-side buddy list features.
     * </li>
     * </ul>
     * 
     * <p>
     * The following example shows how to handle the request to be added to a buddy list.
     * <pre>
     * smartFox.addEventListener(SFSEvent.onBuddyPermissionRequest, new ISFSEventHandler()
     *   {
     *       public void handleEvent(SFSEvent evt)
     *       {
     *           System.out.println(evt.getParams().getString("sender") + "wants to add you to his/her buddy list: " + evt.getParams().getString("message"));
     *       }
     *   });
     * </pre>
     * </p>
     * 
     * @see SmartFoxClient#addBuddy
     * 
     * @since SmartFoxServer Pro v1.6.0
     */
    public static final String onBuddyPermissionRequest = "onBuddyPermissionRequest";


    /**
     * Dispatched in response to a {@link SmartFoxClient#getBuddyRoom} request.
     * 
     * <p>
     * The {@code params} object contains the following parameters.
     * </p>
     * <ul>
     * <li>
     * idList ({@code int[]}): the list of id of the rooms in which the buddy is currently logged;
     *                         if users can't be present in more than one room at the same time,
     *                         the list will contain one room id only, at 0 index.
     * </li>
     * </ul>
     * 
     * <p>
     * The following example shows how to join the same room in which the buddy currently is.
     * <pre>
     * smartFox.addEventListener(SFSEvent.onBuddyRoom, new ISFSEventHandler()
     *   {
     *       public void handleEvent(SFSEvent evt)
     *       {
     *           int[]  = (int[])evt.getParams().get("idList");
     *           // Reach the buddy in his room
     *           smartFox.join(idList[0]);
     *       }
     *   });
     * Buddy buddy = smartFox.getBuddyByName("jack");
     * smartFox.getBuddyRoom(buddy);
     * </pre>
     * </p>
     * 
     * @see SmartFoxClient#getBuddyRoom
     * 
     * @since SmartFoxServer Basic / Pro v1.x.x
     */
    public static final String onBuddyRoom = "onBuddyRoom";


    /**
     * Dispatched when an error occurs while loading the external SmartFoxClient configuration file.
     * 
     * <p>
     * The {@code params} object contains the following parameters.
     * </p>
     * <ul>
     * <li>
     * message ({@code String}): the error message.
     * </li>
     * </ul>
     * 
     * <p>
     * The following example shows how to handle a potential error in configuration loading.
     * <pre>
     * smartFox.addEventListener(SFSEvent.onConfigLoadFailure, new ISFSEventHandler()
     *   {
     *       public void handleEvent(SFSEvent evt)
     *       {
     *           System.out.println("Failed loading config file: " +
     *             evt.getParams().getString("message"));
     *       }
     *   });
     * smartFox.loadConfig("testEnvironmentConfig.xml");
     * </pre>
     * </p>
     * 
     * @see #onConfigLoadSuccess
     * @see SmartFoxClient#loadConfig
     * 
     * @since SmartFoxServer Pro v1.6.0
     */
    public static final String onConfigLoadFailure = "onConfigLoadFailure";


    /**
     * Dispatched when the external SmartFoxClient configuration file has been loaded successfully.
     * <p>
     * This event is dispatched only if the <i>autoConnect</i> parameter of the
     * {@link SmartFoxClient#loadConfig} method is set to {@code true}; otherwise the connection is made and
     * the {@link #onConnection} event fired.
     * </p>
     * 
     * <p>
     * No parameters are provided.
     * </p>
     * 
     * <p>
     * The following example shows how to handle a successful configuration loading.
     * <pre>
     * smartFox.addEventListener(SFSEvent.onConfigLoadSuccess, new ISFSEventHandler()
     *   {
     *       public void handleEvent(SFSEvent evt)
     *       {
     *           System.out.println("Config file loaded, now connecting...");
     *           smartFox.connect(smartFox.ipAddress, smartFox.port);
     *       }
     *   });
     * smartFox.loadConfig("testEnvironmentConfig.xml", false);
     * </pre>
     * </p>
     * 
     * @see #onConfigLoadFailure
     * @see SmartFoxClient#loadConfig
     * 
     * @since SmartFoxServer Pro v1.6.0
     */
    public static final String onConfigLoadSuccess = "onConfigLoadSuccess";



    /**
     * Dispatched in response to the {@link SmartFoxClient#connect} request.
     * <p>
     * The connection to SmartFoxServer may have succeeded or failed:
     * the <i>success</i> parameter must be checked.
     * </p>
     * 
     * <p>
     * The {@code params} object contains the following parameters.
     * </p>
     * <ul>
     * <li>
     * success ({@code Boolean}): the connection result: {@code true} if the connection succeeded,
     *                            {@code false} if the connection failed.
     * </li>
     * <li>
     * error ({@code String}): the error message in case of connection failure.
     * </li>
     * </ul>
     * 
     * <p>
     * The following example shows how to handle the connection result.
     * <pre>
     * smartFox.addEventListener(SFSEvent.onConnection, new ISFSEventHandler()
     *   {
     *       public void handleEvent(SFSEvent evt)
     *       {
     *           if(evt.getParams().getBool("success"))
     *           {
     *               System.out.println("Connection successful");
     *           }
     *           else
     *           {
     *               System.out.println("Connection failed");
     *           }
     *       }
     *   });
     * smartFox.connect("127.0.0.1", 9339);
     * </pre>
     * </p>
     * 
     * @see SmartFoxClient#connect
     * 
     * @since SmartFoxServer Basic / Pro v1.x.x
     */
    public static final String onConnection = "onConnection";


    /**
     * Dispatched when the connection with SmartFoxServer is closed (either from the client or from the server).
     * 
     * <p>
     * No parameters are provided.
     * </p>
     * 
     * <p>
     * The following example shows how to handle the connection result.
     * <pre>
     * smartFox.addEventListener(SFSEvent.onConnectionLost, new ISFSEventHandler()
     *   {
     *       public void handleEvent(SFSEvent evt)
     *       {
     *           System.out.println("Connection lost!");
     *       }
     *   });
     * </pre>
     * </p>
     * 
     * @see SmartFoxClient#disconnect
     * 
     * @since SmartFoxServer Basic / Pro v1.x.x
     */
    public static final String onConnectionLost = "onConnectionLost";


    /**
     * Dispatched when an error occurs during the creation of a room.
     * Usually this happens when a client tries to create a room but its name is already taken.
     * 
     * <p>
     * The {@code params} object contains the following parameters.
     * </p>
     * <ul>
     * <li>
     * error ({@code String}): the error message.
     * </li>
     * </ul>
     * 
     * <p>
     * The following example shows how to handle a potential error in room creation.
     * <pre>
     * smartFox.addEventListener(SFSEvent.onCreateRoomError, new ISFSEventHandler()
     *   {
     *       public void handleEvent(SFSEvent evt)
     *       {
     *           System.out.println("Room creation error; the following error occurred: " + evt.getParams().getString("error"));
     *       }
     *   });
     * 
     * Map&lt;String, Object&gt; roomProperties = new HashMap&lt;String, Object&gt;();
     * roomProperties.put("isGame", true);
     * Map&lt;String, RoomVariableRequest&gt; variables = new HashMap&lt;String, RoomVariableRequest&gt;();
     * variables.put("ogres", new RoomVariableRequest("5", SFSVariable.TYPE_NUMBER, true));
     * variables.put("skeletons", new RoomVariableRequest("4", SFSVariable.TYPE_NUMBER));
     * roomProperties.put("vars", variables);
     * smartFox.createRoom("The Cave", 15, roomProperties);
     * </pre>
     * </p>
     * 
     * @see SmartFoxClient#createRoom
     * 
     * @since SmartFoxServer Basic / Pro v1.x.x
     */
    public static final String onCreateRoomError = "onCreateRoomError";


    /**
     * Dispatched when a debug message is traced by the SmartFoxServer API.
     * <p>
     * In order to receive this event you have to enable debug messages.
     * </p>
     * 
     * <p>
     * The {@code params} object contains the following parameters.
     * </p>
     * <ul>
     * <li>
     * message ({@code String}): the debug message.
     * </li>
     * </ul>
     * 
     * <p>
     * The following example shows how to handle a potential error in room creation.
     * <pre>
     * smartFox.addEventListener(SFSEvent.onDebugMessage, new ISFSEventHandler()
     *   {
     *       public void handleEvent(SFSEvent evt)
     *       {
     *           System.out.println("[SFS DEBUG] : " + evt.getParams().getString("message"));
     *       }
     *   });
     * 
     * Map&lt;String, Object&gt; roomProperties = new HashMap&lt;String, Object&gt;();
     * roomProperties.put("isGame", true);
     * Map&lt;String, RoomVariableRequest&gt; variables = new HashMap&lt;String, RoomVariableRequest&gt;();
     * variables.put("ogres", new RoomVariableRequest("5", SFSVariable.TYPE_NUMBER, true));
     * variables.put("skeletons", new RoomVariableRequest("4", SFSVariable.TYPE_NUMBER));
     * roomProperties.put("vars", variables);
     * smartFox.createRoom("The Cave", 15, roomProperties);
     * </pre>
     * </p>
     * 
     * @see SmartFoxClient#setDebug(boolean)
     * 
     * @since SmartFoxServer Basic / Pro v1.x.x
     */
    public static final String onDebugMessage = "onDebugMessage";


    /**
     * Dispatched when a command/response from a server-side extension is received.
     * 
     * <p>
     * The {@code params} object contains the following parameters.
     * </p>
     * <ul>
     * <li>
     * dataObj : an object containing all the data sent by the server-side extension.
     *           The object type depends on the protocol type. {@code SFSObject} for XML protocol,
     *           {@code JSONObject} for JSON protocol and {@code String[]} for String protocol.
     *           By convention, a String property called <b>_cmd</b> should always be present,
     *           to distinguish between different responses coming from the same extension
     *           (in case of String protocol the element at zero index of the array).
     * </li>
     * <li>
     * type ({@code String}): one of the following response protocol types:
     *                        {@link SmartFoxClient#XTMSG_TYPE_XML},
     *                        {@link SmartFoxClient#XTMSG_TYPE_STR},
     *                        {@link SmartFoxClient#XTMSG_TYPE_JSON}.
     *                        By default {@link SmartFoxClient#XTMSG_TYPE_XML} is used.
     * </li>
     * </ul>
     * 
     * <p>
     * The following example shows how to handle an extension response.
     * <pre>
     * smartFox.addEventListener(SFSEvent.onExtensionResponse, new ISFSEventHandler()
     *   {
     *       public void handleEvent(SFSEvent evt)
     *       {
     *           String type = evt.getParams().getString("type");
     *           Object data = evt.getParams().get("dataObj");
     * 
     *           // Handle XML responses
     *           if(type.equals(SmartFoxClient.XTMSG_TYPE_XML))
     *           {
     *               // TODO: check command and perform required actions
     *           }
     *           // Handle RAW responses
     *           else if(type.equals(SmartFoxClient.XTMSG_TYPE_STR))
     *           {
     *               // TODO: check command and perform required actions
     *           }
     *           // Handle JSON responses
     *           else if(type.equals(SmartFoxClient.XTMSG_TYPE_JSON))
     *           {
     *               // TODO: check command and perform required actions
     *           }
     *       }
     *   });
     * </pre>
     * </p>
     * 
     * @see SmartFoxClient#XTMSG_TYPE_XML
     * @see SmartFoxClient#XTMSG_TYPE_STR
     * @see SmartFoxClient#XTMSG_TYPE_JSON
     * @see SmartFoxClient#sendXtMessage
     * 
     * @since SmartFoxServer Pro v1.x.x
     */
    public static final String onExtensionResponse = "onExtensionResponse";


    /**
     * Dispatched when a room is joined successfully.
     * 
     * <p>
     * The {@code params} object contains the following parameters.
     * </p>
     * <ul>
     * <li>
     * room ({@code Room}): the {@link Room} object representing the joined room.
     * </li>
     * </ul>
     * 
     * <p>
     * The following example shows how to handle an successful room joining.
     * <pre>
     * smartFox.addEventListener(SFSEvent.onJoinRoom, new ISFSEventHandler()
     *   {
     *       public void handleEvent(SFSEvent evt)
     *       {
     *           Room joinedRoom = (Room)evt.getParams().get("room");
     *           System.out.println("Room " + joinedRoom.getName() + " joined successfully");
     *       }
     *   });
     * smartFox.joinRoom("The Entrance");
     * </pre>
     * </p>
     * 
     * @see #onJoinRoomError
     * @see it.gotoandplay.smartfoxclient.data.Room
     * @see it.gotoandplay.smartfoxclient.SmartFoxClient#joinRoom
     * 
     * @since SmartFoxServer Basic / Pro v1.x.x
     */	
    public static final String onJoinRoom = "onJoinRoom";


    /**
     * Dispatched when an error occurs while joining a room.
     * <p>
     * This error could happen, for example, if the user is trying to join a room which is currently full.
     * </p>
     * 
     * <p>
     * The {@code params} object contains the following parameters.
     * </p>
     * <ul>
     * <li>
     * error ({@code String}): the error message.
     * </li>
     * </ul>
     * 
     * <p>
     * The following example shows how to handle a potential error in room joining.
     * <pre>
     * smartFox.addEventListener(SFSEvent.onJoinRoomError, new ISFSEventHandler()
     *   {
     *       public void handleEvent(SFSEvent evt)
     *       {
     *           String error = evt.getParams().getString("error");
     *           System.out.println("Room join error; the following error occurred: " + error);
     *       }
     *   });
     * smartFox.joinRoom("The Entrance");
     * </pre>
     * </p>
     * 
     * @see #onJoinRoom
     * @see SmartFoxClient#joinRoom
     * 
     * @since SmartFoxServer Basic / Pro v1.x.x
     */
    public static final String onJoinRoomError = "onJoinRoomError";


    /**
     * Dispatched when the login to a SmartFoxServer zone has been attempted.
     * 
     * <p>
     * The {@code params} object contains the following parameters.
     * </p>
     * <ul>
     * <li>
     * success ({@code Boolean}): the login result: {@code true} if the login to the provided zone succeeded;
     *                            {@code false} if login failed.
     * </li>
     * <li>
     * name ({@code String}): the user's actual username.
     * </li>
     * <li>
     * error ({@code String}): the error message in case of login failure.
     * </li>
     * </ul>
     * 
     * <p>
     * <b>NOTE</b>: the server sends the username back to the client because not all usernames are valid:
     *              for example, those containing bad words may have been filtered during the login process.
     * </p>
     * 
     * <p>
     * The following example shows how to handle the login result.
     * <pre>
     * smartFox.addEventListener(SFSEvent.onLogin, new ISFSEventHandler()
     *   {
     *       public void handleEvent(SFSEvent evt)
     *       {
     *           if(evt.getParams().getBool("success"))
     *           {
     *               System.out.println("Successfully logged in as " + evt.getParams().getString("name"));
     *           }
     *           else
     *           {
     *               System.out.println("Zone login error; the following error occurred: " + evt.getParams().getString("error"));
     *           }
     *       }
     *   });
     * smartFox.login("simpleChat", "jack", "");
     * </pre>
     * </p>
     * 
     * @see #onLogout
     * @see SmartFoxClient#login
     * 
     * @since SmartFoxServer Basic / Pro v1.x.x
     */
    public static final String onLogin = "onLogin";


    /**
     * Dispatched when the user logs out successfully.
     * <p>
     * After a successful logout the user is still connected to the server,
     * but he/she has to login again into a zone, in order to be able to interact with the server.
     * </p>
     * 
     * <p>
     * No parameters are provided.
     * </p>
     * 
     * <p>
     * The following example shows how to handle the "logout" event.
     * <pre>
     * smartFox.addEventListener(SFSEvent.onLogout, new ISFSEventHandler()
     *   {
     *       public void handleEvent(SFSEvent evt)
     *       {
     *           System.out.println("Logged out successfully");
     *       }
     *   });
     * smartFox.logout();
     * </pre>
     * </p>
     * 
     * @see #onLogin
     * @see SmartFoxClient#logout
     * 
     * @since SmartFoxServer Pro v1.5.5
     */
    public static final String onLogout = "onLogout";


    /**
     * Dispatched when a message from a Moderator is received.
     * 
     * <p>
     * The {@code params} object contains the following parameters.
     * </p>
     * <ul>
     * <li>
     * message ({@code String}): the Moderator's message.
     * </li>
     * <li>
     * sender ({@code User}): the {@link it.gotoandplay.smartfoxclient.data.User} object representing
     *                        the Moderator.
     * </li>
     * </ul>
     * 
     * <p>
     * The following example shows how to handle a message coming from a Moderator.
     * <pre>
     * smartFox.addEventListener(SFSEvent.onModeratorMessage, new ISFSEventHandler()
     *   {
     *       public void handleEvent(SFSEvent evt)
     *       {
     *           User sender = (User)evt.getParams().get("sender");
     *           String message = evt.getParams().getString("message");
     *           System.out.println("Moderator " + sender.getName() + " said: " + message);
     *       }
     *   });
     * </pre>
     * </p>
     * 
     * @see #onAdminMessage
     * @see it.gotoandplay.smartfoxclient.data.User
     * @see it.gotoandplay.smartfoxclient.SmartFoxClient#sendModeratorMessage
     * 
     * @since SmartFoxServer Pro v1.4.5
     */
    public static final String onModeratorMessage = "onModMessage";


    /**
     * Dispatched when an object is received.
     * 
     * <p>
     * The {@code params} object contains the following parameters.
     * </p>
     * <ul>
     * <li>
     * obj ({@code SFSObject}): the object received.
     * </li>
     * <li>
     * sender ({@code User}):  object representing the user that sent the object.
     * </li>
     * </ul>
     * 
     * <p>
     * The following example shows how to handle an Actionscript object received from a user.
     * <pre>
     * smartFox.addEventListener(SFSEvent.onObjectReceived, new ISFSEventHandler()
     *   {
     *       public void handleEvent(SFSEvent evt)
     *       {
     *           // Assuming another client sent his X and Y positions in two properties called px, py
     *           User sender = (User)evt.getParams().get("sender");
     *           double px = evt.getParams().getNumber("px");
     *           double py = evt.getParams().getNumber("py");
     *           System.out.println("Data received from user:  " + sender.getName());
     *           System.out.println("X = " + px + ", Y = " + py);
     *       }
     *   });
     * </pre>
     * </p>
     * 
     * @see it.gotoandplay.smartfoxclient.data.User
     * @see SmartFoxClient#sendObject
     * @see SmartFoxClient#sendObjectToGroup
     * 
     * @since SmartFoxServer Basic / Pro v1.x.x
     */
    public static final String onObjectReceived = "onObjectReceived";


    /**
     * Dispatched when a private chat message is received.
     * 
     * Dispatched when an object is received.
     * 
     * <p>
     * The {@code params} object contains the following parameters.
     * </p>
     * <ul>
     * <li>
     * message ({@code String}): the private message received.
     * </li>
     * <li>
     * sender ({@code User}):  the {@link it.gotoandplay.smartfoxclient.data.User} object representing
     *                         the user that sent the message;
     *                         this property is {@code null} if the sender isn't in the same room of
     *                         the recipient.
     * </li>
     * <li>
     * roomId ({@code Integer}):  the id of the room where the sender is.
     * </li>
     * <li>
     * userId ({@code Integer}):  the user id of the sender (useful in case of private messages across
     *                            different rooms, when the {@code sender} object is not available).
     * </li>
     * </ul>
     * 
     * <p>
     * The following example shows how to handle a private message.
     * <pre>
     * smartFox.addEventListener(SFSEvent.onPrivateMessage, new ISFSEventHandler()
     *   {
     *       public void handleEvent(SFSEvent evt)
     *       {
     *           System.out.println("User " +
     *             ((User)evt.getParams().getObj("sender")).getName() +
     *             " sent the following private message: " + evt.getParams().getString("message"));
     *       }
     *   });
     * smartFox.sendPrivateMessage("Hallo Jack!", 22);
     * </pre>
     * </p>
     * 
     * @see #onPublicMessage
     * @see it.gotoandplay.smartfoxclient.data.User
     * @see SmartFoxClient#sendPrivateMessage
     * 
     * @since SmartFoxServer Basic / Pro v1.x.x
     */
    public static final String onPrivateMessage = "onPrivateMessage";


    /**
     * Dispatched when a public chat message is received.
     * 
     * <p>
     * The {@code params} object contains the following parameters.
     * </p>
     * <ul>
     * <li>
     * message ({@code String}):  the public message received.
     * </li>
     * <li>
     * sender ({@code User}):  the {@link it.gotoandplay.smartfoxclient.data.User} object representing the
     *                         user that sent the message.
     * </li>
     * <li>
     * roomId ({@code Integer}):  the id of the room where the sender is.
     * </li>
     * </ul>
     * 
     * <p>
     * The following example shows how to handle a public message.
     * <pre>
     * smartFox.addEventListener(SFSEvent.onPublicMessage, new ISFSEventHandler()
     *   {
     *       public void handleEvent(SFSEvent evt)
     *       {
     *           System.out.println("User " +
     *             ((User)evt.getParams().getObj("sender")).getName() +
     *             " said: " + evt.getParams().getString("message"));
     *       }
     *   });
     * smartFox.sendPublicMessage("Hello world!");
     * </pre>
     * </p>
     * 
     * @see #onPrivateMessage
     * @see it.gotoandplay.smartfoxclient.data.User
     * @see SmartFoxClient#sendPublicMessage
     * 
     * @since SmartFoxServer Basic / Pro v1.x.x
     */
    public static final String onPublicMessage = "onPublicMessage";


    /**
     * Dispatched in response to a {@link SmartFoxClient#getRandomKey} request.
     * 
     * <p>
     * The {@code params} object contains the following parameters.
     * </p>
     * <ul>
     * <li>
     * key ({@code String}): a unique random key generated by the server.
     * </li>
     * </ul>
     * 
     * <p>
     * The following example shows how to handle the request a random key to the server.
     * <pre>
     * smartFox.addEventListener(SFSEvent.onRandomKey, new ISFSEventHandler()
     *   {
     *       public void handleEvent(SFSEvent evt)
     *       {
     *           System.out.println("Random key received from server: " +
     *           evt.getParams().getString("key"));
     *       }
     *   });
     * smartFox.getRandomKey();
     * </pre>
     * </p>
     * 
     * @see SmartFoxClient#getRandomKey
     * 
     * @since SmartFoxServer Pro v1.x.x
     */
    public static final String onRandomKey = "onRandomKey";


    /**
     * Dispatched when a new room is created in the zone where the user is currently logged in.
     * 
     * <p>
     * The {@code params} object contains the following parameters.
     * </p>
     * <ul>
     * <li>
     * room ({@code Room}): the {@link Room} object representing the room that was created.
     * </li>
     * </ul>
     * 
     * <p>
     * The following example shows how to handle a new room being created in the zone.
     * <pre>
     * smartFox.addEventListener(SFSEvent.onRoomAdded, new ISFSEventHandler()
     *   {
     *       public void handleEvent(SFSEvent evt)
     *       {
     *           Room room = (Room)evt.getParams().get("room");
     *           System.out.println("Room " + room.getName() + " was created");
     *
     *           // TODO: update available rooms list in the application interface
     *       }
     *   });
     * </pre>
     * </p>
     * 
     * @see #onRoomDeleted
     * @see Room
     * @see SmartFoxClient#createRoom
     * 
     * @since SmartFoxServer Basic / Pro v1.x.x
     */
    public static final String onRoomAdded = "onRoomAdded";


    /**
     * Dispatched when a room is removed from the zone where the user is currently logged in.
     * 
     * <p>
     * The {@code params} object contains the following parameters.
     * </p>
     * <ul>
     * <li>
     * room ({@code Room}): the {@link Room} object representing the room that was removed.
     * </li>
     * </ul>
     * 
     * <p>
     * The following example shows how to handle a new room being removed in the zone.
     * <pre>
     * smartFox.addEventListener(SFSEvent.onRoomDeleted, new ISFSEventHandler()
     *   {
     *       public void handleEvent(SFSEvent evt)
     *       {
     *           Room room = (Room)evt.getParams().get("room");
     *           System.out.println("Room " + room.getName() + " was removed");
     *
     *           // TODO: update available rooms list in the application interface
     *       }
     *   });
     * </pre>
     * </p>
     * 
     * @see #onRoomAdded
     * @see Room
     * 
     * @since SmartFoxServer Basic / Pro v1.x.x
     */
    public static final String onRoomDeleted = "onRoomDeleted";


    /**
     * Dispatched when a room is left in multi-room mode, in response of a
     * {@link SmartFoxClient#leaveRoom} request.
     * 
     * <p>
     * The {@code params} object contains the following parameters.
     * </p>
     * <ul>
     * <li>
     * roomId ({@code Integer}): the id of the room that was left.
     * </li>
     * </ul>
     * 
     * <p>
     * The following example shows how to handle the "room left" event.
     * <pre>
     * smartFox.addEventListener(SFSEvent.onRoomLeft, new ISFSEventHandler()
     *   {
     *       public void handleEvent(SFSEvent evt)
     *       {
     *           int roomId = (Integer)evt.getParams().get("roomId");
     *           System.out.println("You left room " + roomId);
     *       }
     *   });
     * </pre>
     * </p>
     * 
     * @see SmartFoxClient#leaveRoom
     * 
     * @since SmartFoxServer Basic / Pro v1.x.x
     */
    public static final String onRoomLeft = "onRoomLeft";


    /**
     * Dispatched when the list of rooms available in the current zone is received.
     * <p>
     * If the default login mechanism provided by SmartFoxServer is used, then this event is
     * dispatched right after a successful login. This is because the SmartFoxServer API, internally,
     * call the {@link SmartFoxClient#getRoomList} method after a successful login is performed.
     * If a custom login handler is implemented, the room list must be manually requested to the server by
     * calling the mentioned method.
     * </p>
     * 
     * <p>
     * The {@code params} object contains the following parameters.
     * </p>
     * <ul>
     * <li>
     * roomList ({@code Map<Integer, Room>}): a {@code Map} with room id as key and
     *          {@link Room} objects as key.
     * </li>
     * </ul>
     * 
     * <p>
     * The following example shows how to handle the list of rooms sent by SmartFoxServer.
     * <pre>
     * smartFox.addEventListener(SFSEvent.onRoomListUpdate, new ISFSEventHandler()
     *   {
     *       public void handleEvent(SFSEvent evt)
     *       {
     *           // Dump the names of the available rooms in the current zone
     * 		for(Integer rId : evt.getParams().get("roomList").keySet())
     * 		    System.out.println(evt.getParams().get("roomList").get(r).getName());
     *       }
     *   });
     * smartFox.login("simpleChat", "jack");
     * </pre>
     * </p>
     * 
     * @see Room
     * @see SmartFoxClient#getRoomList
     * 
     * @since SmartFoxServer Basic / Pro v1.x.x
     */
    public static final String onRoomListUpdate = "onRoomListUpdate";


    /**
     * Dispatched when Room Variables are updated.
     * <p>
     * A user receives this notification only from the room(s) where he/she is currently logged in.
     * Also, only the variables that changed are transmitted.
     * </p>
     * 
     * <p>
     * The {@code params} object contains the following parameters.
     * </p>
     * <ul>
     * <li>
     * room ({@code Room}): the {@link Room} object representing the room where the update took place.
     * </li>
     * <li>
     * changedVars ({@code Set<String>}): {@code Set} with the names of the changed variables.
     * </li>
     * </ul>
     * 
     * <p>
     * The following example shows how to handle an update in Room Variables.
     * <pre>
     * smartFox.addEventListener(SFSEvent.onRoomVariablesUpdate, new ISFSEventHandler()
     *   {
     *       public void handleEvent(SFSEvent evt)
     *       {
     *           Set&lt;String&gt; changedVars = (Set&lt;String&gt;)evt.getParams().get("changedVars");
     *           Room room = (Room)evt.getParams().get("room");
     *           // Iterate on the 'changedVars' to check which variables were updated
     *           for(String v : changedVars)
     *           {
     *               System.out.println(v + " room variable was updated; new value is: " + room.getVariable(v).getValue());
     *           }
     *       }
     *   });
     * </pre>
     * </p>
     * 
     * @see Room
     * @see SmartFoxClient#setRoomVariables
     * 
     * @since SmartFoxServer Basic / Pro v1.x.x
     */
    public static final String onRoomVariablesUpdate = "onRoomVariablesUpdate";


    /**
     * Dispatched when a response to the {@link SmartFoxClient#roundTripBench} request is received.
     * <p>
     * The "roundtrip time" represents the number of milliseconds that it takes to a message to go from
     * the client to the server and back to the client. A good way to measure the network lag is to
     * send continuos requests (every 3 or 5 seconds) and then calculate the average roundtrip time on a
     * fixed number of responses (i.e. the last 10 measurements).
     * </p>
     * 
     * <p>
     * The {@code params} object contains the following parameters.
     * </p>
     * <ul>
     * <li>
     * elapsed ({@code Long}): the roundtrip time.
     * </li>
     * </ul>
     * 
     * <p>
     * The following example shows how to check the average network lag time.
     * <pre>
     * smartFox.addEventListener(SFSEvent.onRoundTripResponse, new ISFSEventHandler()
     *   {
     *       public void handleEvent(SFSEvent evt)
     *       {
     *           long lag = (Long)evt.getParams().get("elapsed");
     *           System.out.println("Lag: " + lag + "milliseconds.");
     *       }
     *   });
     * smartFox.roundTripBench();
     * </pre>
     * </p>
     * 
     * @see SmartFoxClient#roundTripBench
     * 
     * @since SmartFoxServer Basic / Pro v1.x.x
     */
    public static final String onRoundTripResponse = "onRoundTripResponse";


    /**
     * Dispatched in response to the {@link SmartFoxClient#switchSpectator} request.
     * <p>
     * The request to turn a spectator into a player may fail if another user did the same before your request,
     * and there was only one player slot available.
     * </p>
     * 
     * <p>
     * The {@code params} object contains the following parameters.
     * </p>
     * <ul>
     * <li>
     * success ({@code Boolean}): the switch result: {@code true} if the spectator was turned into a player,
     *                           otherwise {@code false}.
     * </li>
     * <li>
     * newId ({@code Integer}): the player id assigned by the server to the user.
     * </li>
     * <li>
     * room ({@code Room}): the {@link Room} object representing the room where the switch occurred.
     * </li>
     * </ul>
     * 
     * <p>
     * The following example shows how to handle the spectator switch.
     * <pre>
     * smartFox.addEventListener(SFSEvent.onSpectatorSwitched, new ISFSEventHandler()
     *   {
     *       public void handleEvent(SFSEvent evt)
     *       {
     *           if(evt.getParams().getBool("success"))
     *           {
     *               System.out.println("You have been turned into a player; your player id is " + evt.getParams().get("newId"));
     *           }
     *           else
     *           {
     *               System.out.println("The attempt to switch from spectator to player failed");
     *           }
     *       }
     *   });
     * smartFox.switchSpectator();
     * </pre>
     * </p>
     * 
     * @see it.gotoandplay.smartfoxclient.data.User#getPlayerId
     * @see Room
     * @see SmartFoxClient#switchSpectator
     * 
     * @since SmartFoxServer Basic / Pro v1.x.x
     */
    public static final String onSpectatorSwitched = "onSpectatorSwitched";

    /**
     * Dispatched in response to the {@link SmartFoxClient#switchPlayer} request.
     * <p>
     * The request to turn a player into a spectator may fail if another user did the same before your request,
     * and there was only one spectator slot available.
     * </p>
     *
     * <p>
     * The {@code params} object contains the following parameters.
     * </p>
     * <ul>
     * <li>
     * success ({@code Boolean}): the switch result: {@code true} if the player was turned into a spectator,
     *                           otherwise {@code false}.
     * </li>
     * <li>
     * newId ({@code Integer}): the player id assigned by the server to the user.
     *                          If the switch is successful it's -1.
     * </li>
     * <li>
     * room ({@code Room}): the {@link Room} object representing the room where the switch occurred.
     * </li>
     * </ul>
     *
     * <p>
     * The following example shows how to handle the player switch.
     * <pre>
     * smartFox.addEventListener(SFSEvent.onPlayerSwitched, new ISFSEventHandler()
     *   {
     *       public void handleEvent(SFSEvent evt)
     *       {
     *           if(evt.getParams().getBool("success"))
     *           {
     *               System.out.println("You have been turned into a spectator; your id is " + evt.getParams().get("newId"));
     *           }
     *           else
     *           {
     *               System.out.println("The attempt to switch from player to spectator failed");
     *           }
     *       }
     *   });
     * smartFox.switchPlayer();
     * </pre>
     * </p>
     *
     * @see it.gotoandplay.smartfoxclient.data.User#getPlayerId
     * @see Room
     * @see SmartFoxClient#switchPlayer
     *
     * @since SmartFoxServer Pro v1.6.6
     */
    public static final String onPlayerSwitched = "onPlayerSwitched";

    /**
     * Dispatched when the number of users and/or spectators changes in a room within the current zone.
     * <p>
     * This event allows to keep track in realtime of the status of all the zone rooms in terms of users and
     * spectators. In case many rooms are used and the zone handles a medium to high traffic,
     * this notification can be turned off to reduce bandwidth consumption, since a message is
     * broadcasted to all users in the zone each time a user enters or exits a room.
     * </p>
     * 
     * <p>
     * The {@code params} object contains the following parameters.
     * </p>
     * <ul>
     * <li>
     * room ({@code Room}): the {@link Room} object representing the room where the change occurred.
     * </li>
     * </ul>
     * 
     * <p>
     * The following example shows how to check the handle the user count cgange notification.
     * <pre>
     * smartFox.addEventListener(SFSEvent.onUserCountChange, new ISFSEventHandler()
     *   {
     *       public void handleEvent(SFSEvent evt)
     *       {
     *           // Assuming this is a game room
     *           Room room = (Room)evt.getParams().get("room");
     *           String roomName = room.getName();
     *           int playersNum = room.getUserCount();
     *           int spectatorsNum = room.getSpectatorCount();
     *           System.out.println("Room " + roomName + "has " + playersNum + " players and " + spectatorsNum + " spectators");
     *       }
     *   });
     * smartFox.switchSpectator();
     * </pre>
     * </p>
     * 
     * @see #onUserEnterRoom
     * @see #onUserLeaveRoom
     * @see Room
     * @see SmartFoxClient#createRoom
     * 
     * @since SmartFoxServer Basic / Pro v1.x.x
     */
    public static final String onUserCountChange = "onUserCountChange";


    /**
     * Dispatched when another user joins the current room.
     * 
     * <p>
     * The {@code params} object contains the following parameters.
     * </p>
     * <ul>
     * <li>
     * roomId ({@code Integer}): the id of the room joined by a user
     *                          (useful in case multi-room presence is allowed).
     * </li>
     * <li>
     * user ({@code User}): the {@link it.gotoandplay.smartfoxclient.data.User} object representing the user
     *                      that joined the room.
     * </li>
     * </ul>
     * 
     * <p>
     * The following example shows how to check the handle the user entering room notification.
     * <pre>
     * smartFox.addEventListener(SFSEvent.onUserEnterRoom, new ISFSEventHandler()
     *   {
     *       public void handleEvent(SFSEvent evt)
     *       {
     *           User user = (User)evt.getParams().get("user");
     *           System.out.println("User " + user.getName() + " entered the room");
     *       }
     *   });
     * </pre>
     * </p>
     * 
     * @see #onUserLeaveRoom
     * @see #onUserCountChange
     * @see it.gotoandplay.smartfoxclient.data.User
     * 
     * @since SmartFoxServer Basic / Pro v1.x.x
     */
    public static final String onUserEnterRoom = "onUserEnterRoom";


    /**
     * Dispatched when a user leaves the current room.
     * <p>
     * This event is also dispatched when a user gets disconnected from the server.
     * </p>
     * 
     * <p>
     * The {@code params} object contains the following parameters.
     * </p>
     * <ul>
     * <li>
     * roomId ({@code Integer}): the id of the room left by a user
     *                          (useful in case multi-room presence is allowed).
     * </li>
     * <li>
     * userId ({@code Integer}): the id of the user that left the room (or got disconnected).
     * </li>
     * <li>
     * userName ({@code String}): the name of the user.
     * </li>
     * </ul>
     * 
     * <p>
     * The following example shows how to check the handle the user leaving room notification.
     * <pre>
     * smartFox.addEventListener(SFSEvent.onUserLeaveRoom, new ISFSEventHandler()
     *   {
     *       public void handleEvent(SFSEvent evt)
     *       {
     *           System.out.println("User " + evt.getParams().getString("userName") + " left the room");
     *       }
     *   });
     * </pre>
     * </p>
     * 
     * @see #onUserEnterRoom
     * @see #onUserCountChange
     * 
     * @since SmartFoxServer Basic / Pro v1.x.x
     */
    public static final String onUserLeaveRoom = "onUserLeaveRoom";


    /**
     * Dispatched when a user in the current room updates his/her User Variables.
     * 
     * <p>
     * The {@code params} object contains the following parameters.
     * </p>
     * <ul>
     * <li>
     * user ({@code User}): the {@link it.gotoandplay.smartfoxclient.data.User} object representing the user who
     *                      updated his/her variables.
     * </li>
     * <li>
     * changedVars ({@code Set<String>}): {@code Set} with the names of the changed variables.
     * </li>
     * </ul>
     * 
     * <p>
     * The following example shows how to handle an update in User Variables.
     * <pre>
     * smartFox.addEventListener(SFSEvent.onUserVariablesUpdate, new ISFSEventHandler()
     *   {
     *       public void handleEvent(SFSEvent evt)
     *       {
     *           // We assume that each user has px and py variables representing the users's avatar coordinates in a 2D environment
     *           Set&lt;String&gt; changedVars = (Set&lt;String&gt;)evt.getParams().get("changedVars");
     *           if(changedVars.contains("px") || changedVars.contains("py"))
     *           {
     *               User user = (user)evt.getParams().get("user");
     *               System.out.println("User " + user.getName() + " moved to new coordinates:");
     *               System.out.println("\t px: " + user.getVariable("px"));
     *               System.out.println("\t py: " + user.getVariable("py"));
     *           }
     *       }
     *   });
     * </pre>
     * </p>
     * 
     * @see it.gotoandplay.smartfoxclient.data.User
     * @see SmartFoxClient#setUserVariables
     * 
     * @since SmartFoxServer Basic / Pro v1.x.x
     */
    public static final String onUserVariablesUpdate = "onUserVariablesUpdate";

    private String name;
    private SFSObject params;
            
    public SFSEvent(String name, SFSObject params)
    {
        this.name = name;
        this.params = params;
    }
    
    public String getName()
    {
        return name;
    }
    
    public SFSObject getParams()
    {
        return params;
    }
    
    @Override
    public String toString()
    {
        return "Type: " + this.name + "\nParams: " + this.params.toString();
    }
}
