Using the streamStatus function

June 11, 1998
by Rett Crocker

One of the great new features of Director 6 is the streamStatus function. This function provides a means for tracking the progress of all downloads. It is fairly easy to implement a tracking system using this feature, and, in fact, I've recently written a behavior which handles most of the common uses of streamStatus functionality. In this article, I'll go through the details of using streamStatus in your own projects and I'll also explain how you would use my behavior to do so quickly and easily without any actual coding.

The first thing that you must do when using streamStatus is to call the tellStreamStatus function. This tells the Director engine to send your streamStatus function as many download events as it can. The most likely location to do this is in your prepareMovie or prepareFrame handlers.

on prepareMovie
  tellStreamStatus TRUE
end

The next step is build your streamStatus function. This function must be in a movie script. As you'll see later, this makes it slightly more difficult to build a completely independent behavior. A barebones streamStatus handler looks like this:

on streamStatus URL, state, bytesSoFar, ¬
  bytesTotal, error
    put URL, state, bytesSoFar, bytesTotal, error
end

Notice that several values are passed into the function. The Director engine handles this without any intervention by you. All you need to do is be prepared to catch the parameters as they are passed in.

We now have a working streamStatus function. Granted, its not particularly useful, but let's change that. First, let's modify it so that the message output is different depending upon the state of the operation. The state of the current operation is passed in as the second variable. The state can be: "Connecting", "Started", "InProgress", "Complete", and "Error".

                   
on streamStatus URL, state, bytesSoFar, bytesTotal¬
  , error
  case state of
    "Connecting":
      put "Connecting to" && URL & "."
    "Started":
      put "Starting download of" && URL & "."
    "InProgress":
      put bytesSoFar & "/" & bytesTotal &&  "bytes"¬
        && "[" & URL & "]"
    "Error":
      put "Error" && error && "downloading"  && URL ¬
        & "."
    "Complete":
      put "Download of" && URL && "complete."
  end case
end

After breaking out the different states we can do more than output text to the message window. The two primary things that you would want to do with this sort of download tracking are show the percentage downloaded and the current state of the download. Commonly, one shows the percent of a download by using some form of progress bar. The state information could be put into a text field.


 on StreamStatus URL, state, bytesSoFar, bytesTotal¬
  , error
  case state of
    "Connecting":
      set lMessage = "Connecting to" && URL & "."
      put lMessage into field "download_status_field"
      set lRect = the rect of sprite 10
      set the right of lRect = (the left of lRect) + 1
      set the rect of sprite 10 = lRect
    "Started":
      set lMessage = "Starting download of" && URL ¬
        & "."
      put lMessage into field "download_status_field"
      set lRect = the rect of sprite 10
      set the right of lRect = (the left of lRect) + 1
      set the rect of sprite 10 = lRect
    "InProgress":
      if bytesTotal > 0 then
        set lPercent = float(bytesSoFar)/¬
          float(bytesTotal)
        set lPercentString = string(integer(lPercent ¬
          * 100)) & "%"
      else
        set lPercent = 0.01
        set lPercentString  = "Size Unknown"
      end if
      set lMessage = lPercentString && "[" & URL & "]"
      put lMessage into field "download_status_field"
      set lRect = the rect of sprite 10
      set the right of lRect = (the left of lRect) + ¬
        integer(lPercent * 100)
      set the rect of sprite 10 = lRect
    "Error":
      set lMessage = "Error" && error && ¬
        "downloading" && URL & "."
      put lMessage into field "download_status_field"
    "Complete":
      set lMessage = "Download of" && URL && ¬
        "complete."
      put lMessage into field "download_status_field"
      set lRect = the rect of sprite 10
      set the right of lRect = (the left of lRect) ¬
         + 100
      set the rect of sprite 10 = lRect
  end case
end

The example above is a rudimentary form of a streamStatus function. I recently created a fully featured behavior which handles all aspects of streamStatus functionality. This behavior does several interesting things.

Firstly, the behavior can control the width of the sprite it is placed onto. This makes it really easy to create a progress bar. All you do is drop the behavior on the sprite which is the progress bar graphic, make sure the progress bar functionality is turned on and make sure that the sprite is stretched to 100% width. The behavior handles the rest.

Secondly, the behavior puts various messages into a text field which you specify. The messages can be customized by you and can even include various tags which get replaced by values the behavior tracks. These tags include: <percent>, <time_left>, <K_per_sec>, <bytes_current>, <bytes_total>, <K_current>, <K_total>, <URL>, <error> and <RETURN>. This limited markup language (LML?) allows you to construct the sort of progress messages you would like.

Finally, the behavior builds a movie script which contains the streamStatus function. This way you don't need to even create that part of the code. The behavior is entirely self contained. Also, when the sprite with this behavior ends, the behavior cleans up after itself and erases the movie script which it created.

Okay, enough talk. Here is a link to the text of the behavior itself, and below you will find an example movie that you can play with. Try downloading various web sites and files. You can also download a non-shocked version of this movie if you want to look at the code (Mac or PC).