Flash

ActionScript 2 / Last updating 27.09.2007

asLocalConnect 0.4 is a ActionScript 3 extension / replacement for the standart LocalConnection.
Its support a lot of more features and is also interesting for beginners, because is is very easy to make and use a LocalConnction.

Please Keep in Mind that english is not my native language, so i try my best to make a clear documentation in english.
When you find errors or something like that, please send me a short email what i can change or which part is mistakable.

Content

The normal LocalConnect have a lot of hurdles and obstacles, for e.g: when the flashfile is deliver from serveral server or a loadbalancer the localconnect dont worked in internet explorer.
For this behavoir there some solution, but not solution which cover all needs and so asLocalConnect is originated.
The goal of this, is to support the normal LocalConnection features and add some additional Features to cover all the needs.

Differenz between LocalConnection and asLocalConnect

Disadvantages of LocalConnection

Advantages of asLocalConnect

The License for asLocalConnect is the BSD License, the License for the examples / documentation is the Creative Commons (by-sa) License. Please also check http://sourceforge.net/projects/aslocalconnect for more Informations.

asLocalConnect is hosted on SourceForge on this page you can also download the lasted version and transmit errors and improvments.

asLocalConnect is a flash component, which need to copy to the right folder.
On Windows, navigate to the following location, replacing the term [username] with the login name for your computer:
C:\Documents and Settings\[username]\Local Settings\Application Data\Macromedia\[Flash 8|Flash MX 2004]\[en|de]\Configuration\Components\

On a Macintosh, go to the following location, replacing the term [username] with your login name, and [System Disk] with the name of your system hard drive (i.e. Macintosh HD):
[System Disk]: Users: [username]: Library: Application Support: Macromedia: [Flash 8 |Flash MX 2004]: [en|de]: Configuration: Components

In this location you can simple create a new folder like "asLocalConnect" and place a copy of the asLocalConnect*.swc file in this new folder.

When you now restart the Flash Editor, you should see a new grouping called "Custom Components" under the Components window (STRG+F7).
Inside of this grouping, you will see the folder "asLocalConnect" and a component named "asLocalConnect*"

You can simple used asLocalConnent when you move this "asLocalConnect" Icon from the Components window to your Library panel.

This example shows a LocalConnection which asLocalConnection an Heartbeat support.

Define Receiver

In this example the Name of the LocalConnection is "FlashB" and it will start a "trace" when something execute the function "test" over LocalConnection.
Its also start the heartbeat with the LocalConnection named "FlashA", so that "FlashA" know when "FlashB" is ready.

Define Transmitter

This LocalConnection has the Name "FlashA" and when both Flashfiles are ready it will send the string "Hello World" to "FlashB".
The last entry start the heartbeat with "FlashB" in the example before.

2 Flashfiles which exchange data with asLocalConnect and Heartbeat

This example should show the different events which are possible with asLocalConnect.
The event-handler "onLoad" and "onUnload" make it possible to tell the flashfile which should done when the LocalConnection is complett or when it is lost.

Please open Example A and Example B in any order, this example can be also open in different browsers on the same computer.
When both Examples are open and the LocalConnection is ready there will be display a Input and a Textbox where you can transmit text over LocalConnection.
Immediately after the LocalConnection is lost, the Input and the Textbox will be hidden again.

ActionScript Code

The actionscript code is only different in the localconnection name and the named to which localconnection the text should be send.

Instanzname and Objectes:
asLocalConnect Name = FlashA
lc_flasha = asLocalConnect Objekt
text = TextInput
txt = TextArea
Submit = Button
a and b = Text above TextInput and TextArea

Instanzname and Objectes:
asLocalConnect Name = FlashB
lc_flashb = asLocalConnect Objekt
text = TextInput
txt = TextArea
Submit = Button
a and b = Text above TextInput and TextArea

Synchronistation with 9 flashfiles and broadcast function

In this example 9 flashfile will be load and try to make a localconnection between each flashfile.
There is a master flashfile which used the "broadcast" function and send the request to increase the counter to the other flashfiles.
The master flashfile is the green counter, the slaves flashfiles are the red counters.

ActionScript Code

The master makes a heartbeat with all other slaves and when all are ready it will send the broadcast request.
When you open the same page in a additional browserwindow you will see that the flashfile dont interrupt them self.

This is the actionscript code for the first slave file, the other slaves has the samecode except the asLocalConnect name and the heartbeat list.

Integration in existing projects or flashfiles

asLocalConnect is not compatible with LocalConnection kompatible, but it is simple to used some of the feature in existings projects or flashfiles and dont touch the old code.
The most problems which LocalConnection occurr because the timing of localconnection is not good enougt to make a localconnection possible.
For this problem you can simple add an first empty frame and add in this frame asLocalConnect with the heartbeat function and when asLocalConnect found all LocalConnection, go to Frame 2 which the orginal code and the other normal LocalConnection.
You can also tell asLocalConnect when it lose the connection with the other flashfile, go back to frame 1 and wait.

The follow example so how you can make sure with asLocalConnect that both flashfiles are availible and begin to started the animation.
Its importen to make this in the flashfile which include the normal LocalConnection.
When you used parents and childs flashfiles, make sure to put this in the right parent and/or childes.
It has no sense to put this in the parent flashfile when only the childes make a LocalConnection.

ActionScript Code

