The server-side NetConnection class lets you create a two-way connection between an Adobe Media Server application instance and an application server, another Adobe Media Server, or another Adobe Media Server application instance on the same server. You can use NetConnection objects to create powerful applications; for example, you can get weather information from an application server or share an application load with other servers that are running Adobe Media Server or application instances.

Availability

Flash Communication Server 1

Property summary

Property

Description

NetConnection.farID

Read-only. A String indetifying the RTMFP identify of the Adobe Media Server instance to which this Adobe MediaAdobe Media Server Instance is connected.

NetConnection.farNonce

Read-only. A String unique to this connection. This value appears to another server as its NetConnection.nearNonce value.

NetConnection.isConnected

Read-only; a boolean value indicating whether a connection has been made.

NetConnection.nearID

Read-only. A String indentifier of this Flash Player or Adobe AIR instance for this NetConnection instance.

NetConnection.nearNonce

Read-only. A String unique to this connection. This value appears to another server as its NetConnection.farNonce value.

NetConnection.objectEncoding

The Action Message Format (AMF) version used to pass binary data between two servers.

NetConnection.rtmfpBindAddresses

An Array of Strings representing the specific address or addresses that the NetConnection binds locally when it opens its RTMFP protocol stack.

NetConnection.rtmfpEndpointName

The endpoint name for the local RTMFP protocol stack.

NetConnection.uri

Read-only; a string indicating the URI parameter of the NetConnection.connect() method.

Method summary

Method

Description

NetConnection.addHeader()

Adds a context header to the Action Message Format (AMF) packet structure.

NetConnection.call()

Invokes a command or method on another Adobe Media Server or an application server to which the application instance is connected.

NetConnection.close()

Closes the connection with the server.

NetConnection.connect()

Connects to another Adobe Media Server or to a Flash Remoting server such as Adobe ColdFusion.

Event handler summary

Event handler

Description

NetConnection.onStatus()

Invoked every time the status of the NetConnection object changes.

NetConnection constructor

 new NetConnection()

Creates a new instance of the NetConnection class.

Availability

Flash Communication Server 1.

Returns

A NetConnection object.

Example

The following example creates a new instance of the NetConnection class:

 newNC = new NetConnection();

NetConnection.addHeader()

 nc.addHeader(name, mustUnderstand, object)

Adds a context header to the Action Message Format (AMF) packet structure. This header is sent with every future AMF packet. If you call addHeader() by using the same name, the new header replaces the existing header, and the new header persists for the duration of the NetConnection object. To remove a header, call addHeader() and pass it the name of the header to remove and an undefined object.

Availability

Flash Communication Server 1

Parameters

name

A string; identifies the header and the ActionScript object data associated with it.

mustUnderstand

A boolean; true indicates that the server must understand and process this header before it handles any of the following headers or messages.

object

An Object.

Example

The following example creates a new NetConnection instance, nc, and connects to an application at web server www.foo.com that is listening at port 1929. This application dispatches the service /blag/SomeCoolService. The last line of code adds a header called foo.

 nc=new NetConnection(); 
 nc.connect("http://www.foo.com:1929/blag/SomeCoolService"); 
 nc.addHeader("foo", true, new Foo());

