ActiveXPowUpload 1.2.0.5
Methods
  Home page
Contact support

Upload methods

GetItem method

Upload method

Stop method

ShowAddFilesDialog method

ShowAddFolderDialog method

AddFormItem method

RemoveFormItem method

RemoveAllFormItems method

RemoveFile method

RemoveSelectedFiles method

RemoveAllFiles method

Paste method

GetServerReply method

GetServerStatusCode method

GetServerStatusText method

ShowProgressWindow method

HideProgressWindow method

Download methods

ShowSelectDownloadFolderDialog method

Download method

StopDownload method

GetDownloadItem method

AddDownloadFile method

RemoveDownloadFile method

RemoveSelectedDownloadFiles method

RemoveAllDownloadFiles method

Other methods

GetItem

Variant GetItem(Index:Variant)

Description

Method returns a FileItem object coresponding to some item in the upload file list. The method allows to get item by numerical index or by file path.

When there is no item corresponding to the index specified (incorrect index), a null value is returned. See examples section.

The prefered way to get a reference to a FileItem object is using a numerical index, that is more effiecient, then refering by file path.

Parameters

Index

It may be other a number or a string, the other types are not allowed. When it is a number, it is interpreted as a 0-based index of the item in the upload file list. The value must be greater than or equal to 0 and less than ActiveXPowUpload.FileListItemCount. You should convert index value if it has String type but stores a number!

When the index is a string, it is interpreted as a full path of the item in the upload file list. Comparision is case insensitive.

See also UploadItems.

Example

<script language="jscript">
	var file = ActiveXPowUpload.GetItem(0); // Get file by position;
	file = ActiveXPowUpload.GetItem("c:\\file.jpg"); // Get file by its full path;
	var index = "0";
	file = ActiveXPowUpload.GetItem(parseInt(index)); // Use this to convert a string into a number
	file = ActiveXPowUpload.GetItem("incorrect index"); // here file == null
</script>

Upload

void Upload()

Upload files of the upload file list and text items in the Form items list.

Description

There are some restrictions on when the upload method can be invoked. It is an error to start upload twice. You must always wait for the last upload to terminate before starting it again. You are not allowed to start upload inside an event handler. Here “event handler” means only a handler of the ActiveXPowUpload event like OnUploadBegin, OnUploadProgress and so on.

Starting from version 1.1.0 the upload method always waits for upload termination.

ActiveXPowUpload sends files in the order they appear in the file list. Each file contained within a separate part with a name "FILE<N>". Where <N> is the index of the file in the list. Index is 0-based.

ActiveXPowUpload traverses a number of upload states while performing upload. The state determines what you can do with the control, what methods you can invoke, what properties you can change.

Example

ActiveXPowUpload.Upload();

Stop

void Stop()

Description

Cancels upload. An upload process is notified to terminate. After a while the upload process notices the cancel request and cancels upload. Sometimes, though, the upload progress might complete before the notification received. In this case the upload terminates as usual. The stop methods doesn't wait for upload termination. Generally you can't start the upload immediately after the Stop method. You should wait for a while.

Example

ActiveXPowUpload.Stop();

ShowAddFilesDialog

Boolean ShowAddFilesDialog()

Description

Shows "Add files" dialog. Selected files will be added to the list.

Return value indicates whether the user selected files to add or canceled the dialog (true - files were selected, false - the dialog was canceled).

Example

ActiveXPowUpload.ShowAddFilesDialog();

ShowAddFolderDialog

Boolean ShowAddFolderDialog()

Description

Shows "Add folder" dialog. All files of the selected folder and its subfolders will be added to the list.

You can set the folder that will be preselected in the dialog using the DefaultUploadFolder property.

Return value indicates whether the user selected a folder to add or canceled the dialog (true - a folder was selected, false - the dialog was canceled).

Example

ActiveXPowUpload.ShowAddFolderDialog();

AddFormItem

void AddFormItem(name: String, value: String)

Description

Adds a (name, value) pair to the list of text fields that will be sent as text Form items. To prevent possible name duplication the name can’t match the pattern used for naming files, see FileFormItemPattern. The name can't be empty.

See also FormItemCount, FormItem, FormItems, AddFormItem, RemoveFormItem, RemoveAllFormItems.

Parameters

name

