All of the processing and conversion of AMF is handled internally by the FlashCom Server (or Flash Player) and the Flash Remoting gateway, so you never have to deal with it. The NetConnection class, the base class for RTMP communications, also serves as the foundation for Remoting. A NetConnection instance on the client provides the developer interface to create the binary data and transmit it to the destination server.

Let's start with a simple example in which the Flash Player is the client. You could also run this example script inside a FlashCom application if the path to the imaginary service were correct. Example 11-1 shows how to use a NetConnection object to call a remote method on an application server with the remoting gateway installed.

my_conn = new NetConnection(  );
my_conn.connect("http://localhost/flashservices/gateway");

response = new Object( );
response.onResult = function (result) {
  trace(result);
};

my_conn.call("services.TestService.dataEcho", response, "test message");

The first two lines should look familiar to anyone building a FlashCom connection. In this case, the URI passed to the connect( ) method refers to the remoting gateway that comes bundled with ColdFusion residing on the local host. Unlike an RTMP connection, the call to connect( ) does not actually make a connection to the server, so the call will always return true. Internally, the client (in this case, the Flash Player) checks the protocol used for the connection. If the protocol is rtmp://, rtmpt://, or rtmps://, the Flash Player immediately tries to establish a socket connection with the remote host, and the connect( ) method returns a Boolean value indicating whether the URI is valid. If the protocol is unspecified or is anything other than rtmp, rtmpt, or rtmps, the Flash Player doesn't try to make a connection to the remote host and always returns true.

The next segment of code creates a response object (also known as a responder), named response, with an onResult( ) method to handle the response to the remote method call. When the server sends back a response, the Player automatically calls the onResult( ) method of the specified object and passes the results as a single argument. Within this body of this method is where you would either process the result or forward the result to another object for processing.

The final line uses NetConnection.call( ) to invoke the remote procedure, using the following format:

NetConnection.call(remoteMethod, resultObject | null [, p1, ...pn])

The remoteMethod parameter is a dot-delimited path to the file, in which the method name is the last part of the string. Depending on the server configuration, the full path from the server root will have to be specified. The remote method format is:

topfolder.subfolder.file_no_extension.method

In Example 11-1, remoteMethod is "services.TestService.dataEcho". This means that the remote method named dataEcho( ) exists in a file named TestService.cfc (for ColdFusion) within a directory named services, which resides in the server root directory.

The resultObject parameter is the object that receives the results from the remote call. If the object has an onResult( ) method defined, it receives a single argument containing results returned by the remote method. If the remote method fails for any reason, the onStatus( ) method, if any, is called instead of onResult( ). The onStatus( ) method receives a single argument, an information object, which has a minimum of three properties: level, code, and description. These properties describe the nature of the error as well as a description of the problem. If the remote procedure does not return any results or you do not need to receive the results, you can pass null as resultObject.

In Example 11-1, resultObject was the response object previously created. The response object's onResult( ) handler simply traces the results returned from the remote method. The response object did not define an onStatus( ) method and therefore will ignore any errors returned by the method call.

The last group of arguments, (p1,...pn), are the optional parameters to supply to the remote method. In Example 11-1, the only argument was a string with the value "test message".