Clients

From EsWiki

Jump to: navigation, search

ElectroServer 4 Flash ActionScript API is the integration point between the developer and ElectroServer. Developers use the API to:

  • Create requests to send to the server
  • Capture responses and events sent from the server
  • Manage users, rooms, and connections

This article covers the general structure and concepts behind the ElectroServer 4 ActionScript API. It also discusses some differences between the ActionScript 2 and ActionScript 3 APIs, and finishes with a list of commonly used classes and methods.

Note: Electrotank does not maintain an ActionScript 1 API for use with ElectroServer 4. If you want to use ActionScript 1 with ElectroServer 4 you can, but you will need to write it yourself.

Contents

ActionScript API Overview

A Flash application must first open a socket connection to ElectroServer. Once the socket has been established, the client and server can communicate. How the client and server communicate (the form that the messages take) is the message protocol. The ElectroServer 4 ActionScript API provides a series of useful classes that handle communication with ElectroServer so developers don’t need to understand the protocol used. The API also internally manages a range of other classes for things like user lists and room lists.

Both ActionScript 2 and ActionScript 3 APIs are available. These APIs are nearly identical. To use the API in your application, you need to download it and add it to your application’s classpath. These APIs are used to create content for the following Flash players and later: Flash 6, Flash 7, Flash 8, Flash 9, Flash Lite 2.1, Flash Lite 3.

There are three important things to know about the ActionScript API, described in detail below.

Note: It is strongly recommended that Flash Develop or other ActionScript development tool that supports Intellisense be used when developing ElectroServer applications. Intellisense (intelligent code hinting) is invaluable when working with any rich API such as the ElectroServer 4 ActionScript APIs. If you choose to code on frames or using the Flash IDE then you may find yourself needing to look up information constantly.

The ElectroServer Class

The most important class in the API is the ElectroServer class which provides useful methods that allows developers to:

  • Create one or more socket connections to ElectroServer
  • Send requests
  • Create an RTMP connection for audio/video streams
  • Create a binary connection for transfer of files such as images
  • Access the internally managed data such as rooms, zones, users, buddies, and connections 
   import com.electrotank.electroserver4.ElectroServer;
   
   var es:ElectroServer = new ElectroServer();
   es.createConnection("127.0.0.1",9875); //ip, port
   
   Figure 1: How to create a connection to ElectroServer 4 using the ElectroServer class.



   var zone:Zone = es.getZoneManager().getZoneByName("Game Zone");
   var room:Room = zone.getRoomByName("Lobby 13");
   var usersInRoom:Array = room.getUsers();
   for (var i:int=0; i<usersInRoom.length;++i) {
   	var user:User = usersInRoom[i];
   	trace("name: "+user.getUserName());
   }
   
   Figure 2:  How to use the API to get the zone list, find a room in the zone, and trace the user names of users in that room.

Requests, Responses, and Events

Nearly every time the Flash client sends something to the server, it is a request such as a LoginRequest with a specific user name, or a JoinRoomRequest to join a room. Some requests will generate a response from the server. For example: A LoginRequest will always cause a LoginResponse. A response is nearly always sent from the server to the client (on rare occasion one is sent from the client to the server). Things that happen on the server that the user needs to know about are called events. User list updates, chat messages, and room list updates are examples of events. Events are always sent from the server to the client. 

   var loginRequest:LoginRequest = new LoginRequest();
   loginRequest.setUserName("coolio");
   es.send(loginRequest);
   
   Figure 3: LoginRequest object is created and then sent to ElectroServer using the ElectroServer class.

Event Handling

The API captures client-bound server responses and events. The developer must use event listeners to tie their own code to these events. The MessageType class contains every request, response, and event the ElectroServer API uses. Every request, response, and event has its own class. This makes for a larger but cleaner and less ambiguous API. 

   import com.electrotank.electroserver4.ElectroServer;
   import com.electrotank.electroserver4.message.MessageType;
   import com.electrotank.electroserver4.message.event.ConnectionEvent;
   
   var es:ElectroServer = new ElectroServer();
   es.createConnection("127.0.0.1",9875);
   es.addEventListener(MessageType.ConnectionEvent, "onConnectionEvent", this);
   function onConnectionEvent(e:ConnectionEvent):Void {
   	if (e.getAccepted()) {
   		//login
   	} else {
   		//tell the user login failed
   	}
   }
   
   Figure 4: Importing the ElectroServer class, the MessageType class, and the ConnectionEvent class.  
   A new instance of ElectroServer class is created and used to create a server connection. 
   An event listener is used to capture the ConnectionEvent.

Differences between the ActionScript 2 and ActionScript 3 APIs

The ActionScript 2 and ActionScript 3 APIs are nearly identical. So much so that documentation is only provided for the ActionScript 3 API. The documentation outlines the rare places where the APIs differ. The documentation contains example code written in ActionScript 3. In general, this code is usable in ActionScript 2 applications as long as you convert 'void' to 'Void' and 'int' to 'Number'.

Here are the places to look out for differences in the APIs:

  • The ActionScript 2 API does not support binary protocol.
  • The ActionScript 2 API EsObject supports get/set Integer, but uses Number.

Commonly Used Classes and Methods

