Using Socket Servers

Download and install the JRE (for Windows) by going to http://www.java.com. This page will probably detect your operating system automatically. Click the download link. The Java software most likely will be installed automatically through the Web browser.

To install and start ElectroServer 3 on Windows, open the Lesson12/Assets directory. Double-click the file called InstallElectroServer.exe to install ElectroServer 3, and follow the series of prompts to completion. You don't need to change any of the default options during the installation process.

To start ElectroServer 3, click Start > All Programs (or Program Files) > Electrotank > ElectroServer 3 > Start ElectroServer.

If you installed the JRE properly, ElectroServer 3 should have started without any problem.

By default, ElectroServer 3 will connect to the 127.0.0.1 IP address, which is the IP address by which your computer refers to itself. Also, the default port on which ElectroServer 3 will exchange data is 9875. Both the IP and the port are configurable, but you won't need to change the settings for the chat exercise.

• ElectroServer 3 (www.electrotank.com/ElectroServer/) is a full-featured socket server that was created specifically to meet the needs of multi-user Flash game developers. As such, it has features (not seen in other socket servers) that appeal to Flash game programmers.

• Macromedia Flash Communication Server (www.macromedia.com) is not a socket server, although it's similar to one. It uses a proprietary data-exchange protocol developed by Macromedia. It can be used to accomplish tasks such as video and audio transfer (for video chatting).

• Unity (www.moock.org/unity/) is a general socket server that can be used to create any number of multi-user applications, including chat and games.

Open Chat1.fla in the Lesson12/Assets folder.

The file contains four layers: the Actions layer, where we'll keep the ActionScript; the Labels layer, which contains the labels for the movie; the Assets layer, containing the text fields and buttons; and the Background layer, which contains the interface graphics.

We'll begin by scripting the code to get a user connected to ElectroServer 3, logged in, and joined to a room. A room is nothing more than a collection of users. When a user sends a chat message, it's automatically sent to everyone in the room. ElectroServer 3, like most socket servers, supports multiple rooms. Many rooms can exists at once, each with users. A user can switch from one room to another, as you'll see later in this exercise.

With the Actions panel open, select Frame 1 of the Actions layer and add the following script:

var es:ElectroServer = ElectroServer.getInstance();

The ElectroServer class is a static class (also known as a singleton), which means that only one instance of it can exist within your movie. To create this instance of the ElectroServer class, simply call the getInstance() method directly on the class, and it will return a reference to itself. The line of code in this step creates a variable named es, which is our reference to the instance of the ElectroServer class.

Using the following code, set the IP and port to which the chat should connect:

es.setIP("127.0.0.1");

es.setPort(9875);

When you installed ElectroServer 3, it created default settings that it would use for its operation. Unless these settings are changed, when you start ElectroServer 3 it will bind to your local IP address (127.0.0.1) and listen on port 9875. The script above tells the ElectroServer class instance at which IP address to look for ElectroServer 3, and which port at that IP it should use.

With the same frame selected, add the following code to capture the connection response from ElectroServer 3:

es.onConnection = function(success:Boolean, error:String) {

  if (success) {

    gotoAndStop("Login");

  } else {

    msg_txt.text = error;

  }

};

In a moment, we'll create the script that connects our application to ElectroServer 3. When the connection happens, an onConnection event occurs, which is what this script handles. Two parameters are passed to the function when the onConnection event is fired: success and error.

The first parameter, success, is a Boolean value. If true, the connection was a success and the user is taken to the Login frame label to log in. If false, the connection failed. If the connection failed, the second parameter, error, is passed to the function. This parameter contains a string that explains what went wrong. When a failed connection occurs, the else part of the statement is executed. This part of the statement displays the error message in the text field named msg_txt. This text field exists at the Connecting frame label on the timeline. To understand how this works, it's important to realize that one of the last scripts we will place on this frame (in Step 9) will move the timeline of our application to the Connecting frame label, where it will wait for a response from the server. If an error occurs, the part of our script that reads:

msg_txt.text = error

will display the error message in the msg_txt text field on the Connecting frame label because our application is paused at that label.

What can cause the connection to fail and what kind of error messages are generated? If the connection failed because the ElectroServer class could not find ElectroServer 3 (possibly due to a wrongly specified IP or port, firewall issues, or the fact that the server was not running), error will contain a string that reads, Could not establish a server connection. Otherwise, an error will be generated dynamically from the server. The server could deny a connection because it has reached its connection limit, which is 20 simultaneous users in the free license version.

Before proceeding further, take a look at the essential steps necessary for chatting using ElectroServer 3. The user must do the following successfully:

1. Connect to ElectroServer 3.

2. Log in to ElectroServer 3, which assigns you a username.

3. Join a room.

Add the following script to capture the login response:

