Recipe 20.6 Invoking a Remote Function on a Service

20.6.1 Problem

You want to call a service function from a Flash movie (see Table 20-1 for Flash Remoting service function types).

20.6.2 Solution

Create a service object by invoking the getService( ) method from the connection object returned by createGatewayConnection( ). The service object is the object returned by getService( ). Then call the service function (any function defined for the service) as a method of the service object.

20.6.3 Discussion

The first step in calling a service function from a Flash movie is to create a connection object (see the Introduction and Recipe 20.1 for more information about this). For example:

#include "NetServices.as"
NetServices.setDefaultGatewayURL("http://localhost/flashservices/gateway");
myConnection = NetServices.createGatewayConnection(  );

Once you have created the connection object, you can create an object that maps to any service available through the specified gateway using the getService( ) method. There are two variations when using the getService( ) method. In the first variation, you specify a single response object to handle responses from all functions invoked on the object. In the second variation, instead of specifying the response object when invoking getService( ), you specify it as the first parameter each time you invoke a service function.

Both variations require that you provide the name of the service as it is known to the Flash Remoting gateway. A service is known by the URL that accesses the service. See the Introduction and Recipe 20.2, Recipe 20.3, and Recipe 20.4 for more details on determining the correct service name.

In the first variation, you also need to provide a reference to an object that will handle the response by default (called the response object). In this variation, the response object should be an object with named result functions (see Recipe 20.7 for details on how to handle results using named result functions). By convention, the object is the same object within which the service object is defined (see also Recipe 20.7 for more details on service objects).

// Create a service object that maps to a service named serviceName and set this (the
// same object within which the service object is defined) to handle the response. 
myService = myConnection.getService("serviceName", this);

Notice that the service object is returned by getService( ), and the response object is optionally passed to getService( ) to handle the response. After obtaining the service object with getService( ), based on the service name, you can invoke any service function as a method of the service object. If the service function expects parameters, you can pass the parameters to it just as with any other method invocation.

// Call a service function named serviceFunction0 with no parameters.
myService.serviceFunction0(  );

// Call a service function named serviceFunction1 with 
// two parameters: a string and a Boolean.
myService.serviceFuncton1("param value", true);

In the alternative approach, when calling the getService( ) method, you don't specify a response object to handle the response. Instead, with this variation, you specify the response object as the first parameter when invoking a service function. However, the response object parameter is not sent to the service function.

// Create the service object without specifying the response object.
myService = myConnection.getService("serviceName");

// Call serviceFunction0, specifying that myResponseObject should handle the results,
// but do not pass any additional parameters. myResponseObject is not sent to the
// service function.
myService.serviceFunction0(myResponseObject);

// Call serviceFunction1, specifying that myResponseObject should handle the results,
// and pass two additional parameters. myResponseObject is not sent to the service
// function, but the string and Boolean values are sent.
myService.serviceFunction1(myResponseObject, "param value", true);

In this variation, the response object should contain an onResult( ) method, as described in Recipe 20.7.

In most cases, the second variation—in which the response object is specified as the first parameter when calling a service function—is the better choice. This option enables you to specify different response objects for each service function call (something you cannot do using the first variation, in which the service object is set when calling getService( )).

It is worth noting that you must always declare a response object, either when calling the getService( ) method or in the service function invocation. This is true even if the service function does not return any result. Also, you should never try to define a response object in both places. Doing so will only create errors.

20.6.4 See Also

Recipe 20.7, Recipe 20.9, Recipe 20.10, and Recipe 20.13