LocalConnection objects can communicate only among AIR applications and SWF files that are running on the same client computer, but they 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 won’t 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 Adobe AIR Language Reference .

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 AIR applications and Adobe® Flash® Player (SWF) applications running in a browser.

The following code defines a LocalConnection object that acts as a server and accepts incoming LocalConnection calls from other applications:

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, AIR looks for that method in the clientObject object.

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

The following snippet demonstrates how to create a LocalConnection with the name conn1:

connection.connect("conn1");

Connecting to the primary application from a secondary application requires that you first create a LocalConnection object in the sending LocalConnection object, and then call the LocalConnection.send() method with the name of the connection and the name of the method to execute. For example, to connect to the LocalConnection object that you created earlier, use the following code:

sendingConnection.send("conn1", "echoMsg", "Bonjour.");

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.

  For content running in the AIR application security sandbox (content installed with the AIR application), in place of the domain used by SWF content running in the browser, AIR uses the string app# followed by the application ID for the AIR application (defined in the application descriptor file), followed by a dot (.) character, followed by the publisher ID for the application. For example, a connectionName for an application with the application ID com.example.air.MyApp and the publisher ID B146A943FBD637B68C334022D304CEA226D129B4 resolves to "app#com.example.air.MyApp.B146A943FBD637B68C334022D304CEA226D129B4:connectionName". (For more information, see Defining the application identity and Getting the application and publisher identifiers.)

  When you allow another AIR application to communicate with your application through the local connection, you must call the allowDomain() of the LocalConnection object, passing in the local connection domain name. For an AIR application, this domain name is formed from the application and publisher IDs in the same fashion as the connection string. For example, if the sending AIR application has an application ID of com.example.air.FriendlyApp and a publisher ID of 214649436BD677B62C33D02233043EA236D13934, then the domain string that you would use to allow this application to connect is: app#com.example.air.FriendlyApp.214649436BD677B62C33D02233043EA236D13934.

  Note: When you run your application with ADL (or with a development tool such as Flash CS3, Flex Builder, or Dreamweaver), the publisher ID is null and must be omitted from the domain string. When you install and run your application, the publisher ID must be included in the domain string. You can assign a temporary publisher ID using the ADL command line arguments. Use a temporary publisher ID to test that the connection string and domain name are properly formatted.