es.loggedIn = function(success:Boolean, error:String) {

  if (success) {

    joinRoom();

  } else {

    msg_txt.text = error;

  }

};

On the frame labeled Login, which will be covered later in this exercise, the user is allowed to enter a username and a room name, and click a button to send a login request to the server. The server will then send back a response either allowing or denying the login request. The loggedIn event is triggered when the server responds to a login request.

Add the following function to handle joining a user to a room:

function joinRoom() {

  var roomOb:Object = new Object();

  roomOb.roomName = roomToJoin;

  es.createRoom(roomOb);

}

Before discussing this function, it's important to realize that on the frame labeled Login there are two TextInput component instancesusername_ti and room_ti. The user will use these text input boxes to enter a username and the name of the chat room that he or she wants to join. A script we will be adding to that frame will take the room name that the user enters and convert it to a variable named roomToJoin, which is used by the function in this step (third line down). Now let's look at how this function works.

As shown in Step 5, when the login response from the server is a success, the joinRoom() function is called and the room that was specified by the user in the login screen is created. Here's how.

There are two methods of the ElectroServer class that are appropriate to mention herecreateRoom() and joinRoom(). The joinRoom() method tells ElectroServer 3 that you want to join a specified room. Here's an example:

es.joinRoom("Sports");

If a room called Sports exists, you will join it. If it doesn't exist, an error will be returned by the server . This error is captured in the roomJoined event, which we'll script in the next step.

With the createRoom() method, you can create a room that doesn't yet exist. If you attempt to create a room that already exists, internally the ElectroServer class will capture the error and attempt to join you to that room instead.

Because the createRoom() function more easily facilitates joining a room, we use that in our function.

In the joinRoom() functionnot to be confused with the joinRoom() method of ElectroServer 3an object named roomOb is created and given a property named roomName. The value of roomName is the string that the user enters into the room_ti field on the Login frame. This object is then passed into the createRoom() method, which either creates the room (based on the properties of the passed-in object), if the user is the first person in that room, or joins the user to that room if it already exists.

To capture the ElectroServer 3 response to attempting to create/join a room, add the following code:

es.roomJoined = function(Results:Object) {

  if (Results.success) {

    gotoAndStop("Chat");

  } else {

    msg_txt.text = Results.error;

  }

};

In Step 6, you added the joinRoom() function, which requests that a room of a certain name be created. If that room doesn't exist, it's created, you're automatically joined to it, and the roomJoined event is fired. If the room already exists, internally the ElectroServer 3 class captures that error and attempts to join you to it, and the roomJoined event is fired. Here we've scripted what should occur when this event is fired.

Add the following line of script at the end of the current script:

_global.style.setStyle("themeColor", 0xE5EEF4);

For the final action on this frame, add this line of script:

gotoAndStop("Connecting");

On the frame labeled Connecting in the Actions layer, add the following two lines of script:

msg_txt.text = "Connecting..."

es.connect();

Move to the frame labeled Login. In the Actions layer, add the following variable declaration and button event handler:

var roomToJoin:String;

login_btn.onRelease = function() {

  var username:String = username_ti.text;

  roomToJoin = room_ti.text;

  if (username.length > 2 && username.length < 15) {

    es.login(username);

    gotoAndStop("Waiting");

  }

};

This frame includes two TextInput instances named username_ti and room_ti, and a button with an instance name of login_btn. When login_btn is clicked, the onRelease event handler shown here is called. It populates the variable roomToJoin with the contents the user entered into the room_ti instance (remember that the value of roomToJoin is used in the script added in Step 6). It also checks to make sure that the username entered is a reasonable size, over 2 characters but less than 15 characters. If the username has an acceptable length, the login() method of the ElectroServer class is called, passing in the username, and the application moves to the Waiting frame label.

Add the following line of script to the Waiting frame in the Actions layer:

msg_txt.text = "Waiting...";

Move to the Chat frame.

This is the frame from which all users who have successfully connected to ElectroServer 3, logged in, and joined a room will chat. Notice that the TextArea component on the screen has an instance name of chatBox_ta, which will be used to display the chat messages. To the right of this instance are two List components with instance names of roomListBox_lb and userListBox_lb. As you can probably guess, the roomListBox_lb instance will be used to show the list of rooms that exist on the server, and userListBox_lb will display the list of users in your current room.

Select the frame on the Chat label in the Actions layer and open the Actions panel. Enter this button's onRelease event handler:

send_btn.onRelease = function() {

  var msg:String = msgBox_ti.text;

  if (msg.length > 0) {

    es.sendMessage("public", msg);

    msgBox_ti.text = "";

  }

};

This script is executed when the Send button is clicked. A variable called msg is created to store the contents of the msgBox_ti instance. If the length of the message to send is greater than 0, the sendMessage() method of the ElectroServer class is executed. The first parameter of this method, "public", informs the ElectroServer class that the message is intended for everyone in the room. The second parameter contains the message to send. In addition to sending a message, the content of the msgBox_ti instance is erased so the user can type another message.

