Package com.smartfoxserver.v2.api

Interface ISFSApi

  • All Known Implementing Classes:
    SFSApi
    public interface ISFSApi

    • Method Detail

      • getResponseAPI

        com.smartfoxserver.v2.api.response.ISFSResponseApi getResponseAPI()

      • getSystemScheduler

        TaskScheduler getSystemScheduler()
        Gets a reference to the global SFS Task Scheduler. This is useful to run delayed or repetitive tasks in one's Extension code.
        Returns:
        a reference to SmartFox's system Task Scheduler
        Since:
        2.11
        See Also:
        TaskScheduler

      • getNewScheduler

        TaskScheduler getNewScheduler​(int threadPoolSize)
        Creates a new TaskScheduler. This is useful if one wants a dedicated scheduler for their extension, especially when it is used to handle hundreds or thousands of task, offloading the System scheduler.
        Parameters:
        threadPoolSize - the size of the thread pool backing the Scheduler
        Returns:
        a new Task Scheduler
        Since:
        2.11
        See Also:
        TaskScheduler

      • checkSecurePassword

        boolean checkSecurePassword​(ISession session,
                            java.lang.String originalPass,
                            java.lang.String encryptedPass)
        Check an encrypted password sent by the User at login time.
        Parameters:
        session - the client session
        originalPass - the original un-encrypted password (typically coming from the user DB)
        encryptedPass - the encrypted password sent by the client
        Returns:
        true if the password is correct, false otherwise. Always return false if any of the two password is null or its length == 0
        Throws:
        java.lang.IllegalArgumentException - if invalid hash strings are passed

      • login

        User login​(ISession session,
           java.lang.String name,
           java.lang.String pass,
           java.lang.String zoneName,
           ISFSObject params)
        Logs a client into a Zone, allowing it to become a User

        The login process is central to SmartFoxServer because it generates a User object. Only Users can interact with the Server and the other connected clients.

        The initial process of connection and login is actually very simple:

        1. Establish socket connection: the client starts a new Session (TCP connection) followed by an API handshake
        2. Log into a Zone: using its Session the client can finally join an Application (Zone) and start the interaction

        Custom Login

        Activating the customLogin feature in the Zone allows developers to listen for login events such as SFSEventType.USER_LOGIN and SFSEventType.USER_JOIN_ZONE and perform custom operations.
        • USER_LOGIN: fired when a client requests to join a Zone. Here you can perform a check on their credentials.
        • USER_JOIN_ZONE: fired when a client has successfully joined a Zone (and turned into a User)

        Security

        The User password is never transmitted in clear. A CHAP (Challenge Handshake Authentication Protocol) protocol is used instead to ensure a high standard of security.
        Parameters:
        session - the client session
        name - the user name
        pass - the user password
        zoneName - the name of the Zone to join
        params - (optional) custom params to send back in the client onLogin event
        Returns:
        the User object assigned to this user.
        See Also:
        User, Zone, SFSEventType.USER_LOGIN, SFSEventType.USER_JOIN_ZONE

      • login

        User login​(ISession session,
           java.lang.String name,
           java.lang.String pass,
           java.lang.String zoneName,
           ISFSObject params,
           boolean forceLogout)
        Uses additional flag to disconnect previous user with same username
        Parameters:
        forceLogout - forces a previous connection out
        Returns:
        the User
        See Also:
        login(ISession, String, String, String, ISFSObject)

      • createNPC

        User createNPC​(java.lang.String userName,
               Zone zone,
               boolean forceLogin)
        throws SFSLoginException
        Create connection-less NPC (Non-Player Character). The NPC will be seen in the system as any other regular User although he can be recognized from its User.isNpc() flag. There is no real, physical connection to the Server (no TCP connection is used)

        NOTE: NPCs must be created once the server engine is up and running. The init() method of your Extension runs before the engine is ready so you will need to do is adding a listener to the SFSEventType.SERVER_READY event and wait for that event before instantiating any NPC.

        Parameters:
        userName - the NPC name
        zone - the Zone
        forceLogin - if a User already exists with that name, it will disconnect it first
        Returns:
        the User
        Throws:
        SFSLoginException

      • kickUser

        void kickUser​(User userToKick,
              User modUser,
              java.lang.String kickMessage,
              int delaySeconds)
        Kicks the User out. The operation allows to send a moderator message to the client and allow a number of seconds for reading it before the connection is closed.
        Parameters:
        userToKick - the User to be kicked
        modUser - the mod/admin user, can be null to indicate generically the "Server"
        kickMessage - a moderator message
        delaySeconds - delay before the disconnection is performed

      • banUser

        void banUser​(User userToBan,
             User modUser,
             java.lang.String banMessage,
             BanMode mode,
             int durationMinutes,
             int delaySeconds)
        Ban a User. The operation allows to send a moderator message to the client and allow a number of seconds for reading it before the connection is closed.

        The length of the banishment and the rules under which the ban can be removed are specified in your Zone configuration

        Parameters:
        userToBan - the User to be banned
        modUser - the mod/admin user, can be null to indicate generically the "Server"
        banMessage - a moderator message
        mode - choose between banning by Ip Address or by User name
        durationMinutes - the duration of the banishment in minutes
        delaySeconds - delay before the disconnection is performed

      • banUser

        void banUser​(User userToBan,
             User modUser,
             java.lang.String banMessage,
             java.lang.String reason,
             BanMode mode,
             int durationMinutes,
             int delaySeconds)
        Ban a User. The operation allows to send a moderator message to the client and allow a number of seconds for reading it before the connection is closed.

        The length of the banishment and the rules under which the ban can be removed are specified in your Zone configuration

        Parameters:
        userToBan - the User to be banned
        modUser - the mod/admin user, can be null to indicate generically the "Server"
        banMessage - a moderator message
        reason - the reason for the banishment (will appear in the AdminTool's BanManager but it's not sent to the User)
        mode - choose between banning by Ip Address or by User name
        durationMinutes - the duration of the banishment in minutes
        delaySeconds - delay before the disconnection is performed

      • disconnectUser

        void disconnectUser​(User user,
                    IDisconnectionReason reason)
        Disconnect a User indicating one specific reason (for example because the User was Idle). Sending a disconnection reason to the client allow avoiding that the User attempts a transparent reconnection (when available)
        Parameters:
        user - the User
        reason - the reason for disconnection
        See Also:
        ClientDisconnectionReason

      • disconnect

        void disconnect​(ISession session)
        Disconnect a Session abruptly.
        Parameters:
        session - the Session

      • createRoom

        Room createRoom​(Zone zone,
                CreateRoomSettings settings,
                User owner,
                boolean joinIt,
                Room roomToLeave)
         throws SFSCreateRoomException
        Create a new Room
        Parameters:
        zone - the Zone in which the Room is going to be created
        settings - the Room settings
        owner - the Room owner, when null it indicates that the Room is owned by the Server itself
        joinIt - if true the Room will be joined by the owner right after creation
        roomToLeave - a previous Room to leave after the join, or null
        Returns:
        the Room
        Throws:
        SFSCreateRoomException
        See Also:
        CreateRoomSettings

      • createRoom

        Room createRoom​(Zone zone,
                CreateRoomSettings settings,
                User owner,
                boolean joinIt,
                Room roomToLeave,
                boolean fireClientEvent,
                boolean fireServerEvent)
         throws SFSCreateRoomException
        Parameters:
        zone - the Zone in which the Room is going to be created
        settings - the Room settings
        owner - the Room owner, when null it indicates that the Room is owned by the Server itself
        joinIt - if true the Room will be joined by the owner right after creation
        roomToLeave - a previous Room to leave after the join, or null
        fireClientEvent - fire a client side Event
        fireServerEvent - fire a server side Event
        Returns:
        the Room
        Throws:
        SFSCreateRoomException
        See Also:
        CreateRoomSettings

      • findUsers

        java.util.List<User> findUsers​(java.util.Collection<User> userList,
                               MatchExpression expression,
                               int limit)
        Find one or more User(s) in the specified collection of Users.
        Parameters:
        userList - the collection of Users to search
        expression - the matching expression
        limit - stop the search after a certain amount of matches (e.g. limit = 10, will return the first 10 Users matching the expression). limit = 0 will return all matches.
        Returns:
        the Users matching the passed expression

      • findRooms

        java.util.List<Room> findRooms​(java.util.Collection<Room> roomList,
                               MatchExpression expression,
                               int limit)
        Find one or more Room(s) in the specified collection of Users.
        Parameters:
        roomList - the list of Rooms to search
        expression - the matching expression
        limit - stop the search after a certain amount of matches (e.g. limit = 10, will return the first 10 Rooms matching the expression). limit = 0 will return all matches.
        Returns:
        the Rooms matching the passed expression

      • getUserById

        User getUserById​(int userId)
        Finds a User from its unique ID
        Parameters:
        userId - the User ID
        Returns:
        the User. It can be null if no User was found with that ID

      • getUserByName

        User getUserByName​(java.lang.String name)
        Finds a User from its name
        Parameters:
        name - the User name
        Returns:
        the User. It can be null if not User was found with that name (case sensitive)

      • getUserBySession

        User getUserBySession​(ISession session)
        Finds a User from its Session
        Parameters:
        session - the Session
        Returns:
        the User. It can be null if not User was found with that Session

      • joinRoom

        void joinRoom​(User user,
              Room room)
       throws SFSJoinRoomException
        Join the user in a room.
        This is the quickest way to join a User in non password-protected Room. By default the User will leave the old Room (if any) after joining the new one and both client and server events will be fired.

        In game rooms the user will be joined as player, if you need to join as spectator you will need to use one of the other overloaded methods.

        Thread safety notes: The same User can be in one join transaction at a time. If you need to join a player in multiple Rooms there are no concurrency concerns, as long as you're working in the same thread (which is expected). In case you have multiple threads attempting to join the same User in multiple Rooms make sure to synchronize the call.

        Parameters:
        user -
        room -
        Throws:
        SFSJoinRoomException

      • joinRoom

        void joinRoom​(User user,
              Room roomToJoin,
              java.lang.String password,
              boolean asSpectator,
              Room roomToLeave)
       throws SFSJoinRoomException
        Join the user in a room.
        A client update and server side event will be also fired
        Parameters:
        user - the User
        roomToJoin - the room to join
        password - an optional password if the room requires it. Use null if no password is needed
        asSpectator - join the room as spectator, in case of a game room
        roomToLeave - optionally specify a Room that should be left if roomToJoin is successfully joined.
        Throws:
        SFSJoinRoomException

      • joinRoom

        void joinRoom​(User user,
              Room roomToJoin,
              java.lang.String password,
              boolean asSpectator,
              Room roomToLeave,
              boolean fireClientEvent,
              boolean fireServerEvent)
       throws SFSJoinRoomException
        Join the user in a room.
        Parameters:
        user - the User
        roomToJoin - the room to join
        password - an optional password if the room requires it. Use null if no password is needed
        asSpectator - join the room as spectator, in case of a game room
        roomToLeave - optionally specify a Room that should be left if roomToJoin is successfully joined.
        fireClientEvent - fires client side Event
        fireServerEvent - fires server side Event
        Throws:
        SFSJoinRoomException

      • leaveRoom

        void leaveRoom​(User user,
               Room room)
        Makes a user leave a room that he has joined
        Parameters:
        user - the User
        room - the Room

      • leaveRoom

        void leaveRoom​(User user,
               Room room,
               boolean fireClientEvent,
               boolean fireServerEvent)
        Removes a User from a previously joined Room
        Parameters:
        user - the User
        room - the Room
        fireClientEvent - fires client side Event
        fireServerEvent - fires server side Event

      • emptyRoom

        void emptyRoom​(Room targetRoom)
        Removes all Users from the target Room. The Room is deactivated first to block other join requests, then its emptied and left deactivated. The Room may be removed after this call if the relative SFSRoomRemoveMode attribute is configured to do so.
        Parameters:
        targetRoom - the Room to be emptied
        See Also:
        SFSRoomRemoveMode

      • emptyRoom

        void emptyRoom​(Room targetRoom,
               boolean deactivateRoom)
        Removes all Users from the target Room. The Room can be deactivated first to block other join requests, and will remain in the required state. The Room may be removed after this call if the relative SFSRoomRemoveMode attribute is configured to do so.
        Parameters:
        targetRoom - the Room to be emptied
        deactivateRoom - use true to deactivate the Room and avoid concurrent and/or subsequent join operations
        See Also:
        SFSRoomRemoveMode

      • emptyRoom

        void emptyRoom​(Room targetRoom,
               boolean deactivateRoom,
               boolean fireClientEvent,
               boolean fireServerEvent)
        Removes all Users from the target Room. The Room can be deactivated first to block other join requests, and will remain in the required state. The Room may be removed after this call if the relative SFSRoomRemoveMode attribute is configured to do so.
        Parameters:
        targetRoom - the Room to be emptied
        deactivateRoom - use true to deactivate the Room and avoid concurrent and/or subsequent join operations
        fireClientEvent - fires client side Event
        fireServerEvent - fires server side Event
        See Also:
        SFSRoomRemoveMode

      • quickJoinOrCreateRoom

        void quickJoinOrCreateRoom​(User user,
                           MatchExpression expression,
                           java.util.Collection<java.lang.String> groupList,
                           CreateRoomSettings settings)
                    throws SFSJoinRoomException,
                           SFSCreateRoomException
        Searches for a Room that matches the provided MatchExpression and joins the User in the first occurrence found. If nothing is found proceeds with creating a Room with the provided configuration and joins the User there instead.
        Parameters:
        user - the User requesting to join
        expression - a MatchExpression to filter specific Rooms
        groupList - one or more valid Room group names where to apply the MatchExpression
        settings - the room settings to use for creating a new Room if the search fails
        Throws:
        SFSJoinRoomException
        SFSCreateRoomException
        Since:
        2.18.2

      • quickJoinOrCreateRoom

        void quickJoinOrCreateRoom​(User user,
                           MatchExpression expression,
                           java.util.Collection<java.lang.String> groupList,
                           CreateRoomSettings settings,
                           Room roomToLeave)
                    throws SFSJoinRoomException,
                           SFSCreateRoomException
        Searches for a Room that matches the provided MatchExpression and joins the User in the first occurrence found. If nothing is found proceeds with creating a Room with the provided configuration and joins the User there instead.
        Parameters:
        user - the User requesting to join
        expression - a MatchExpression to filter specific Rooms
        groupList - one or more valid Room group names where to apply the MatchExpression
        settings - the room settings to use for creating a new Room if the search fails
        roomToLeave - a Room currently joined by the User that should be left upon successful joining
        Throws:
        SFSJoinRoomException
        SFSCreateRoomException
        Since:
        2.18.2

      • removeRoom

        void removeRoom​(Room room)
        Removes a Room from its Zone
        Parameters:
        room - the Room

      • removeRoom

        void removeRoom​(Room room,
                boolean fireClientEvent,
                boolean fireServerEvent)
        Removes a Room from its Zone
        Parameters:
        room - the Room
        fireClientEvent - fires client side Event
        fireServerEvent - fires server side Event

      • sendPublicMessage

        void sendPublicMessage​(Room targetRoom,
                       User sender,
                       java.lang.String message,
                       ISFSObject params)
        Sends a public chat message. The message is broadcast to all Users in the same Room including the sender.
        Parameters:
        targetRoom - the Room where the message is sent
        sender - the User sending the message
        message - the chat message
        params - a custom object with additional parameters (e.g. text color, font size, etc...)

      • sendPrivateMessage

        void sendPrivateMessage​(User sender,
                        User recipient,
                        java.lang.String message,
                        ISFSObject params)
        Sends a private chat message. The message is sent to both the sender and receiver. The sender and receiver can be in any Rooms or even not joined in any rooms at all.
        Parameters:
        sender - the sender of the message
        recipient - the recipient of the message
        message - the chat message
        params - a custom SFSObjects with extra parameters (e.g. the font type, color etc...)

      • sendGenericMessage

        void sendGenericMessage​(com.smartfoxserver.v2.api.GenericMessageType type,
                        User sender,
                        int targetRoomId,
                        java.lang.String message,
                        ISFSObject params,
                        java.util.Collection<ISession> recipients)

      • sendModeratorMessage

        void sendModeratorMessage​(User sender,
                          java.lang.String message,
                          ISFSObject params,
                          java.util.Collection<ISession> recipients)
        Sends a moderator message to a number of Users. The sender parameter must be either a real User with "SuperUser" privileges or null. In this last case the sender becomes the "Server" itself.
        Parameters:
        sender - the moderator user sending this message or null, indicating a Server originated mod message
        message - the message
        params - an SFSObject with custom parameters
        recipients - the recipients of the message

      • sendAdminMessage

        void sendAdminMessage​(User sender,
                      java.lang.String message,
                      ISFSObject params,
                      java.util.Collection<ISession> recipients)
        Sends a administrator message to a number of Users. The sender parameter must be either a real User with "SuperUser" privileges or null. In this last case the sender becomes the "Server" itself.
        Parameters:
        sender - the admin user sending this message or null, indicating a Server originated admin message
        message - the message
        params - an SFSObject with custom parameters
        recipients - the recipients of the message

      • sendObjectMessage

        void sendObjectMessage​(Room targetRoom,
                       User sender,
                       ISFSObject message,
                       java.util.Collection<User> recipients)

        Send an Object message. This message is based on a custom SFSObject that can contain any data. Typically this is used for sending game moves to players or other game/app related updates. The message is sent to all users in the specified target room (with the exclusion of the sender) but you can also pass a collection of Users to specify which clients in that Room should receive the message.

        NOTE: The sender must be joined in the target Room.

        Parameters:
        targetRoom - the room where the message will be sent to
        sender - the sender of the message
        message - a custom SFSObject
        recipients - use null to send the message to all clients in the Room, or specify a collection of users that should receive the message

      • sendExtensionResponse

        void sendExtensionResponse​(java.lang.String cmdName,
                           ISFSObject params,
                           java.util.List<User> recipients,
                           Room room,
                           boolean useUDP)

      • sendExtensionResponse

        void sendExtensionResponse​(java.lang.String cmdName,
                           ISFSObject params,
                           User recipient,
                           Room room,
                           boolean useUDP)

      • setRoomVariables

        void setRoomVariables​(User user,
                      Room targetRoom,
                      java.util.List<RoomVariable> variables)
        Set Room Variables. Only variables that change are broadcast to the Users in the target Room. In order to delete a variable you can set it to null.
        Parameters:
        user - the sender (null == sets ownership of the variables to the Server itself)
        targetRoom - the Room in which variables should be set
        variables - a list of Room variables
        See Also:
        RoomVariable

      • setRoomVariables

        void setRoomVariables​(User user,
                      Room targetRoom,
                      java.util.List<RoomVariable> variables,
                      boolean fireClientEvent,
                      boolean fireServerEvent,
                      boolean overrideOwnership)
        Set Room Variables. Only variables that change are broadcast to the Users in the target Room. In order to delete a variable you can set it to null.
        Parameters:
        user - the sender (null == sets ownership of the variables to the Server itself)
        targetRoom - the Room in which variables should be set
        variables - a list of RoomVariables
        fireClientEvent - fires client side Event
        fireServerEvent - fires server side Event
        overrideOwnership - allow to override the ownership of variables
        See Also:
        RoomVariable

      • setUserVariables

        void setUserVariables​(User owner,
                      java.util.List<UserVariable> variables)
        Set User Variables. Only variables that change are broadcast to the Users that can "see" the owner. In order to delete a variable you can set it to null.
        Parameters:
        owner - the User for which variables are set
        variables - a list of UserVariables
        See Also:
        UserVariable

      • setUserVariables

        void setUserVariables​(User owner,
                      java.util.List<UserVariable> variables,
                      boolean fireClientEvent,
                      boolean fireServerEvent)
        Set User Variables. Only variables that change are broadcast to the Users that can "see" the sender. In order to delete a variable you can set it to null.
        Parameters:
        owner - the User for which variables are set
        variables - a list of UserVariables
        fireClientEvent - fires client side Event
        fireServerEvent - fires server side Event
        See Also:
        UserVariable

      • changeRoomName

        void changeRoomName​(User owner,
                    Room targetRoom,
                    java.lang.String newName)
             throws SFSRoomException
        Rename a Room. Errors can be fired if:
        • the new name is already in use
        • the new name length is out of the range allowed by the Zone configuration
        • the new name contains bad words (if word filter is configured)
        Parameters:
        owner - the User, it can be null if this is called on the server side
        targetRoom - the Room
        newName - the new Room name
        Throws:
        SFSRoomException

      • changeRoomPassword

        void changeRoomPassword​(User owner,
                        Room targetRoom,
                        java.lang.String newPassword)
                 throws SFSRoomException
        Changes the Room password and the Room password-state. The password state indicates if a Room is private and requires a password for accessing it or not. Passing a null or empty string as the password will make room public. Passing a valid string as the password will make the Room private.
        Parameters:
        owner - the User, it can be null if this is called on the server side
        targetRoom - the Room
        newPassword - the new password
        Throws:
        SFSRoomException

      • changeRoomCapacity

        void changeRoomCapacity​(User owner,
                        Room targetRoom,
                        int maxUsers,
                        int maxSpectators)
                 throws SFSRoomException
        Changes the capacity (max number of Users and Spectators) in the Room. In case the Room size is shrunk extra players or spectators will not be kicked out of the Room.
        Parameters:
        owner - owner of the Room, the requester must be owner of the Room or SuperUser
        targetRoom - the room
        maxUsers - new maxUsers value
        maxSpectators - new maxSpectators value
        Throws:
        SFSRoomException

      • subscribeRoomGroup

        void subscribeRoomGroup​(User user,
                        java.lang.String groupId)
        Subscribe User to a Room Group. This will enable the User to receive events for Rooms in that Group
        Parameters:
        user - the User
        groupId - the group name

      • unsubscribeRoomGroup

        void unsubscribeRoomGroup​(User user,
                          java.lang.String groupId)
        Unsubscribe User to a Room Group.
        Parameters:
        user - the User
        groupId - the group name

      • spectatorToPlayer

        void spectatorToPlayer​(User user,
                       Room targetRoom,
                       boolean fireClientEvent,
                       boolean fireServerEvent)
                throws SFSRoomException
        Turns a spectator in a Game Room to a Player. The action will fail if no player slot is available.
        Parameters:
        user - the User
        targetRoom - the Room in which the spectator will be turned into a player
        fireClientEvent - if true send an update to the client (recommended)
        fireServerEvent - if true fire a server side event
        Throws:
        SFSRoomException

      • playerToSpectator

        void playerToSpectator​(User user,
                       Room targetRoom,
                       boolean fireClientEvent,
                       boolean fireServerEvent)
                throws SFSRoomException
        Turns a player in a Game Room to a spectator. The action will fail if no spectator slot is available.
        Parameters:
        user - the User
        targetRoom - the Room in which the player will be turned into a spectator
        fireClientEvent - if true send an update to the client (recommended)
        fireServerEvent - if true fire a server side event
        Throws:
        SFSRoomException