Communicating with other Flash Player and AIR instances

LocalConnection objects can communicate only among AIR applications and SWF files that are running on the same client computer. However, the applications can run in different applications. For example, two AIR applications can communicate using the LocalConnection class, as can an AIR application and a SWF file running in a browser.

The simplest way to use a LocalConnection object is to allow communication only between LocalConnection objects located in the same domain or the same AIR application. That way, you do not have to worry about security issues. However, if you need to allow communication between domains, you have several ways to implement security measures. For more information, see the discussion of the connectionName parameter of the send() method and the allowDomain() and domain entries in the LocalConnection class listing in the ActionScript 3.0 Reference for the Adobe Flash Platform .

To add callback methods to your LocalConnection objects, set the LocalConnection.client property to an object that has member methods, as the following code shows:

var lc = new air.LocalConnection(); 
var clientObject = new Object(); 
clientObject.doMethod1 = function() { 
    air.trace("doMethod1 called."); 
} 
clientObject.doMethod2 = function(param1) { 
    air.trace("doMethod2 called with one parameter: " + param1); 
    air.trace("The square of the parameter is: " + param1 * param1); 
} 
lc.client = clientObject;

The LocalConnection.client property includes all callback methods that can be invoked.

You use the LocalConnection class to communicate between different AIR applications and between different Adobe® Flash® Player (SWF) applications running in a browser. You can also use the LocalConnection class to communicate between an AIR application and a SWF application running in a browser.

var lc = new air.LocalConnection(); 
lc.connect("connectionName"); 
var clientObject = new Object(); 
clientObject.echoMsg = function(msg) { 
    air.trace("This message was received: " + msg); 
} 
lc.client = clientObject;

This code first creates a LocalConnection object named lc and sets the client property to an object, clientObject . When another application calls a method in this LocalConnection instance, the runtime looks for that method in the clientObject object.

If you already have a connection with the specified name, an Argument Error exception is thrown, indicating that the connection attempt failed because the object is already connected.

connection.connect("conn1");

sendingConnection.send("conn1", "doQuit");

This code connects to an existing LocalConnection object with the connection name conn1 and invokes the doMessage() method in the remote application. If you want to send parameters to the remote application, you specify additional arguments after the method name in the send() method, as the following snippet shows:

sendingConnection.send("conn1", "doMessage", "Hello world");

To allow communications only from specific domains, you call the allowDomain() or allowInsecureDomain() method of the LocalConnection class and pass a list of one or more domains that are allowed to access this LocalConnection object, passing one or more names of domains to be allowed.

There are two special values that you can pass to the LocalConnection.allowDomain() and LocalConnection.allowInsecureDomain() methods: * and localhost . The asterisk value (*) allows access from all domains. The string localhost allows calls to the application from content locally installed, but outside of the application resource directory.

If the LocalConnection.send() method attempts to communicate with an application from a security sandbox to which the calling code does not have access, a securityError event( SecurityErrorEvent.SECURITY_ERROR ) is dispatched. To work around this error, you can specify the caller's domain in the receiver's LocalConnection.allowDomain() method.

If you implement communication only between content in the same domain, you can specify a connectionName parameter that does not begin with an underscore ( _ ) and does not specify a domain name (for example, myDomain:connectionName ). Use the same string in the LocalConnection.connect(connectionName) command.

If you implement communication between content in different domains, you specify a connectionName parameter that begins with an underscore. Specifying the underscore makes the content with the receiving LocalConnection object more portable between domains. Here are the two possible cases:

• If the string for connectionName does not begin with an underscore, the runtime adds a prefix with the superdomain name and a colon (for example, myDomain:connectionName ). Although this ensures that your connection does not conflict with connections of the same name from other domains, any sending LocalConnection objects must specify this superdomain (for example, myDomain:connectionName ). If you move the HTML or SWF file with the receiving LocalConnection object to another domain, the runtime changes the prefix to reflect the new superdomain (for example, anotherDomain:connectionName ). All sending LocalConnection objects have to be manually edited to point to the new superdomain.

• If the string for connectionName begins with an underscore (for example, _connectionName ), the runtime does not add a prefix to the string. This means the receiving and sending LocalConnection objects use identical strings for connectionName . If the receiving object uses LocalConnection.allowDomain() to specify that connections from any domain will be accepted, you can move the HTML or SWF file with the receiving LocalConnection object to another domain without altering any sending LocalConnection objects.

  A downside to using underscore names in connectionName is the potential for collisions, such as when two applications both try to connect using the same connectionName . A second, related downside is security-related. Connection names that use underscore syntax do not identify the domain of the listening application. For these reasons, domain-qualified names are preferred.