GFS Server - Documentation
GFS Server is relatively easy to work with. There are certain events that you will subscribe to from your Flash CS3 or Flex 3 applications/games as well there are numerous method calls you can make to talk to the GFS Server. If you haven't done so already you will probably want to go through the tutorials first before reading further.
Using the methods and events listed here is critical to using GFS Server. Take a look at the GFS Admin Tool, FlexChat, and FlashChat project's source code to get a good understanding of how to use these.
GFS Server - Methods
Methods highlighted in blue are typically used in your chat or game applications. Events highlighted in red are usually only used for administrative functions.
Creating the GFSServerXMLSocketManager Class
Before doing anything else you need to create a new instance of the GFSServerXMLSocketManager and hand it the address and port you wish to connect to.
var manager:GFSServerXMLSocketManager = new
GFSServerXMLSocketManager("127.0.0.1", 843);
Connection Methods
disconnect - Disconnects the user from the GFS Server.
connect - This is called when you want to make the socket connection to GFS Server.
Login Methods
login(username:String, password:String) - Logs the user in using the username and password passed in the parameters.
loginNoPassword(username:String) - Logs the user in using the username passed in the parameters (no security). This is good for scenarios where you have an anonymous chat application, or anonymous games where you won't be saving properties.
Account Methods
changePassword(username:String, newPassword:String) - Changes the specified user's password using the supplied newPassword parameter. If the resquest comes from a user then it will only change the user's password. If the request comes from the admin account, then the admin can specifiy any valid username to change their password.
createAccount(userName:String, password:String) - Creates a new account with the passed in parameters. If your calling this from the admin account you can create any username (that isn't already used). You can create accounts from the GFS Admin Tool as well as through this method call from a connected user.
checkIfAccountIsDisabled(username:String) - Checks to see if the specified username's account is disabled. This method can only be called by the admin account.
deleteAccount(userName:String) - Deletes the specified account and can only be called from the admin account.
disableAccount(username:String) - Disables an account. This method takes a string as a parameter which would be the user account you want to disable. This method can only be called by the admin account.
enableAccount(username:String) - Enables an account. This method takes a string as a parameter which would be the user account you want to enable. This method can only be called by the admin account.
Broadcast Methods
sendGameMessage(messageText:String) - Sends a game message. This can be almost anything but should not be displayed visibly to the user. An example would be sending an update to all users in a game room, for example: Name:Player1,Health:100,XCoord:14,YCoord:40
You can then take the incoming game messages on the other player's machines and parse the information and update accordingly.
sendPrivateMessage(toUsername:String, messageText:String) - Sends a private message to the username specified. Doesn't matter what room the user is a member of as long as they are currently connected.
sendRoomMessage(messageText:String) - Sends a message to the room the user is currently a member of.
sendSystemBroadcast(messageText:String) - This message can be sent from the GFS Admin Tool (or programmatically) and is used to send a system message to all connected clients. Example: "The Server is going down in 5 minutes, please log out". Only an admin can call this method.
Room Methods
createRoom() - Creates a new room. The new room always takes the user's username.
joinRoom(roomName:String) - Joins the specified room. The room the user is currently a member of will be notified that the user has left the room.
leaveRoom() - The user will leave the current room and return to the lobby. The lobby is always present. Remaining users in the room the user just left will be notified of their depature.
requestRoomList() - Requests the newest room list. See the FlashChat or FlexChat projects to see how to parse the incoming data from this request.
Property Methods
insertProperty(propertyName:String, propertyValue:String) - Inserts a new persistent property in the database. This property can be deleted and updated as required. It will stay in the database between the user's connections. This property will remain in the database until the deleteProperty method is called on it.
Property names are limited to 15 characters
Property values are limited to 100 characters
deleteProperty(userName:String, propertyName:String) - Deletes the specified persistent property for the specified username. Only users can delete their own properties, an admin can delete anyone's property.
readProperty(userName:String, propertyName:String) - Reads a specified property for the specified username. Only users can read their own properties, an admin can read anyone's property.
updateProperty(propertyName:String, propertyValue:String) - Updates the specified persistent property.
insertGlobalProperty(propertyName:String, propertyValue:String) - Inserts a new persistent global property in the database. This property can be deleted and updated as required. This property will remain in the database until the deleteGlobalProperty method is called on it.
Global Property names are limited to 15 characters
Global Property values are limited to 100 characters
deleteGlobalProperty(userName:String, propertyName:String) - Deletes the specified persistent global property.
readGlobalProperty(propertyName:String) - Reads a specified global property.
updateGlobalProperty(propertyName:String, propertyValue:String) - Updates the specified persistent global property.
getAllUserPropertyNames(username:String) - Gets all the persistent database property names for the specified user. This method takes a string as a parameter which would be the username you want to query. If this method is called by the admin account you can use any valid username, if this is called from a regular user then they will only see their property names.
readSessionProperty(propertyName:String) - Reads a specified session property for the specified username. Only user can read their own session properties, an admin can read anyone's session property.
There are two properties that are populated by the GFS Server each time a user logs in and is kept updated by the GFS Server. GFS Server will record their: IP Address and Room (the room they are currently in). For a user called "Joe" I could read these properties like this:
socketManager.readProperty("Joe", "ip");
socketManager.readProperty("Joe", "room");
Where socketManager is an instance of the GFSServerXMLSocketManager class.
To get the results you need to be subscribed to the READ_SESSION_PROPERTY_RESULT
insertSessionProperty(propertyName:String, propertyValue:String) - Inserts a new session property for the user. Session properties only last as long as the user's current connection stays open. When the connection is closed this property is deleted.
updateSessionProperty(propertyName:String, propertyValue:String) - Updates the specified session property.
Administrative Methods
block(ip:String) - Block an IP address. The blocked IP will not be allowed to connect anymore. This method can only be called by the admin account.
You can get a connected user's IP address by calling the
unblock(ip:String) - Unblocks an IP address. This method can only be called by the admin account.
getAllDBUsernames - Gets all the usernames from the database. The returned result is the usernames in a comma delimted format. This method can only be called by the admin account.
getUserLastLogin(username:String) - Gets the specified user's last login date. This method takes a string as a parameter which would be the username you want to query. This method can only be called by the admin account.
kick(username:String) - Kicks a user from the GFS Server and deletes their account. This method can only be called by the admin account.
shutdownServer() - Shuts the GFS Server down cleanly. You should always call this from the GFS Admin Tool when you want to shutdown the GFS Server. This can only be called by the admin account.
retrieveAdminPassword - If you have forgotten the admin password you can call this method from any account. A text file will be written the the location where the GFS Server jar file resides called "AdminPassword". This file will contain the admin password. You must have access to the server hosting the GFS Server in order to open this file.
Misc. Methods
requestUserList() - Requests the newest user list. See the FlashChat or FlexChat projects to see how to parse the incoming data from this request.
getOnlineUserCount() - Gets the total amount of connected users to the GFS Server.
getServerVersion() - Gets the version of the GFS Server being used.
getUsersIP(username:String) - Gets the IP address for a specified user.
GFS Server Events
Events highlighted in blue are typically used in your chat or game applications. Events highlighted in red are usually only used for administrative functions and not exposed to the user from their applications
The GFSServerEvent passes back four kinds of information which may or may not be populated - depends on the event. Looking at the source code for the FlashChat, FlexChat, and GFS Admin Tool will show you how to use this.
Connection Events
CONNECTED - The client has been connected to GFS Server.
NOT_CONNECTED - The user is not connected to GFS Server.
CONNECTION_LIMIT_HIT - All available connections are used.
SESSION_TIMED_OUT - The user has been inactive for too long and has been disconnected. This time is defaulted to 120 seconds (2 minutes). You can change this value from the GFS Admin Tool.
USER_DISCONNECTED - A user has disconnected.
Login Events
LOGIN_OK - The user is now logged in (using authentication).
LOGIN_ERROR_USER_ALREADY_LOGGED_IN - The username is already logged in. This should not happen unless someone has shared their username/password or they are trying to log in twice.
LOGIN_ERROR_WRONG_PASSWORD_OR_USERNAME - Wrong username or password.
Account Events
ACCOUNT_CREATED - A new account has been created.
ACCOUNT_CREATION_ERROR_UNSPECIFIED - Unknown error when attempting to create the new account.
ACCOUNT_CREATION_ERROR_USERNAME_EXISTS - A username already exists so the one the user is trying to use will need to be changed to something else.
ACCOUNT_STATUS - Returns the account status which will either return "T" (True) or "F" (False). "True" meaning the account is enabled, "False" meaning it is disabled.
Incoming (Broadcast) Events
INCOMING_GAME_MESSAGE - A new message is coming into the room the user is subscribed to, this is can be something like a game update (Example: Player 4's health has decreased to 5)
INCOMING_PRIVATE_MESSAGE - A new private message is coming to the user from another user.
INCOMING_ROOM_MESSAGE - A new message is coming into the room the user is subscribed to.
INCOMING_SYSTEM_BROADCAST_MESSAGE - This message can be sent from the GFS Admin Tool (or programmatically) and is used to send a system message to all connected clients. Example: "The Server is going down in 5 minutes, please log out". You should display this to all connected users and perhaps use a red font to signify the importance.
INCOMING_ROOM_LIST - The rooms list has been updated
INCOMING_USER_LIST - The user list has been updated
INCOMING_USER_COUNT - The connected user count has been updated
INCOMING_DB_USERS_LIST - Returns all the usernames in the embedded database.
INCOMING_LAST_LOGIN_DATE - Gets the last time the user logged in.
INCOMING_USER_PROPERTY_NAMES - Gets all the property namesfrom the database that are set for the specified user.
INCOMING_GLOBAL_PROPERTY_NAMES - Gets all the global property names from the database.
Room Events
ROOM_CREATED - A new room has been created. This only gets broadcasted in the lobby room.
USER_LEFT_ROOM - A user has left the room that the current user is a member of.
USER_JOINED_ROOM - A user has joined the room that the current user is a member of.
Property Events
READ_PROPERTY_RESULT - A request to read a user's property has completed (this kind of property is persisted in the database between connects and can be updated and deleted as needed).
READ_GLOBAL_PROPERTY_RESULT - A request to read a global property has completed (this kind of property is persisted in the database between connects and can be updated and deleted as needed).
READ_SESSION_PROPERTY_RESULT - A request to read a user's session property (only valid during the time the user is connected and is erased when they log out) has completed.
Password Events
PASSWORD_CHANGED - A user's password has been changed.
PASSWORD_CHANGED_ERROR - The user's password could not be changed.
Last Updated: Mar. 11, 2008