Add the following event handler to capture the chat messages coming in from ElectroServer 3:

es.messageReceived = function(type:String, message:String, from:String) {

  chatBox_ta.text += from + ": " + message + newline;

  chatBox_ta.vPosition = chatBox_ta.maxVPosition;

};

This script assigns an event handler to the messageReceived event, which is triggered whenever an incoming message is received from the server. When this event is fired, it is passed three parameter values. The first parameter, type, can be a value of either "public" or "private". In this exercise, all messages are public messages, so we don't need to worry about using that first parameter. However, in a full-featured chat front-end you would want to know whether an arriving message was public or private. If it's a private message, you might want Flash to play a sound or color code the text to give an indication to the person chatting that he or she just received a private message.

The second parameter, message, contains the chat message that has arrived. The final parameter, from, contains the username of the person who sent the message.

The first line of script inside the function adds a line of text to the chatBox_ta TextArea component. It starts with the name of the user who sent the message, adds a colon and the contents of the message, and finally adds a newline so the next message received will be on its own line.

To display the list of users in the room, the userListUpdated event must be captured and used. Add the following script at the end of the current script:

function showUsers() {

  var userlist:Array = es.getUserList();

  userListBox_lb.setDataProvider(userlist);

}

es.userListUpdated = showUsers;

showUsers();

First we create a function called showUsers(). This function grabs the most recent user list from the ElectroServer class using the getUserList() method and stores it as an array called userlist. As a result, the userlist array will contain one object for each user in the room. Each of these objects has a property named label that contains the username of the user that the object represents. If there are seven users in the room, the getUserList() method will return an array containing seven items; the array is stored in the array object named userlist.

The second line in the function takes the userlist array object and passes it into the setDataProvider() method of the userListBox_lb List component instance. The result is that the userListBox_lb is populated with a list of all of the usernames in the room.

On the first line of script below the function definition, we assign the showUsers() function to the userListUpdated event. This event is triggered by the server automatically whenever the list of users in the room changes. Thus, whenever someone enters or leaves the chat room, the showUsers() function is called and the user list shown in the userListBox_lb instance is updated.

To show the list of rooms, add the following code:

function showRooms() {

  var roomlist:Array = es.getRoomList();

  roomListBox_lb.setDataProvider(roomlist);

}

es.roomListUpdated = showRooms;

showRooms();

This script is almost identical to the script that captures and displays the user list. The showRooms() function grabs the room list (an array of objects, each representing one room) from the ElectroServer class and passes it into the setDataProvider() method of the roomListBox_lb List component instance.

The showRooms() function is then assigned as the event handler for the roomListUpdated event. Every time something about a room list changes, such as the number of people in a room or the addition/removal of a room, this event is fired.

To allow a person to click the name of a room to join that room, add the following script:

var roomClickListenerObject:Object = new Object();

roomClickListenerObject.change = function(eventObject:Object) {

  var room:String = eventObject.target.value;

  es.joinRoom(room);

};

roomListBox_lb.addEventListener("change", roomClickListenerObject);

When a user arrives at the Chat frame, he or she will see the list of rooms in the roomListBox_lb instance. As the list of rooms changes, the box will update. The script that you just added gives the user the ability to click any room in the list and be joined to that room automatically.

We first create an object and then create a function called change on the object. Finally, we assign this object as an event listener to the roomListBox_lb component instance. The change event is fired whenever a user changes the selected room in the roomListBox_lb instance. Usually, this is accomplished by the user's clicking a room in the list, although it can also be accomplished using the keyboard.

When the change event is fired, an Event object is passed into the event handler. We extract the name of the item that was selected and give it a variable name of room. The value of that variable is then passed into the joinRoom() method to join the user to that room.

Start ElectroServer 3.

The default IP and port for ElectroServer 3 are 127.0.0.1 and 9875. When you start ElectroServer 3, it will attempt to bind itself to your local IP and listen on the default port.

Choose File > Export > Movie to export this project to an SWF file in this lesson's directory on your hard drive. Navigate to that directory and double-click the exported SWF. Log in and send some chat messages.

You should see your chat messages appear in the chatBox_ta TextArea component. Try opening more than one copy of this SWF and log in with different usernames. You should be able to see all the users in the userListBox_lb List component.

Close the test movie and save your work as Chat2.fla.

You've accomplished a lot in this exercise. You've created a basic chat application using the ElectroServer class, a little bit of ActionScript, and some components.

If you're interested in creating a more advanced chat room, look through the ElectroServer class documentation on the CD-ROM or download some source files from http://www.electrotank.com/ElectroServer/.

• Enable password-protected rooms

• Allow private messaging

• Let a user create a new room from the Chat frame label

• Build in support for emoticons