NetConnection.call()

 nc.call(methodName, [resultObj [, p1, ..., pN])

Invokes a command or method on another Adobe Media Server or an application server to which the application instance is connected. The NetConnection.call() method on the server works the same way as the NetConnection.call() method on the client: it invokes a command on a remote server.

Note:

To call a method on a client from a server, use the Client.call() method.

Availability

Flash Communication Server 1

Parameters

methodName

A string indicating a method specified in the form "[objectPath/]method". For example, the someObj/doSomething command tells the remote server to invoke the clientObj.someObj.doSomething() method, with all the p1, ..., pN parameters. If the object path is missing, clientObj.doSomething() is invoked on the remote server.

resultObj

An Object. This optional parameter is used to handle return values from the server. The result object can be any object that you defined and can have two defined methods to handle the returned result: onResult() and onStatus(). If an error is returned as the result, onStatus() is invoked; otherwise, onResult() is invoked.

p1, ..., pN

Optional parameters that can be of any ActionScript type, including a reference to another ActionScript object. These parameters are passed to the methodName parameter when the method is executed on the remote application server.

Returns

For RTMP connections, returns a boolean value of true if a call to methodName is sent to the client; otherwise, false. For application server connections, it always returns true.

Example

The following example uses RTMP to execute a call from one Adobe Media Server to another Adobe Media Server. The code makes a connection to the App1 application on server 2 and then invokes the Sum() method on server 2:

 nc1.connect("rtmp://server2.mydomain.com/App1", "svr2",); 
 nc1.call("Sum", new Result(), 3, 6);

The following Server-Side ActionScript code is on server 2. When the client is connecting, this code checks to see whether it has a parameter that is equal to svr1. If the client has that parameter, the Sum() method is defined so that when the method is called from svr1, svr2 can respond with the appropriate method:

 application.onConnect = function(clientObj){ 
     if(arg1 == "svr1"){ 
         clientObj.Sum = function(p1, p2){ 
             return p1 + p2; 
         } 
     }  
     return true;  
 };

The following example uses an Action Message Format (AMF) request to make a call to an application server. This allows Adobe Media Server to connect to an application server and then invoke the quote() method. The Java™ adaptor dispatches the call by using the identifier to the left of the dot as the class name and the identifier to the right of the dot as a method of the class.

 nc = new NetConnection; 
 nc.connect("http://www.xyz.com/java"); 
 nc.call("myPackage.quote", new Result());

NetConnection.close()

 nc.close()

Closes the connection with the server. After you close the connection, you can reuse the NetConnection instance and reconnect to an old application or connect to a new one.

Note:

The NetConnection.close() method has no effect on HTTP connections.

Availability

Flash Communication Server 1

NetConnection.connect()

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

Call NetConnection.connect() to do any of the following:

  • (Flash Media Server 1.0) Connect over HTTP to an application server, such as Adobe® ColdFusion®, running a Flash Remoting gateway.

    note: You cannot use HTTP to connect to another Adobe Media Server or to media assets.

  • (Flash Media Server 3.0) Multi-point publishing over RTMP/S. Connect over RTMP/S to another Adobe Media Server and publish a stream to the server.

  • (Flash Media Server 4.0) Multi-point publishing over RTMFP. Connect over RTMFP to an application on the same server or on another Adobe Media Server and publish a stream to the server.

    Create a server-side NetConnection, connect to the target server with an RTMFP URI (for example, "rtmfp://ams.example.com/myapp"). Then create a NetStream without passing a GroupSpecifier string as a constructor argument. This technique is traditional multi-point publishing but over an RTMFP connection.

  • (Flash Media Server 4.0) Publish a live stream into a NetGroup. Connect over RTMFP to the current application or to an application on another Adobe Media Server.

    After you create an RTMFP NetConnection, use a GroupSpecifier to create a NetGroup and a NetStream. The server application joins a group and becomes a peer in the group mesh. A single client can join multiple groups. Once connected, you can interact with other peers in the group and publish into the group. Use this technique to ingest a live stream and publish it into a group.

    note: Server-Side ActionScript doesn't support opening an RTMFP NetConnection directly to a client peer (DIRECT_CONNECTIONS in the client API).

  • (Flash Media Server 4.5) Pass the string "rtmfp:" to create a serverless network endpoint for RTMFP communication. This mode can be used only for RTMFP groups; it cannot be used for direct connections.

    This mode is more fault-tolerate and supports the ability to cluster servers via RTMFP with no single point of failure. See Distribute introductions across servers.

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 (AMF) connections, check NetConnection.onStatus().

Availability

Flash Communication Server 1

Parameters

URI  A string indicating a URI to connect to. URI has the following format:

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

The following are legal URIs:

 http://appserver.mydomain.com/webapp 
 rtmp://ams.mydomain.com/realtimeapp 
 rtmps://ams.mydomain.com/secureapp 
 rtmp://localhost/realtimeApp 
 rtmp:/realtimeApp 
rtmfp://ams.mydomain.com/p2papp 
rtmfp://

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, RTMP parameters are ignored.

Returns

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

Example

The following example creates an RTMP connection to an application instance on Adobe Media Server:

 nc = new NetConnection(); 
 nc.connect("rtmp://ams.example.com/vod/instance1");

NetConnection.farID

 nc.farId

Read-only. A String indentifying the RTMFP identify of the Adobe Media Server instance to which this Adobe Media Server is connected. This property is meaningful only for RTMFP connections. The value of this property is available only after an RTMFP connection is established.

Availability

Flash Media Server 4

See also

NetConnection.farNonce

 nc.farNonce

Read-only. A String unique to this connection. This value appears to another server as its NetConnection.nearNonce value. This value is defined for RTMFP, RTMPE, and RTMPTE connections.

Availability

Flash Media Server 4

See also

NetConnection.isConnected

 nc.isConnected

Read-only; a boolean value indicating whether a connection has been made. It is set to true if there is a connection to the server. It’s a good idea to check this property value in an onStatus() callback function. This property is always true for AMF connections to application servers.

Availability

Flash Communication Server 1

Example

The following example uses NetConnection.isConnected in an onStatus() handler to check whether a connection has been made:

 nc = new NetConnection(); 
 nc.connect("rtmp://tc.foo.com/myApp"); 
 nc.onStatus = function(infoObj){ 
     if (info.code == "NetConnection.Connect.Success" && nc.isConnected){ 
         trace("We are connected"); 
     } 
 };

NetConnection.nearID

 nc.nearId

A String.

Read-only. A String indentifier of this Adobe Media Server instance for this NetConnection session. This property is meaningful only for RTMFP connections.

Availability

Flash Media Server 4

See also

NetConnection.nearNonce

 nc.nearNonce

Read-only. A String unique to this connection. This value appears to another server as its NetConnection.farNonce value. This value is defined for RTMFP, RTMPE, and RTMPTE connections.

Availability

Flash Media Server 4

See also

NetConnection.objectEncoding

 nc.objectEncoding

The Action Message Format (AMF) version used to pass binary data between two servers. The possible values are 3 (ActionScript 3.0 format) and 0 (ActionScript 1.0 and ActionScript 2.0 format). The default value is 3. When Adobe Media Server acts as a client trying to connect to another server, the encoding of the client should match the encoding of the remote server.

Flash Media Server versions 1 and 2 support AMF0. Flash Media Server versions 3 and later support AMF0 and AMF3.

The value of objectEncoding is determined dynamically according to the following rules when the server receives a NetConnection.onStatus() event with the code property NetConnection.Connect.Success:

  • If the onStatus()info object contains an objectEncoding property, its value is used.

  • If the onStatus()info object does not contain an objectEncoding property, 0 is assumed even if the connecting server has set objectEncoding to 3.

  • Once the NetConnection instance is connected, the objectEncoding property is read-only.

These rules turn Flash Media Server 3 into an AMF0 client when it connects to a remote Flash Media Server version 2 or earlier (which only support AMF0).

Note:

The server always serializes data in AMF0 while executing Flash Remoting functions.

Availability

Flash Media Server 3

NetConnection.onStatus()

 nc.onStatus = function(infoObject) {}

Invoked every time the status of the NetConnection object changes. For example, if the connection with the server is lost in an RTMP connection, the NetConnection.isConnected property is set to false, and NetConnection.onStatus() is invoked with a status message of NetConnection.Connect.Closed. For AMF connections, NetConnection.onStatus() is used only to indicate a failed connection. Use this event handler to check for connectivity.

Availability

Flash Communication Server 1

Parameters

infoObject

An Object with properties that provide information about the status of a NetConnection information object. This parameter is optional, but it is usually used. The NetConnection information object contains the following properties:

Property

Meaning

code

A string identifying the event that occurred.

description

A string containing detailed information about the code. Not every information object includes this property.

level

A string indicating the severity of the event.

The following table contains the code and level property values and their meanings:

Code

Level

Meaning

NetConnection.Call.Failed

error

The NetConnection.call() method was not able to invoke the server-side method or command.

NetConnection.Connect.AppShutdown

error

The application has been shut down (for example, if the application is out of memory resources and must shut down to prevent the server from crashing) or the server has shut down.

NetConnection.Connect.Closed

status

The connection was closed successfully.

NetConnection.Connect.Failed

error

The connection attempt failed.

NetConnection.Connect.Rejected

error

The client does not have permission to connect to the application, or the application name specified during the connection attempt was not found on the server. This information object also has an application property that contains the value returned by application.rejectConnection().

NetConnection.Connect.Success

status

The connection attempt succeeded.

NetConnection.Proxy.NotResponding

error

The proxy server is not responding. See the ProxyStream class.

Example

The following example defines a function for the onStatus() handler that outputs messages to indicate whether the connection was successful:

 nc = new NetConnection(); 
 nc.onStatus = function(info){ 
     if (info.code == "NetConnection.Connect.Success") { 
         _root.gotoAndStop(2); 
     }    else { 
         if (! nc.isConnected){ 
             _root.gotoAndStop(1); 
         } 
     } 
 };

NetConnection.rtmfpBindAddresses

 nc.rtmfpBindAddresses

An Array of Strings representing the specific address or addresses that the NetConnection binds locally when it opens its RTMFP protocol stack. This value is ignored for all other protocols. If you assign an NetConnection.rtmfpEndpointName to a NetConnection, assign this property also so that other peers can interact with the instance at a known IP address and port.

When assigning an Array of address Strings to this property, each String must specify an IPv4 or IPv6 address to bind and listen on, optionally followed by a colon (":") and a UDP port number. To specify an IPv6 address and a port, enclose the IPv6 address in square brackets. If no port value is specified, the next available system port is bound. Upon successful bind, the String value in the property representing the address is updated to include the ephemeral port number that has been bound.

By default, the RTMFP protocol stack binds "0.0.0.0" if connecting to an IPv4 RTMFP server, or "::" if connecting to an IPv6 server when the computer, network and Adobe Media Server support IPv6. These values direct the RTMFP protocol stack to listen on either all available IPv4 or IPv6 interfaces, but not both.To bind and listen on IPv4 and IPv6 interfaces concurrently, assign an Array of addresses such as: ["0.0.0.0:31000", "[::]:31000"]. In this example, all local IPv4 and IPv6 interfaces are bound on port 31000. Use non-wildcard address values to selectively bind specific interfaces rather than all of them.

This property can be read at any time but can only be set when the NetConnection is in a disconnected state and no connect attempt is in progress.

This property throws an error if any arguments within the assigned Array are of the wrong type or missing, address values are improperly formatted, or the NetConnection is connected or is in the process of connecting.

Binding happens after the NetConnection.connect() method is called. If a bind attempt fails, a NetConnection.Connect.Failed event is dispatched, and details of the bind failure are logged to the application log.

Availability

Flash Media Server 4.5

Example

The following example tells the NetConnection to bind and listen on any IPv4 interfaces at port 31000:

nc.rtmfpBindAddresses = ["0.0.0.0:31000];

NetConnection.rtmfpEndpointName

 nc.rtmfpEndpointName

The endpoint name for the local RTMFP protocol stack; ignored for all other protocols. The default value is null, which is ignored by the local RTMFP protocol stack. This property can be read at any time but cannot be assigned while the NetConnection is connected or in the process of connecting.

This property throws an error if the assigned name is of the wrong type or missing, or if the NetConnection is currently connected or in the process of connecting.

Availability

Flash Media Server 4.5

Example

The following example assigns an RTMFP endpoint name:

nc.rtmfpEndpointName = "bootstrap-peer";

NetConnection.uri

 nc.uri

Read-only; a string indicating the URI parameter of the NetConnection.connect() method. This property is set to null before a call to NetConnection.connect() or after a call to NetConnection.close().

Availability

Flash Communication Server 1

This work is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License  Twitter™ and Facebook posts are not covered under the terms of Creative Commons.

Legal Notices   |   Online Privacy Policy