Let's see how to use the Remoting classes to accomplish some common goals. Example 11-2 shows how to consume the Google web service with the NetServices package, allowing you to add a Google search capability to your application. This example assumes that you have Flash Remoting installed and configured to accept web services. The client-side ActionScript in the example should be entered in the first frame of the Actions layer of a Flash movie. Look over the code, and we'll discuss it momentarily.

// To run this example from a FlashCom appication, 
// use load("netservices.asc") instead of #include "NetServices.as".
#include "NetServices.as"
// To run this example from a FlashCom appication, wrap the rest of this
// example in an application.onAppStart( ) function.
NetServices.setDefaultGatewayUrl("http://localhost/flashservices/gateway");
my_conn = NetServices.createGatewayConnection( );

GoogleService = my_conn.getService("http://api.google.com/GoogleSearch.wsdl", this);

this.doGoogleSearch_Result = function (data) {
  trace("we have data");
  searchdata = data;
};

this.doGoogleSearch_Status = function (error) {
  for (var i in error) {
    trace(i + " : " + error[i]);
  }
};

// You need to insert your Google developer key as a string for the key property.
params = {
  key:"Your developer key goes here",
  q:"amfphp",
  start:0,
  maxResults:10,
  filter:true,
  restrict:"",
  safeSearch:false,
  lr:"",
  ie:"UTF-8",
  oe:"UTF-8"
}

GoogleService.doGoogleSearch(params);

As in the first line of the example, you must include NetServices.as to use the Flash Remoting components. This loads the NetServices class and several other classes. In a FlashCom application, the SSAS syntax to load the NetServices class is:

load ("netservices.asc");

The setDefaultGatewayUrl( ) method provides a means to set a URL to use for all calls to createGatewayConnection( ). The createGatewayConnection( ) method also accepts a URL that overrides the default gateway URL.

You can use either of the following to create the gateway connection:

NetServices.setDefaultGatewayUrl("http://localhost/flashservices/gateway");
my_conn = NetServices.createGatewayConnection( );

or:

my_conn = NetServices.createGatewayConnection(
             "http://localhost/flashservices/gateway");

Using setDefaultGatewayUrl( ) to set the default gateway avoids having to specify the connection path every time you create a gateway connection with createGatewayConnection( ).

The createGatewayConnection( ) method returns a NetConnection object that is used to communicate with the remote server. (The NetServices.as file adds several remoting-specific methods to the NetConnection class.) You must assign the results of createGatewayConnection( ) to a variable, or the connection object will be destroyed; it is not cached locally within the NetServices class.

The getService( ) method, one of the methods of NetConnection added by NetServices.as, builds and returns an object that acts as a proxy to the remote service definition:

myService = NetConnection.getService(serviceName[, responseObject]);

The serviceName parameter is the path to the service definition for the remote server. Its format is the same as the first parameter for the NetConnection.call( ) method without the method name included in the string. In Example 11-2, its value is "http://api.google.com/GoogleSearch.wsdl".

The responseObject is the object that should respond to all methods called through this service object. This parameter is optional, and in most applications not practical. Typically, unless there is a specific reason to do so, using a single object to respond to all remote calls will end in an unnecessarily complicated result definition. Instead, you'll usually implement separate responders for each method called through the service.

Example 11-2 shows one way to handle the results of a remote method invocation. The doGoogleSearch_Result( ) method handles the results returned by the call to doGoogleSearch( ) (The Flash Remoting components automatically look for a handler of the same name with "_Result" appended for this purpose.) The example simply traces a message stating that results were returned by the call and stores the result data in a variable named searchdata. You can use the Debug→ List Variables command in the Flash authoring tool's Test Player to inspect the format of the returned results. The NetConnection Debugger, discussed in Chapter 3, is also useful for analyzing data transmitted via Flash Remoting.

The doGoogleSearch_Status( ) method is triggered if the service returns any errors (again, Flash automatically looks for a handler of the same name with "_Status" appended for this purpose). We will come back to handling errors later; the method here simply traces the error message if something goes wrong.

Finally, the remote method is executed. The Google web service requires many parameters, which are passed in a single parameters object. The two important properties of the parameters object are key and q. The key property is a required string assigned to each developer. A developer obtains a key by registering to use the Google search web service at http://www.google.com/apis. The q property is the string for which you want to search. The other parameters manipulate how the search is processed and returned. Consult Google's documentation at the preceding URL for details of each parameter. Finally, doGoogleSearch( ) is invoked on the GoogleService service to execute the remote procedure.