Section 3.2. Managing a Connection

3.2. Managing a Connection

After a successful connection is made, it can be broken by various occurrences. A well-scripted Flash movie monitors the network status and takes appropriate action as changes occur. This is easily done inside your NetConnection.onStatus( ) handler, which is notified whenever the connection status changes. When a connection is first established, the objects and components that rely on it can begin using it. When a connection is closed, these objects may have to be disabled or disposed of. It is especially important that the user doesn't experience a sudden and unexplained loss of functionality when a network connection is dropped by the server or lost because of a network problem.

Avoiding Timing Problems

A commonand sometimes difficult to debugproblem occurs when scripts define the onStatus( ) handler after calling the connect( ) method:

 nc = new NetConnection(  ); nc.connect(  ); // WRONG: do this after   onStatus   is defined! nc.onStatus = function (info) {   trace("info.code: " + info.code); }; 

If connect( ) is called prematurely, the network connection may be established or the connection rejected before the onStatus( ) handler has been defined. The result is that the messages representing those events are never returned to the handler. The onStatus( ) method must always be defined before the connect( ) call is made. The preceding example should be rewritten as:

 nc = new NetConnection(  ); nc.onStatus = function (info) {   trace("info.code: " + info.code); }; nc.connect( ); 

For the most part, when a connection is closed, the info object passed to the onStatus( ) method will have a level value of "status" and a code value of "NetConnection.Connect.Closed". This will happen if the network goes down, the server disconnects the client, the server stops, or the connection is closed using NetConnection.close( ) . It is also possible that the level value will be "error" and the code value "NetConnection.Connect.AppShutdown". The following sections discuss how to deal with various connection status changes.

3.2.1. Dealing with Success

