SFS2X Docs / ExamplesFlash / connector

» Connector

» Overview

The Connector example is the most simple application you can create: it just shows how to load the external client configuration and connect to SmartFoxServer 2X.

The SmartFoxServer 2X client API allows the connection details to be stored in an external xml configuration file which can be loaded right after the main API class (SmartFox) is instantiated. An external configuration file is used to avoid client recompilation in case, for example, the IP address of the server is changed (this is a common scenario when moving an application from the development/testing environment to the production environment) or when you need to turn on/off debug messages easily.
The main connection parameters contained in the xml file and used by this example are the server's IP address to connect to and the TCP port used for communication. For a detailed list of available parameters, please refer to the AS3 API documentation.

After the external configuration is loaded, the connection can be established automatically by the API, or manually by calling the proper method (see the Code highlights paragraph below). An event is then fired to notify if the connection has been established or not.

This simple example features a single button which causes, when pushed, the external configuration to be loaded and the connection to the SmartFoxServer 2X instance to be established. A text area displays some notifications when events are received, making it clear what is going on.

>> DOWNLOAD the source files <<

» Installation

» Running the example

In order to run the application follow these steps:

1. make sure your SmartFoxServer 2X installation contains the BasicExamples Zone definition;
2. start SmartFoxServer 2X;
3. make sure the client will connect to the right IP address by editing the <ip> entry in the xml file available under the /deploy folder;
4. open the /deploy/Connector.html file in a browser.

» Source code setup

The example assets are contained in the /source folder and they don't require a specific setup: simply open the .fla file in Adobe Flash.

» Code highlights

The example's FLA file references the separate Connector document class (Connector.as file) which contains all the required methods and properties.
In the constructor we create the main SmartFoxServer client API class instance, which takes care of the whole communication between the client and the server. As this class is also responsible of dispatching the events coming from the server, we also have to setup the appropriate event listeners (in this case just a few, being the example very basic).

	public function Connector()
	{
		// Create an instance of the SmartFox class
		sfs = new SmartFox()
	
		// Turn on the debug feature
		sfs.debug = true
		
		// Add SFS2X event listeners
		sfs.addEventListener(SFSEvent.CONNECTION, onConnection)
		sfs.addEventListener(SFSEvent.CONNECTION_LOST, onConnectionLost)
		sfs.addEventListener(SFSEvent.CONFIG_LOAD_SUCCESS, onConfigLoadSuccess)
		sfs.addEventListener(SFSEvent.CONFIG_LOAD_FAILURE, onConfigLoadFailure)
		
		// Connect button listener
		bt_connect.addEventListener(MouseEvent.CLICK, onBtConnectClick)
	
		dTrace("SmartFox API: "+ sfs.version)
		dTrace("Click the CONNECT button to start...")
	}

In the code above we also enable the API debug feature, which traces in the Flash console all messages exchanged between the client and the server. That line is not really necessary, as the debug flag can be set more appropriately in the external configuration file (which also overrides this manual setting).
The dTrace method is used to output messages to the example's text area.

When the CONNECT button in the interface is clicked, the onBtConnectClick listener is called which in turn calls the SmartFox.loadConfig method. If no argument is passed, this method looks for the default external configuration file called sfs-config.xml and, if loaded successfully, it also attempts the connection to the server automatically. This behavior can be changed using the method's second parameter.
Depending on the configuration loading result the onConfigLoadSuccess listener or the onConfigLoadFailure listener is called. Both methods simply output a string to display the connection attempt result; the first method also logs the main connection settings loaded from the external configuration file.

	private function onConfigLoadSuccess(evt:SFSEvent):void
	{
		dTrace("Config load success!")
		dTrace("Server settings: "  + sfs.config.host + ":" + sfs.config.port)
	}
	
	private function onConfigLoadFailure(evt:SFSEvent):void
	{
		dTrace("Config load failure!!!")
	}

Due to the arguments' default values of the SmartFox.loadConfig method, right after dispatching the configLoadSuccess event, the API tries to connect to the SmartFoxServer instance using the loaded connection details. The onConnection listener is then called, reporting the connection success or failure. A successful connection is the starting point of any multiuser application or game; the following step is usually collecting the user credentials and executing the login process. In this basic example we just trace the result.

	private function onConnection(evt:SFSEvent):void
	{
		if (evt.params.success)
		{
			dTrace("Connection Success!")
		}
		else
		{
			dTrace("Connection Failure: " + evt.params.errorMessage)
		}
	}

One last event listener, onConnectionLost, is added to detect the automatic disconnection due to the client being idle for a number of seconds exceeding the related server setting. This should be the main disconnection reason, due to the fact that this application does nothing else after the connection. Of course in a real world scenario the disconnection could happen due to other causes too, so the actual reason is reported in the event parameters.

	private function onConnectionLost(evt:SFSEvent):void
	{
		dTrace("Connection was lost. Reason: " + evt.params.reason)
	}

You can now proceed to more advanced examples showing real applications and games.

» More resources

You can learn more about the SmartFoxServer basics by consulting the following resources:

• Development basics (introduction to the Zone concept and basic client-server communication steps)
• ConfigData class (external configuration parameters description)
• The connection phase (server connection basics)

(c) 2004-2024 gotoAndPlay() — All rights reserved — www.smartfoxserver.com