1. File Downloader 7.0.9
  2. Using File Downloader

Error Handling

On different stages of the download process you may encounter errors that should be properly handled. Errors which occur when calling JavaScript functions generally can be detected by checking the return values, but this does not help much when you need to track problems that happen during data transmission. In this case, you can use special events provided by File Downloader for download status checking and error handling.

Download Errors

There are two special events that are raised when the download is finished. Using them you can detect why the process stopped: either because of the download completion or an error.

DownloadItemComplete Event

This event is raised when a download of a single file is finished. It has the following parameters:

  1. Result with a completion status. See the DownloadItemComplete event reference for the list of status values.
  2. ErrorPage with the HTML describing the server error. This value is provided by the server. If the value of the Result parameter is a successful one, the ErrorPage parameter does not contain anything.
  3. Url with the URL of the file which has been downloaded.
  4. FileName with the name of the file which has been downloaded.
  5. ContentType with the MIME type of the file which has been downloaded.
  6. FileSize with the size of the file which has been downloaded.

Below is the example of handling this event.

JavaScript 
<script language="javascript">
function onDownloadItemComplete(Result, ErrorPage, Url, FileName, ContentType,
	FileSize){
	//The handler will display the error description
	switch (Result){
		case 1: alert("An error has occurred while downloading the file " +
			FileName);
				break;
		case 4: alert("The server returned a wrong MIME type (should be " + 
			ContentType + ") for the file " + FileName);
				break;
		case 5: alert("The server returned a wrong size (should be " + 
			FileSize + ") for the file " + FileName);
				break;
		case 6: alert("An error has occurred while writing the file " + 
			FileName + " to disk");
				break;
		case 7: alert("The file " + FileName + " could not be found on the " +
			"server");
				break;
		case 8: alert("Access to the file " + FileName + " is denied");
				break;
		case 9: alert("Time out while downloading the file " + FileName);
				break;
	}
}

var fd = new FileDownloaderWriter("FileDownloader", 122, 44);
fd.addEventListener("DownloadItemComplete", "onDownloadItemComplete");
fd.writeHtml();
</script>

All errors, that can be discovered using the DownloadItemComplete event, will be logged and displayed to the user after the download completion.

DownloadComplete Event

This event is raised when the whole download process is completed. It has only one parameter, Result, and some of the values of this parameter correspond to errors. They are illustrated in the following example.

JavaScript 
<script language="javascript">
function onDownloadComplete(Result){
	//The handler will display the error description
	switch (Result){
		case 1: alert("An error has occurred while downloading the file list");
				break;
		case 2: alert("An error has occurred while creating the file list");
				break;
		case 3: alert("The file list is empty");
				break;
		case 7: alert("The file list could not be found on the server");
				break;
		case 8: alert("Access to the file list denied");
				break;
		case 9: alert("Time out while downloading the file list");
				break;
	}
}

var fd = new FileDownloaderWriter("FileDownloader", 122, 44);
fd.addEventListener("DownloadComplete", "onDownloadComplete");
fd.writeHtml();
</script>

Error Event

A more general way to track errors occurring during the operation of File Downloader is to use the Error event. This event is raised if something goes wrong when the control performs such actions as file list transmission or parsing, file transmission or saving, and so on. In this case and in case of other unexpected situations, handle the Error event.

This event provides five parameters:

  1. Code with the code of an error. Available error codes cover the following exceptional situations:
    • File list items errors. The 10x codes correspond to these errors.
    • Connection errors. The 20x codes correspond to these errors.
    • File saving errors. The 30x codes correspond to these errors.
    • Memory errors. The 40x codes correspond to these errors.
    • An unexpected error. The code of this error is 500.
    • File list errors. The 60x codes correspond to these errors.
    To get the full list of the values, see the Error event reference.
  2. Description with the additional information on the error occured.
  3. HttpCode with the code of a server error. The difference between Code and HttpCode is that HttpCode is valid only if the server returns the error, and Code can be used in case of any errors. A description corresponding to a specific value of HttpCode can be read from the Page and Description parameter.
  4. Page with the HTML describing the server error. This value is also provided by the server.
  5. Url with the URL of the file which was being downloaded when the error occurred.
  6. Index with the number (in a file list) of the file which was being downloaded when the error occured.

To track the Error event, you need to register its handler. That is how this can be done.

JavaScript 
<script language="javascript">
function onError(Code, Description, HttpCode, Page, Url, Index){
	//The handler will display the error description returned by the server
	//If the server does not return any description, the internal error code
	//will be displayed.
	var newWindow = window.open();
	with (newWindow.document){
		open("text/html");
		if (Page) write(Page);
		else write("<html><head>Error</head><body>The internal code of the " +
			"error is " + Code + ". The error description is " + Description + ".</body></html>");
		close();
	}
}

var fd = new FileDownloaderWriter("FileDownloader", 122, 44);
fd.addEventListener("Error", "onError");
fd.writeHtml();
</script>

See Also

Reference

Manual