The LocalConnection explained
The LocalConnection is a very powerfull way to have multiple Flash player instances exchange complex data.
LocalConnection class definition in the Actionscript dictionary:
“The LocalConnection object lets you develop Flash movies (SWFs) that can send instructions to each other without the use of FSCommand or JavaScript. LocalConnection objects can communicate only between movies that are running on the same client machine, but they can be running in two different applications—for example, a Flash movie running in a browser and a Flash movie running in a projector.”
You might wonder: only between Flash movies?
Having Flash movies and applications communicate through LocalConnections would be much more powerfull than the limited fscommand/setvariable interface: you wouldn’t be limited to exchanging strings but any AMF datatype (string, number, array, object, etc). This isn’t even against Macromedia interests to document how the LocalConnection works so hopefully we will have a complete, cross platform documentation here.
The Win32 implementation
Notes:
- the LocalConnection is very OS-dependent but it should be similar for the Linux and Mac systems. Feel free to describe other implementations.
- these information & code samples work with Flash 6, 7 and 8 SWFs.
- these observations and sample codes may not be a very reliable source for you own developments!
Spying Flash
So I made a dummy SWF which calls some dummy method from a dummy LocalConnection.
To know what’s going on when the LocalConnection is created, you can use some tool to spy the Flash player. I used the great and free Systernal's ProcessExplorer.
The Process Explorer shows us all the kernel objects owned by SAFlashPlayer.exe. We can see two new items that where not here before the creation of the LocalConnection:
| Type | Name |
|---|---|
| Section | \BaseNamedObject\MacromediaFMOmega |
| Mutant | \BaseNamedObject\MacromediaMutexOmega |
What does that mean?
It means that Macromedia simply uses the most common and reliable way to exchange data between process.
- MacromediaFMOmega is the name of a File Mapping object. It is a memory file that can be shared by several processes (i.e. applications, plug-ins, etc.),
- MacromediaMutexOmega is the name of a Mutex object. It’s role is to make sure that only one and only process will have access to the FileMapping.
How does it work
The good news is that any application that knows the name of a kernel object can have access to it. So technically, if you can call Win32 API functions, you will be able to fake a LocalConnection.
Listening
To create a listening LocalConnection, you just have to set a thread to:
- register the application as a valid LocalConnection listener,
- require the mutex to have exclusive access to the shared memory,
- access the shared memory and check the recipient,
- if you are the recipient, read the message and mark it read,
- release the shared memory and the mutex,
- repeat indefinitely from step 2.
Accessing the memory is the easy part. The tough part will be to “read the message” because the LocalConnection can be used to send complex data. These data are encoded as AMF data types, so you will have to check AMFPHP (PHP), AMF::Perl (Perl) or AMFPP (C++) sources to decode the messages.
Sending
To send a message to a LocalConnection apparently works like that:
- require the mutex to have exclusive access to the shared memory,
- access the shared memory and check that the listener is connected,
- if the recipient is registered, write the message,
- release the shared memory and the mutex.
The main thing you have to care about is the timestamp - simply call GetTickCount() - and the message size. If your message is correctly encoded, it should be received by the listening LocalConnection.
Memory format
Some facts:
- The header is 16 bytes,
- The message can be up to 40Ko,
- The listeners block starts at 40Ko+16 = 40976 bytes,
- To add a listener, simply append its name in the listeners list (null terminated strings)
| HEADER | |
|---|---|
| unsigned long | unknown |
| unsigned long | unknown |
| unsigned long | timestamp1) |
| unsigned long | message size |
| MESSAGE | |
| AMF string | connection name |
| AMF string | protocol |
| AMF string | method name |
| any AMF type | message data |
| ... | |
| LISTENERS | |
| string | connection name |
| ... | |
For more detailed AMF format info look here:
http://vanrijkom.org/archives/2005/06/amf_format.html
Sample applications
License for the following sources: Public domain.
UPDATE 2007/05/31: bidirectional communication
This code sets a bidirectional local connection between an EXE file (ANSI C implementation) and a SWF. When the SWF sends a text message, the EXE sends a message back.
ARCHIVE: listener
Here is a sample ANSI C application which registers itself as a listening LocalConnection.
ARCHIVE: sender
Here is a sample ANSI C application which waits for a LocalConnection to register itself as a listening LocalConnection.