NetConnection.connect()

Availability

Flash Communication Server MX 1.0.

Usage

myNetConnection.connect(URI, [p1, ..., pN])

Parameters

URI A URI to connect to.

p1, ..., pN Optional parameters that can be of any ActionScript type, including references to other ActionScript objects. These parameters are sent as connection parameters to the application.onConnect event handler for RTMP connections. For AMF connections to application servers, any RTMP parameters are ignored.

Returns

For RTMP connections, a Boolean value of true for success; false otherwise. For AMF connections to application servers, true is always returned.

Description

Method; connects to an application server or another Flash Media Server. The host URI has the following format:

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

The following example shows legal URIs:

http://appServer.mydomain.com/webApp
rtmp://rtserver.mydomain.com/realtimeApp
rtmps://rtserver.mydomain.com/secureApp

You can use the NetConnection.connect() method to connect to an application server for server-to-server interactions using standard protocols (such as HTTP) or connect to another Flash Media Server for sharing audio, video, and data using the Macromedia Real-Time Messaging Protocol format (RTMP) or SSL (RTMPS). SSL in Flash Media Server uses a third-party open source library called OpenSSL.

It is good practice to write an application.onStatus callback function and check the NetConnection.isConnected property for RTMP connections to see whether a successful connection was made. For Action Message Format connections, check NetConnection.onStatus.

About secure connections

Flash Media Server accepts only RTMPS connections on designated secure ports. A port is marked as secure by specifying a minus sign (-) in front of the port in the HostPort tag of the Adaptor.xml file, as shown in the following code:

<HostPort>:1935,80,-443</HostPort>

This code specifies that FMS can listen on any interface, on ports 1935, 80, and 443, where 443 is designated as a secure port that receives only RTMPS connections. Attempting an RTMPS connection to 1935 or 80 fails because the client tries to perform an SSL "handshake" that the server cannot complete. Similarly, a regular RTMP connection to port 443 fails because the server tries to perform an SSL handshake that the client cannot complete.

You can determine whether a connection to the server is over a secure channel by checking the server-side Client.secure property, as shown in the following example:

application.onConnect = function(client){
    if (client.secure){
        trace("This client is connected over a secure connection.");
    }
}

Creating a debugging connection

You can append a property and key to an Internet connection request to create a debug connection. A debug connection gives you greater access to an application; for example, you can play streams and view shared objects.

To create a debug connection:

Call NetConnection.connect() and append a 4-digit debug request number, as shown in the following example:
```
nc.connect("rtmp://fmsaddress/appName/instanceName?_fcs_debugreq_=1234
```
For security, the Internet connection is put in a pending state.
Call the server management API approveDebugSession() and pass it the same debug request number.
The debug connection attempts to connect to the application.
If the Application.allowDebug property is true, the connection is approved.
To provide total security against debug connections, set application.allowDebug to false in the application.xml file. This setting overrides debug connections that are approved in server-side code.
If the connection is approved, Services.onDebugConnect is invoked.
If you can use the onConnect handler to reject the connection.

Escaping the connection URI

It is important to convert (or escape) special characters in any URI used to connect to Flash Media Server to URL-encoding. If you do not escape special characters, shared objects cannot function correctly over an Internet connection. Escaping URIs is especially important when creating a debugging connection because there are special characters in the debugging property that must be appended to the URI. Use the following code to escape a URI:

function escapeURI(uri){
    index = uri.indexOf('?');
    if (index == -1){
        return uri;
    }

    prefix = uri.substring(0, index);
    uri = uri.substring(index);

    return prefix += escape(uri);
}
basicString = "rtmp://serverName/appName/instance?_fcsdebug_req=someNumber";
escapedString = escapeURI(BasicString);
nc.connect(EscapedString);

Example

The following example creates an RTMP connection to a Flash Media Server for the myConn instance of NetConnection:

myConn = new NetConnection();
myConn.connect("rtmp://tc.foo.com/myApp/myConn");

The following example creates an AMF connection to an application server for the myConn instance of NetConnection:

myConn = new NetConnection();
myConn.connect("http://www.xyz.com/myApp/");

The following example creates a debug connection:

nc_admin = new NetConnection();
nc_admin.connect("rtmp://tc.foo.com/myApp/myConn?_fcs_debugreq_=1234");
nc_admin.call("approveDebugSession", null, "myApp/myConn", 1234);