Packageflash.system
Classpublic class LoaderContext
InheritanceLoaderContext Inheritance Object
SubclassesJPEGLoaderContext

Language version: ActionScript 3.0
Runtime version: 

The LoaderContext class provides options for loading SWF files and other media by using the Loader class. The LoaderContext class is used as the 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.load()
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
flash.system.ImageDecodingPolicy


Public Properties
 PropertyDefined by
  allowCodeImport : Boolean
Specifies whether you can use a Loader object to import content with executable code, such as a SWF file, into the caller's security sandbox.
LoaderContext
  allowLoadBytesCodeExecution : Boolean
Legacy property, replaced by allowCodeImport, but still supported for compatibility.
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
 Inheritedconstructor : Object
A reference to the class object or constructor function for a given object instance.
Object
  imageDecodingPolicy : String
Specifies whether to decode bitmap image data when it is used or when it is loaded.
LoaderContext
  parameters : Object
An Object containing the parameters to pass to the LoaderInfo object of the content.
LoaderContext
 Inheritedprototype : Object
[static] A reference to the prototype object of a class or function object.
Object
  requestedContentParent : DisplayObjectContainer
The parent to which the Loader will attempt to add the loaded content.
LoaderContext
  securityDomain : SecurityDomain = null
Specifies the security domain to use for a Loader.load() operation.
LoaderContext
Public Methods
 MethodDefined by
  
LoaderContext(checkPolicyFile:Boolean = false, applicationDomain:ApplicationDomain = null, securityDomain:SecurityDomain = null)
Creates a new LoaderContext object, with the specified settings.
LoaderContext
 Inherited
Indicates whether an object has a specified property defined.
Object
 Inherited
Indicates whether an instance of the Object class is in the prototype chain of the object specified as the parameter.
Object
 Inherited
Indicates whether the specified property exists and is enumerable.
Object
 Inherited
Sets the availability of a dynamic property for loop operations.
Object
 Inherited
Returns the string representation of this object, formatted according to locale-specific conventions.
Object
 Inherited
Returns the string representation of the specified object.
Object
 Inherited
Returns the primitive value of the specified object.
Object
Property detail
allowCodeImportproperty
public var allowCodeImport:Boolean

Language version: ActionScript 3.0
Runtime version: AIR 2.0

Specifies whether you can use a Loader object to import content with executable code, such as a SWF file, into the caller's security sandbox. There are two affected importing operations: the Loader.loadBytes() method, and the Loader.load() method with LoaderContext.securityDomain = SecurityDomain.currentDomain. (The latter operation is not supported in the AIR application sandbox.) With the allowCodeImport property set to false, these importing operations are restricted to safe operations, such as loading images. Normal, non-importing SWF file loading with the Loader.load() method is not affected by the value of this property.

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 false. In non-application content (which includes all content in Flash Player), the default value is true.

The allowCodeImport property was added in Flash Player 10.1 and AIR 2.0. However, this property is made available to SWF files and AIR applications of all versions when the Flash Runtime supports it.

See also

allowLoadBytesCodeExecutionproperty 
allowLoadBytesCodeExecution:Boolean  [read-write]

Language version: ActionScript 3.0
Runtime version: AIR 1.0

Legacy property, replaced by allowCodeImport, but still supported for compatibility. Previously, the only operation affected by allowLoadBytesCodeExecution was the Loader.loadBytes() method, but as of Flash Player 10.1 and AIR 2.0, the import-loading operation of Loader.load() with LoaderContext.securityDomain = SecurityDomain.currentDomain is affected as well. (The latter operation is not supported in the AIR application sandbox.) This dual effect made the property name allowLoadBytesCodeExecution overly specific, so now allowCodeImport is the preferred property name. Setting either of allowCodeImport or allowLoadBytesCodeExecution will affect the value of both.

Specifies whether you can use a Loader object to import content with executable code, such as a SWF file, into the caller's security sandbox. With this property set to false, these importing operations are 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.

Implementation
    public function get allowLoadBytesCodeExecution():Boolean
    public function set allowLoadBytesCodeExecution(value:Boolean):void

See also

applicationDomainproperty 
public var applicationDomain:ApplicationDomain = null

