ActionScript
Using LocalConnection For Swf Communications in ActionScript 3.
April 18, 2009
0

LocalConnection enables two or more Flash files to communicate with each other.  You can also use other methods, such as SharedObject, but the benefit of LocalConnection is the real-time nature of LocalConnection. For more information, click Adobe documentation here.  You can also use LocalConnection if you need to communicate with an ActionScript 2 Flash files.

This example shows how to set up two swfs that communicates using LocalConnection.

Creating the LocalConnection

Use the LocalConnection constructor to create the connection.  For communicating, both swfs need to create a LocalConnection object.

The Receiver

In this tutorial, the Receiver is the swf which will receive message from other swf(s).

The code below creates a LocalConnection object; assigns a name to it; and sets a message handler. The term message handler refers to the function(s) that can be called by other swf(s). In the example below, there’s only one, appropriately named messageHandler, but you can use any valid function name.

package
{
	import flash.net.LocalConnection;
	import flash.text.TextField;
	import flash.display.MovieClip;
	import flash.events.StatusEvent;

	public class Receiver extends MovieClip
 	{
		private var mLocalConnection:LocalConnection;

		public function Receiver()
		{
			mLocalConnection=new LocalConnection();
			mLocalConnection.connect("myLocalConnection");
			mLocalConnection.client=this;
			mLocalConnection.addEventListener(StatusEvent.STATUS, onLocalConnectionStatus);
		}

		public function messageHandler(localConnectionMessage:String):void
  		{
			trace("Received message:"+localConnectionMessage);
		}

		public function onLocalConnectionStatus(statusEvent:StatusEvent):void
		{
			if (statusEvent.level=="error")
			{
			}
		}
	}
}

The above code creates a local connection by the name “myLocalConnection”. The line localConnection.client=this; means that this class will handle message. Why is this important? Because you can create another class that specifically handles LocalConnection messages. For instance I can have a class named ReceiverHandler that handles the message directed to the LocalConnection, so that I don’t have to clutter the Receiver class, like below:

package
{
	import flash.net.LocalConnection;
	import flash.text.TextField;
	import flash.display.MovieClip;
	import flash.events.StatusEvent;
	public class Receiver extends MovieClip
 	{
		private var mLocalConnection:LocalConnection;
		public function Receiver()
		{
			mLocalConnection=new LocalConnection();
			mLocalConnection.connect("myLocalConnection");
			mLocalConnection.client=new ReceiverHandler();
			mLocalConnection.addEventListener(StatusEvent.STATUS, onLocalConnectionStatus);
		}
		public function onLocalConnectionStatus(statusEvent:StatusEvent):void
		{
			if (statusEvent.level=="error")
			{
			}
		}
	}

	public class ReceiverHandler
 	{
		public function messageHandler(localConnectionMessage:String):void
  		{
			trace("Received message:"+localConnectionMessage);
		}
	}
}

Sending Messages To The LocalConnection

The Sender

The Sender is the swf that wants to send message to the Receiver object. To establish communication, Sender needs to create its own LocalConnection and call send. Send takes the name of the connection. In our example, the name is “myLocalConnection” — this name is arbitrary, but Sender needs to know the name. The second parameter is the function that the LocalConnection should call. In out example, it is messageHandler.

Again, the choice of connection name and the function name are arbitrary. You can call the function anything as long as both Receiver and Sender knows the name.

If you want to pass parameters to the function, you can tag them as the remaining parameters. In our case, the messageHandler function takes only one parameter, a String. Let’s pass the string “hello” as the parameter.

package
{
	import flash.net.LocalConnection;
	import flash.text.TextField;
	import flash.display.MovieClip;
	import flash.events.StatusEvent;
	import flash.events.MouseEvent;

	public class Sender extends MovieClip
 	{
		private var mLocalConnection:LocalConnection;

		public function Sender()
		{
			mLocalConnection=new LocalConnection();
			sendButton.addEventListener(MouseEvent.CLICK, onClickedSend);
			mLocalConnection.send("myLocalConnection", "messageHandler", "hello");
		}
	}
}

The code above connects to the local connection named myLocalConnection , and calls a function named messageHandler in the Receiver end, passing one parameter to the function. I.e.: it’s the same as saying: please call messageHandler(“hello”); in the Receiver swf.

 

Running Example

Below are two swf files. The first one is the Receiver discussed above. The second one is the Sender. You can type a message in the Sender and when the Receiver receives it, the message will be displayed.

Download the source.

Notes

  • To send and receive message back and forth (that is, allowing each swf to act as Sender and Receiver as opposed to one-way connection like in the above example), you need to have two LocalConnection on each end, one for receiving, and one for sending responses. Click here to read about two-ways LocalConnection and to see an example..
  • You cannot have more than one LocalConnection with the same connection name running at the same time, even if the connections are from a different swf. The reason is obvious: sender won’t know which one is being targeted since a LocalConnections are identified by their connection-names. When the function connect detects that a connection with the same-name is running, it will throw an ArgumentError.
  • On the other hand, you can have one LocalConnection listening for messages from multiple swfs. For example, below is another swf. You can send a message below and see that it is received by the same Receiver swf above.
  • You can use StatusEvent.STATUS to check for connection-failure. StatusEvent.level will have the value of “error” if you try to call send to a non-existent LocalConnection. See onLocalConnectionStatus on the Receiver class example.
        var localConnection:LocalConnection=new LocalConnection();
        localConnection.connect("myLocalConnection");
        localConnection.addEventListener(StatusEvent.STATUS, onLocalConnectionStatus);
    
  • You should call close() when you are done using the LocalConnection. Flash Garbage Collector may not garbage-collect your class if there's an open connection.
        localConnection.close();
    
  • AsyncErrorEvent is something that you will likely encounter. The error is something like this:
    Unhandled AsyncErrorEvent:.
    text=Error #2095: flash.net.LocalConnection was unable to invoke callback bogusMethod.
    error=ReferenceError: Error #1069:
    Property bogusMathod not found on flash.net.LocalConnection and there is no default value.
    

    This error could be caused by one or both of these:
    1. The sender is trying to invoke a non-existent method on the Receiver. For example, the above error would hapen if I try to call a function called bogusMethod because the function bogusMethod doesn't exists in our example. The function we have is called messageHandler, not bogusMethod. The fix is easy, check your code to make sure, the function you're calling is spelled correctly; it is case sensitive.

    2. The Receiver did not set the client property of the Receiver class (ie: you did not specify the class instance that should be used as the client for the connection). See this line in the Receiver class above:mLocalConnection.client=this;, and make sure it is present.

  • To communicate with LocalConnection from another domain, The Receiver must call allowDomain
  • LocalConnection works on stand alone player, not just within browsers.

PS: I think the biggest issue with LocalConnection class is the poor/ambiguous names. For example, the name client is ambiguous, and new users could easily assume it has something to do with a client-swf, not itself. It probably should be called connectionHandler or something more intuitive. Other than poor names, you see that LocalConnection is actually very straightforward to use.