Recipe 18.2. Sending Data

Problem

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

Solution

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

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 method or properties of the LocalConnection class, or the send( ) call will fail. The built-in method and property names that cannot be used as the method name parameter are send, connect, close, allowDomain, allowInsecureDomain, client, and domain.

You should define the receiving method so it accepts the parameters sent to it. In this example, a local connection receiver class is created that contains a method named example( ). The method expects three parameters: str, num, and bool; for example:

package {   import flash.net.LocalConnection;   public class ExampleReceiver {     private var _receiver:LocalConnection;     public function ExampleReceiver(  ) {       // Instantiate the local connection receiver and listen on the        // "_exampleChannel" channel for other movies calling the example        // method.       _receiver = new LocalConnection(  );       _receiver.connect( "_exampleChannel" );       _receiver.client = this;     }     public function example( str:String, num:Number, bool:Boolean):void {       trace( "The parameters are: " + str + "\n" + num + "\n" + bool );     }   } }

The following code snippet sends a message that calls example( ) in the receiving movie and passes it parameters, similar to invoking it like: example( "a string", 6.5, true ):

// Send three parameters to a receiving movie's local connection  // method named example( ). The parameters happen to be a String, a  // Number, and a Boolean. var sender:LocalConnection = new LocalConnection(  ); sender.send( "_exampleChannel", "example", "a string", 6.5, true);

You are not limited to sending just primitive datatypes. 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 17.6, but the required steps are:

1. Define the custom class, and if necessary, import it in both the sending and receiving movies.

2. Register the class in the sending and receiving movies by using the flash.net.registerClass( ) method, making sure to use the same alias in all movies.

3. Send a class instance over a local connection with the send( ) method.

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 called Person:

// Create a Person class in the model package package model {   public class Person {        private var _firstName:String;     private var _age:int;          public function Person(firstName:String, age:int) {       _firstName = firstName;       _age = age;         }          public function toString(  ):String {       return _firstName + " is " + _age + " years old";         }        }    }

Here's the receiving .swf code:

import flash.net.registerClassAlias; import model.Person; registerClassAlias( "model.Person", model.Person ); package {   import flash.net.LocalConnection;   public class ExampleReceiver {     private var _localConnection:LocalConnection;     public function ExampleReceiver(  ) {       _localConnection = new LocalConnection(  );       _localConnection.connect("_exampleChannel");       _localConnection.client = this;     }     public function example( person:Person ):void {       trace( person.toString(  ) );     }   } }

And here's the sending .swf code:

package {   import flash.net.registerClassAlias;   import model.Person;   public class ExampleSender {     public function ExampleSender(  ) {       registerClassAlias( "model.Person", Person );       // Create a Person instance to send across       var person:Person = new Person("Darron", 24);       // Create the local connection and send a Person instance        // to the receiving movie.       var sender:LocalConnection = new LocalConnection(  );       sender.send( "_exampleChannel", "example", person );     }   } }

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's 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 18.3).

See Also

Recipes 17.6 and 18.3