XUpload User Manual - Chapter 6: File Download Functionality

Home
What's New
User Manual
1. Introduction
2. Basic Uploads
3. Config Params
4. Advanced
5. International
6. File Downloads

Object Reference
Live Demos
Support
Download & Buy

Other Products
Contact Us

Chapter 6: File Download Functionality

6.1 Introduction to the Download Control
6.2 Obtaining Download Status
6.3 Redirection
6.4 Other Configuration Parameters
6.5 Using AspUpload's Directory Listing

6.1 Introduction to the Download Control

Version 3.0 of XUpload includes another ActiveX control, XDownload, which enables your application to download multiple files from various locations on the Internet to the user's local hard drive.
XDownload resides in the same library file as XUpload (XUpload.ocx). However, being a totally separate COM object, it has its own Class ID and its own set of properties, methods and events.
To do useful work, XDownload needs to be given one or more pairs of source and destination parameters. A source parameter is a URL such as http://www.someserver.com/file.ext. A destination parameter is a local file path such as c:\my files\file.ext. A destination can also start with a keyword designating a personal user folder, such as @DESKTOP (see Section 3.1).
The source and destination parameters are passed to XDownload via the <PARAM NAME="SourceN"> and <PARAM NAME="DestinationN"> pairs of PARAMs, where N is 1, 2, 3, etc. For example:
HTML:

<OBJECT
  classid="CLSID:70E6CD54-8979-4977-9321-48DA55439F6C"
  codeBase="XUpload.ocx"
  height="200"
  id="DownloadCtl"
  width="500">
<PARAM NAME="Source1" VALUE="http://aspupload.com/ps_logo.gif">
<PARAM NAME="Destination1" VALUE="c:\ps_logo.gif">
<PARAM NAME="Source2" VALUE="http://www.persits.com/index.html">
<PARAM NAME="Destination2" VALUE="c:\index.html">
<PARAM NAME="Source3" VALUE="http://aspupload.com/ps_logo.gif">
<PARAM NAME="Destination3" VALUE="@PERSONAL\My Pictures\ps_logo.gif">
</OBJECT>

To start a download, right-click on the control and select Download from the pop-up menu. Alternatively, a download can be started programmatically by invoking the Download method via a button click or another event. Using the Download method, as opposed to the pop-up menu, causes XDownload to display a warning message for script-safety purposes:

Note that starting with version 3.0.0.3, this warning message can be disabled by adding the current site to the Trusted sites list.
Click the links below to run this code sample:
http://localhost/xupload/06_download.asp
In addition to the SourceN/DestinationN PARAMs just described, items can be added to the XDownload control programmatically via the AddFile method, but not interactively. They can, however, be interactively removed from the list. To enable interactive removal, use the CanRemove PARAM, as follows:
<PARAM NAME="CanRemove" VALUE="True">
This way, the user will be able to remove existing items from the list by highlighting them and selecting Remove from the pop-up menu. An item can also be removed programmatically via the Remove method, even when interactive removal is not enabled.

6.2 Obtaining Download Status

Section 4.5 of this User Manual described XUpload's SelectedFiles collection that gives programmatic access to the currently selected file items on the list. The XDownload control also supports the SelectedFiles collection, although the pertinent SelectedFile properties are now Index, Path, URL and Selected (but not Size).
XDownload uses another instance of this collection to provide programmatic access to the download status of each file being downloaded.
During a download, one or more files on the list may fail to download properly for one reason or another (invalid URL or local path, connection problem, etc.) XDownload keeps track of each file's download status and stores it in the DownloadedFiles collection. Each item in the collection is, once again, a SelectedFile object, but this time around the pertinent properties are: Index, Path, URL, Size, DownloadStatus and DownloadSuccess.
The DownloadedFiles collection is empty at first and should only be used at the end of a download, preferably in the Done event handler. If a file was successfully downloaded, its corresponding DownloadSuccess property is set to True, and Size to its actual size in bytes. Otherwise, DownloadSuccess is False and DownloadStatus contains a detailed description of the problem. This could be a network error such as "HTTP Status Code 404" or local system error such as "System cannot find the file specified."
The following code sample demonstrates the usage of the DownloadedFiles collection. For the sake of demonstration, the URLs and paths of the last two items on the list are deliberately set to invalid values.
HTML:

<script type="text/javascript" for="DownloadCtl" event="Done()">
  for( i = 1; i <= DownloadCtl.DownloadedFiles.Count; i++ )
  {
    file = DownloadCtl.DownloadedFiles(i);
    txtULR.innerHTML += file.URL + "<br>";
    txtPath.innerHTML += file.Path + "<br>";
    txtSuccess.innerHTML += file.DownloadSuccess + "<br>";
    txtStatus.innerHTML += file.DownloadStatus + "<br>";
  }
</script>
<HTML>
<BODY>
<OBJECT
  classid="CLSID:70E6CD54-8979-4977-9321-48DA55439F6C"
  codeBase="XUpload.ocx"
  height="200"
  id="DownloadCtl"
  width="500">
<PARAM NAME="Source1" VALUE="http://aspupload.com/ps_logo.gif">
<PARAM NAME="Destination1" VALUE="c:\ps_logo.gif">
<PARAM NAME="Source2" VALUE="http://www.persits.com/index.html">
<PARAM NAME="Destination2" VALUE="c:\index.html">
<PARAM NAME="Source3" VALUE="http://aspupload.com/ps_ logo.gif">
<PARAM NAME="Destination3" VALUE="c:\ps_logo.gif">
<PARAM NAME="Source4" VALUE="http://www.persits.com/index.html">
<PARAM NAME="Destination4" VALUE="c:\nonexistentdir\index.html">
</OBJECT>
<P>
<table border="1">
<TR>
  <TH>URL</TH><TH>Path</TH><TH>Success</TH><TH>Status</TH>
</TR>
<TR>
  <TD><SPAN ID="txtULR"></SPAN></TD>
  <TD><SPAN ID="txtPath"></SPAN></TD>
  <TD><SPAN ID="txtSuccess"></SPAN></TD>
  <TD><SPAN ID="txtStatus"></SPAN></TD>
</TR>
</table>
</BODY>
</HTML>

Click the link below to run this code sample:
http://localhost/xupload/06_status.asp

6.3 Redirection

The code sample in the previous section uses the DownloadedFiles collection to display download status on the same page as the control itself.
Alternatively, XDownload can be programmed to redirect to another page upon the completion of a download, where the results can be displayed. To enable the redirect functionality, the RedirectURL PARAM must be set to a valid URL, as follows:
HTML:

<OBJECT
  classid="CLSID:70E6CD54-8979-4977-9321-48DA55439F6C"
  codeBase="XUpload.ocx"
  height="200"
  id="DownloadCtl"
  width="500">
...
<PARAM NAME="RedirectURL" VALUE="http://localhost/xupload/06_redirect_display.asp">
</OBJECT>

When performing the redirect, XDownload uses the POST method and sends along the status information for each item under the names URL, Path, Size, Status and Success. To display the information, use the Request.Form collection, as follows:
Server-Side VBScript:

<table border="1">
<TR>
<TH>URL</TH><TH>Path</TH><TH>Size</TH> <TH>Success</TH><TH>Status</TH>
</TR>
<%
count = Request.Form("path").Count
For i = 1 To count
%>
<TR>
  <TD><% = Request.Form("URL")(i)%></TD>
  <TD><% = Request.Form("Path")(i)%></TD>
  <TD><% = Request.Form("Size")(i)%></TD>
  <TD><% = Request.Form("Status")(i)%></TD>
  <TD><% = Request.Form("Success")(i)%></TD>
</TR>
<%
Next
%>
</table>

Click the links below to run this code sample:
http://localhost/xupload/06_redirect.asp
Just like XUpload, XDownload supports the RedirectTarget parameter which specifies which window or frame (if there is a frameset) the redirect URL should appear in upon the completion of a download. For example, to have the download results appear in a new window, use the following PARAM:
<PARAM NAME="RedirectTarget" VALUE="_blank">
For more information about the RedirectTarget parameter, see Section 2.2.

6.4 Other Configuration Parameters

6.4.1 WarnOverwrite
Before starting a download, XDownload checks whether any of the files specified via DestinationN parameters already exist on the local hard drive. If one or more such files are found, the following warning is displayed:

This warning can be disabled by setting the WarnOverwrite parameter to False, as follows:
<PARAM NAME="WarnOverwrite" VALUE="False">
6.4.2 CanSelectFolder & Directory
By default, the items on the XDownload list cannot be modified by the user. If the CanSelectFolder parameter is set to True, the pop-up menu gains another menu item, Select Folder, which enables the user to select a new destination folder for all items on the list:
<PARAM NAME="CanSelectFolder" VALUE="True">
The Select Folder dialog can be invoked programmatically via the SelectFolder method regardless of the CanSelectFolder parameter value.
The initial directory for the Select Folder dialog box can optionally be specified via the Directory parameter, as follows:
<PARAM NAME="Directory" VALUE="c:\My Documents">
This parameter also accepts special keywords designating personal user folders such as @DESKTOP, @PERSONAL, etc. See Section 3.1 for the full list of supported keywords.
6.4.3 International
XDownload's usage of the International parameter is completely identical to XUpload, See Section 5.2 for details.
6.4.4 ShowProgress
Just like XUpload, XDownload allows you to disable its default progress bar window by setting the ShowProgress parameter to False, and optionally implement a custom progress bar based on the Progress event. See Section 4.2 for details. Note that XDownload fires the DownloadProgress event (instead of XUpload's UploadProgress) and there is no WaitingForReply event.
6.4.5 Username & Password
The Username and Password parameters, if specified, are passed to the server from which a download is attempted. This is useful if the download URLs are protected with basic authentication. The specified Username/Password information is shared by all the URLs on the list.

6.4.6 Authorization
The Authorization parameter may not be as useful in XDownload as it is in XUpload, but has been implemented nonetheless. See Section 3.3 for usage information.
6.4.7 RegKey
The usage of the RegKey parameter is identical to that in XUpload. The same registration key, if available, should be used in both controls. See Section 1.5 for details.

If your application needs to populate XDownload with all (or some) files from a certain directory on the server, you may take advantage of AspUpload's Directory Listing functionality.
AspUpload's Directory method returns a collection of files and subfolders in a specified folder that match a specified wildcard. A server-side script can use this collection to automatically generate the <PARAM NAME="SourceN"> and <PARAM NAME="DestinationN"> tags for the XDownload control, as follows:
Server-Side VBScript:

<OBJECT ...>
<%
  Count = 1
  For each file in dir
    If Not file.IsSubdirectory Then
%>
<PARAM NAME="Source<% = Count %>"
  VALUE="http://localhost/rootdir/<% = file.Filename %>">
<PARAM NAME="Destination<% = Count %>"
  VALUE="c:\temp\<% = file.Filename %>">
<%
      Count = Count + 1
    End If
  Next
%>
</OBJECT>

In the code snippet above, we use the property file.IsDirectory to separate files from subdirectories, and file.Filename to obtain the names of all files.
If one or more files in the directory contain Unicode characters, this code snippet will not work properly. The filenames need to be UTF-8 encoded before they can become part of <PARAM> tags. XDownload provides a method, ToUTF8 which takes a Unicode string as a parameter and produces a binary array of bytes representing the UTF-8 encoding of this string. The expressions
<% = file.Filename %>
in the code snippet above need to be replaced by
<% Response.BinaryWrite( XDownload.ToUTF8(file.Filename) )%>
Also, the script file needs to have a META tag indicating that UTF-8 encoding is in use:
<META http-equiv="Content-Type" content="text/html; charset=utf-8">
The complete code sample looks as follows:
Server-Side VBScript:

<HTML>
<HEAD>
<META http-equiv="Content-Type" content="text/html; charset=utf-8">
</HEAD>
<BODY>
<%
' Use AspUpload's Directory Listing functionality
Set upload = server.createobject("persits.upload")
' Set to your own directory on the server
Path = "c:\upload\*.*"
set dir = upload.directory( Path )
' Xupload.ocx must be registered on the server with regsvr32
Set XDownload = Server.CreateObject("Persits.XDownload")
%>
<OBJECT
  classid="CLSID:70E6CD54-8979-4977-9321-48DA55439F6C"
  codeBase="XUpload.ocx"
  height="200"
  id="DownloadCtl"
  width="500">
<%
  Count = 1
  For each file in dir
    If Not file.IsSubdirectory Then
%>
<PARAM NAME="Source<% = Count %>"
  VALUE="http://localhost/rootdir/<% Response.BinaryWrite( XDownload.ToUTF8( file.filename ) ) %>">
<PARAM NAME="Destination<% = Count %>"
  VALUE="c:\temp\<% Response.BinaryWrite( XDownload.ToUTF8( file.filename ) ) %>">
<%
      Count = Count + 1
    End If
  Next
%>
</OBJECT>
</BODY>
</HTML>

Note that XUpload.ocx must be registered on the server with regsvr32 for this code sample to run. Note also that Unicode URLs are currently fully supported by IIS6 only.
Click the links below to run this code sample:
http://localhost/xupload/06_filelist.asp