The API is extensive, so we've provided some common classes and methods for quick reference.

The full API documentation can be found at http://electro-server.com/documentation/docs/es4/as3/index.html

Commonly Used Classes

ConnectionEvent
Fired when an attempted connection to ElectroServer succeeds or fails
LoginRequest
Used to log in to the server
LoginResponse
Message with success information that is sent back to a client requesting to log in
CreateRoomRequest
Provides a way to create a room with many configurable options
JoinRoomEvent
Fired when a logged-in user joins a room
PublicMessageRequest
Used to create a chat message to send to a room that the logged-in user belongs to
PublicMessageEvent
Triggered when a chat message is sent to a room that the logged-in user belongs to
UserListUpdateEvent
Fired when the user list changes in a room that the logged-in user is in; contains useful information about what changed

Common ElectroServer Class Methods

createConnection(ip:String, port:Number): Attempts to create a socket connection between the Flash client and ElectroServer. The ConnectionEvent event is fired with the results of the request.

send(request): When sending something to ElectroServer you must first create a request object (such as LoginRequest), populate it with custom information if needed, and then use the send method to send to ElectroServer.

createRtmpConnection(ip:String, port:Number): An RTMP connection must be created to stream live audio and video using ElectroServer. When the connection has succeeded or failed the RtmpConnectionEvent is fired.

Errors

The word error has a wide meaning here. When working with ElectroServer a client can perform actions that indicate the client did something inappropriate (such as using vulgarity in a public message) or that the server could not do what was asked of it (such as joining a room that doesn't exist).

Most errors are received by the client as a GenericErrorEvent. The specific error that occurred is contained within the event details. For instance, if the user reaches the idle time out (they have been inactive for too long) then they receive a GenericErrorEvent that contains a more specific IdleTimeReached error.

If a user sent a request that requires a response, and that request caused an error, then the error is contained within the response object. For instance, if a user sends a LoginRequest to the server that contains a user name that is already in use, then the LoginResponse object contains a UserNameExists error.

Error List

UserNameExists
The user name used during login already exists.
UserAlreadyLoggedIn
The user trying to login is already logged in.
InvalidMessageNumber
The API sent a message to the server with an invalid message number.
InboundMessageFailedValidation
The API sent a message to the server that did not pass validation.
MaximumClientConnectionsReached
The user trying to login cannot successfully login because the maximum number of client connections for the server license has been reached.
ZoneNotFound
The zone that the client is trying to work with was not found.
RoomNotFound
The room that the client is trying to work with was not found.
RoomAtCapacity
The room that the client is attempting to join is already at capacity.
RoomPasswordMismatch
The password that the client submitted when joining a room is not correct.
GatewayPaused
The gateway to which a client is connected is paused.
AccessDenied
The client does not have permission to perform the requested action.
RoomVariableLocked
The room variable that a client is trying to update cannot be updated because it is locked.
RoomVariableAlreadyExists
The room variable that a client is trying to create cannot be created because it already exists.
DuplicateRoomName
The room that the client is trying to create fails because the room name is already in use in the specified zone.
UserVariableAlreadyExists
The user variable the client is trying to create fails because it already exists.
UserVariableDoesNotExist
The user variable that the client is trying to update or delete fails because it does not exist.
UserBanned
The client was banned.
UserAlreadyInRoom
The client trying to join a room is already in that room.
VulgarityCheckFailed
Content submitted by the client failed a language filter check. This applies to chat messages, room names, and user names.
ActionCausedError
The client sent a message that caused an error. The client is disconnected.
ActionRequiresLogin
The client has tried to perform an action that requires login.
PluginNotFound
The client tried to communicate with a plugin that could not be found.
LoginEventHandlerFailure
An exception happened in a LoginEventHandler during the login process.
InvalidUserName
The client specified a user name that does not exist.
ExtensionNotFound
The client tried to use an extension that was not found.
PluginInitializationFailed
The client created a room with a plugin and that plugin failed to initialize.
FloodingFilterCheckFailed
The client sent too many messages that were detected as flooding.
UserNotJoinedToRoom
Client attempted to interact with a room in a way that only a user in that room can.
ManagedObjectNotFound
Client attempted to communicate with a ManagedObject that was not found.
IdleTimeReached
The client has been idle (no activity) for longer than the allowed idle time. The client will be disconnected.
ServerError
The client performed an action that caused an error.
OperationNotSupported
The client called a plugin and that plugin did not implement the request event.
InvalidLanguageFilterSettings
The language filter settings supplied during the room creation process were not valid.
InvalidFloodingFilterSettings
The flooding filter settings supplied during the room creation process were not valid.
ExtensionForcedReload
See Extension Reloading Process.
UserLogOutRequested
The server is requesting that the client log out.
OnlyRtmpConnectionRemains
The socket connection has been lost and only an RTMP connection remains.
GameDoesntExist
The game specified by the client does not exist.
FailedToJoinGameRoom
The game that a client is attempting to join fails.
GameIsLocked
The game that a client is attempting to join is locked.
PublicMessageRejected
The server captured a public message and decided to kill it. This error is sent back to the sending client.
Retrieved from "http://es-wiki.com/index.php?title=Clients"
Personal tools
download