public class SFSApi extends java.lang.Object implements ISFSApi
APIManager
,
SmartFoxServer.getAPIManager()
,
SFSBuddyApi
,
SFSGameApi
,
SFSMMOApi
Modifier and Type | Field and Description |
---|---|
protected com.smartfoxserver.v2.entities.managers.IUserManager |
globalUserManager |
protected org.slf4j.Logger |
log |
protected com.smartfoxserver.v2.api.response.ISFSResponseApi |
responseAPI |
protected SmartFoxServer |
sfs |
Constructor and Description |
---|
SFSApi(SmartFoxServer sfs) |
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 params,
User owner)
Create a new Room
|
Room |
createRoom(Zone zone,
CreateRoomSettings params,
User owner,
boolean joinIt,
Room roomToLeave)
Create a new Room
|
Room |
createRoom(Zone zone,
CreateRoomSettings params,
User owner,
boolean joinIt,
Room roomToLeave,
boolean fireClientEvent,
boolean fireServerEvent) |
void |
disconnect(ISession session)
Removes a Session and the User connected with that session, if one exists
|
void |
disconnectUser(User user)
Disconnect a User from the server.
|
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 sender,
java.lang.String name,
java.lang.String pass,
java.lang.String zoneName,
ISFSObject paramsOut)
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 sender,
java.lang.String name,
java.lang.String pass,
java.lang.String zoneName,
ISFSObject paramsOut,
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.
|
protected final SmartFoxServer sfs
protected final org.slf4j.Logger log
protected com.smartfoxserver.v2.entities.managers.IUserManager globalUserManager
protected final com.smartfoxserver.v2.api.response.ISFSResponseApi responseAPI
public SFSApi(SmartFoxServer sfs)
public TaskScheduler getSystemScheduler()
getSystemScheduler
in interface ISFSApi
TaskScheduler
public TaskScheduler getNewScheduler(int threadPoolSize)
getNewScheduler
in interface ISFSApi
threadPoolSize
- the size of the thread pool backing the SchedulerTaskScheduler
public com.smartfoxserver.v2.api.response.ISFSResponseApi getResponseAPI()
getResponseAPI
in interface ISFSApi
public User getUserById(int userId)
getUserById
in interface ISFSApi
userId
- the User IDpublic User getUserByName(java.lang.String name)
getUserByName
in interface ISFSApi
name
- the User namepublic User getUserBySession(ISession session)
getUserBySession
in interface ISFSApi
session
- the Sessionpublic void kickUser(User userToKick, User modUser, java.lang.String kickMessage, int delaySeconds)
public void 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
banUser
in interface ISFSApi
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 performedpublic java.util.List<Room> findRooms(java.util.Collection<Room> roomList, MatchExpression expression, int limit)
findRooms
in interface ISFSApi
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.public java.util.List<User> findUsers(java.util.Collection<User> userList, MatchExpression expression, int limit)
findUsers
in interface ISFSApi
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.public void disconnect(ISession session)
disconnect
in interface ISFSApi
session
- the sessionpublic void disconnectUser(User user, IDisconnectionReason reason)
disconnectUser
in interface ISFSApi
user
- the Userreason
- the reason for disconnectionClientDisconnectionReason
public void disconnectUser(User user)
disconnectUser
in interface ISFSApi
user
- the userISFSApi.disconnectUser(User, IDisconnectionReason)
public void removeRoom(Room room)
removeRoom
in interface ISFSApi
room
- the Roompublic void removeRoom(Room room, boolean fireClientEvent, boolean fireServerEvent)
removeRoom
in interface ISFSApi
room
- the RoomfireClientEvent
- fires client side EventfireServerEvent
- fires server side Eventpublic boolean checkSecurePassword(ISession session, java.lang.String originalPass, java.lang.String encryptedPass)
checkSecurePassword
in interface ISFSApi
session
- the client sessionoriginalPass
- the original un-encrypted password (typically coming from the user DB)encryptedPass
- the encrypted password sent by the clientpublic User login(ISession sender, java.lang.String name, java.lang.String pass, java.lang.String zoneName, ISFSObject paramsOut)
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.
login
in interface ISFSApi
sender
- the client sessionname
- the user namepass
- the user passwordzoneName
- the name of the Zone to joinparamsOut
- (optional) custom params to send back in the client onLogin eventUser
,
Zone
,
SFSEventType.USER_LOGIN
,
SFSEventType.USER_JOIN_ZONE
public User login(ISession sender, java.lang.String name, java.lang.String pass, java.lang.String zoneName, ISFSObject paramsOut, boolean forceLogout)
login
in interface ISFSApi
forceLogout
- forces a previous connection outISFSApi.login(ISession, String, String, String, ISFSObject)
public void logout(User user)
logout
in interface ISFSApi
user
- the UserISFSApi.login(ISession, String, String, String, ISFSObject)
public 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.
createNPC
in interface ISFSApi
userName
- the NPC namezone
- the ZoneforceLogin
- if a User already exists with that name, it will disconnect it firstSFSLoginException
public Room createRoom(Zone zone, CreateRoomSettings params, User owner) throws SFSCreateRoomException
createRoom
in interface ISFSApi
zone
- the Zone in which the Room is going to be createdparams
- the Room settingsowner
- the Room owner, when null it indicates that the Room is owned by the Server itselfSFSCreateRoomException
CreateRoomSettings
public Room createRoom(Zone zone, CreateRoomSettings params, User owner, boolean joinIt, Room roomToLeave) throws SFSCreateRoomException
createRoom
in interface ISFSApi
zone
- the Zone in which the Room is going to be createdparams
- 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
public Room createRoom(Zone zone, CreateRoomSettings params, User owner, boolean joinIt, Room roomToLeave, boolean fireClientEvent, boolean fireServerEvent) throws SFSCreateRoomException
createRoom
in interface ISFSApi
zone
- the Zone in which the Room is going to be createdparams
- 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
public void 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.
joinRoom
in interface ISFSApi
SFSJoinRoomException
public void joinRoom(User user, Room roomToJoin, java.lang.String password, boolean asSpectator, Room roomToLeave) throws SFSJoinRoomException
joinRoom
in interface ISFSApi
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
public void joinRoom(User user, Room roomToJoin, java.lang.String password, boolean asSpectator, Room roomToLeave, boolean fireClientEvent, boolean fireServerEvent) throws SFSJoinRoomException
joinRoom
in interface ISFSApi
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
public void leaveRoom(User user, Room room, boolean fireClientEvent, boolean fireServerEvent)
public void sendPublicMessage(Room targetRoom, User sender, java.lang.String message, ISFSObject params)
sendPublicMessage
in interface ISFSApi
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...)public void sendPrivateMessage(User sender, User recipient, java.lang.String message, ISFSObject params)
sendPrivateMessage
in interface ISFSApi
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...)public void sendBuddyMessage(User sender, User recipient, java.lang.String message, ISFSObject params) throws SFSBuddyListException
sendBuddyMessage
in interface ISFSApi
SFSBuddyListException
public void sendModeratorMessage(User sender, java.lang.String message, ISFSObject params, java.util.Collection<ISession> recipients)
sendModeratorMessage
in interface ISFSApi
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 messagepublic void sendAdminMessage(User sender, java.lang.String message, ISFSObject params, java.util.Collection<ISession> recipients)
sendAdminMessage
in interface ISFSApi
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 messagepublic 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.
sendObjectMessage
in interface ISFSApi
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 messagepublic void sendExtensionResponse(java.lang.String cmdName, ISFSObject params, java.util.List<User> recipients, Room room, boolean useUDP)
sendExtensionResponse
in interface ISFSApi
public void sendExtensionResponse(java.lang.String cmdName, ISFSObject params, User recipient, Room room, boolean useUDP)
sendExtensionResponse
in interface ISFSApi
public void setRoomVariables(User user, Room targetRoom, java.util.List<RoomVariable> variables)
setRoomVariables
in interface ISFSApi
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
public void setRoomVariables(User user, Room targetRoom, java.util.List<RoomVariable> variables, boolean fireClientEvent, boolean fireServerEvent, boolean overrideOwnership)
setRoomVariables
in interface ISFSApi
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
public void setUserVariables(User owner, java.util.List<UserVariable> variables)
setUserVariables
in interface ISFSApi
owner
- the User for which variables are setvariables
- a list of UserVariablesUserVariable
public void setUserVariables(User owner, java.util.List<UserVariable> variables, boolean fireClientEvent, boolean fireServerEvent)
setUserVariables
in interface ISFSApi
owner
- the User for which variables are setvariables
- a list of UserVariablesfireClientEvent
- fires client side EventfireServerEvent
- fires server side EventUserVariable
public void changeRoomName(User owner, Room targetRoom, java.lang.String newName) throws SFSRoomException
changeRoomName
in interface ISFSApi
owner
- the User, it can be null if this is called on the server sidetargetRoom
- the RoomnewName
- the new Room nameSFSRoomException
public void changeRoomPassword(User owner, Room targetRoom, java.lang.String newPassword) throws SFSRoomException
changeRoomPassword
in interface ISFSApi
owner
- the User, it can be null if this is called on the server sidetargetRoom
- the RoomnewPassword
- the new passwordSFSRoomException
public void changeRoomCapacity(User owner, Room targetRoom, int maxUsers, int maxSpectators) throws SFSRoomException
changeRoomCapacity
in interface ISFSApi
owner
- owner of the Room, the requester must be owner of the Room or SuperUsertargetRoom
- the roommaxUsers
- new maxUsers valuemaxSpectators
- new maxSpectators valueSFSRoomException
public void subscribeRoomGroup(User user, java.lang.String groupId)
subscribeRoomGroup
in interface ISFSApi
user
- the UsergroupId
- the group namepublic void unsubscribeRoomGroup(User user, java.lang.String groupId)
unsubscribeRoomGroup
in interface ISFSApi
user
- the UsergroupId
- the group namepublic void sendGenericMessage(com.smartfoxserver.v2.api.GenericMessageType type, User sender, int targetRoomId, java.lang.String message, ISFSObject params, java.util.Collection<ISession> recipients)
sendGenericMessage
in interface ISFSApi
public void spectatorToPlayer(User user, Room targetRoom, boolean fireClientEvent, boolean fireServerEvent) throws SFSRoomException
ISFSApi
spectatorToPlayer
in interface ISFSApi
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
public void playerToSpectator(User user, Room targetRoom, boolean fireClientEvent, boolean fireServerEvent) throws SFSRoomException
ISFSApi
playerToSpectator
in interface ISFSApi
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