When Flash establishes a connection, any streams and shared objects that rely on the connection can be set up. Testing for the "NetConnection.Connect.Success" code in the onStatus( ) handler is the easiest way to do this:

 if (info.code = "NetConnection.Connect.Success") {   // Initialize and connect dependent objects and components (not shown). } 

3.2.2. Dealing with Problems

When a connection cannot be established or is lost, a number of possible message sequences can be sent to an onStatus( ) handler:

• A single error code

• An error code followed by a closed status

• A single closed status

The isConnected property of the NetConnection object is false when any of these events occurs. Whenever a problem occurs, you may want your script to take action, such as informing the user. The simplest way to deal with problems is to look at the isConnected property in the onStatus( ) handler:

 if (!this.isConnected) {   if (info.code = "NetConnection.Connect.Rejected") {     // Tell the user the connection was rejected by the application.   }   else {     // Give the user more info based on   info.code   and/or   info.level   .   }   // Clean up any objects and components that need them.   // Change state by going to another frame on the main timeline. } 

Displaying a message whenever isConnected is false may lead to the user seeing two messagesa reject message followed by a closed message. To avoid displaying two messages, the onStatus( ) handler must be stopped from acting on the second message. One way to do this is to remove the onStatus( ) handler completely by setting the onStatus property to null after the first message arrives. This can be done inside the onStatus( ) method:

 this.onStatus = null; 

Removing the onStatus( ) handler so that no further message processing can take place may seem like a drastic solution. However, the onStatus property can be reset later to a method that can handle messages. Alternatively, another NetConnection object, with a working onStatus( ) handler, can be created and used to connect again. Another approach is to create an extra property of the NetConnection object that toggles the handling of certain messages. When messages are expected after a connect( ) call is made or after a "success" status message, the property is set to true . When a connection has been closed, the property can be set to false . Example 3-2 shows one way to do this.

3.2.3. Closing the Connection from the Client

Another potential problem is that when you let the user close the connection via NetConnection.close( ) , the onStatus( ) handler still receives a "closed" status message. There is often little point in showing this message to the user since she was responsible for closing the connection in the first place. It may be simpler to just change the state of the application by, for example, moving the playhead of the main timeline. Again, a property can be stored in a NetConnection object or the onStatus( ) method can be set to null , to avoid displaying a close message.

Example 3-2 uses a property named handleCloseEvents to indicate if error and close messages should be processed . This is just one way to write an onStatus( ) handler using this type of flag, and it can be altered as requirements dictate . An example that assigns values dynamically to the onStatus property is included in the online version of Example 3-2 (at http://flash-communications.net). Figure 3-1 shows the timeline for the movie used in Example 3-2. The movie can be in one of three states, each represented by a label at the beginning of a series of frames . Init starts on the first frame and is played only when the movie first loads; the Login frame is shown when the movie is in a disconnected state and the user can try to connect; the Connected frame is shown when the movie is in the connected state.

Figure 3-1. The timeline from Example 3-2

The script in Example 3-2, located on frame 1 of the Scripts layer of the main timeline, displays user messages in a text field. The ActionScript sends the playhead to either the Login or Connected frame depending on the state of the network connection.

Example 3-2. A script that handles connection- related events

 //   writeln(  )   writes messages into a text field named   trace_txt   // and is a runtime alternative to   trace( )   and the Output panel. function writeln (msg) {   trace_txt.text += msg + "\n";   trace_txt.scroll = trace_txt.maxscroll; } /* A simple   onStatus( )   handler that moves the playhead to   Login   if a  * connection is closed and to   Connected   when a connection is established.  * User messages are written via   writeln( )   into a text window.  * The   this.handleCloseEvents   flag is used to make sure the user never  * sees redundant messages.  */ NetConnection.prototype.onStatus = function (info) {   // Always deal with successful connections.   if (info.code == "NetConnection.Connect.Success") {     this.handleCloseEvents = true;     writeln("Success, you are connected!");     gotoAndPlay("Connected");   }   // Handle messages when the connection is closed.   if (!this.isConnected && this.handleCloseEvents) {     if (info.code == "NetConnection.Connect.Rejected") {       writeln(info.application.message);       writeln('Did you use the username "Guest" and password "Guest"?');     }     else {       writeln("Error: Connection Closed.");     }     this.handleCloseEvents = false;     gotoAndPlay("Login");   }   // Handle remote method call errors here if you need to. }; // Create a   NetConnection   object. lobby_nc = new NetConnection( ); // Called when the   Connect   button in the   Login   frames is clicked. function doConnect ( ) {   lobby_nc.handleCloseEvents = true;   if (lobby_nc.connect("rtmp:/testLobby/",                        userName_txt.text, password_txt.text)) {     writeln("Please wait. Attempting connection...");   }   else {     writeln("Can't attempt connection. Is the URI correct?");   } } // Called when the   Disconnect   button in the   Connected   frames is clicked. function doDisconnect ( ) {   // User is requesting a close so we don't handle it in   onStatus( )   .   lobby_nc.handleCloseEvents = false;   lobby_nc.close( );   gotoAndPlay("Login"); } gotoAndPlay("Login"); 

The script listed in Example 3-2 needs an application to which to connect. Therefore, we need a testLobby subdirectory in the applications directory on the server from which the movie is downloaded. Once the directory is created, the main.asc file shown in Example 3-3 can be placed in the testLobby subdirectory to provide the application with its logic. This server-side script accepts connections only from users who log in using the username "Guest" and the password "Guest". Rejected clients are passed a message to display to the user.

Example 3-3. Server-side script (main.asc) to accept or reject connections based on username and password

 /* The   application.onConnect(  )   method handles each client  * connection request. In this case, users who log in  * with   userName   "Guest" and   password   "Guest" are  * allowed to connect. Other connection requests are rejected.  */ application.onConnect = function (client, userName, password) {   if (userName == "Guest" && password == "Guest") {     client.writeAccess = "";   // Don't give write access.     application.acceptConnection(client);   }   else {     application.rejectConnection(client,       {message: "This application has refused your connection."});   } }; 

Whenever a Flash movie connects to an application instance, the onConnect( ) method of the instance's application object is called. The first parameter passed to onConnect( ) is always a Client object that represents the client-side Flash movie. The remaining parameters are the parameters passed into the connect( ) method in the movie.

Therefore, when a client attempts to connect to the testLobby FlashCom application, the main.asc file shown in Example 3-3 checks the username and password passed in. A full-fledged version could validate the username and password against a database of valid users.

3.2.4. Using a Connection

A NetConnection object represents a network connection within a Flash movie. Any object that communicates over a network connection must have access to a NetConnection object. For example, the NetStream class requires a NetConnection object be passed into its constructor function:

 myStream_ns = new NetStream(myNetConnection); 

Working with the NetStream class is covered in Chapter 5.

Similarly, a remote shared object's connect( ) method must be passed a NetConnection object:

 myRemote_so = SharedObject.getRemote("SOName", myNetConnection.uri, true); myRemote_so.onStatus = onStatusFunction; if (myRemote_so.connect(myNetConnection)) {   trace("Connection ok so far..."); } 

Macromedia designed both the NetStream and SharedObject classes so that, with some exceptions, they could be used as soon as a NetConnection object was passed to them. In both cases, the NetConnection object should be one that has attempted to make a connection even if the connection is not yet established. For example the process of sending data can be started via a NetStream.send( ) or SharedObject.send( ) method call before a connection is established. The data is held in a queue until the connection is made. Similarly, a NetStream object can start the process of publishing or playing audio or video before a connection is made. In this case, when the connection is made, the stream will begin to publish or play.

The important exception to this is shared object data and the shared object onSync( ) handler described in Chapter 8. As an added convenience, if onStatus( ) handlers are not created for SharedObject and NetStream objects, the onStatus( ) handler of the NetConnection with which they are associated will be called and passed the SharedObject and NetStream information objects. In some cases, especially when data is sent, these conveniences are useful, but for the most part should be avoided. It is often easier to manage an application and provide better information to the user if objects that depend on a network connection define their own onStatus( ) event handlers and do nothing until a connection is successfully made.