NetConnection

[ LiB ]

The first step in any Flash communication app is to connect to the server through the NetConnection object. Once connected, you can do all kinds of wild things (such as publish or play media streams plus send and receive messages to other connected users to name the two biggies). It always begins with a connection, however, and everything that follows is tied to that connection. Luckily it's pretty easy to confirm your connection gets established properly before preceding .

Basic Connecting

You can connect to an FCS app with just two lines of code; however, it's really best to set up a callback because it's an asynchronous operation. That is, you need to wait for the connection to complete before proceeding (and, confirm it was successful). Listing 8.1 is a nice starter skeleton on which to build.

Listing 8.1. Basic Connect Skeleton

 1 my_nc = new NetConnection(); 2 my_nc.onStatus = function(info) { 3 trace(info.code); 4 if (info.code == "NetConnection.Connect.Success") { 5 //proceed 6 } 7 if ( info .code == "NetConnection.Connect.Closed") { 8 //say goodbye 9 } 10 }; 11 my_nc.connect("rtmp:/my_app/my_instance1"); 

After you create a NetConnection object (line 1), you can connect (as in line 11). The string passed in the connect() method looks for an app called my_app (so it's imperative you create a folder in the applications folder called my_app). It looks as though my_instance1 is a subfolder, but it's actually an optional instance name. That is, you can have multiple copies of the my_app app running independently. If you forgo the instance name, _definst_ will be used (for default instance). In fact, you can use just lines 1 and 11, and it should work. The onStatus event, however, is useful to ensure your connection was successful (in which case the parameter that I'm calling info will have a property called code containing the specific string "NetConnection.Connect.Successful" ). Naturally, you would want to replace lines 5 and 8 with your choice of code to react to a successful or failed connection, respectively. Realize that the onStatus event might trigger much laterfor instance, if the server goes down. It also triggers when you purposely disconnect (by calling the NetConnection close() method). For this situation, you'll probably want to first set the onStatus event equal to null before you close() so that it doesn't run code you wrote to handle unintentional disconnects.

Although the preceding skeleton is suitable for many apps, there are more details worth discussing.

NetConnection Object Details

You just saw how the connect() method can optionally specify an instance name. There are actually more options, although they're not optional parameters; everything is tied to the first parameter (a string called a URIfor Universal Resource Identifier). You can vary the URI to connect absolutely to an FCS hosted elsewhere, to specify different ports, and to control how RTMP data can tunnel through HTTP connections. The following sections cover these three variations.

Absolute Connections

Listing 8.1 assumes a relative path to FCSalmost as if localhost was passed as the address. When your SWF is not running on the same host as the FCS, you need to make an absolute reference. To make an absolute connection to FCS, you just add the domain or IP address in front of the application name. For example, the following code hard-wires the my_domain.com domain:

 my_nc.connect("rtmp://my_domain.com/my_app/my_instance"); 

The part that messes me up all the time is that you must precede a domain with double slashes ( // ), whereas your app follows a single slash ( / ). So, when you leave off the domain, you have just a single slash.

Ports and HTTP Tunneling

When the Flash Player encounters the connect() method, it attempts to connect to your FCS following a very specific pattern. It first attempts to connect over port 1935, then port 443, then port 80, and then it automatically attempts to tunnel through by sending RTMP data over HTTP (also called RTMPT). It turns out the automatic sequence of attempts is fine for many situations. However, you may find some users can't make a connection (well, the NetConnection can't) because their firewall blocks data from traveling through port 1935. If those users can visit any web sites, they can surely use the standard port 80. And even if their setup blocks RTMP data (another issue with some firewalls), they'll still be able to use RTMPT because that's really just plain HTTP. You might think the final attempt by the Flash Player (RTMPT on port 80) is the perfect failsafe. However, the problem is that if you are running your web server on the same machine that's running FCS, they can't both use port 80. A perfectly legitimate solution is to just use two computers: one for your web server (on port 80), and one for FCS (on port 1935, but with ports 443 and 80 open for when they're needed). Naturally, two computers probably means you'll need to specify the domain absolutely as you just saw.

Going out and buying two computers is not the only solution. In addition, relying on the Flash Player's sequence of port attempts is not ideal because connections take slightly longer as each attempt must time out before proceeding. Also, RTMPT only works with newer Flash Players (6,0,65 or later). In any event, you can override the default behavior with a little bit of scripting.

To force the Flash Player to try to connect through a specific port (that is, not follow it's normal sequence of 1935, 443, 80, and then 80 using HTTP), you need to take two steps. First, include a colon and then the port number in the connect() method. This is placed immediately before the application name. (That's after the host if you include it.) For instance, this example makes the SWF try just port 8080:

 my_nc.connect("rtmp::8500/my_app/my_instance"); 

Notice that if you include the host domain, it appears between the two colons, as follows:

 my_nc.connect("rtmp://my_domain.com:8500/my_app/my_instance"); 

Because the connect() method is inside your SWF, it just directs the Flash Player how to make a connection. Just saying "just try port 8500" isn't enough, howeveryour FCS has to be set up to listen to connect attempts coming in through that port. It's just a matter of adding any additional ports to the <HostPort> tag of your Adaptor.xml file. In summary, specifying ports requires you to edit both the connect() script and the Adaptor.xml. Also, forcing the SWF to connect through a particular port will tend to make connections complete more quickly because you don't have to wait for the player to keep trying ports.

Finally, the new HTTP tunneling feature is very cool because it means your RTMP data can travel over the innocuous HTTP protocol. As previously mentioned, RTMPT (that's RTMP over HTTP) is attempted on port 80 after all other attempts failprovided you let the Flash Player follow its default (automatic) behavior. To override this and force RTMPT, you need to replace rtmp with rtmpt in your connect() method. For example, the following code uses RTMP over port 8080:

 my_nc.connect("rtmpt::8080/my_app/my_instance"); 

Of course, you need to configure FCS to listen to port 8080.

Tip

RTMPT Is Explicit

Just remember that when you do specify RTMPT or port numbers , you're overriding the way the Flash Player naturally attempts different ports and protocols.

Before moving on to what you can do after you're connected, let me mention two other connection- related features we'll explore in the "Messaging" section of Chapter 9, "Advanced Communication Server." That is, you can pass additional parameters (after the URI), and those values are received on the server where they can be sorted out. For example, you can let people pass their username so that the server can track who all is connected. In addition, the server can accept or reject connections. Right now, provided you have that application folder, everyone is automatically accepted. If you've reached the capacity of users (say, 50 for FCS Personal), however, additional connects are rejected out of hand. Another thing you'll learn in the next chapter is how to send meaningful information back to the client when they get rejected (so that the SWF can take appropriate action). At this point, however, you have all you need to move on more exciting FCS features.

[ LiB ]