Connection & Login Tutorial
From EsWiki
This is a concise tutorial that covers the most basic steps needed to use ElectroServer: connecting and logging in.
Contents |
What You'll Learn
- The most common classes and packages needed to import
- How to create and use the ElectroServer class
- How to create a request and handle events
Prerequisites
- You must have ElectroServer 4 installed and running.
- You need the client-side ElectroServer 4 API.
- Client-side Development Environment
Let's Get Started!
In the steps below you'll learn how to connect to ElectroServer, capture the connection event, attempt a login, and capture the login response. When you send a message to the server this is called a Request. If the server responds to that Request it is called a Response. If the server sends you any other messages, they are Events. In this tutorial we'll work with all three of these message types.
Create a new FLA
Create a new FLA file (AS2 or AS3) and save it. Make sure the ES4 API is in the classpath. We recommend that you add the AS2 and AS3 APIs to the global classpath so that you don't have add it for every application. The API should be added at the src folder, so that the packages can be found easily starting with com.
Note: The code shown in this tutorial is identical for AS2 and AS3 except for the keyword void. However, there is an AS2 version of the ES4 API and an AS3 version. Make sure you're using the appropriate API!
Import the needed classes
Select frame 1 and open the Actions panel. Enter these import statements:
//Import the needed classes import com.electrotank.electroserver4.ElectroServer; import com.electrotank.electroserver4.entities.Protocol; import com.electrotank.electroserver4.message.MessageType; import com.electrotank.electroserver4.message.request.*; import com.electrotank.electroserver4.message.event.*; import com.electrotank.electroserver4.message.response.*; import com.electrotank.electroserver4.errors.*;
Line 2 imports the ElectroServer class. That's the class that you'll directly interact with most of the time. The next line imports the MessageType class. You use that class to point to ES event constants. The next three lines import all of the Request, Response, and Event message types. Finally, the EsError class is imported for error handling.
Note: This may seem like a lot of imports to remember. Just copy and paste these every time you use ElectroServer! You'll need them for anything you do.
Create the ElectroServer instance
Now create a new instance of the ElectroServer class called es. Turn on debugging. All debugging does is trace inbound and outbound messages. Enter this code:
//Create the ElectroServer instance var es:ElectroServer = new ElectroServer(); es.setDebug(true);
Set the Protocol (optional)
If you are using text protocol, this step may be skipped, since TEXT is the default protocol. Binary protocol is only available with AS3, and HTTP protocol gets a bit complicated. You must use the port and protocol that matches your ES4's gateway listener. To specify that you are using Binary protocol, just add this line:
es.setProtocol(Protocol.BINARY);
ConnectionEvent
When you invoke the createConnection method a ConnectionEvent event will be fired. This can be fired due to a response from ElectroServer, or because ElectroServer was not found. Enter the following code to register to listen for the ConnectionEvent, and to handle this event. Note that we'll modify this event handler two steps down for login.
//Listen for and handle the ConnectionEvent
es.addEventListener(MessageType.ConnectionEvent, "onConnectionEvent", this);
public function onConnectionEvent(ev:ConnectionEvent):Void {
if (ev.success) {
trace("Connected!");
} else {
trace("Error: Failed to connect.");
}
}
Create a connection with ElectroServer
Establish a connection with ElectroServer. Use the createConnection method to pass in the ip and port on which ES4 is running. We haven't added event handling yet, so you can't tell if it worked. If you took the defaults when you installed ES4, and are programming on the same computer as the ES4 server, the following ip and port will work for text protocol.
//Create a connection with ElectroServer
es.createConnection("127.0.0.1", 9899);
Test
Now test what you've done by publishing the FLA in the Flash IDE. You should see a trace output of "Connected!". If you don't see that then make sure ElectroServer is up and running properly and you entered the correct ip and port. You may also need to edit your Flash Global Security Settings to include the locations where you run SWFs from your hard drive (or just use C:/).
LoginRequest
Now we're going to handle creating and sending a LoginRequest to ElectroServer, and in the following step we'll capture the LoginResponse. Notice the onConnectionEvent function below. We have modified it by adding 3 lines of code underneath the trace("Connected!"); statement. This code creates a new LoginRequest, populates it with a username, and then tells the ElectroServer class to send it.
public function onConnectionEvent(ev:ConnectionEvent):Void {
if (ev.success) {
trace("Connected!");
var loginRequest:LoginRequest = new LoginRequest();
loginRequest.setUserName("testName");
es.send(loginRequest);
} else {
trace("Error: Failed to connect.");
}
}
LoginResponse
In the previous step you created and sent a LoginRequest to ElectroServer. ElectroServer will respond in the form of LoginResponse. Enter the following code to listen for that event and to handle it.
//Listen for and handle the LoginResponse
es.addEventListener(MessageType.LoginResponse, "onLoginResponse", this);
public function onLoginResponse(ev:LoginResponse):Void {
if (ev.success) {
trace("Logged in!");
} else {
trace("Error: Failed to login. Error message: "+ev.getEsError().getDescription());
}
}
Note: Login can fail for any number of reasons. If it fails the reason should be traced out in the code above. To test this, try logging two clients in with the same username. Or, try logging in with a profane name, such as the 'f' word.
Note: You can do more with LoginRequest such as pass in a password or create user variables. See the documentation for more information.
Finished!
See it's not that hard! You've just connected to ElectroServer and logged in. Next you'll want to try creating a room and chatting.
