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

Package | flash.media
Class | public class SoundLoaderContext
Inheritance | SoundLoaderContext Object

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

The SoundLoaderContext class provides security checks for SWF files that load sound. SoundLoaderContext objects are passed as an argument to the constructor and the `load()` method of the Sound class.

When you use this class, consider the Flash Player security model:

- Loading and playing a sound is not allowed if the calling SWF file is in a network sandbox and the sound file to be loaded is local.
- By default, loading and playing a sound is not allowed if the calling SWF is local and tries to load and play a remote sound. A user must grant explicit permission to allow this.
- Certain operations dealing with sound are restricted. The data in a loaded sound cannot be accessed by a SWF file in a different domain unless you implement a URL policy file. Sound-related APIs that fall under this restriction are the `Sound.id3` property and the `SoundMixer.computeSpectrum()`, `SoundMixer.bufferTime`, and `SoundTransform()` methods.

For more information related to security, see the following:

- The security chapter in the Programming ActionScript 3.0 book and the latest comments on LiveDocs
- The Flash Player Developer Center Topic: Security

Public Properties
Hide Inherited Public Properties
Show Inherited Public Properties

| Property | Defined By
--- | --- | ---
|  | bufferTime : Number = 1000 The number of seconds to preload a streaming sound into a buffer before the sound starts to stream. | SoundLoaderContext
|  | checkPolicyFile : Boolean = false Specifies whether Flash Player should try to download a URL policy file from the loaded sound's server before beginning to load the sound. | SoundLoaderContext
|  | 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

Public Methods
Hide Inherited Public Methods
Show Inherited Public Methods

| Method | Defined By
--- | --- | ---
|  | SoundLoaderContext(bufferTime:Number = 1000, checkPolicyFile:Boolean = false) Creates a new sound loader context object. | SoundLoaderContext
|  | 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

bufferTime | property

`public var bufferTime:Number = 1000`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

The number of seconds to preload a streaming sound into a buffer before the sound starts to stream.

Note that you cannot override the value of `SoundLoaderContext.bufferTime` by setting the global `SoundMixer.bufferTime` property. The `SoundMixer.bufferTime` property affects the buffer time for embedded streaming sounds in a SWF and is independent of dynamically created Sound objects (that is, Sound objects created in ActionScript).

checkPolicyFile | property |

`public var checkPolicyFile:Boolean = false`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

Specifies whether Flash Player should try to download a URL policy file from the loaded sound's server before beginning to load the sound. This property applies to sound that is loaded from outside the calling SWF file's own domain using the `Sound.load()` method.

Set this property to `true` when you load a sound from outside the calling SWF file's own domain and you need low-level access to the sound's data from ActionScript. Examples of low-level access to a sound's data include referencing the `Sound.id3` property to get an ID3Info object or calling the `SoundMixer.computeSpectrum()` method to get sound samples from the loaded sound. If you try to access sound data without setting the `checkPolicyFile` property to `true` at loading time, you may get a SecurityError exception because the required policy file has not been downloaded.

If you don't need low-level access to the sound data that you are loading, avoid setting `checkPolicyFile` to `true`. Checking for a policy file consumes network bandwidth and might delay the start of your download, so it should only be done when necessary.

When you call `Sound.load()` with `SoundLoaderContext.checkPolicyFile` set to `true`, Flash Player must either successfully download a relevant cross-domain policy file or determine that no such policy file exists before it begins downloading the specified sound. Flash Player performs the following actions, in this order, to verify the existence of a policy file:

- Flash Player considers policy files that have already been downloaded.
- Flash Player tries to download any pending policy files specified in calls to `Security.loadPolicyFile()`.
- Flash Player tries to download a policy file from the default location that corresponds to the sound's URL, which is `/crossdomain.xml` on the same server as `URLRequest.url`. (The sound's URL is specified in the `url` property of the URLRequest object passed to `Sound.load()` or the Sound constructor.)

