ActionScript 3.0 Language and Components Reference | All Packages | All Classes | Language Elements | Index | Appendixes | Conventions | Frames No Frames |
LoaderContext

Package | flash.system
Class | public class LoaderContext
Inheritance | LoaderContext Object
Subclasses | JPEGLoaderContext

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

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.

See also

flash.display.Loader.load()
flash.display.Loader.loadBytes()
flash.system.ApplicationDomain
flash.system.LoaderContext.applicationDomain
flash.system.LoaderContext.checkPolicyFile
flash.system.LoaderContext.securityDomain
flash.system.SecurityDomain
Specifying loading context

Public Properties
Hide Inherited Public Properties
Show Inherited Public Properties

| Property | Defined By
--- | --- | ---
|  | applicationDomain : ApplicationDomain = null Specifies the application domain to use for the Loader.load() or Loader.loadBytes() method. | LoaderContext
|  | checkPolicyFile : Boolean = false Specifies whether Flash Player 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

Public Methods
Hide Inherited Public Methods
Show Inherited Public Methods

| Method | Defined By
--- | --- | ---
|  | LoaderContext(checkPolicyFile:Boolean = false, applicationDomain:ApplicationDomain = null, securityDomain:SecurityDomain = null) Creates a new LoaderContext object, with the specified settings. | LoaderContext
|  | hasOwnProperty(name:String):Boolean Indicates whether an object has a specified property defined. | Object
|  | isPrototypeOf(theClass:Object):Boolean Indicates whether an instance of the Object class is in the prototype chain of the object specified as the parameter. | Object
|  | propertyIsEnumerable(name:String):Boolean Indicates whether the specified property exists and is enumerable. | Object
|  | setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void Sets the availability of a dynamic property for loop operations. | Object
|  | toString():String Returns the string representation of the specified object. | Object
|  | valueOf():Object Returns the primitive value of the specified object. | Object

Property Detail

applicationDomain | property

`public var applicationDomain:ApplicationDomain = null`

Language Version : | ActionScript 3.0

Player Version : | 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 writing `new MyClassDefinedInParent()`. The parent, however, cannot use this syntax; if the parent wishes to use the child's classes, it must call `ApplicationDomain.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 the `ApplicationDomain.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 the `ApplicationDomain.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

flash.display.Loader.load()
flash.display.Loader.loadBytes()
flash.system.ApplicationDomain

checkPolicyFile | property |

`public var checkPolicyFile:Boolean = false`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

Specifies whether Flash Player 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`, Flash Player 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 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, Flash Player requires that the given policy file exist on its server, that it provide access to the object at `URLRequest.url` by virtue of the policy file's location, and that it permit access by the domain of the calling SWF file by virtue of one or more `<allow-access-from>` tags.

If you set `checkPolicyFile` to `true`, Flash Player waits until policy file completion to begin the main download that you specify in the `Loader.load()` method. 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 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. Flash Player always attempts to retrieve policy files that correspond to the 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`.

See also

flash.display.BitmapData.draw()
flash.display.Loader.content
flash.display.Loader.load()
flash.display.LoaderInfo.childAllowsParent
flash.display.LoaderInfo.url
flash.system.Security.allowDomain()
flash.system.Security.loadPolicyFile()
Specifying loading context

securityDomain | property |

`public var securityDomain:SecurityDomain = null`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

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.

For more information, see the "Security" chapter in Programming ActionScript 3.0.

See also

flash.display.Loader.load()
flash.system.SecurityDomain
Specifying loading context
Flash Player security
Constructor Detail

LoaderContext | () | Constructor

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

Language Version : | ActionScript 3.0

Player Version : | 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.

Parameters

| `checkPolicyFile:Boolean` (default = `false`)`` — Specifies whether Flash Player should check 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.

See also

flash.display.Loader.load()
flash.display.Loader.loadBytes()
flash.system.ApplicationDomain
flash.system.SecurityDomain

Submit Feedback on LiveDocs
© 2004-2008 Adobe Systems Incorporated. All rights reserved.
Tue May 20 2008, 04:02 AM -07:00