NetConnection.connect

Client-Side Communication ActionScript > NetConnection.connect

Availability

Flash Player 6.

Flash Communication Server MX.

Usage

myConnection.connect(targetURI, [, p1 ... pN])

Parameters

targetURI The Uniform Resource Identifier (URI) of the application on the Flash Communication Server that runs when the connection is made. For targetURI, use the following general format (items in brackets are optional):

protocol:[//host][:port]/appname/[instanceName]

For protocol, specify either rtmp or rtmpt. If rtmp is specified, Flash Player will create a persistent socket connection with Flash Communication Server. If rtmpt is specified, Flash Player will create an HTTP "tunneling" connection to the server. For more information on RTMP and RTMPT, see the description section below.

You can omit the host parameter if the Flash movie is served from the same host where Flash Communication Server is installed.

If the instanceName parameter is omitted, Flash Player connects to the application's default instance (_definst_).

By default, RTMP connections use port 1935, and RTMPT connections use port 80.

For example, the following URIs are formatted correctly:

	rtmp://www.myCompany.com/myMainDirectory/groupChatApp/HelpDesk
	rtmpt:/sharedWhiteboardApp/June2002
	rtmp::1234/chatApp/room_name

p1 ... pN Optional parameters of any type to be passed to the application specified in targetURI. If the application is unable to process the parameters in the order in which they are received, NetConnection.onStatus is invoked with the code property set to NetConnection.Connect.Rejected.

Returns

A Boolean value of true if you passed in a valid URI, false otherwise. (To determine if the connection was successfully completed, use NetConnection.onStatus.)

Description

Method; connects to an application on the Flash Communication Server. This method can also be used to communicate with an application server. For information, see Using Flash Remoting.

In general, use the RTMP protocol, which opens a persistent connection between Flash Player and Flash Communication Server. If, however, clients are connecting from behind a firewall or through HTTP proxy servers that prohibit direct RTMP socket connections, use the RTMPT protocol, which transmits RTMP data over an HTTP connection. The RTMPT protocol explicitly requests an HTTP connection and enables a faster connection time for clients who can't connect through RTMP.

If Flash Player fails to connect to the server over an RTMP connection on the default port, it will automatically try to establish a connection using a predetermined sequence of ports and protocols. For example, if an application tries and fails to connect using nc.connect("rtmp:/myserver/myapp"), Flash Player will automatically try the following sequence of connections, until successful:

nc.connect("rtmp://myserver:443/myapp");
nc.connect("rtmp://myserver:80/myapp");
nc.connect("rtmpt://myserver:80/myapp");

This connection sequence can enable connections to succeed that otherwise would not. However, during this connection sequence users may wait several seconds for multiple connection attempts to time out.

Note: This automatic retry sequence will occur only if the initial connection specifies the RTMP protocol and uses the default port—for example, nc.connect("rtmp:/myserver/myapp").

If you want to use this connection for publishing or playing audio or video in real time, or to publish or play previously recorded audio or video streams, you must connect to the Flash Communication Server and then create a NetStream object within this NetConnection object. For more information, see the NetStream (object) entry.

If you want to use this connection for synchronizing data among multiple clients or between the client and a server, you must connect to the Flash Communication Server and then create a remote shared object within this NetConnection object. For more information, see the SharedObject (object) entry.

When you call this method, the NetConnection.onStatus event handler is invoked with an information object that specifies whether the connection succeeded or failed. For more information, see NetConnection.onStatus. If the connection is successful, NetConnection.isConnected is set to true.

Because of network and thread timing issues, it is better to place a NetConnection.onStatus handler in a script before a NetConnection.connect method. Otherwise, the connection might complete before the script executes the onStatus handler initialization. Also, all security checks are made within the connect method, and notifications will be lost if the onStatus handler is not yet set up.

If the specified connection is already open when you call this method, an implicit NetConnection.close method is invoked, and then the connection is reopened.

During the connection process, any server responses to subsequent NetConnection.call, NetStream.send, or SharedObject.send methods are queued until the server authenticates the connection and NetConnection.onStatus is invoked. The call or send methods are then processed in the order received. Any pending updates to remote shared objects are also queued until the connection is successful, at which point they are transmitted to the server.

Video and audio, however, are not queued during the connection process. Any video or audio that is streaming from the server is ignored until the connection is successfully completed. For example, confirm that the connection was successful before enabling a button that calls the NetStream.publish method.

If your connection fails, make sure you have met all the requirements for connecting successfully:

	You are specifying the correct protocol name for connecting to the server (`rtmp`, or `rtmpt`, for the Flash Communication Server).
	You are connecting to a valid application on the correct server.
	You have a subdirectory in the Flash Communication Server applications directory with the same name as the application specified in the connection URL.
	The server is running.

To distinguish among different instances of a single application, pass a value for instanceName as part of targetURI. For example, you may want to give different groups of people access to the same application without having them interact with each other. To do so, you can open multiple chat rooms at the same time, as shown below.

nc.connect("rtmp://www.myserver.com/chatApp/peopleWhoSew")
nc.connect("rtmp://www.myserver.com/chatApp/peopleWhoKnit")

In another case, you may have an application named lectureSeries that records and plays back classroom lectures. To save individual lectures, pass a different value for instanceName each time you record a lecture, as shown below.

// Record Monday's lecture
nc.connect("rtmp://www.myserver.com/lectureSeries/Monday");
...
ns.connect(nc);
ns.publish("lecture", "record");

// Record Tuesday's lecture
nc.connect("rtmp://www.myserver.com/lectureSeries/Tuesday");
...
ns.connect(nc);
ns.publish("lecture", "record");
// and so on

// Play back one of the lectures
nc.connect("rtmp://www.myserver.com/lectureSeries/Monday");
...
ns.connect(nc);
ns.play("lecture")

You can also nest instance names, as shown below.

nc.connect("rtmp://www.myserver.com/chatApp/peopleWhoSew/Monday")
nc.connect("rtmp://www.myserver.com/chatApp/peopleWhoSew/Tuesday")

For information on where recorded streams are stored on the server, see NetStream.publish.

Understanding file naming and domains used with this method If an HTML page containing a movie is accessed differently (with regards to domain names) from the way the movie itself accesses the Flash Communication Server, then the connection will not be successful. This is a security feature of the Flash Player. But in some cases, this may be inconvenient.

For example, if a web page containing a movie is served on an intranet from, say, http://deptserver.mycorp.com, it can also be accessed simply by http://deptserver. If the page is accessed via, say, http://deptServer/tcpage.htm, but the movie specifies deptServer.mycorp.com in targetURI, then the movie will not make a successful connection to the server. Similarly, if the web page and movie are accessed as http://deptserver.mycorp.com/tcpage.htm, but the movie specifies rtmp://deptserver in targetURI, it will not connect.

There are a few things you can do to prevent the security policies from inconveniencing you or your users. The first, and easiest, is to use a target URI that doesn't specify a server name. (This is applicable only if the Flash Communication Server and web server are running from the same IP address.) To do so, leave off the second slash in the targetURI parameter. For example, the following commands will make the Flash Player attempt to connect to the same host and domain as the web server the SWF file was served from.

nc = new NetConnection();
nc.connect("rtmp:/myApp");

Second, there is a bit of JavaScript you can use in your HTML page to avoid the security problem. Assuming the movie uses a fully qualified domain name URL to access the Flash Communication Server, this JavaScript redirects the web page to an explicitly named full URL, like this:

<SCRIPT language="javascript">
//if the URL didn't have the domain on it
if (document.URL.indexOf("mycorp.com") == -1) {
    //redirect to a version that does   
    document.URL="http://deptServer.mycorp.com/tcpage.htm";
}
</script>

Finally, if you own a domain name, have access to the DNS records of that domain name, and have a static IP address for your Flash Communication Server, you can create address ("A") records to point a host name to that IP address. For instance, flashcom.mycorp.com could map to the machine running the Flash Communication Server and having an IP address provided by your IT department or ISP. Your web pages can continue to be hosted by whatever means you are currently using. ("CNAME" records are recommended if you need to forward traffic to a server that has a DNS-accessible host name but may or may not have a static IP address.)

Example

The following example connects over the RTMP protocol to the default instance of the funAndGames application located on the real host of the macromedia server using the default port.

conn = new NetConnection();
conn.connect("rtmp://real.macromedia.com/funAndGames");

The following example connects over the RTMPT protocol to the room_01 application instance of the chat application using the default port. In this example, the Flash movie is served from the same host and domain as the Flash Communication Server, so the host parameter is omitted.

con = new NetConnection();
con.connect("rtmpt:/chat/room_01");