Responding to error events and status -- Flash CS3

One of the most noticeable improvements to error handling in ActionScript 3.0 is the support for error event handling for responding to asynchronous run-time errors. (For a definition of asynchronous errors, see Types of errors.)

You can create event listeners and event handlers to respond to the error events. Many classes dispatch error events the same way they dispatch other events. For example, an instance of the XMLSocket class normally dispatches three types of events: Event.CLOSE, Event.CONNECT, and DataEvent.DATA. However, when a problem occurs, the XMLSocket class can dispatch the IOErrorEvent.IOError or the SecurityErrorEvent.SECURITY_ERROR. For more information about event listeners and event handlers, see Handling events.

Subtopics

Working with error events

The ErrorEvent class and its subclasses contain error types for handling errors dispatched by Flash Player as it tries to read or write data.

The following example uses both a try..catch statement and error event handlers to display any errors detected while trying to read a local file. You can add more sophisticated handling code to provide a user with options or otherwise handle the error automatically in the places indicated by the comment "your error-handling code here":

package
{
    import flash.display.Sprite;
    import flash.errors.IOError;
    import flash.events.IOErrorEvent;
    import flash.events.TextEvent;
    import flash.media.Sound;
    import flash.media.SoundChannel;
    import flash.net.URLRequest;
    import flash.text.TextField;

    public class LinkEventExample extends Sprite
    {
        private var myMP3:Sound;
        public function LinkEventExample()
        {
            myMP3 = new Sound();
            var list:TextField = new TextField();
            list.autoSize = TextFieldAutoSize.LEFT;
            list.multiline = true;
            list.htmlText = "<a href=\"event:track1.mp3\">Track 1</a><br>";
            list.htmlText += "<a href=\"event:track2.mp3\">Track 2</a><br>";
            addEventListener(TextEvent.LINK, linkHandler);
            addChild(list);
        }
        
        private function playMP3(mp3:String):void
        {
            try
            {
                myMP3.load(new URLRequest(mp3));
                myMP3.play();
            }
            catch (err:Error)
            {
                trace(err.message);
                // your error-handling code here
            }
            myMP3.addEventListener(IOErrorEvent.IO_ERROR, errorHandler);
        }

        private function linkHandler(linkEvent:TextEvent):void
        {
            playMP3(linkEvent.text);
            // your error-handling code here
        }
        
        private function errorHandler(errorEvent:IOErrorEvent):void
        {
            trace(errorEvent.text);
            // your error-handling code here
        }
    }
}

Working with status change events

Flash Player dynamically changes the value of the netStatus.info.level or status.level properties for the classes that support the level property. The classes that have the netStatus.info.level property are NetConnection, NetStream, and SharedObject. The classes that have the status.level property are HTTPStatusEvent, Camera, Microphone, and LocalConnection. You can write a handler function to respond to the change in level value and track communication errors.

The following example uses a netStatusHandler() function to test the value of the level property. If the level property indicates that an error has been encountered, the code traces the message "Video stream failed".

package
{
    import flash.display.Sprite;
    import flash.events.NetStatusEvent;
    import flash.events.SecurityErrorEvent;
    import flash.media.Video;
    import flash.net.NetConnection;
    import flash.net.NetStream;

    public class VideoExample extends Sprite
    {
        private var videoUrl:String = "Video.flv";
        private var connection:NetConnection;
        private var stream:NetStream;

        public function VideoExample()
        {
            connection = new NetConnection();
            connection.addEventListener(NetStatusEvent.NET_STATUS, netStatusHandler);
            connection.addEventListener(SecurityErrorEvent.SECURITY_ERROR, securityErrorHandler);
            connection.connect(null);
        }

        private function netStatusHandler(event:NetStatusEvent):void
        {
            if (event.info.level = "error")
            {
                trace("Video stream failed")
            }
            else 
            {
                connectStream();
            }
        }

        private function securityErrorHandler(event:SecurityErrorEvent):void
        {
            trace("securityErrorHandler: " + event);
        }

        private function connectStream():void
        {
            var stream:NetStream = new NetStream(connection);
            var video:Video = new Video();
            video.attachNetStream(stream);
            stream.play(videoUrl);
            addChild(video);
        }
    }
}

Comments

M. Koevoets said on Oct 4, 2007 at 7:12 AM :

The 'error event' example will not compile without importing the flash.text.TextFieldAutoSize class as well.

The netStatusHandler function in the 'status change' example only gives the 'promised' error at the specified point because of an error in the code:
if (event.info.level = "error")
should of course read
if (event.info.level == "error")
In fact the NetStatusEvent error is thrown later in the code when the stream object is created, but this exception is not caught.

adbe_paul said on Oct 4, 2007 at 4:56 PM :

@M. Koevoet:
Thanks for pointing out the errors. We'll fix them for the next documentation update.

Just FYI, the error that you are noting for the netStatusHandler example happens because there isn't an FLV file to load (if there's an FLV file named "Video.flv" in the same folder as the FLA, you don't get any error). The example is actually not written to intentionally cause an error; it's only if one does occur that the error handling code is called.