Recipe 14.2 Connecting to the FlashCom Server

14.2.1 Problem

You want to connect to a FlashCom server application.

14.2.2 Solution

Create a NetConnection object and invoke the connect( ) method from it. To detect the connection status, add an onStatus( ) method to the NetConnection object.

14.2.3 Discussion

The NetConnection class enables you to connect your Flash movies to a FlashCom server application. You first need to create a NetConnection object and then invoke the connect( ) method from that instance. The connect( ) method requires the Universal Resource Identifier (URI) to the FlashCom server application to which you wish to connect.

// Create the NetConnection object.
myConnection = new NetConnection(  );

// Call the connect(  ) method to connect to an application named myApplication, where
// the FlashCom server is on the same machine as the .swf file.
myConnection.connect("rtmp:/myApplication/");

The URI must always be in one of two formats (the items in brackets are optional):

rtmp://host[:port]/applicationName[/instanceName]

or:

rtmp:[:port]/applicationName[/instanceName]

You should use the first URI format when the FlashCom server and the .swf file are not on the same machine (as is the case in most production environments). The second URI format is acceptable when the FlashCom server and the .swf file are on the same machine (which is typically the case in a development environment). In either case, you need to supply the port number only if the FlashCom server is running on a port other than the default FlashCom port (1935). The applicationName portion of a URI must match the name of a subdirectory in the FlashCom applications directory (see Recipe 14.1). Finally, the optional instanceName allows you to create unique instances of an application. Each instance shares the common functionality of the application but manages clients and other values separately. The common example is that of a chat room application in which all rooms share the same basic functionality of the main application, but each room (instance) has its own list of users (clients). If you don't specify an instance name, then your Flash movie will connect to the default instance, _definst_.

Here's an example of a URI for an application named myVideoChatApp that resides on www.myflashcomsever.com. The server is running FlashCom on the default port, so there is no need to specify the port. Notice that when you specify a URI that includes the host portion, you must follow rtmp: with two forward slashes (//).

rtmp://www.myflashcomserver.com/myVideoChatApp

If www.myflashcomserver.com is running FlashCom on a port other than 1935, such as port 1940, then you would need to use the following URI:

rtmp://www.myflashcomserver.com:1940/myVideoChatApp

Next, here is an example of a URI that connects to myGroupPaintApp, which resides on the same host as the .swf file. Because they are on the same host, there is no need to specify the host as part of the URI. Notice that when you don't specify the host, the rtmp: is followed by only one forward slash (/).

rtmp:/myGroupPaintApp

If the localhost is running FlashCom on a nondefault port, you should specify the port in the URI, as shown here (note the two colons):

rtmp::1940/myGroupPaintApp

You can monitor the connection status by adding an onStatus( ) method to the net connection instance. The onStatus( ) method is automatically invoked every time there is a change in connection status. Each time the onStatus( ) method is invoked, it is automatically passed an info object whose code property indicates the change in status. For example, when the connection is successfully made, the onStatus( ) method is invoked and passed an info object with a code property of "NetConnection.Connect.Success". Any other value indicates that the connection has either been lost or rejected.

Here is an example onStatus( ) handler that detects the code property of the info object:

myConnection.onStatus = function (infoObj) {
  if (infoObj.code == "NetConnection.Connect.Success") {
    trace("connection made successfully");
  }
};

The onStatus( ) method is invoked both when there is a connection attempt and when the connection is closed. You can use the onStatus( ) method to:

• Perform proper initialization when a connection is made

• Perform necessary actions when a connection is closed (i.e., try to reestablish a connection or tell the user that the application has closed)

• Perform error handling when a connection fails or is closed unexpectedly

Here is an example onStatus( ) handler that deals with various status conditions:

myConnection.onStatus = function (infoObj) {
  switch (infoObj.code) {
    case "NetConnection.Connect.Success":
      // Perhaps initialize necessary elements in the movie, such as video objects.
      break;
    case "NetConnection.Connect.Failed":
      // The connection failed because the server is unreachable. Perhaps try again
      // or simply tell the user that the server cannot be reached.
      break;
    case "NetConnection.Connect.Rejected":
      // The connection was rejected because of invalid credentials or parameters.
      // Perhaps prompt the user for valid information.
      break;
    case "NetConnection.Connect.InvalidApp":
      // The connection failed because no application by the specified name exists.
      break;
    case "NetConnection.Connect.Closed":
      // The connection was closed successfully by a command issued from the client.
      // Use the opportunity to remove any elements, such as video objects; go to
      // another screen; or otherwise inform the user of the closure.
      break;
    case "NetConnection.Connect.AppShutDown":
      // The application was shut down by an administrator or because the server is
      // being shut down or restarted.

  }
} ;