asLocalConnect make a heartbeat with "flashb", when both files a ready they will go to frame 2.
You can also use additional commands or different framenummers / framenames.

This is not realy differnt from the above example, its only used the LocalConnection name "flashb" and make the heartbeat with "flasha". Please keep in mind that you should not used asLocalConnect as a preloader, because most of the feature are not supportet at this way.
For e.g: with asLocalConnect you can open the same flashfiles 10 times, without that the flashfiles interrupt themself.
With the normal LocalConnection the flashfiles are interrupt themself so that only the first open flashfiles will worked.

This is a detail overview, which show all functions, events and constructors of asLocalConnect.
Below this there are more details information for each function, event and constructor.

Overview over constructors

Overview over functions

Overview over Events

asLocalConnect(connectionName:String)

This will make the asLocalConnect object and assign it to a variable, this is needed to access this object later.
You can also pass the ConnectionName, when this is passed, the asLocalConnect object will automatic connect to this ConnectionName so there is not need to used connect.

In this example the LocalConnection Object with the Name "lc_Flash123" will created and it has the ConnectionName "Flash123".
Please attend that the ConnectionName need to be 4 characters and more, the ConnectionName will automatic add internal a "_" before the ConnectionName, so you dont need to pass the name with a "_". But when you pass the named with a "_" e.g: "_Flash123", asLocalConnect dectect this and can handel this as well.

connect(connectionName:String) : Boolean

With connect you set the connectionName for this connection, when you allready pass this connectionName, you dont need the connect command.
When you dont pass the connectionName, you can use connect to set up a connectionName for this connection.

This example is in the end the same as the above example, but the different is that here the object is first declare and after this the connection with the connectionName will be made.

listen(listnerName:String, functionName:Function) : Void

"listen" defined which listnerName will execute which functionName, this function will execute when a asLocalConnect Object send a request for the listnerName.

In this example trace('Hello World'); will be executed when a asLocalConnect Object send a request to Flash123 with the name hello or world.

allowDomain(domain:String) : Void

With "allowDomain" you defined which domains could communicate with the asLocalConnect object, for this is also relevate to used the right setSecurity option.
This function dont support wildchars, but you can used setSecurity to allow special parts of the domain.

In this example is the domain reifanhp.de and animearchive.de add to the AllowDomain list, flashfiles from this domain are allow to communicate with the flashfile in this example.

setSecurity(securityLevel:Number) : Void

In asLocalConnect there is a security modell, which resonds depends on the security level.

In this example flashfiles from the domain reifanhp.de and animearchive.de are allow to make a connection to this flashfile.
But connection from the same domain e.g: flash.area-network.de are not allowed and will be ignore.

send(connectionName:String, methodName:String, args:Object) : Boolean

Send data to the pass connectionName and methodName with the given args (arguments), the methodName is defined over the function listen.

In this example a request to Flash123 to execute the methode hello, this was defined in the listen example as a trace output with "Hello World".

broadcast(methodName:String, args:Object) : Boolean

Send data to all over heartbeat defined connections with the pass methodName and args (arguments), the methodName is defined over the function listen.

This is example is explainded in "Exented examples".

domain() : String

Return the domain as String.

This will return the Domain from the LocalConnection over trace.

heartbeat(connectionNames:Array) : Void

Add a heartbeat for the passed connectionNames, you should always used the heartbeat to make sure that all LocalConnections are ready.
The heartbeat use special timing to make this processor frienldy, to that the heartbeat has no impact on the CPU load.
A lot of method e.g: broadcast need the HeartBeat to worked correct.

In this example a HeartBeat with slave_1, slave_2, slave_3, slave_4, slave_5, slave_6 , slave_7, slave_8 is started, so the Master knows when all are ready or if someone lost the connection
Please keep in mind that every asLocalConnect Object should used a Heartbeat to the others asLocalConnect Objects, which are exchange data with this asLocalConnect Object.

heartbeatstatus(connectionName:String) : Boolean

Return the current status for the passed connectionName. When no connectionName is passed, the status for all connectionNames will returned.

In this example the status will be return as trace and as return value.

info() : Void

This start a "trace" output with the LocalConnection Name, LocalConnection Channel and the Status of this Connection. The status means if this Object is connect to a LocalConnection Name.

The channel is used to make sure that serveral flashfile with the same connectionName dont interrupt them self.

close() : Void

Ended the LocalConnection and if need the Heartbeat.

In this example the connection with the name Master was ended.

The events are the essential part of asLocalConnect, with the help of the events is it possible to control the flashfiles. How they should act when all asLocalConnection objects are ready or when a connection is lost.

onLoad(onLoad_function:Function) : Void

This event will be called when all connection defined over heartbeat are ready and avalible
. You should used this to execute commands when all objects are ready, e.g: start a animation .

When FlashB is ready, FlashA will execute the function show_ff(true) and send "Hello World" to FlashB, its also set the variable status to "Connected".

onUnload(onUnload_function:Function) : Void

This event will be called when a connection is lost after a successfull connection.
So you can very easy detect when the other flashfile was closed.

If FlashA lost the connection to FlashB, the function show_ff(false) will be executed and the variable status will set to "Disconnected".

onHeartBeat(HeartBeat_function:Function) : Void

This event will be called on every heartbeat, how often a heartbeat will send depends on the amount of the supervising asLocalConnect objects.
You can restart a movieclip to display the heartbeat graphically.

This example restart the movieclip Bumper on every heartbeat.