import SecurityDomain from "./SecurityDomain"; import ApplicationDomain from "./ApplicationDomain"; declare namespace openfl.system { /** * 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 `openfl.display.Loader` * */ export class LoaderContext { /** * Creates a new LoaderContext object, with the specified settings. For * complete details on these settings, see the descriptions of the * properties of this class. * * @param checkPolicyFile Specifies whether a check should be made for * the existence of a URL policy file before * loading the object. * @param applicationDomain Specifies the ApplicationDomain object to use * for a Loader object. * @param securityDomain 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. * */ constructor(checkPolicyFile?: boolean, applicationDomain?: ApplicationDomain, securityDomain?: SecurityDomain); /** * 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. * */ allowCodeImport: boolean; /** * 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`. * */ allowLoadBytesCodeExecution: boolean; /** * 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 the _OpenFL * Developer's Guide_. * */ applicationDomain: ApplicationDomain; /** * 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 * `` 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. * */ checkPolicyFile: boolean; /** * 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 _Haxe * Developer's Guide_. * */ securityDomain: SecurityDomain; } } export default openfl.system.LoaderContext;