Recipe 17.2 Sending Data Using Local Connections

17.2.1 Problem

You want to send data to one or more movies playing on the same computer.

17.2.2 Solution

Pass the data as additional parameters to the send( ) method of the sending local connection object.

17.2.3 Discussion

You can send data to another movie using a local connection by passing the data as additional parameters to the send( ) method of the sending local connection object. The send( ) method requires at least two parameters: the name of the connection and the name of the method to invoke on the receiving movie. Any additional parameters passed to the send( ) method are automatically passed as parameters to the receiving movie's method. Note that the name of the method you are invoking on the receiving movie cannot be one of the built-in methods of the LocalConnection class, such as send, connect, etc. For a complete list of the built-in methods of a local connection, see the "Language Reference" section of ActionScript for Flash MX: The Definitive Guide, or the Reference panel (Window Reference) in Flash.

You should define the receiving method so it accepts the parameters sent to it. In this example, the receiving movie contains a local connection with a method named myMethod( ). The method expects three parameters: str, num, and bool.

receiving_lc = new LocalConnection(  );
receiving_lc.connect("_myConnection");
receiving_lc.myMethod = function (str, num, bool) {
  _root.output_txt.text = "The parameters are: " +
                          str + newline + 
                          num + newline + 
                          bool;
};

Here is a code snippet from a sending movie that calls myMethod( ) in the receiving movie and passes it parameters, similar to invoking it as follows: myMethod( "a string", 6, true).

// Send three parameters to a receiving movie's local connection method named
// myMethod(  ). The parameters happen to be a string, a number, and a Boolean.
sending_lc = new LocalConnection(  );
sending_lc.send("_myConnection", "myMethod", "a string", 6, true);

You are not limited to sending primitive datatypes only. Specifically, you can send data of the following complex types: Object, Array, Date, TextFormat, and XML.

Additionally, you can send objects of custom types. The process for doing so involves many of the same steps as storing and retrieving custom object types from a shared object. You can find more details about the theory behind this in Recipe 16.2, but the required steps are:

The following is an example of the code in a sending movie and a receiving movie that passes data of a custom object type from one to the other.

First, let's define the custom class in its own .as file so that we can easily include it in both the sending and receiving movies. For the purposes of this example, name the file MyClass.as.

// Define the custom class, MyClass.
function MyClass(val) {

  // Since the constructor contains initialization code, enclose it in an if 
  // statement so that it is executed only when the object is first created and not
  // on subsequent deserializations. The inited property is used to track whether the
  // data has been initialized.
  if (!this.inited) {
    this.inited = true;
    this.val = val;
  }
}

// Let's define a method for the class so that we can show that Flash allows us to 
// invoke the method in the receiving movie.
MyClass.prototype.getVal = function (  ) {
  return this.val;
};

// Register the class to an arbitrary ID.
Object.registerClass("MyClassID", MyClass);

Here's the receiving movie code:

#include "MyClass.as"

// Define the local connection object to listen over "_myConnection".
receiving_lc = new LocalConnection(  );
receiving_lc.connect("_myConnection");

receiving_lc.myMethod = function (param) {
  // If the parameter is an instance of MyClass, display its val property by the
  // getVal(  ) method.
  if (param instanceof MyClass) {
    trace("Parameter value is " + param.getVal(  ));
  } else {
    trace("Param is not of the expected type.");
  }
};

and here's the sending movie code:

#include "MyClass.as"

// Create the local connection and send a MyClass object to the receiving movie.
sending_lc = new LocalConnection(  );
sending_lc.send("_myConnection", "myMethod", new MyClass("test"));

Regardless of what type of data is being sent, the same rules apply to any type of local connection communication. Both movies must be running on the same computer at the same time, and the receiving movie must be listening on the same channel that the sending movie uses to send. Also, it is worth noting that once you have defined a custom datatype in both the sending and receiving movies, you can send that type of data in both directions (although you should use two separate channels for bidirectional communication, as discussed in Recipe 17.3).

17.2.4 See Also

Recipe 17.1