In all cases, Flash Player requires that an appropriate policy file exist on the sound's server, that it provide access to the sound file at `URLRequest.url` by virtue of the policy file's location, and that it allow the domain of the calling SWF file to access the sound, through one or more `<allow-access-from>` tags.

If you set `checkPolicyFile` to `true`, Flash Player waits until the policy file is verified before loading the sound. You should wait to perform any low-level operations on the sound data, such as calling `Sound.id3` or `SoundMixer.computeSpectrum()`, until `progress` and `complete` events are dispatched from the Sound object.

If you set `checkPolicyFile` to `true` but no appropriate policy file is found, you will not receive an error until you perform an operation that requires a policy file, and then Flash Player throws a `SecurityError` exception. After you receive a `complete` event, you can test whether a relevant policy file was found by getting the value of `Sound.id3` within a `try` block and seeing if a `SecurityError` is thrown.

Be careful with `checkPolicyFile` if you are downloading sound from a URL that uses server-side HTTP redirects. Flash Player tries to retrieve policy files that correspond to the `url` property of the URLRequest object passed to `Sound.load()`. If the final sound file comes from a different URL because of HTTP redirects, then the initially downloaded policy files might not be applicable to the sound's final URL, which is the URL that matters in security decisions.

If you find yourself in this situation, here is one possible solution. After you receive a `progress` or `complete` event, you can examine the value of the `Sound.url` property, which contains the sound's final URL. Then call the `Security.loadPolicyFile()` method with a policy file URL that you calculate based on the sound's final URL. Finally, poll the value of `Sound.id3` until no exception is thrown.

For more information on policy files, see the "Flash Player Security" chapter in Programming ActionScript 3.0.

See also

flash.media.Sound.load()
flash.media.Sound.id3
flash.media.SoundMixer.computeSpectrum()
flash.media.Sound.url
flash.system.Security.loadPolicyFile()
Specifying loading context
Constructor Detail

SoundLoaderContext | () | Constructor

`public function SoundLoaderContext(bufferTime:Number = 1000, checkPolicyFile:Boolean = false)`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

Creates a new sound loader context object.

Parameters

| `bufferTime:Number` (default = `1000`)`` — The number of seconds to preload a streaming sound into a buffer before the sound starts to stream.
| `checkPolicyFile:Boolean` (default = `false`)`` — Specifies whether Flash Player should check for the existence of a URL policy file upon loading the object (`true`) or not.

Example
In the following example, the buffer for the sound that will be loaded is set to three seconds.

The first parameter of a SoundLoaderContext object (`context`) is used to increase the default buffer value of one second to three seconds. (The value is in milliseconds.) If the second parameter of the SoundLoaderContext object is set to `true`, Flash Player will check for a cross-domain policy file upon loading the object. Here it is set to the default value `false`, so no policy file will be checked. The `load()` method of the sound object will use the context setting to make sure it will take three seconds to preload the streaming sound into a buffer before the sound starts to stream. The `URLRequest` object determines the location of the file, which is a podcast from Adobe. If an `IOErrorEvent.IO_ERROR` error occurs during the loading of the sound file, the `errorHandler()` method is invoked.

    package {
        import flash.display.Sprite;
        import flash.net.URLRequest;
        import flash.media.Sound;
        import flash.media.SoundLoaderContext;
        import flash.events.IOErrorEvent;

        public class SoundLoaderContextExample extends Sprite {

            public function SoundLoaderContextExample() {
                var snd:Sound = new Sound();
                var req:URLRequest = new URLRequest("http://av.adobe.com/podcast/csbu_dev_podcast_epi_2.mp3");
                var context:SoundLoaderContext = new SoundLoaderContext(30000, false);

                snd.load(req, context);
                snd.play();

                snd.addEventListener(IOErrorEvent.IO_ERROR, errorHandler);
            }

            private function errorHandler(errorEvent:IOErrorEvent):void {
                trace("The sound could not be loaded: " + errorEvent.text);
            }

        }
    }

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