Next

Using DownloadX ActiveX Download Control

The following code examples demonstrate how to perform certains tasks associated with the DownloadX control.

Registering the DownloadX control

DownloadX is an ActiveX control and in order to be used by the application, an ActiveX control must be registered on the machine where it will be used. The DownloadX control is automatically registered when you install the DownloadX package. However, if you will ever need to register or unregister the DownloadX control manually you can do that by simply using the regsvr32 command in Windows Command Prompt. For example, to register the DownloadX control (DownloadXPro.dll) you could use the following command:

regsvr32 DownloadXPro.dll

Make sure you specify the full path for DownloadXPro.dll when using the regsvr32 command. DownloadXPro.dll is located in your DownloadX installation folder, usually the C:\Program Files\DownloadXCtrl\DownloadX ActiveX Download Control{version} folder.

Similary, if you wish to manually unregister the DownloadX control (DownloadXPro.dll) you could use the following command:

regsvr32 /u DownloadXPro.dll

When using the DownloadX control inside the HTML page, you don't need to manually register the DownloadX control. On the HTML page, the DownloadX control is referenced by the <object> element and Internet Explorer will automatically install and register it if it's not installed and registered already. This is explained in detail in the next chapter.

Creating the DownloadX control

Once you have the DownloadX control installed on the machine where you will be using it, you are ready to create the DownloadX control in your application code. How you will create the DownloadX control (or any other ActiveX control) in your application depends on the development environment (and programming language) you are using. Generally, there are 2 approaches: you are either allowed to add the DownloadX control to the toolbox where your other controls are located in your development environment and then simply use the DownloadX control like any other control already on the toolbox, or you need to create the DownloadX control programatically in order to use it in your code.

For example, if you are using Microsoft Visual Studio to build your Windows application you can simply add the DownloadX control to the toolbox by righ-clicking the toolbox and choosing Choose Items... from the context menu. A dialog box will appear where you should click the COM Components tab and then in the list put the checked mark beside DownloadX Pro Class entry and click the OK button. The DownloadX control will appear on the toolbox from where you can drag it to the form and start using it by setting its properties and calling its methods from your code.

Figure 2. Adding the DownloadX control to the Visual Studio toolbox.

When you wish to place the DownloadX control on the HTML page, you need to use the <object> element, like this:

<object id="DownloadX" width="600" height="400"
        classid="clsid:D1A7314E-03BD-40e0-BA6A-F37AB575FECF"
        codebase="DownloadXPro.cab#Version=1,6,5,0">
...
</object>

The id attribute of the <object> element identifies the DownloadX control so you can access the control instance in your JavaScript or VBScript code. The width and height attributes define the size of the control. Every ActiveX control has two identifiers that are used to identify the ActiveX control and to create it. Those two identifiers are called class identifiers (CLSIDs) and programmatic identifiers (ProgIDs). CLSIDs are globally unique identifiers (GUIDs) which uniquely identify particular ActiveX control, while ProgIDs are a text-based alternative used to identify the particular ActiveX control (they are simply text mappings for CLSIDs). Sometimes you will have to specify CLSID of the ActiveX control you wish to create and sometimes ProgID will be required. So, the classid attribute of our <object> element contains the DownloadX control's CLSID which the Web browser will use to create the instance of the control. And finally, the codebase attribute specifies where the DownloadX .cab file resides relative to the current HTML page. The .cab files actually contain the code of an ActiveX control. The Web browser will check whether the DownloadX control specified in the classid attribute is already installed on this computer and if it's not, the Web browser will download the .cab file specified in the codebase attribute and install the DownloadX control. Currently, the only Web browser supporting ActiveX controls on HTML pages is Microsoft Internet Explorer.

The following table shows CLSIDs, ProgIDs and codebase values (.cab file names) for different DownloadX versions:

Version CLSID ProgID codebase (.cab file name)
1.5.2 D1A7314E-03BD-40e0-BA6A-F37AB575FECF DownloadXPro.DownloadX.1.5 DownloadXPro.cab#Version=1,5,2,0
1.6.1 D1A7314E-03BD-40e0-BA6A-F37AB575FECF DownloadXPro.DownloadX.1.6 DownloadXPro.cab#Version=1,6,1,0
1.6.2 D1A7314E-03BD-40e0-BA6A-F37AB575FECF DownloadXPro.DownloadX.1.6 DownloadXPro.cab#Version=1,6,2,0
1.6.5 D1A7314E-03BD-40e0-BA6A-F37AB575FECF DownloadXPro.DownloadX.1.6 DownloadXPro.cab#Version=1,6,5,0

ProgID is required when you wish to create an ActiveX control in scripting languages. For example, to create the DownloadX control in JavaScript or VBScript, use the following code:

[JavaScript]
var dwX;
dwX = new ActiveXObject("DownloadXPro.DownloadX.1.6");

...

delete dwX;

[VBScript]
Dim dwX
Set dwX = CreateObject("DownloadXPro.DownloadX.1.6")

...

Set dwX = Nothing

Although not all development environments have been covered here, creating the DownloadX control in other development environments and programming languages is very similar to methods described here. For more information on how to create and use ActiveX controls in your development environment, please see your development environment documentation.

Downloading files with the DownloadX control

Downloading files with the DownloadX control is quite simple. All you have to do is specify files you wish to download and start the downloading process. To use the DownloadX control on the HTML page and download some files, first you need to create the DownloadX control like this:

<object id="DownloadX" width="600" height="400"
        classid="clsid:D1A7314E-03BD-40e0-BA6A-F37AB575FECF"
        codebase="http://localhost/DownloadXPro.cab#Version=1,6,5,0">
...
</object>

The <object> element above will create the DownloadX control and assumes that DownloadXPro.cab can be downloaded from the local server (localhost). Make sure the codebase attribute contains valid URL from where the DownloadXPro.cab can be downloaded.

After the DownloadX control has been created, you can start downloading files. To download files with the DownloadX control, use the AddFile method to add files you wish to download and then call the Download method.

IMPORTANT: When downloading files with the DownloadX control you must set the DownloadSessionTempSubfolder property before calling the Download method. When calling the Download method, files that are going to be downloaded represent the single download session and the value specified in the DownloadSessionTempSubfolder property identifies this download session. Different download sessions must have unique DownloadSessionTempSubfolder values. For example, when downloading has been stopped and you need to resume it later, you have to set the DownloadSessionTempSubfolder property to the correct value first in order to identify the download session you wish to resume.

To download a file using the DownloadX control created with the <object> element above, the following code can be used (please replace 1st, 3rd and 4th parameter in AddFile call with the real file URL and the real file name of the file you wish to download):

[JavaScript]
<script type="text/javascript">
   DownloadX.DownloadSessionTempSubfolder = "session-4639E7BD-47A7-4303-A522-759EA100A4CF";
   var nFileId;
   // TODO: Replace 1st, 3rd and 4th parameter with the real file URL and the real file name.
   nFileId = DownloadX.AddFile("http://www.domain.com/MyFile.zip",
                               "-1",
                               "MyFile.zip",
                               "\\MyFile.zip",
                               1,
                               "",
                               "",
                               "",
                               0);
   DownloadX.Download();
</script>

[VBScript]
<script type="text/vbscript">
   DownloadX.DownloadSessionTempSubfolder = "session-4639E7BD-47A7-4303-A522-759EA100A4CF"  
   Dim nFileId
   ' TODO: Replace 1st, 3rd and 4th parameter with the real file URL and the real file name.
   nFileId = DownloadX.AddFile("http://www.domain.com/MyFile.zip", _
                               "-1", _
                               "MyFile.zip", _
                               "\MyFile.zip", _
                               1, _
                               "", _
                               "", _
                               "", _
                               0)
   DownloadX.Download
</script>

The DownloadX control fires various events during the download process to inform your application of the current downloading progress. For example, when the DownloadX control has finished downloading all files in a download session, the OnDownloadComplete event is fired. Your application can respond to this event, like in the following code:

[JavaScript]
<script type="text/javascript">
   function DownloadX::OnDownloadComplete(result)
   {
      if (result) alert("Download Completed Successfully!");
      else alert("Download Failed: " + DownloadX.GetLastErrorDesc());
   }
</script>

[VBScript]
<script type="text/vbscript">
   Sub DownloadX_OnDownloadComplete(result)
      If result Then 
         alert("Download Completed Successfully!")
      Else 
         alert("Download Failed: " & DownloadX.GetLastErrorDesc())
      End If
   End Sub
</script>

You can customize almost every aspect of the DownloadX control by using its properties and methods. To specify columns the DownloadX control should display for each file being downloaded, use the Columns property and the SetColumn method to specify column headers and their widths. Colors are changed with ColumnsForeColor, ColumnsBackColor and BackColor properties. Font characteristics are set with the Font property. You can also choose whether to display the progress bar and specify its height with the SetProgressBar method. To change the number of files being downloaded at the same time, use the ConcurrentDownloadFileCount property. When a file is split into several segments before it gets downloaded, you can define minimum file segment size (in bytes) with the MinFileSegmentSize property. You can even specify the buffer size (in bytes) the DownloadX control uses when receiving data from the server by using the ReceiveBufferSize property. When a file is successfully downloaded, you can choose whether to remove it automatically from the list by using the AutoRemoveCompletedFiles property. If an error occurs during the download, you can configure the DownloadX control to automatically retry the failed operation by using RetryWait and RetryCount properties. If you are using the proxy server, set its parameters with the SetProxy method. You can also manually stop the current download at any time by using the StopDownload method, later you can resume it with the ResumeDownload method. For more information, see the complete list of the DownloadX properties, methods and events.

NOTE: There are demo applications to help you explore the DownloadX control features. You can find those DownloadX demo applications in the Examples subfolder of your DownloadX installation folder, usually the C:\Program Files\DownloadXCtrl\DownloadX ActiveX Download Control{version} folder.

Resuming downloads with the DownloadX control

In case the connection with the server is lost during the download (or download is stopped by the user), you can resume your download later right where it left off by using the ResumeDownload method. Before calling the ResumeDownload method, you must identify the download session you are resuming by setting the DownloadSessionTempSubfolder property, like this:

[JavaScript]
<script type="text/javascript">
   DownloadX.DownloadSessionTempSubfolder = "session-4639E7BD-47A7-4303-A522-759EA100A4CF";
   DownloadX.ResumeDownload();
</script>

[VBScript]
<script type="text/vbscript">
   DownloadX.DownloadSessionTempSubfolder = "session-4639E7BD-47A7-4303-A522-759EA100A4CF"  
   DownloadX.ResumeDownload
</script>