Name of text Form item. Must be unique. It is similar to the HTML "Name" parameter of a Form item.

value

Value of text Form item. It is similar to the HTML "Value" parameter of a Form item.

Example

ActiveXPowUpload.AddFormItem("username", "Jdoe");

RemoveFormItem

void RemoveFormItem(key: Variant)

Description

Removes the text field item from the text fields list with the specified key.

See also FormItemCount, FormItem, FormItems, AddFormItem, RemoveFormItem, RemoveAllFormItems.

Parameters

key

It may be either a string or an interger. If string, the key is an item name. If interger, the key is 0-based index of the text item.

Example

ActiveXPowUpload.RemoveFormItem("username");

RemoveAllFormItems

void RemoveAllFormItems()

Description

Removes all items from the text fields list.

See also FormItemCount, FormItem, FormItems, AddFormItem, RemoveFormItem, RemoveAllFormItems.

Example

ActiveXPowUpload.RemoveAllFormItems();

RemoveFile

void RemoveFile(index:Long)

Description

Removes file list element, either file or folder.

Parameters

index

A number that indicates a 0-based index of a file list element. The value must be greater than or equal to 0 and less than ActiveXPowUpload.FileListItemCount.

Example

ActiveXPowUpload.RemoveFile(0);

RemoveSelectedFiles

void RemoveSelectedFiles()

Description

Method removes selected (highlighted) file list items.

Example

ActiveXPowUpload.RemoveSelectedFiles();

RemoveAllFiles

void RemoveAllFiles()

Description

Method removes all file list items.

Example

ActiveXPowUpload.RemoveAllFiles();

Paste

void Paste()

Description

Method adds files from clipboard into the list. If the clipboard contains inappropriate data, nothing will be done. Folders are processed recursively.

Example

ActiveXPowUpload.Paste();

GetServerReply

String GetServerReply(codepage: Long)

Description

Returns server reply as a string. It’s everything that server sends in response to upload, normally an html page. The component may detect page encoding automatically most of the time (pass 0 as parameter to use that feature). If automatic detection fails, you may specify the correct codepage in parameter. For example, code page number 65001 is for UTF-8 encoding. See msdn for the complete list of allowed code pages: Code Page Identifiers.

Parameters

codepage

Code page of the server response. Use 0 for autodetection.

Example

window.alert(ActiveXPowUpload.GetServerReply(0));

GetServerStatusCode

Long GetServerStatusCode ()

Description

HTTP status code of the server response. 200 in most cases means success, 500 - internal error. You can find most HTTP status codes with short descriptions at the w3.org website.

See also GetServerStatusText.

Example

window.alert(ActiveXPowUpload.GetServerStatusCode());

GetServerStatusText

String GetServerStatusText()

Description

A short description of the HTTP status code, a reason phrase. For code 200 it is usually "OK". You can find most HTTP status codes with short descriptions at the w3.org website.

See also GetServerStatusCode.

Example

window.alert(ActiveXPowUpload.GetServerStatusText());

ShowProgressWindow

void ShowProgressWindow()

Description

Shows upload progress window.

See also HideProgressWindow.

Example

ActiveXPowUpload.ShowProgressWindow();

HideProgressWindow

void HideProgressWindow()

Description

Hides upload progress window.

See also ShowProgressWindow.

Example

ActiveXPowUpload.HideProgressWindow();

ShowSelectDownloadFolderDialog

Boolean ShowSelectDownloadFolderDialog()

Description

Shows a select download folder dialog. A user selects a folder where downloaded files will be saved. The folder must exist.

Use the DownloadFolder property to determine the selected folder.

You can set the folder that will be preselected in the dialog using the DefaultDownloadFolder property.

Return value indicates whether the user selected the download folder or canceled the dialog (true - the download folder was selected, false - the dialog was canceled).

Download

void Download()

Description

Starts download process.

ActiveXPowUpload traverses a number of download states while performing download. The state determines what you can do with the control, what methods you can invoke, what properties you can change.

StopDownload

void StopDownload()

Description

Cancels download process.

GetDownloadItem

Variant GetDownloadItem(Index: Variant)

Description

Returns an object representing a download file. The index may be either a number or a string. If it is a number, it is a 0-based index of the download file in the range [0, DownloadFileCount). If it is a string, it is URL of the download file. When there is no item corresponding to the index specified (incorrect index), a null value is returned. See examples section.

