SilentDownload in Seamonkey
Overview
SilentDownload is a background transfer method that allows files to be downloaded to the users machine without interfering with their network performance. SilentDownload does this by only downloading while the network library is not busy. In this way, users can "silently download" large files over a period of time and be notified when the file transfer is complete.
SilentDownload has a JavaScript API that enables web sites to "add" new transfers to the SilentDownload que. These SilentDownload APIs all go through a security verification in which the caller of the API has been digitally signed and has permission to do an SilentDownload. Once a new transfer has been added to the queue, it can only be removed by that signer or the end user via a user interface.
SilentDownload also will accessible from XPCOM. This means that any where in Seamonkey, you manage SilentDownload. An example of this is a possible interface in the context menu (the one that you get when you right click) that allows users to add items to the SilentDownload que.
A Quick Look
Suppose you wanted to deliver software to an end user. The current method is to have the end user click on a link or trigger a SmartUpdate. Both of these method display a progress dialog during the download and consume as much network bandwidth as they can. What SilentDownload offer is an alternative and more.
SilentDownload can download anything, but it is meant to download native installers, or preferably a SmartUpdate Install. Once this is done, a JavaScript must be written similar to this:
au = SilentDownload.find("CoolSoftware")
if (au == null)
{
au = new SilentDownloadTask();
au.Init("CoolSoftware",
"http://home.foo.com/download/5.1/SilentDownload.jar",
"http://home.foo.com/download/5.1/SilentDownload.html");
}
switch (au.state)
{
case SilentDownloadTask.SDL_ERROR:
au.Remove();
break;
case SilentDownloadTask.SDL_COMPLETE:
au.Remove();
// open the downloaded jar file, which puts up the
// UI and does the install break;
}
As you can see the script is very straight forward (and is partly pseudo-code). The first time the user runs this script, the query for CoolSoftware will fail. Since au is NULL, we will create a new SilentDownloadTask. Then we will initialize it by passing in a key value, the URL to download and the script to callback to. The key value should be a human readable string. This value can be presented to the user in UIs. The URL to download is self Explanatory. The script to callback, or the callback script is script which will be called when the state of a SilentDownloadTask changes or when SilentDownload first starts up.
Periodically SilentDownload will call a javascript that you passed into the Init() function of SilentDownloadTask. This javascript usually has the same format as able. It will try to find the key value using the Find() function of SilentDownload. If it fails, the script will create a new SilentDownloadTask. Once we know that we have a good SilentDownload task, we will check its state value. This will tell us what is going on with this object.
Most of the states of SilentDownloadTask are fine if you leave them unhanded, but two are important. The first is SDL_COMPLETE. When the state value of a task equals this, you know that the download is complete. You can do just about anything you want here. For example, if it is a SmartUpdate that you are download, you can open a new window is the download. The second state that you should worry about is SDL_ERROR. When this appears, something went wrong with the Download that is irrecoverable. For both of these cases you should call the Remove() function of SilentDownloadTask which will clean up your SilentDownloadTask().
Once you have written this script and your software is packaged, you must place it on a server that support Byte Ranges. If you are unfamiliar with what type of server you have, please check with your administer. Also, if you plan to use SmartUpdate jar files, be sure to set the MIME type of JAR archives on the server to application/java-archive.
APIs
- SilentDownloadTask
- Constructor. Creates a new SilentDownloadTask. The state of this is set to SDL_NOT_INITED.
- SilentDownloadTask.Init(ID, download_URL, callbackJavascript_URL);
- The following method sets up the SilentDownload download. All the information that is passed to this method is stored in a persistent store. The ID is a unique human readable string callbackJavascript_URL and the download_URL are strings. The state of the SilentDownloadTask is set to SDL_STARTED.
- SilentDownloadTask.Suspend();
- The following method suspends the SilentDownloadTask. It is the responsibility of the download script writer to resume the SilentDownload again. The state of SilentDownload object is set to SUSPEND.
- SilentDownloadTask.Resume();
- The following method resumes the SilentDownloadTask (i.e. it starts downloading the data onto users disk in background). The state of SilentDownload object is set to SDL_STARTED whenever it is downloading.
- SilentDownloadTask.Remove();
- The following method cleans up the data that is downloaded and it also removes entries from persistent store for this object. This should be called when you are all done with the SilentDownloadTask. Once this is called, your javascript callback will not be called again.
- SilentDownloadTask.DownloadNow();
- The following method downloads the data immediately without regard for the current network activity. The state of SilentDownload object is set to DOWNLOADING_NOW.
- SilentDownloadTask.ID
- A read-only string that is the key by which SilentDownloadTask are found.
- SilentDownloadTask.URL
- A read-only string which is the URL being downloaded.
- SilentDownloadTask.Script
- A read-only string which is the JavaScript callback for the current SilentDownloadTask.
- SilentDownloadTask.State
- A read-only integer that hold the state information about this SilentDownloadTask.
- SilentDownloadTask.NextByte
- The next byte of the file that SilentDownload will retrieve during the next idle period.
- SilentDownloadTask.OutFile
- The file location where this file will be saved on the users machine.
- SilentDownloadTask.ErrorMsg
- The last human readable string message.
- SilentDownload
- A state class that hold management functions and data for all SilentDownload Tasks
- SilentDownload.Find(id)
- Returns a SilentDownloadTask that matches the parameter ID. If none match null is returned.
- SilentDownload.Range
- The byte count to download during idle time.
- SilentDownload.Interval
- The number of microseconds between checking to idle time. (Should I change to seconds?)