Language version: ActionScript 3.0
Runtime version: 

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:

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 the ActionScript 3.0 Developer's Guide.

See also

checkPolicyFileproperty 
public var checkPolicyFile:Boolean = false

Language version: ActionScript 3.0
Runtime version: 

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

imageDecodingPolicyproperty 
public var imageDecodingPolicy:String

Language version: ActionScript 3.0
Runtime version: AIR 2.6

Specifies whether to decode bitmap image data when it is used or when it is loaded.

Under the default policy, ImageDecodingPolicy.ON_DEMAND, the runtime decodes the image data when the data is needed (for display or some other purpose). This policy maintains the decoding behavior used by previous versions of the runtime.

Under the ImageDecodingPolicy.ON_LOAD policy, the runtime decodes the image immediately after it is loaded and before dispatching the complete event. Decoding images on load rather than on demand can improve animation and user interface performance. You can see improvements when several loaded images are displayed in quick succession. Some examples of a rapid display of images are scrolling lists, or cover flow control. On the other hand, using the onLoad policy indiscriminately can increase the peak memory usage of your application. More decoded image data could be in memory at one time than would be the case under the onDemand policy.

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 decode the image again the next time it is required.

To set the image decoding policy (for example, to ON_LOAD):

     var loaderContext:LoaderContext = new LoaderContext(); 
     loaderContext.imageDecodingPolicy = ImageDecodingPolicy.ON_LOAD 
     var loader:Loader = new Loader(); 
     loader.load(new URLRequest("http://www.adobe.com/myimage.png"), loaderContext);
     

See also

parametersproperty 
public var parameters:Object

Language version: ActionScript 3.0
Runtime version: AIR 2.6

An Object containing the parameters to pass to the LoaderInfo object of the content.

Normally, the value of the contentLoaderInfo.parameters property is obtained by parsing the requesting URL. If the parameters var is set, the contentLoaderInfo.parameters gets its value from the LoaderContext object, instead of from the requesting URL. The parameters var accepts only objects containing name-value string pairs, similar to URL parameters. If the object does not contain name-value string pairs, an IllegalOperationError is thrown.

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 loadBytes() method, since LoadBytes does not provide a means of passing parameters through the URL. Parameters can be forwarded successfully only to another AS3 SWF file; an AS1 or AS2 SWF file cannot receive the parameters in an accessible form, although the AVM1Movie's AS3 loaderInfo.parameters object will be the forwarded object.

For example, consider the following URL:

http://yourdomain/users/jdoe/test01/child.swf?foo=bar;

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:

trace(loaderInfo.parameters.foo);

If the content loaded successfully, this trace prints "bar".

requestedContentParentproperty 
public var requestedContentParent:DisplayObjectContainer

Language version: ActionScript 3.0
Runtime version: AIR 2.6

The parent to which the Loader will attempt to add the loaded content.

When content is completely loaded, the Loader object normally becomes the parent of the content. If requestedContentParent is set, the object that it specifies becomes the parent, unless a runtime error prevents the assignment. This reparenting can also be done after the complete event without use of this property. However, specifying the parent with LoaderContext.requestedContentParent eliminates extra events.

LoaderContext.requestedContentParent sets the desired parent before frame one scripts in the loaded content execute, but after the constructor has run. If requestedContentParent is null (the default), the Loader object becomes the content's parent.

If the loaded content is an AVM1Movie object, or if an error is thrown when addChild() is called on the requestedContentParent object, then the following actions occur:

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 requestedContentParent to place the loaded content into a Sprite object:

      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.

securityDomainproperty 
public var securityDomain:SecurityDomain = null

Language version: ActionScript 3.0
Runtime version: AIR 1.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 the ActionScript 3.0 Developer's Guide.

See also

Constructor detail
LoaderContext()constructor
public function LoaderContext(checkPolicyFile:Boolean = false, applicationDomain:ApplicationDomain = null, securityDomain:SecurityDomain = null)

Language version: ActionScript 3.0
Runtime version: 

Creates a new LoaderContext object, with the specified settings. For complete details on these settings, see the descriptions of the properties of this class.

Parameters
checkPolicyFile: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