Package | flash.system |
Class | public class LoaderContext |
Inheritance | LoaderContext Object |
Subclasses | JPEGLoaderContext |
Language Version: | ActionScript 3.0 |
Runtime Versions: | AIR 1.0 Flash Player 9 |
context
parameter in the load()
and
loadBytes()
methods of the Loader class.
When loading SWF files with the Loader.load()
method, you have two decisions to make:
into which security domain the loaded SWF file should be placed, and into which application domain
within that security domain? For more details on these choices, see the
applicationDomain
and securityDomain
properties.
When loading a SWF file with the Loader.loadBytes()
method, you have the same
application domain choice to make as for Loader.load()
, but it's not
necessary to specify a security domain, because Loader.loadBytes()
always
places its loaded SWF file into the security domain of the loading SWF file.
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
checkPolicyFile
property. If you want to apply deblocking when loading
an image, use the JPEGLoaderContext class instead of the LoaderContext class.
See also
flash.display.Loader.loadBytes()
flash.system.ApplicationDomain
flash.system.JPEGLoaderContext
flash.system.LoaderContext.applicationDomain
flash.system.LoaderContext.checkPolicyFile
flash.system.LoaderContext.securityDomain
flash.system.SecurityDomain
Specifying a LoaderContext
Creating class instances from loaded applications
Property | Defined By | ||
---|---|---|---|
allowLoadBytesCodeExecution : Boolean = false
Specifies whether you can use the loadBytes() method of a Loader object
to load content with executable code, such as a SWF file. | LoaderContext | ||
applicationDomain : ApplicationDomain = null
Specifies the application domain to use for the Loader.load() or
Loader.loadBytes() method. | LoaderContext | ||
checkPolicyFile : Boolean = false
Specifies whether the application should attempt to download a URL policy file from the
loaded object's server before beginning to load the object itself. | LoaderContext | ||
constructor : Object
A reference to the class object or constructor function for a given object instance. | Object | ||
prototype : Object [static]
A reference to the prototype object of a class or function object. | Object | ||
securityDomain : SecurityDomain = null
Specifies the security domain to use for a Loader.load() operation. | LoaderContext |
Method | Defined By | ||
---|---|---|---|
LoaderContext(checkPolicyFile:Boolean = false, applicationDomain:ApplicationDomain = null, securityDomain:SecurityDomain = null)
Creates a new LoaderContext object, with the specified settings. | LoaderContext | ||
Indicates whether an object has a specified property defined. | Object | ||
Indicates whether an instance of the Object class is in the prototype chain of the object specified
as the parameter. | Object | ||
Indicates whether the specified property exists and is enumerable. | Object | ||
Sets the availability of a dynamic property for loop operations. | Object | ||
Returns the string representation of this object, formatted according to locale-specific conventions. | Object | ||
Returns the string representation of the specified object. | Object | ||
Returns the primitive value of the specified object. | Object |
allowLoadBytesCodeExecution | property |
public var allowLoadBytesCodeExecution:Boolean = false
Runtime Versions: | AIR 1.0 |
Specifies whether you can use the loadBytes()
method of a Loader object
to load content with executable code, such as a SWF file. With his property set to false
(the default), the loadBytes()
method is restricted to safe operations, such as loading images.
In AIR content in the application sandbox, the default value is false
. In non-application content, the
default value is true
.
Note: This API is likely to be replaced in a future release of AIR. When that occurs, you will need to be adjust code to use the new API and recompile before destributing an application for the new version of AIR.
See also
applicationDomain | property |
public var applicationDomain:ApplicationDomain = null
Language Version: | ActionScript 3.0 |
Runtime Versions: | AIR 1.0 Flash Player 9 |
Specifies the application domain to use for the Loader.load()
or
Loader.loadBytes()
method. Use this property only when loading a SWF file
written in ActionScript 3.0 (not an image or a SWF file written in ActionScript 1.0 or ActionScript 2.0).
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
LoaderContext.applicationDomain
. Attempting to pass an application domain
from any other security domain results in a SecurityError
exception.
You have four choices for what kind of ApplicationDomain
property to use:
- Child of loader's ApplicationDomain. The default. You can
explicitly represent this choice with the syntax
new ApplicationDomain(ApplicationDomain.currentDomain)
. This allows the loaded SWF file to use the parent's classes directly, for example by writingnew MyClassDefinedInParent()
. The parent, however, cannot use this syntax; if the parent wishes to use the child's classes, it must callApplicationDomain.getDefinition()
to retrieve them. The advantage of this choice is that, if the child defines a class with the same name as a class already defined by the parent, no error results; the child simply inherits the parent's definition of that class, and the child's conflicting definition goes unused unless either child or parent calls theApplicationDomain.getDefinition()
method to retrieve it. - Loader's own ApplicationDomain. You use this application domain when using
ApplicationDomain.currentDomain
. When the load is complete, parent and child can use each other's classes directly. If the child attempts to define a class with the same name as a class already defined by the parent, the parent class is used and the child class is ignored. - Child of the system ApplicationDomain. You use this application domain when using
new ApplicationDomain(null)
. This separates loader and loadee entirely, allowing them to define separate versions of classes with the same name without conflict or overshadowing. The only way either side sees the other's classes is by calling theApplicationDomain.getDefinition()
method. - Child of some other ApplicationDomain. Occasionally you may have
a more complex ApplicationDomain hierarchy. You can load a SWF file into any
ApplicationDomain from your own SecurityDomain. For example,
new ApplicationDomain(ApplicationDomain.currentDomain.parentDomain.parentDomain)
loads a SWF file into a new child of the current domain's parent's parent.
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
ApplicationDomain.getDefinition()
. Either side can retrieve a reference to
its own application domain by using ApplicationDomain.currentDomain
. The loading
SWF file can retrieve a reference to the loaded SWF file's ApplicationDomain via
Loader.contentLoaderInfo.applicationDomain
. If the loaded SWF file knows how it
was loaded, it can find its way to the loading SWF file's ApplicationDomain object. For example, if
the child was loaded in the default way, it can find the loading SWF file's application domain
by using ApplicationDomain.currentDomain.parentDomain
.
For more information, see the "ApplicationDomain class" section of the "Client System Environment" chapter of Programming ActionScript 3.0.
See also
checkPolicyFile | property |
public var checkPolicyFile:Boolean = false
Language Version: | ActionScript 3.0 |
Runtime Versions: | AIR 1.0 Flash Player 9 |
Specifies whether the application should attempt to download a URL policy file from the
loaded object's server before beginning to load the object itself. This flag is applicable to
the Loader.load()
method, but not to the Loader.loadBytes()
method.
Set this flag to true
when you are loading an image (JPEG, GIF, or PNG) from outside the calling
SWF file's own domain, and you expect to need access to the content of that image from ActionScript.
Examples of accessing image content include referencing the Loader.content
property
to obtain a Bitmap object, and calling the BitmapData.draw()
method to obtain a
copy of the loaded image's pixels. If you attempt one of these operations without having
specified checkPolicyFile
at loading time, you may get a SecurityError
exception because the needed policy file has not been downloaded yet.
When you call the Loader.load()
method with LoaderContext.checkPolicyFile
set to
true
, the application does not begin downloading the specified object in URLRequest.url
until it has either successfully downloaded a relevant URL policy file or discovered
that no such policy file exists. Flash Player or AIR first considers policy files that have already
been downloaded, then attempts to download any pending policy files specified in calls to
the Security.loadPolicyFile()
method, then attempts to download a policy file from the default
location that corresponds to URLRequest.url
, which is /crossdomain.xml
on the same server as URLRequest.url
. In all cases, the given policy file is required to exist
at URLRequest.url
by virtue of the policy file's location, and the file must permit access
by virtue of one or more <allow-access-from>
tags.
If you set checkPolicyFile
to true
, the main download that specified in the
Loader.load()
method does not load until the policy file has been completely processed.
Therefore, as long as the
policy file that you need exists, as soon as you have received any ProgressEvent.PROGRESS
or
Event.COMPLETE
events from the contentLoaderInfo
property of your Loader object,
the policy file download is complete, and you can safely begin performing operations that require
the policy file.
If you set checkPolicyFile
to true
, and no relevant policy file is found,
you will not receive any error indication until you attempt an operation that throws a
SecurityError
exception. However, once the LoaderInfo object dispatches a
ProgressEvent.PROGRESS
or Event.COMPLETE
event, you can test whether a relevant
policy file was found by checking the value of the LoaderInfo.childAllowsParent
property.
If you will not need pixel-level access to the image that you are loading, you should not set the
checkPolicyFile
property to true
. Checking for a policy file in this case is
wasteful, because it may delay the start of your download, and it may consume network bandwidth unnecessarily.
Also try to avoid setting checkPolicyFile
to true
if you are using the
Loader.load()
method to download a SWF file. This is because SWF-to-SWF permissions are not
controlled by policy files, but rather by the Security.allowDomain()
method, and thus
checkPolicyFile
has no effect when you load a SWF file. Checking for a policy file in
this case is wasteful, because it may delay the download of the SWF file, and it may consume
network bandwidth unnecessarily. (Flash Player or AIR cannot tell whether your main download will be a
SWF file or an image, because the policy file download occurs before the main download.)
Be careful with checkPolicyFile
if you are downloading an object from a URL that
may use server-side HTTP redirects. Policy files are always retrieved from the corresponding initial
URL that you specify in URLRequest.url
. If the final
object comes from a different URL because of HTTP redirects, then the initially downloaded policy
files might not be applicable to the object's final URL, which is the URL that matters in
security decisions. If you find yourself in this situation, you can examine the value of
LoaderInfo.url
after you have received a ProgressEvent.PROGRESS
or Event.COMPLETE
event, which tells you the object's final URL. Then call the
Security.loadPolicyFile()
method with a policy file URL based on the object's final
URL. Then poll the value of LoaderInfo.childAllowsParent
until it becomes true
.
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 BitmapData.draw()
method using any loaded image
content as the source.
See also
securityDomain | property |
public var securityDomain:SecurityDomain = null
Language Version: | ActionScript 3.0 |
Specifies the security domain to use for a Loader.load()
operation. Use this property
only when loading a SWF file (not an image).
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
myLoaderContext.securityDomain
to be equal to SecurityDomain.currentDomain
. This is
called import loading, and it is equivalent, for security purposes, to copying the
loaded SWF file to your own server and loading it from there. In order for import loading to
succeed, the loaded SWF file's server must have a policy file trusting the domain of the
loading SWF file.
You can pass your own security domain only in LoaderContext.securityDomain
.
Attempting to pass any other security domain results in a SecurityError
exception.
Content in the air application security sandbox cannot load content from other sandboxes into its SecurityDomain.
For more information, see the "Security" chapter in Programming ActionScript 3.0.
See also
LoaderContext | () | Constructor |
public function LoaderContext(checkPolicyFile:Boolean = false, applicationDomain:ApplicationDomain = null, securityDomain:SecurityDomain = null)
Language Version: | ActionScript 3.0 |
Runtime Versions: | AIR 1.0 Flash Player 9 |
Creates a new LoaderContext object, with the specified settings. For complete details on these settings, see the descriptions of the properties of this class.
ParameterscheckPolicyFile:Boolean (default = false ) — Specifies whether a check should be made for the existence
of a URL policy file before loading the object.
| |
applicationDomain:ApplicationDomain (default = null ) — Specifies the ApplicationDomain object to use for a Loader object.
| |
securityDomain:SecurityDomain (default = null ) — Specifies the SecurityDomain object to use for a Loader object.
Note: Content in the air application security sandbox cannot load content from other sandboxes into its SecurityDomain. |
See also
Fri Mar 19 2010, 02:45 AM -07:00