Note: The SystemUpdater API is supported on desktop platforms.
This class contains static constants that are used with the
Use the values defined by the TouchscreenType class with the
Application domains are used when an external SWF file is loaded through the Loader class.
All ActionScript 3.0 definitions in the loaded SWF file are stored in the application
domain, which is specified by the
All code in a SWF file is defined to exist in an application domain. The current application domain is where your main application runs. The system domain contains all application domains, including the current domain, which means that it contains all Flash Player classes.
Every application domain, except the system domain, has an associated parent domain. The parent domain of your main application's application domain is the system domain. Loaded classes are defined only when their parent doesn't already define them. You cannot override a loaded class definition with a newer definition.
For usage examples of application domains, see the ActionScript 3.0 Developer's Guide.
The
Notes:
Begin by creating the RuntimeClasses.swf file from the following code:
Then implement the following code:
Notes:
Create a Greeter.as file in the "en" directory with the following code:
Then create a very similar Greeter.as file in the "es" directory:
Compile SWF files for both and then implement the following code:
In Flash Professional, specifying "~~" is the only way to allow access to nonlocal SWF files from local SWF files that have been published using Access Network Only for the Local Playback Security option in the Flash authoring tool.
Note:
The wildcard value does not work for subdomains. For example, you cannot use
Note: Calling this method from code in the AIR application sandbox throws a SecurityError exception. Content outside of the application security domain cannot directly cross-script content in the application sandbox. However, content outside of the application sandbox can communicate with content in the application security sandbox using a sandbox bridge.
If two SWF files are served from the same domain — for example, http://mysite.com/swfA.swf and http://mysite.com/swfB.swf — then swfA.swf can examine and modify variables, objects, properties, methods, and so on in swfB.swf, and swfB.swf can do the same for swfA.swf. This is called cross-movie scripting or cross-scripting.
If two SWF files are served from different domains — for example, http://siteA.com/swfA.swf and
http://siteB.com/siteB.swf — then, by default, Flash Player does not allow swfA.swf to script
swfB.swf, nor swfB.swf to script swfA.swf. A SWF file gives permission to SWF files from other domains
by calling
In any cross-domain situation, it is important to be clear about the two parties involved. For the purposes of this discussion, the side performing the cross-scripting is called the accessing party (usually the accessing SWF), and the other side is called the party being accessed (usually the SWF file being accessed). When siteA.swf scripts siteB.swf, siteA.swf is the accessing party, and siteB.swf is the party being accessed.
Cross-domain permissions that are established with
In addition to protecting SWF files from cross-domain scripting originated by other SWF files, Flash Player
protects SWF files from cross-domain scripting originated by HTML files. HTML-to-SWF scripting can
occur with older browser functions such as
Specifying an IP address as a parameter to
Version-specific differences
Flash Player's cross-domain security rules have evolved from version to version. The following table summarizes the differences.
The versions that control the behavior of Flash Player are SWF versions
(the published version of a SWF file), not the version of Flash Player itself.
For example, when Flash Player 8 is playing a SWF file published for version 7, it
applies behavior that is consistent with version 7. This practice ensures that player upgrades do not
change the behavior of
The version column in the previous table shows the latest SWF version involved in a cross-scripting operation. Flash Player determines its behavior according to either the accessing SWF file's version or the version of the SWF file that is being accessed, whichever is later.
The following paragraphs provide more detail about Flash Player security changes involving
Version 5. There are no cross-domain scripting restrictions.
Version 6. Cross-domain scripting security is introduced. By default, Flash Player forbids
cross-domain scripting;
Version 7. Superdomain matching is changed to exact domain matching. Two files are
permitted to script each other only if the host names in their URLs are identical; otherwise, a call to
Version 8. There are two major areas of change:
Occasionally, you may encounter the following situation: You load a child SWF file from a different domain and want to allow the child SWF file to script the parent SWF file, but you don't know the final domain of the child SWF file. This can happen, for example, when you use load-balancing redirects or third-party servers.
In this situation, you can use the
Make sure that you wait until the child SWF file begins loading to get the correct
value of the
The opposite situation can also occur; that is, you might create a child SWF file
that wants to allow its parent to script it, but doesn't know what the domain of its parent
will be. In this situation, you can access the
If you are publishing for Flash Player 8 or later, you can also handle these situations by calling
For more information related to security, see the Flash Player Developer Center Topic:
Specifying "~~" is the only way to allow access to nonlocal SWF files from local SWF files that have been published using the Access Network Only option for the Local Playback Security setting (File > Publish Settings > Flash tab) in the Flash authoring tool.
Note:
The wildcard value does not work for subdomains. For example, you cannot use
Flash Player provides
Note: Calling this method from code in the AIR application sandbox throws a SecurityError exception. Content outside of the application security domain cannot directly cross-script content in the application sandbox. However, content outside of the application sandbox can communicate with content in the application security sandbox using a sandbox bridge.
This method works in the same way as
Use
Note that the following information is only one possible scenario, designed to
help you understand
Suppose you are building an e-commerce site that consists of two components: a catalog, which does not need to be secure, because it contains only public information; and a shopping cart/checkout component, which must be secure to protect users' financial and personal information. Suppose you are considering serving the catalog from http://mysite.com/catalog.swf and the cart from https://mysite.com/cart.swf. One requirement for your site is that a third party should not be able to steal your users' credit card numbers by taking advantage of a weakness in your security architecture.
Suppose that a middle-party attacker intervenes between your server and your users, attempting to steal the credit card numbers that your users enter into your shopping cart application. A middle party might, for example, be an unscrupulous ISP used by some of your users, or a malicious administrator at a user's workplace — anyone who has the ability to view or alter network packets transmitted over the public Internet between your users and your servers. This situation is not uncommon.
If cart.swf uses HTTPS to transmit credit card information to your servers, then the middle-party attacker can't directly steal this information from network packets, because the HTTPS transmission is encrypted. However, the attacker can use a different technique: altering the contents of one of your SWF files as it is delivered to the user, replacing your SWF file with an altered version that transmits the user's information to a different server, owned by the attacker.
The HTTPS protocol, among other things, prevents this "modification" attack from working, because, in addition to being encrypted, HTTPS transmissions are tamper-resistant. If a middle-party attacker alters a packet, the receiving side detects the alteration and discards the packet. So the attacker in this situation can't alter cart.swf, because it is delivered over HTTPS.
However, suppose that you want to allow buttons in catalog.swf, served over HTTP,
to add items to the shopping cart in cart.swf, served over HTTPS. To accomplish this,
cart.swf calls
Obviously, this implementation is not desired, but you still want to allow
cross-scripting between the two SWF files on your site. Here are two possible ways to redesign
this hypothetical e-commerce site to avoid
Web browsers have enforced separation between HTTPS and non-HTTPS files for years, and the scenario described illustrates one good reason for this restriction. Flash Player gives you the ability to work around this security restriction when you absolutely must, but be sure to consider the consequences carefully before doing so.
For more information related to security, see the Flash Player Developer Center Topic:
With
This causes Flash Player or AIR to attempt to retrieve a policy file from the specified URL. Any permissions granted by the policy file at that location will apply to all content at the same level or lower in the virtual directory hierarchy of the server.
For example, following the previous code, these lines do not throw an exception:
However, the following code does throw a security exception:
You can use
When checking for a master policy file, Flash Player waits three seconds for a server response.
If a response isn't received, Flash Player assumes that no master policy file exists.
However, there is no default timeout value for calls to
You cannot connect to commonly reserved ports. For a complete list of blocked ports, see "Restricting Networking APIs" in the ActionScript 3.0 Developer's Guide.
Using the
This causes Flash Player or AIR to attempt to retrieve a policy file from the specified host and port.
Upon establishing a connection with the
specified port, Flash Player or AIR transmits
You can prevent a SWF file from using this method by setting the
For more information related to security, see the Flash Player Developer Center Topic:
In Flash Player 6, the domain used for these player settings was based on the trailing portion of the domain of the SWF file. If the domain of a SWF file includes more than two segments, such as www.example.com, the first segment of the domain ("www") is removed, and the remaining portion of the domain is used: example.com. So, in Flash Player 6, www.example.com and store.example.com both use example.com as the domain for these settings. Similarly, www.example.co.uk and store.example.co.uk both use example.co.uk as the domain for these settings. In Flash Player 7 and later, player settings are chosen by default according to a SWF file's exact domain; for example, a SWF file from www.example.com would use the player settings for www.example.com, and a SWF file from store.example.com would use the separate player settings for store.example.com.
When
If you previously published a version 6 SWF file and
created persistent shared objects from it, and you now need to
retrieve those persistent shared objects from that SWF file
after porting it to version 7 or later, or from a different SWF file of
version 7 or later, set
For more information related to security, see the Flash Player Developer Center Topic:
When loading SWF files with the
When loading a SWF file with the
When loading images (JPEG, GIF, or PNG) instead of SWF files, there is no need to
specify a SecurityDomain or an application domain, because those concepts are
meaningful only for SWF files. Instead, you have only one decision to make: do you need
programmatic access to the pixels of the loaded image? If so, see the
Note: Content in the air application security sandbox cannot load content from other sandboxes into its SecurityDomain.
This property is useful when you want to import image content into your sandbox - for example, when you want to replicate or process an image from a different domain - but you don't want to take the security risk of receiving a SWF file when you expected only an image file. Since SWF files may contain ActionScript code, importing a SWF file is a much riskier operation than importing an image file.
In AIR content in the application sandbox, the default value is
The
Every security domain is divided into one or more application domains, represented by ApplicationDomain objects. Application domains are not for security purposes; they are for managing cooperating units of ActionScript code. If you are loading a SWF file from another domain, and allowing it to be placed in a separate security domain, then you cannot control the choice of application domain into which the loaded SWF file is placed; and if you have specified a choice of application domain, it will be ignored. However, if you are loading a SWF file into your own security domain — either because the SWF file comes from your own domain, or because you are importing it into your security domain — then you can control the choice of application domain for the loaded SWF file.
You can pass an application domain only from your own security domain in
You have four choices for what kind of
When a load is complete, either side (loading or loaded) may need to find its own
ApplicationDomain, or the other side's ApplicationDomain, for the purpose of calling
For more information, see the "ApplicationDomain class" section of the "Client System Environment" chapter of the ActionScript 3.0 Developer's Guide.
Set this flag to
When you call the
If you set
If you set
If you will not need pixel-level access to the image that you are loading, you should not set the
Also try to avoid setting
Be careful with
You do not need to set this property for AIR content running in the application sandbox. Content
in the AIR application sandbox can call the
Under the default policy,
Under the
Under both policies, the runtime uses the same cache and flush behavior after the image is decoded. The runtime can flush the decoded data at any time and re-decode the image the next time it is required.
Normally, the value of the
The intent of this API is to enable the loading SWF file to forward its parameters to a loaded SWF file.
This functionality is especially helpful when you use the
For example, consider the following URL:
The following code uses the LoaderContext.parameters property to replicate a parameter passed to this URL:
import flash.system.LoaderContext; import flash.display.Loader; var l:Loader = new Loader(); var lc:LoaderContext = new LoaderContext; lc.parameters = { "foo": "bar" }; l.load(new URLRequest("child.swf"), lc);
To verify that the parameter passed properly, use the following trace statement after you run this code:
If the content loaded successfully, this trace prints "bar".
When content is completely loaded, the Loader object normally becomes the parent of the content.
If
If the loaded content is an AVM1Movie object, or if an
error is thrown when
If the requested parent and the loaded content are in different security sandboxes, and if the requested parent does not have access to the loaded content, then the following actions occur:
The following code uses
import flash.system.LoaderContext; import flash.display.Loader; import flash.display.Sprite; var lc:LoaderContext = new LoaderContext(); var l:Loader = new Loader(); var s:Sprite = new Sprite(); lc.requestedContentParent = s; addChild(s); l.load(new URLRequest("child.swf"), lc);
When this code runs, the child SWF file appears on stage. This fact confirms that the Sprite object you added to the stage is the parent of the loaded child.swf file.
The choice of security domain is meaningful only if you are loading a SWF file that might
come from a different domain (a different server) than the loading SWF file. When you load a
SWF file from your own domain, it is always placed into your security domain. But when you
load a SWF file from a different domain, you have two options. You can allow the loaded SWF file to
be placed in its "natural" security domain, which is different from that of the
loading SWF file; this is the default. The other option is to specify that you want to place the
loaded SWF file placed into the same security domain as the loading SWF file, by setting
You can pass your own security domain only in
Content in the AIR application security sandbox cannot load content from other sandboxes into its SecurityDomain.
For more information, see the "Security" chapter in the ActionScript 3.0 Developer's Guide.
Specifies whether you can use a
In AIR content in the application sandbox, the default value is
The JPEGLoaderContext class extends the LoaderContext class. Set the
However, some capabilities of Adobe AIR are not listed as properties in the Capabilities class. They are properties of other classes:
Do not use
You can send capabilities information, which is stored in the
A=t&SA=t&SV=t&EV=t&MP3=t&AE=t&VE=t&ACC=f&PR=t&SP=t& SB=f&DEB=t&V=WIN%209%2C0%2C0%2C0&M=Adobe%20Windows& R=1600x1200&DP=72&COL=color&AR=1.0&OS=Windows%20XP& L=en&PT=External&AVD=f&LFD=f&WD=f&IME=t
The following table lists the properties of the Capabilities class and corresponding server strings:
There is also a
All properties of the Capabilities class are read-only.
For content in Adobe AIR™, this property applies only to content in security sandboxes other than the application security sandbox. Content in the application security sandbox can always access the user's camera and microphone.
trace(Capabilities.cpuArchitecture);
Operating systems differ in region information returned in locale strings. One operating system
may return
The first entry in the returned array generally has the same primary language ID
as the
The server string is
On English systems, this property returns only the language code (
Note: The value of
The server string is
The
Reading runtime shared libraries is also blocked
if this property is set to
The server string is
Do not use
The server string is
The server string is
Do not use
The server string is
The following example shows a URL-encoded string:
A=t&SA=t&SV=t&EV=t&MP3=t&AE=t&VE=t&ACC=f&PR=t&SP=t& SB=f&DEB=t&V=WIN%208%2C5%2C0%2C208&M=Adobe%20Windows& R=1600x1200&DP=72&COL=color&AR=1.0&OS=Windows%20XP& L=en&PT=External&AVD=f&LFD=f&WD=f
trace(Capabilities.supports32BitProcesses);
trace(Capabilities.supports64BitProcesses);
WIN 9,0,0,0 // Flash Player 9 for Windows MAC 7,0,25,0 // Flash Player 7 for Macintosh LNX 9,0,115,0 // Flash Player 9 for Linux AND 10,2,150,0 // Flash Player 10 for Android
Do not use
The server string is
In the following example, the fscommand()
function sets Flash Player to
scale the SWF file to the full monitor screen size when the fullscreen_btn
button or
unfullscreen_btn
is released:
this.fullscreen_btn.onRelease = function() { fscommand("fullscreen", true); }; this.unfullscreen_btn.onRelease = function() { fscommand("fullscreen", false); };
The following example uses the fscommand()
function applied to a button in Flash to
open a JavaScript message box in an HTML page. The message itself is sent to JavaScript as the
fscommand
parameter.
You must add a function to the HTML page that contains the SWF file. This function,
myDocument
_DoFSCommand
, sits in the HTML page and waits for an
fscommand()
function in Flash. When an fscommand
is triggered in Flash
(for example, when a user presses the button), the command
and args
strings
are passed to the myDocument
_DoFSCommand
function. You can use the
passed strings in your JavaScript or VBScript code in any way you like. In this example, the function
contains a conditional if
statement that checks to see if the command string is
"messagebox
". If it is, a JavaScript alert box (or "message box") opens
and displays the contents of the args
string.
function myDocument_DoFSCommand(command, args) { if (command == "messagebox") { alert(args); }
In the Flash document, add the fscommand()
function to a button:
fscommand("messagebox", "This is a message box called from within Flash.")
You can also use expressions for the fscommand()
function and parameters, as in the
following example:
fscommand("messagebox", "Hello, " + name + ", welcome to our website!")
To test the SWF file, select File > Publish Preview > HTML.
Note: If you publish your SWF file using the Flash with FSCommand template in the
HTML
tab of the Publish Settings dialog box, the myDocument_DoFSCommand
function is inserted
automatically. The SWF file's NAME
and ID
attributes will be the filename.
For example, for the file myDocument.fla, the attributes would be set to myDocument
.
The
You can prevent a SWF file from using this method by setting the
The
For more information related to security, see the Flash Player Developer Center Topic:
Usage 1: To use
Not all of the commands listed in the table are available in all applications:
The
Usage 2: To use
In a web browser,
In the web page that contains the SWF file, set the
In Flash Player 10 and later running in a browser, using this method programmatically to open a pop-up window may not be successful. Various browsers (and browser configurations) may block pop-up windows at any time; it is not possible to guarantee any pop-up window will appear. However, for the best chance of success, use this method to open a pop-up window only in code that executes as a direct result of a user action (for example, in an event handler for a mouse click or key-press event.)
Usage 3: The
Usage 4: In VisualBasic, Visual C++, and other programs that can host ActiveX controls,
Note: The ExternalInterface class provides better functionality
for communication between JavaScript and ActionScript (Usage 2) and between ActionScript and VisualBasic, Visual C++, or other
programs that can host ActiveX controls (Usage 4). You should continue to use
Note: this example should be executed in the standalone Flash Player and not within a web browser.
AIR profile support: This feature is supported
on desktop operating systems, but it is not supported on all mobile devices. It is also not supported on
AIR for TV devices. You can test for support at run time using the
IMEs let users type non-ASCII text characters in multibyte languages such as Chinese, Japanese, and Korean. For more information on working with IMEs, see the documentation for the operating system for which you are developing applications. For additional resources, see the following websites:
If an IME is not active on the user's computer, calls to IME methods or properties,
other than
The following table shows the platform coverage of this class:
~~ Not all Windows IMEs support all of these operations. The only IME that supports them all is the Japanese IME.
~~~~ On the Macintosh, only the Japanese IME supports these methods, and third-party IMEs do not support them.
The ActionScript 3.0 version of this class does not support Macintosh Classic.
If no text field has focus, this method fails and throws an error.
Additional properties and methods are in other classes within the flash.system package:
the Capabilities class,
This class contains only static methods and properties. You cannot create new instances of the System class.
For the standalone Flash Player debugger version only.
AIR applications should call the
For the Flash Player debugger version or the AIR Debug Launcher (ADL) only.
For the Flash Player debugger version or the AIR Debug Launcher (ADL) only.
This method is provided for SWF content running in Flash Player 9. It allows only adding String content to the Clipboard.
Flash Player 10 content and content in the application security sandbox in an AIR application can call
the
AIR developers should use this property to determine the entire memory consumption of an application.
For Flash Player, this includes the memory used by the container application, such as the web browser.
This property is expressed as a Number, which allows higher values than the
This property does not return all memory used by an Adobe AIR application
This property does not return all memory used by an Adobe AIR application
If the amount of memory allocated is greater than the maximum value for a uint object (
Text that you load as an external file (using
If you load external text files that are not Unicode-encoded, set
System.useCodePage = true;
When this code is present, the application interprets external text using the traditional code page of the operating system. For example, this is generally CP1252 for an English Windows operating system and Shift-JIS for a Japanese operating system.
If you set
To ensure that users on all platforms can view external text files used in your
application, you should encode all external text files as Unicode and leave
Flash Player identifies the need for a Flash-Access-module update by dispatching a NetStatusEvent event.
The event has a
Flash Player identifies the need for a player update by dispatching a StatusEvent event, with several
possible
Note: The SystemUpdater API is supported on all desktop platforms.
After the update begins, listen for the events defined in this class. The following events
events indicate the end of an update and allow a new update or update attempt to proceed,
as does calling the