LocalConnection Class

	ActionScript for Flash MX: The Definitive Guide, 2nd Edition By Colin Moock
	Chapter 18.  ActionScript Language Reference

LocalConnection Class

Flash 6

---

transmit data directly between movies running on the same system

Constructor

new LocalConnection()

Methods

close( )

Stop a connection from receiving messages.

connect( )

Open a named connection.

domain( )

Returns a string indicating the movie's subdomain.

send( )

Invoke a method on a remote LocalConnection object.

Event Handlers

allowDomain( )

Callback to permit or deny a cross-domain connection attempt.

onStatus( )

Callback indicating initial status of a send( ) invocation.

Description

The LocalConnection class lets movies running in different Flash Players communicate with each other. The Players must be running on the same computer, but they can be embedded in any application. For example, movies running in the Netscape Flash 6 plugin, the Internet Explorer ActiveX Flash Player, and the Standalone Flash Player can all communicate with each other as long as they are running on the same machine. To transfer information between two Flash Players running on different machines use XML, LoadVars, XMLSocket, or the Macromedia Flash Communication Server MX (Comm Server).

All LocalConnection applications involve at least two LocalConnection objects, one in the receiver (the movie that receives messages) and one in the sender (the movie that sends messages). Although, in practice, both movies may act as both senders and receivers, let's start with simple one-way communication for illustration purposes.

The first line of code in the receiver is:

receiveConn = new LocalConnection();

And the first line in the sender is:

sendConn = new LocalConnection();

Once the receiver and sender have each created a LocalConnection object, they must agree in advance on a name for the connection. On the receiver's end, the connection name is specified when the connection is opened. However, the connection should not be opened until the receiver has defined methods that the sender will invoke remotely. These methods form the basis of all intermovie communication. For example, here we define a method on our receiveConn object that displays a supplied argument in a text field:

// Create the text field this.createTextField("received_txt", 1, 50, 100, 400, 100); received_txt.border = true;     // Define the method receiveConn.displayMsg = function (msg) {   received_txt.text = msg; }

With the receiveConn.displayMsg( ) method defined, we now can safely open the receiver's connection. On the receiver side, we use the connect( ) method to start listening for messages. The connection name is supplied as an argument to the connect( ) method; in the following line, it is "channel1":

receiveConn.connect("channel1");

Our receiver movie is now open for business. All that's left to do is send a request from the sender to invoke displayMsg( ) on the receiver movie. The sender uses the send( ) method to perform remote method invocations. Arguments to send( ) specify the connection name ("channel1"), the method to invoke ("displayMsg"), and the method argument(s) ("hello world"), as follows:

sendConn.send("channel1", "displayMsg", "hello world");

Here is the complete code required to establish basic LocalConnection communication:

// CODE IN THE RECEIVING MOVIE receiveConn = new LocalConnection(); receiveConn.methodName = function (param1, param2) {   // statements } receiveConn.connect("connectionName");     // CODE IN THE SENDING MOVIE sendConn = new LocalConnection(); sendConn.send("connectionName", "methodName", "value1", "value2");

For security reasons, when the sender and receiver are posted at different domains, they cannot, by default, communicate over a LocalConnection. See LocalConnection.allowDomain( ) for details on allowing movies to communicate across domains. All movies running on the local filesystem are considered in the same domain ("localhost"), and are therefore not subject to security restrictions.

Communication over LocalConnection is many-to-one, from the sender's perspective. Any number of senders can send messages to a specific named connection, but only one receiver can listen on that connection. If a different receiver tries to open a named connection that is already open, the latter connection attempt fails, and the connect( ) method returns false.

A LocalConnection object can act as both a sender and a receiver, allowing two objects to engage in bidirectional communication. For sample code, see the Example heading under LocalConnection.onStatus( ).

Prior to Flash 6, local intermovie communication could be achieved only with fscommand( ) and JavaScript, and only in specific browser/platform combinations. See fscommand( ) for details.

See Also

fscommand( )