public interface ISFSApi
Modifier and Type | Method and Description |
---|---|
void |
banUser(User userToBan,
User modUser,
java.lang.String banMessage,
BanMode mode,
int durationMinutes,
int delaySeconds)
Ban a User.
|
void |
changeRoomCapacity(User owner,
Room targetRoom,
int maxUsers,
int maxSpectators)
Changes the capacity (max number of Users and Spectators) in the Room.
|
void |
changeRoomName(User owner,
Room targetRoom,
java.lang.String newName)
Rename a Room.
|
void |
changeRoomPassword(User owner,
Room targetRoom,
java.lang.String newPassword)
Changes the Room password and the Room password-state.
|
boolean |
checkSecurePassword(ISession session,
java.lang.String originalPass,
java.lang.String encryptedPass)
Check an encrypted password sent by the User at login time.
|
User |
createNPC(java.lang.String userName,
Zone zone,
boolean forceLogin)
Create connection-less NPC (Non-Player Character).
|
Room |
createRoom(Zone zone,
CreateRoomSettings settings,
User owner)
Create a new Room
|
Room |
createRoom(Zone zone,
CreateRoomSettings settings,
User owner,
boolean joinIt,
Room roomToLeave)
Create a new Room
|
Room |
createRoom(Zone zone,
CreateRoomSettings settings,
User owner,
boolean joinIt,
Room roomToLeave,
boolean fireClientEvent,
boolean fireServerEvent) |
void |
disconnect(ISession session)
Disconnect a Session abruptly.
|
void |
disconnectUser(User user)
Disconnect User abruptly
|
void |
disconnectUser(User user,
IDisconnectionReason reason)
Disconnect a User indicating one specific reason (for example because the User was Idle).
|
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.
|
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.
|
TaskScheduler |
getNewScheduler(int threadPoolSize)
Creates a new TaskScheduler.
|
com.smartfoxserver.v2.api.response.ISFSResponseApi |
getResponseAPI() |
TaskScheduler |
getSystemScheduler()
Gets a reference to the global SFS Task Scheduler.
|
User |
getUserById(int userId)
Finds a User from its unique ID
|
User |
getUserByName(java.lang.String name)
Finds a User from its name
|
User |
getUserBySession(ISession session)
Finds a User from its Session
|
void |
joinRoom(User user,
Room room)
Join the user in a room.
|
void |
joinRoom(User user,
Room roomToJoin,
java.lang.String password,
boolean asSpectator,
Room roomToLeave)
Join the user in a room.
|
void |
joinRoom(User user,
Room roomToJoin,
java.lang.String password,
boolean asSpectator,
Room roomToLeave,
boolean fireClientEvent,
boolean fireServerEvent)
Join the user in a room.
|
void |
kickUser(User userToKick,
User modUser,
java.lang.String kickMessage,
int delaySeconds)
Kicks the User out.
|
void |
leaveRoom(User user,
Room room)
Makes a user leave a room that he has joined
|
void |
leaveRoom(User user,
Room room,
boolean fireClientEvent,
boolean fireServerEvent)
Removes a User from a previously joined Room
|
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.
|
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
|
void |
logout(User user)
Log a User out of the current Zone
|
void |
playerToSpectator(User user,
Room targetRoom,
boolean fireClientEvent,
boolean fireServerEvent)
Turns a player in a Game Room to a spectator.
|
void |
removeRoom(Room room)
Removes a Room from its Zone
|
void |
removeRoom(Room room,
boolean fireClientEvent,
boolean fireServerEvent)
Removes a Room from its Zone
|
void |
sendAdminMessage(User sender,
java.lang.String message,
ISFSObject params,
java.util.Collection<ISession> recipients)
Sends a administrator message to a number of Users.
|
void |
sendBuddyMessage(User sender,
User recipient,
java.lang.String message,
ISFSObject params) |
void |
sendExtensionResponse(java.lang.String cmdName,
ISFSObject params,
java.util.List<User> recipients,
Room room,
boolean useUDP) |
void |
sendExtensionResponse(java.lang.String cmdName,
ISFSObject params,
User recipient,
Room room,
boolean useUDP) |
void |
sendGenericMessage(com.smartfoxserver.v2.api.GenericMessageType type,
User sender,
int targetRoomId,
java.lang.String message,
ISFSObject params,
java.util.Collection<ISession> recipients) |
void |
sendModeratorMessage(User sender,
java.lang.String message,
ISFSObject params,
java.util.Collection<ISession> recipients)
Sends a moderator message to a number of Users.
|
void |
sendObjectMessage(Room targetRoom,
User sender,
ISFSObject message,
java.util.Collection<User> recipients)
Send an Object message.
|
void |
sendPrivateMessage(User sender,
User recipient,
java.lang.String message,
ISFSObject params)
Sends a private chat message.
|
void |
sendPublicMessage(Room targetRoom,
User sender,
java.lang.String message,
ISFSObject params)
Sends a public chat message.
|
void |
setRoomVariables(User user,
Room targetRoom,
java.util.List<RoomVariable> variables)
Set Room Variables.
|
void |
setRoomVariables(User user,
Room targetRoom,
java.util.List<RoomVariable> variables,
boolean fireClientEvent,
boolean fireServerEvent,
boolean overrideOwnership)
Set Room Variables.
|
void |
setUserVariables(User owner,
java.util.List<UserVariable> variables)
Set User Variables.
|
void |
setUserVariables(User owner,
java.util.List<UserVariable> variables,
boolean fireClientEvent,
boolean fireServerEvent)
Set User Variables.
|
void |
spectatorToPlayer(User user,
Room targetRoom,
boolean fireClientEvent,
boolean fireServerEvent)
Turns a spectator in a Game Room to a Player.
|
void |
subscribeRoomGroup(User user,
java.lang.String groupId)
Subscribe User to a Room Group.
|
void |
unsubscribeRoomGroup(User user,
java.lang.String groupId)
Unsubscribe User to a Room Group.
|
com.smartfoxserver.v2.api.response.ISFSResponseApi getResponseAPI()
TaskScheduler getSystemScheduler()
TaskScheduler
TaskScheduler getNewScheduler(int threadPoolSize)
threadPoolSize
- the size of the thread pool backing the SchedulerTaskScheduler
boolean checkSecurePassword(ISession session, java.lang.String originalPass, java.lang.String encryptedPass)
session
- the client sessionoriginalPass
- the original un-encrypted password (typically coming from the user DB)encryptedPass
- the encrypted password sent by the clientjava.lang.IllegalArgumentException
- if invalid hash strings are passedUser login(ISession session, java.lang.String name, java.lang.String pass, java.lang.String zoneName, ISFSObject params)
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:
SFSEventType.USER_LOGIN
and SFSEventType.USER_JOIN_ZONE
and perform custom operations.
session
- the client sessionname
- the user namepass
- the user passwordzoneName
- the name of the Zone to joinparams
- (optional) custom params to send back in the client onLogin eventUser
,
Zone
,
SFSEventType.USER_LOGIN
,
SFSEventType.USER_JOIN_ZONE
User login(ISession session, java.lang.String name, java.lang.String pass, java.lang.String zoneName, ISFSObject params, boolean forceLogout)
forceLogout
- forces a previous connection outlogin(ISession, String, String, String, ISFSObject)
void logout(User user)
user
- the Userlogin(ISession, String, String, String, ISFSObject)
User createNPC(java.lang.String userName, Zone zone, boolean forceLogin) throws SFSLoginException
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.
userName
- the NPC namezone
- the ZoneforceLogin
- if a User already exists with that name, it will disconnect it firstSFSLoginException
void kickUser(User userToKick, User modUser, java.lang.String kickMessage, int delaySeconds)
userToKick
- the User to be kickedmodUser
- the mod/admin user, can be null to indicate generically the "Server"kickMessage
- a moderator messagedelaySeconds
- delay before the disconnection is performedvoid banUser(User userToBan, User modUser, java.lang.String banMessage, BanMode mode, int durationMinutes, int delaySeconds)
The length of the banishment and the rules under which the ban can be removed are specified in your Zone configuration
userToBan
- the User to be bannedmodUser
- the mod/admin user, can be null to indicate generically the "Server"banMessage
- a moderator messagemode
- choose between banning by Ip Address or by User namedurationMinutes
- the duration of the banishment in minutesdelaySeconds
- delay before the disconnection is performedvoid disconnectUser(User user)
user
- the UserdisconnectUser(User, IDisconnectionReason)
void disconnectUser(User user, IDisconnectionReason reason)
user
- the Userreason
- the reason for disconnectionClientDisconnectionReason
void disconnect(ISession session)
session
- the SessionRoom createRoom(Zone zone, CreateRoomSettings settings, User owner) throws SFSCreateRoomException
zone
- the Zone in which the Room is going to be createdsettings
- the Room settingsowner
- the Room owner, when null it indicates that the Room is owned by the Server itselfSFSCreateRoomException
CreateRoomSettings
Room createRoom(Zone zone, CreateRoomSettings settings, User owner, boolean joinIt, Room roomToLeave) throws SFSCreateRoomException
zone
- the Zone in which the Room is going to be createdsettings
- the Room settingsowner
- the Room owner, when null it indicates that the Room is owned by the Server itselfjoinIt
- if true the Room will be joined by the owner right after creationroomToLeave
- a previous Room to leave after the join, or nullSFSCreateRoomException
CreateRoomSettings
Room createRoom(Zone zone, CreateRoomSettings settings, User owner, boolean joinIt, Room roomToLeave, boolean fireClientEvent, boolean fireServerEvent) throws SFSCreateRoomException
zone
- the Zone in which the Room is going to be createdsettings
- the Room settingsowner
- the Room owner, when null it indicates that the Room is owned by the Server itselfjoinIt
- if true the Room will be joined by the owner right after creationroomToLeave
- a previous Room to leave after the join, or nullfireClientEvent
- fire a client side EventfireServerEvent
- fire a server side EventSFSCreateRoomException
CreateRoomSettings
java.util.List<User> findUsers(java.util.Collection<User> userList, MatchExpression expression, int limit)
userList
- the collection of Users to searchexpression
- the matching expressionlimit
- 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.java.util.List<Room> findRooms(java.util.Collection<Room> roomList, MatchExpression expression, int limit)
roomList
- the list of Rooms to searchexpression
- the matching expressionlimit
- 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.User getUserById(int userId)
userId
- the User IDUser getUserByName(java.lang.String name)
name
- the User nameUser getUserBySession(ISession session)
session
- the Sessionvoid joinRoom(User user, Room room) throws SFSJoinRoomException
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.
user
- room
- SFSJoinRoomException
void joinRoom(User user, Room roomToJoin, java.lang.String password, boolean asSpectator, Room roomToLeave) throws SFSJoinRoomException
user
- the UserroomToJoin
- the room to joinpassword
- an optional password if the room requires it. Use null if no password is neededasSpectator
- join the room as spectator, in case of a game roomroomToLeave
- optionally specify a Room that should be left if roomToJoin is successfully joined.SFSJoinRoomException
void joinRoom(User user, Room roomToJoin, java.lang.String password, boolean asSpectator, Room roomToLeave, boolean fireClientEvent, boolean fireServerEvent) throws SFSJoinRoomException
user
- the UserroomToJoin
- the room to joinpassword
- an optional password if the room requires it. Use null if no password is neededasSpectator
- join the room as spectator, in case of a game roomroomToLeave
- optionally specify a Room that should be left if roomToJoin is successfully joined.fireClientEvent
- fires client side EventfireServerEvent
- fires server side EventSFSJoinRoomException
void leaveRoom(User user, Room room)
user
- the Userroom
- the Roomvoid leaveRoom(User user, Room room, boolean fireClientEvent, boolean fireServerEvent)
user
- the Userroom
- the RoomfireClientEvent
- fires client side EventfireServerEvent
- fires server side Eventvoid removeRoom(Room room)
room
- the Roomvoid removeRoom(Room room, boolean fireClientEvent, boolean fireServerEvent)
room
- the RoomfireClientEvent
- fires client side EventfireServerEvent
- fires server side Eventvoid sendPublicMessage(Room targetRoom, User sender, java.lang.String message, ISFSObject params)
targetRoom
- the Room where the message is sentsender
- the User sending the messagemessage
- the chat messageparams
- a custom object with additional parameters (e.g. text color, font size, etc...)void sendPrivateMessage(User sender, User recipient, java.lang.String message, ISFSObject params)
sender
- the sender of the messagerecipient
- the recipient of the messagemessage
- the chat messageparams
- a custom SFSObjects with extra parameters (e.g. the font type, color etc...)void sendBuddyMessage(User sender, User recipient, java.lang.String message, ISFSObject params) throws SFSBuddyListException
SFSBuddyListException
void sendGenericMessage(com.smartfoxserver.v2.api.GenericMessageType type, User sender, int targetRoomId, java.lang.String message, ISFSObject params, java.util.Collection<ISession> recipients)
void sendModeratorMessage(User sender, java.lang.String message, ISFSObject params, java.util.Collection<ISession> recipients)
sender
- the moderator user sending this message or null, indicating a Server originated mod messagemessage
- the messageparams
- an SFSObject with custom parametersrecipients
- the recipients of the messagevoid sendAdminMessage(User sender, java.lang.String message, ISFSObject params, java.util.Collection<ISession> recipients)
sender
- the admin user sending this message or null, indicating a Server originated admin messagemessage
- the messageparams
- an SFSObject with custom parametersrecipients
- the recipients of the messagevoid 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.
targetRoom
- the room where the message will be sent tosender
- the sender of the messagemessage
- a custom SFSObjectrecipients
- use null to send the message to all clients in the Room, or specify a collection of users that should receive the messagevoid sendExtensionResponse(java.lang.String cmdName, ISFSObject params, java.util.List<User> recipients, Room room, boolean useUDP)
void sendExtensionResponse(java.lang.String cmdName, ISFSObject params, User recipient, Room room, boolean useUDP)
void setRoomVariables(User user, Room targetRoom, java.util.List<RoomVariable> variables)
user
- the sender (null == sets ownership of the variables to the Server itself)targetRoom
- the Room in which variables should be setvariables
- a list of Room variablesRoomVariable
void setRoomVariables(User user, Room targetRoom, java.util.List<RoomVariable> variables, boolean fireClientEvent, boolean fireServerEvent, boolean overrideOwnership)
user
- the sender (null == sets ownership of the variables to the Server itself)targetRoom
- the Room in which variables should be setvariables
- a list of RoomVariablesfireClientEvent
- fires client side EventfireServerEvent
- fires server side EventoverrideOwnership
- allow to override the ownership of variablesRoomVariable
void setUserVariables(User owner, java.util.List<UserVariable> variables)
owner
- the User for which variables are setvariables
- a list of UserVariablesUserVariable
void setUserVariables(User owner, java.util.List<UserVariable> variables, boolean fireClientEvent, boolean fireServerEvent)
owner
- the User for which variables are setvariables
- a list of UserVariablesfireClientEvent
- fires client side EventfireServerEvent
- fires server side EventUserVariable
void changeRoomName(User owner, Room targetRoom, java.lang.String newName) throws SFSRoomException
owner
- the User, it can be null if this is called on the server sidetargetRoom
- the RoomnewName
- the new Room nameSFSRoomException
void changeRoomPassword(User owner, Room targetRoom, java.lang.String newPassword) throws SFSRoomException
owner
- the User, it can be null if this is called on the server sidetargetRoom
- the RoomnewPassword
- the new passwordSFSRoomException
void changeRoomCapacity(User owner, Room targetRoom, int maxUsers, int maxSpectators) throws SFSRoomException
owner
- owner of the Room, the requester must be owner of the Room or SuperUsertargetRoom
- the roommaxUsers
- new maxUsers valuemaxSpectators
- new maxSpectators valueSFSRoomException
void subscribeRoomGroup(User user, java.lang.String groupId)
user
- the UsergroupId
- the group namevoid unsubscribeRoomGroup(User user, java.lang.String groupId)
user
- the UsergroupId
- the group namevoid spectatorToPlayer(User user, Room targetRoom, boolean fireClientEvent, boolean fireServerEvent) throws SFSRoomException
user
- the UsertargetRoom
- the Room in which the spectator will be turned into a playerfireClientEvent
- if true send an update to the client (recommended)fireServerEvent
- if true fire a server side eventSFSRoomException
void playerToSpectator(User user, Room targetRoom, boolean fireClientEvent, boolean fireServerEvent) throws SFSRoomException
user
- the UsertargetRoom
- the Room in which the player will be turned into a spectatorfireClientEvent
- if true send an update to the client (recommended)fireServerEvent
- if true fire a server side eventSFSRoomException