Recipe 14.16 Invoking Server-Side Functions from the Client Movie

14.16.1 Problem

You want to invoke a server-side function from a client movie.

14.16.2 Solution

In the .asc file (main.asc or another .asc file included in main.asc), define the server-side function as a method of the client object. Then, from the client, invoke the call( ) method from the net connection object.

14.16.3 Discussion

To invoke a server-side function from a client, you must first associate the server-side function with the connected client object. You can do this by assigning the function as a method of the client object. Generally, this is done within the onConnect( ) method, as follows:

application.onConnect = function (newClient) {
  application.acceptConnection(newClient);
  newClient.ssFunction = function (  ) {
    // Do something here.
  };
};

Then, from the client movie you can use the call( ) method to invoke the server-side client method:

// Invoke the server-side ssFunction(  ) method from a net connection object.
myConnection.call("ssFunction");

If you want the server-side method to return a value to the client, you must define a response object on the client. A response object is an object derived from the Object class for which you have defined an onResult( ) method. The value returned from the server-side method is passed to the client-side onResult( ) method as a parameter.

myResponse = new Object(  );
myResponse.onResult = function (result) {
  // Do something with result here.
};

Once you have defined the response object on the client, you need to tell Flash to associate it with the response for a given call to a server-side function. To do this, you should modify your call( ) invocation by passing it a reference to the response object:

myConnection.call("ssFunction", myResponse);

Let's look at an example of how you might use this. First, in the .asc file you should define a custom method for each of the connecting clients:

application.onConnect = function (newClient) {
  
  // Accept the connection to the new client.
  application.acceptConnection(newClient);

  // Define a custom getUserCount(  ) method for the client object.
  newClient.getUserCount = function (  ) {

    // Return the number of connected clients.
    return application.clients.length;
  };
};

Then, from within the client code you can invoke the server-side getUserCount( ) method. Don't forget to create a response object as well.

myResponse = new Object(  );
myResponse.onResult = function (result) {
  _root.numberOfUsers_txt.text = result;
};
myConnection.call("getUserCount", myResponse);

14.16.4 See Also

Recipe 14.14 and Recipe 14.17