The prefered way to get a reference to a DownloadItem object is using a numerical index, that is more effiecient, then refering by URL.

Parameters

index

It may be other a number or a string, other types are not allowed. A number indicates a 0-based index of the download file. The value must be greater than or equal to 0 and less than ActiveXPowUpload.DownloadFileCount. When the index is a string, it is interpreted as URL of the download item.

Example

<script language="jscript">
	var item = ActiveXPowUpload.GetDownloadItem(0); // Get item by position;
	item = ActiveXPowUpload.GetDownloadItem("http://myserver.com/path/file.txt"); // Get item by its URL;
	var index = "0";
	item = ActiveXPowUpload.GetDownloadItem(parseInt(index)); // Use this to convert a string into a number
	item = ActiveXPowUpload.GetItem("http://myserver.com/url/not/in/the/list"); // here file == null
	/* URL must be well-formed, otherwise you'll get exception, as in this case: */
	item = ActiveXPowUpload.GetItem("http://incorrect url!");
</script>

AddDownloadFile

long AddDownloadFile(URL: String, RelPath: StringOpt, FileName: StringOpt, Size: VariantOpt)

Adds a URL to download list.

Description

URL specifies the file to download. Relative URls are supported, but the URL may not be blank or resolve to a blank URL.

A full file name of the downloaded file consists of three components: a Download Folder, a Relative Path, and a File Name. The File Name can be specified explicitly through the FileName parameter or it will be generated based on the value extracted from the URL.

For example, let's

The full file name will be "C:\dir1\dir2\dir3\dir4\file.ext".

It's not necessary the Download Folder to be set before you start adding files. The Download Folder can be changed after files added.

The RelPath parameter undergos changes. Components consisting of a single dot are removed from the path. Parent references are handled inside the path (double dot component is removed with the preceding path component), but references to the parent folders outside the path are not allowed. Path may not contain empty components. Path may not start with a backslash.

For example, the path ".\dir1\dir2\..\dir3\dir4\." becomes "dir1\dir3\dir4". The path "dir1\..\..\dir2\" is illegal because it references to the parent folder outside. The path "dir1\\dir2" is illegal because it contains empty dir name. The path "\dir1\dir2\" is illegal because it starts with a backslash.

Empty path means the downloaded file will be saved in the Download Folder directly. A single dot (".") means the same.

After processing Relative Path becomes the value of the RelPath property.

The FileName is an optional parameter. By default it is empty string. If the FileName is not an empty string, that name will be used to save the download file. If the FileName is an empty string, the file name will be generated based on the value extracted from the URL.

If you specify the file name explicitly, make sure that different URLs will be saved in different files.

Size - optional parameter specifying download file size. If it is not specified, file size is not defined. Actual server file size will be determined when the file will be started download. Server does not always tell the size of the file. Setting the Size parameter helps to calculate download progress when server does not tell the size of the file. The Size parameter must contain not negative integer less than or equal to 2^31 - 1 = 2147483641 = 2 Gb - 1.

Parameters

URL

A uniform resource locator of the file to download. Supports http and https protocols.

RelPath

A relative path where the downloaded file will be saved. It must be a folder path, not a file path. Optional parameter.

FileName

A file name under which the downloaded file will be saved. Optional parameter.

Size

Download file size. Optional parameter.

Return value

Index of the added file.

Example

ActiveXPowUpload.AddDownloadFile("http://www.server.com/dir1/file.ext",
    "dir", "myname.ext", 1000);
ActiveXPowUpload.AddDownloadFile("http://www.server.com/dir1/file.ext",
    "dir", "", 1000); // here the FileName parameter is omitted
ActiveXPowUpload.AddDownloadFile("http://www.server.com/dir1/file.ext",
    "dir"); // here the Size and FileName parameters are omitted

RemoveDownloadFile

void RemoveDownloadFile(Index: Long)

Description

Removes the file with the index Index from the list of download files. The Index must be from 0 to DownloadFileCount-1.

Parameters

index

An index of the file in the download file list to remove.

RemoveSelectedDownloadFiles

void RemoveSelectedDownloadFiles()

Description

Removes all selected items from the list of download files.

RemoveAllDownloadFiles

void RemoveAllDownloadFiles()

Description

Removes all files from the list of download files.