ActiveXPowUpload 1.2.0.5
DownloadItem object properties
  Home page
Contact support

DownloadItem object provides a way to access individual elements of the download file list. Each element represents a file. You cannot create the DownloadItem object directly. You must obtain it from the GetDownloadItem method of the ActiveXPowUpload object.

URL property

Name property

RelName property

FullName property

RelPath property

Error property

State property

ServerFileSize property

ServerStatusCode property

ServerStatusText property

Selected property

Focused property

Index property

URL

String URL {read only}

Uniform Resource Locator of the download file. The property gets its value from the URL parameter of the AddDownloadFile method.

Name

String Name {read only}

File name without a path where downloaded file will be saved.

Description

The name under which the downloaded file will be saved may be specified explicitly in the AddDownloadFile method or extracted from the URL.

For example, for URL "http://www.server.com/dir1/dir2/file.ext?par1=val#ch1" name will be "file.ext"; for URL "http://www.server.com/" name will be an empty string; for URL "https://www.server.com/dir1/?par1=val1" name will be an empty string.

If the file name is not specified, it is generated as described below.

At the time new download file is added the Name property gets it preliminary value. The file name may changes later right before the file starts downloaded. When user requests download, the file name is reviewed. ActiveXPowUpload normalizes file name, so it will be a valid file name with regard to the windows file naming rules. There are two phases of normalization.

  1. In the first phase prohibited characters are replaced by the underscore ('_') character, invalid file names like "." and ".." are replaced with an empty string, file name is truncated so full file name would fit the Windows file name length limit. If after the first phase we get not empty name and it is not already used by another file in the download list, it is used to save the current file. Otherwise we proceed to the second phase.
  2. In the second phase a unique file name is generated. That unique name must not be used by another file in the download file list, and the corresponding file must not exist.

So the Name property contains a preliminary name before download is started. In the OnDownloadBegin event handler we see the name that will be used to save the file unless the download file list is modified by the handler. In the latter case use OnDownloadFileBegin event handler to get the final value of the property.

See the State property and events.

RelName

String RelName {read only}

File name with a path relative to the Download Folder where downloaded file will be saved. The relative file name is composed from the Relative Path and the Name properties.

RelName never contains the backslash as its first character. If Relative Path is empty, RelName has the same value as the Name property. If both Relative Path and Name are empty, RelName is empty too. If only Name is empty, RelPath is Relative Path with the backslash added at the end.

For example:

FullName

String FullName {read only}

Full file name with a path where downloaded file will be saved. Full file name is defined if the download folder is selected, otherwise it is an empty string. To generate the value of the FullName property we must concatenate Download Folder with Relative Name adding a backslash between if necessary.

RelPath

String RelPath {read only}

File name path relative to the Download Folder. The property gets its value from the RelPath parameter of the AddDownloadFile method.

Relative Path does not contain ".", "..", "" components, its first and last character is not the backslash. It can be an empty string. Though it's not guaranteed this path can be created.

Error

String Error {read only}

Error description.

Description

If download failed, this property contains a user-friendly description of the error. This property is not an empty string if and only if the State property is "error".

State

Long State {read only}

Download file state.

Description

The State property can have the following values:

1
Initial state. Download is not yet started.
2
Download in progress.
3
Download completed successfully.
4
Error. See the Error property for error description.

ServerFileSize

Variant ServerFileSize {read only}

Size of the file on the server.

Description

This property can contain two types of values. If the size of the download file is known, it is a number equal to the size of the file in bytes. If download file size is undefined, the value is null.

Example

Assuming the download file list contains at least one file, the following jscript code distinguishes whether the size property is defined or not.

<script language="jscript">
	var file = ActiveXPowUpload.GetDownloadItem(0); // assuming at least one file exists 
	/* == operator would work here as well. */
	if(file.ServerFileName === null)
		alert("ServerFileName is undefined");
	else
		alert("ServerFileName = " + file.ServerFileName);
</script>

ServerStatusCode

Short ServerStatusCode {read only}

HTTP server status code.

Description

Contains HTTP status code that server returned after download. If the status code is unknown because download has not been started yet, for example, the value is 0.

ServerStatusText

String ServerStatusText {read only}

A short description of the HTTP server status code.

Description

Contains HTTP status code short description that server returned after download. If the status code is unknown because download has not been started yet, for example, the value is an empty string.

Selected

Bool Selected {set/get}

Determines whether the item is selected (highlighted) in the list and allows to change selection.

Focused

Bool Focused {set/get}

Determines whether the item has the focus in the list.

Description

Determines whether the item has the focus in the list and allows to change the focus. Only one item in a list may have the focus, but it is possible that none has the focus.

Example

var isFocused=ActiveXPowUpload.GetDownloadItem(0).Focused;
// set the focus to the first item of the list
ActiveXPowUpload.GetDownloadItem(0).Focused = true;

Index

Long Index {read only}

Description

0-based index of file in the download list.

Example

// index of first file in the download list. Value should be 0.
var index = ActiveXPowUpload.GetDownloadItem(0).Index;