Welcome to XFile Version v2.5.1!

Last update: 05/2010

What is SoftArtisans XFile?

Features and Benefits

XFile Editions

New Version 2

Requirements

Related Products

Copyright © 2010 SoftArtisans, Inc. All rights reserved.


What is SoftArtisans XFile?

SoftArtisans XFile is a powerful ActiveX product with a non-visual COM file transfer engine. XFile is a complete HTTP client that may be used from Internet Explorer, ASP, ASP.NET, Visual Basic, or through the Windows Shell Extension.

XFile's file transfer engine submits uploads from client to server, receives downloads, and transfers files from server to server. The file transfer engine (the XFRequest object) can be used in client-side (HTML) code through the <object> tag, or in server-side (ASP) code through Server.CreateObject.

In addition to the file transfer engine - XFile's principal object - XFile includes a visual upload control and a visual download control. Note that the file transfer engine (the XFRequest object) always sends and receives the file transfer, while the visual controls provide a graphical user interface to use with the file transfer engine. You must use the file transfer engine, but you do not have to use the visual controls.

There are two editions of XFile:

  • XFileSE
    XFile Standard Edition (XFileSE) can be used with either FileUpSE or FileUpEE on the server XFileSE can handle uploads of up to 4-GB. XFileSE does not support resumable uploading or downloading.

  • XFileEE
    XFile Enterprise Edition (XFileEE) can be used with either FileUpSE or FileUpEE on the server. There is no upload size limit when you use XFileEE with FileUpEE on the server. XFileEE includes resumable uploading and downloading.

For more information on edition differences, see XFile Editions.


Features and Benefits

  • Encrypted HTTP header support
    • When using FileUpEE with XFileEE, use the Encryption.Encrypt() method to passs an encrypted header value to XFileEE.
  • Non-visual file transfer engine
    • Allows multiple HTTP Gets or Posts in a single operation
    • Generates events for capture by Internet Explorer or Visual Basic
    • Supports SSL, proxies, and multiple authentication mechanisms
    • Can be used from Internet Explorer (optional silent operation), Visual Basic or ASP
  • Visual upload and download controls
    • Upload and download GUIs work with XFile's file transfer engine
    • Can be used from Windows Internet Explorer, Visual Basic
    • Supports drag-and-drop
    • List of files to transfer can be preset
    • Accurate progress indicator

  • Resumable File Transfer Requests
    • Resumable uploads
    • Resumable downloads

      This feature is notavailable in XFileSE.

  • Server-side file transfers
    • Transfer files without user intervention
    • Perform cascaded uploads (client to server to server)
    • Transfer files from server to server

  • Receive files
    • Download multiple files to preset locations
    • Download to a string or to a file

  • Send files
    • Upload via RFC1867 Post (compatible with SA-FileUp™) or HTTP Put
    • Post a file, several files, and/or form elements

  • Multilingual support
    • SoftArtisans XFile is Unicode compliant, enabling the transfer of data between systems, regardless of language, without the risk of data corruption.

  • Easy to use Shell Extension allows uploads directly from Windows Explorer

  • Integration
    • Use in conjunction with SoftArtisans FileManager™ (included free with SoftArtisans XFile™) to preset files or manipulate files before or after transfer
    • Use with SoftArtisans Archive™ (included free with SoftArtisans XFile™) to compress files before or after transfer
    • Fully compatible with SoftArtisans FileUp™ to receive files on the server


XFile Editions

SoftArtisans offers two editions of XFile:

  • XFileSE
    XFile Standard Edition (XFileSE) can be used with either FileUpSE or FileUpEE on the server. XFileSE can handle uploads of up to 4-GB. XFileSE does not support resumable uploading or downloading.

  • XFileEE
    XFile Enterprise Edition (XFileEE) can be used with either FileUpSE or FileUpEE on the server. There is no upload size limit when you use XFileEE with FileUpEE on the server. XFileEE includes resumable uploading and downloading.
Edition Differences

The following table lists the differences between the two editions of XFile. All other XFile features are available in both editions.

 | XFileSE | XFileEE
Upload size limit | 4-GB | No limit when you use FileUpEE to process the upload on the server.
Resumable uploads | No | Yes
Resumable downloads | No | Yes
Concurrent uploads | Up to 4 | Unlimited

When you create a client-side instance of one of XFile's objects using the HTML <object> tag, you must set the object's classid. The classid specifies which control to create. For example, to create an instance of XFileSE's visual upload control, use:

<OBJECT classid="CLSID:230C3D02-DA27-11D2-8612-00A0C93EEA3C" id="AXFFile"
      codebase="[path]/saxfile.cab">

The objects of XFileSE and XFileEE have different classids. When setting an object's classid, be careful to set the classid for the version of XFile that you are using. The following table lists the classids for XFileSE and XFileEE:

Object | Classid
 | XFileSE | XFileEE
XFRequest | C3A57B60-C117-11D2-BD9B-00105A0A7E89 | 8B3512EF-4FF5-4aa4-9CDE-56BB03E04B9F
AXFFile | 230C3D02-DA27-11D2-8612-00A0C93EEA3C | 7B7929AB-E06A-4508-BE68-1CC7A6997808
AXFFileDownload | B82FA17C-F3A9-11D2-B5DD-0050041B7FF6 | AD58C149-8AE2-4878-99DC-3A164E32F814
AXFFileProgress | C3EAF164-E06A-11D2-B5C9-0050041B7FF6 | 9C6E12BB-F8AE-44aa-9694-9912396B6033
XFResume | Not available in XFileSE | 53B29E97-9753-44B4-AE57-D51322B2BD49
SoftArtisans Archive | D3400FEE-041F-11D3-B1C5-00A0C9B4587A | D3400FEE-041F-11D3-B1C5-00A0C9B4587A
SoftArtisans FileManager | E7B62F4E-82F4-11D2-BD41-00105A0A7E89 | E7B62F4E-82F4-11D2-BD41-00105A0A7E89


New in this Version

New in Version 2.5.1

  • Fully supports non-administrative ActiveX installation in Internet Explorer 8 on platforms running Windows Vista and later (for reference see MSDN article: Non-Admin ActiveX Controls)
  • Significantly improved performance of XFile ASP.NET samples using custom HTML client-side progress indicator

New in Version 2.5.0

  • HTTP Header Encryption when using the XFRequest.AddEncryptedRequestHTTPHeader along with FileUpEE's Encryption.Encrypt() method.*

New in Version 2.3.3

  • Resumable uploads can now be done asynchronously. Previously, the Start method had an asynchronous option, but the Resume method did not.
  • TopFolder property now creates directory structure for storing resume info if the directories do not exist.
  • XFResume.IsOpen method was added to determine if the object is already open to a location.

New in Version 2.2.3

  • TransferStatusChange event has been added to the XFRequest object to encompass the round-trip of a file transfer, from client to server back to the client.
  • The following methods have been added to the XFRequest object to sync events when XFile is run in scripting or VBA environments:
    • AddTransferCompleteEventHandler
    • AddTransferErrorEventHandler
    • AddTransferProgressEventHandler
    • AddTransferStartEventHandler
    • AddTransferStatusChangeEventHandler

New in Version 2.1.4

  • New transfer engine (XFRequest) properties:
    • IsActive
    • OpenAfterDownloadIndex
    • XFRequestStream

  • New XFFile method:
    • OpenInApplication

  • New visual upload control methods and properties:
    • FileViewType
    • FileSelectorWidth
    • FileSelectorHeight
    • FileNameColumnHeading
    • FileSizeColumnHeading
    • AddFileSelectorFilter
    • ClearFileSelectorFilters

  • New visual download control methods and properties:
    • FileNameColumnHeading
    • URLColumnHeading
    • FileNameColumnWidth

  • New visual progress indicator property:
    • DisableAnimatedGif

New in Version 2.0

  • Resumable uploading and downloading with XFileEE.*

  • Unlimited upload size with XFileEE (when you use FileUpEE on the server).*

  • HEAD request support.

  • Cancelmethod lets you cancel the current transfer request in script.

  • DownloadErrorobject allows you to store and retrieve error information.

  • SaveOnDownloadErrorallows you to disable saving of downloaded files if an error occurs.

  • AllDownloadsSuccessfullets you check if an error occured downloading one or more files.

  • SaveLocationPromptTypeand DefaultSavePathproperties let you specify whether XFile should set a download destination directory, or prompt the user to select a destination directory for downloaded files.

  • Support for Windows Integrated authentication and the ability for users to be prompted for their user name and password with Basic authentication.

*This feature is notavailable in XFileSE.


Requirements

System Requirements

  • Internet Explorer 4 or higher* must be installed on the computer running SoftArtisans XFile. The current version of SoftArtisans XFile uses Microsoft's WinInet API, which is supplied with Internet Explorer.

  • 200 Mhz X86 Processor.

  • Microsoft Windows 95/98/Me, NT 4.0 (Server/Workstation), 2000 (Workstation/Server/Advanced Server), XP, or Server 2003, Vista, Server 2008, or 7.

  • 64 MB of RAM.
  • 20 MB of hard disk space during installation.

  • 10 MB of hard disk space after installation.

  • If running SoftArtisans XFile as a server-side component, IIS 4 or later, or Personal Web Server for Windows NT and Win95/98.
* Note regarding recent changes in Internet Explorer's implementation of ActiveX support: You will not need to make any changes to your existing code. The ActiveX control can still be scripted for client side automation. The only difference will be that when using XFile's graphical user interface, the end user will need to click on the object in order to activate it.


Related Products

Related Products from SoftArtisans

Industry-Standard File Transfer Technology

As the leader in HTTP-based file transfer technology, SoftArtisans has been providing world-class products and services since 1996 for both large corporations and individual developers seeking the secure, reliable and cost-effective delivery of business-critical data. Whether it's transferring multi-gigabyte files, providing flexible client-side functionality, or solving complex security and Web farm issues, SoftArtisans provides three different editions to meet your needs: FileUp Standard Edition, FileUp Professional Edition, and FileUp Enterprise Edition.

Delivering Business Information The Way You Want It

Now you can take customized Microsoft Excel and Word reports off your desktop and securely deliver them from a Web server to anyone and anywhere. A cross-platform product available for ASP and ASP.NET, SoftArtisans OfficeWriter is the first Web reporting product that utilizes the most popular content formats - Microsoft Excel and Word – to produce full-function, native Microsoft Office reports for distribution over the Web. This high-powered tool unites SoftArtisans ExcelWriter and WordWriter, allowing users to create, share, and analyze crucial business data through both powerful spreadsheets and rich documents.


install

Installation Instructions

Installing SoftArtisans XFile

Distribution to the Client

Signing XFile

Client-side Installation and Instantiation

Upgrading SoftArtisans XFile

Removing SoftArtisans XFile


Installing SoftArtisans XFile

  • Automatic Installation
  • Manual Installation

    • Did you install an evaluation version of XFile?
    If you did, see Upgrading SoftArtisans XFilefor instructions on upgrading the CAB version on the client.

Automatic installation

Double-click XFile's Setup.exe, and follow the InstallShield instructions. The automatic installation will register XFile's dll files on your server.

By default, the automatic installation copies two sets of dlls to the following directory: C:\Program Files\Software Artisans\SA-XFile. One set is wrapped in a cabinet file (SAXFile.cab in XFileSE and SAXFileEE.cab in XFileEE) that is signed by SoftArtisans, and the other set is found as a collection of individual dlls in the directory. It is the second set of individual files that is registered on the server. The following table lists the files installed with each XFile editon:

XFileEE | XFileSE | Description
SAXFileEE.cab | SAXFile.cab | Cabinet file containing all XFile's dlls except SAXFShExEE.dll/SAXFShEx.dll.
SAXFileEE.dll | SAXFile.dll | Non-visual file-transfer engine
xfclient.dll | xfclient.dll
SAAXFileEE.dll | SAAXFile.dll | Visual upload and download controls
SAXFShExEE.dll | SAXFShEx.dll | Shell extension
SAArch.dll | SAArch.dll | Archive file creation/extraction component
SAFilMgr.dll | SAFilMgr.dll | File management component

Note: SAXFShEx.dll (shell extension) is not included in the SoftArtisans signed CAB file, but is registered on the server with the default installation.

XFile includes two sets of dlls (in a CAB file, and outside of a CAB file) for the following reasons:

  1. In order to use the XFile server-side/ASP code samples, the dlls must be registered on the server. This requires that there exist at least one set of dlls that exist outside of a CAB file.

  2. In order to use the XFile client side/HTML code samples, the dlls must be available in a downloadable CAB file, or distributed and installed by some other method, client-side. Since internet distribution is the most common scenario, a signed CAB file has been provided so that the client-side/HTML code samples can be run immediately.

  3. To discourage malicious use of the CAB file that is signed by SoftArtisans, those dlls have been altered so that they will always display a dialog asking if the user agrees to upload or download a file, regardless of any browser security settings.

  4. The individual dlls that are not included in the CAB file do not ask the user to accept uploads and downloads. This allows for completely hidden and silent file transfer. If an application is to be developed with these dlls and distributed via the internet, they will need to be placed in their own CAB file and signed accordingly.

If you are using one development machine as both client and server, the default installation of XFile may not be ideal for reproducing the client-side experience. See Client-Side Installation for more information.

Manual Installation

To install SoftArtisans XFile the first time, run the automatic installation. Once InstallShield has unpacked the files that contain XFile, you can re-install XFile manually (if, for example, you are moving the component to a different server). By default, the automatic installation installs two sets of dll files: one set is wrapped in a cabinet file that is signed by SoftArtisans, and the other set is a collection of individual dlls. The file names are different in XFileSE and XFileEE. The following table lists the files installed with each edition:

XFileEE | XFileSE | Description
SAXFileEE.cab | SAXFile.cab | Cabinet file containing all XFile's dlls except SAXFShExEE.dll/SAXFShEx.dll.
SAXFileEE.dll | SAXFile.dll | Non-visual file-transfer engine
xfclient.dll | xfclient.dll
SAAXFileEE.dll | SAAXFile.dll | Visual upload and download controls
SAXFShExEE.dll | SAXFShEx.dll | Shell extension
SAArch.dll | SAArch.dll | Archive file creation/extraction component
SAFilMgr.dll | SAFilMgr.dll | File management component

To register the dll files manually:

  1. Copy SAXFile.dll, SAAXFile.dll, SAXFShEx.dll, SAArch.dll, and SAFilMgr.dll to a stable location on your web server, for example, c:\winnt\system32 on Windows NT/2000.

  2. Register each of the dll files in the system registry, as follows.

    • Open a DOS prompt window.
    • Enter "net stop iisadmin /y" to stop the Web server.
    • Enter "regsvr32 path\SAXFile.dll," and click "Ok."
    • Enter "regsvr32 path\xfclient.dll," and click "Ok."
    • Enter "regsvr32 path\SAAXFile.dll," and click "Ok."
    • Enter "regsvr32 path\SAXFShEx.dll," and click "Ok."
    • Enter "regsvr32 path\SAArch.dll," and click "Ok."
    • Enter "regsvr32 path\SAFilMgr.dll," and click "Ok."
    • To restart Web services, enter, "net start w3svc."

Registering the dlls is necessary to run the server-side samples. However, if you do not plan to use XFile in server-side code (that is, instantiate XFile using Server.CreateObject), you do not need to register the dlls. See Client-Side Installation for more information.


Distribution to the Client

Testing Distribution Behavior, Choosing the Appropriate Files

If you are testing your application by using your development machine as both the server and the client, the default installation of XFile may not be ideal for reproducing the client-side experience. This is because two sets of deliberately different dlls are provided with XFile, and the set of dlls that are registered on the server may not be the same set of dlls that are ultimately distributed and registered on the client.

Which dlls are registered on my server by default?

In a typical installation of XFile to a Web server, two sets of dlls are copied to the following directory: C:\Program Files\SoftArtisans\XFile. One set is wrapped in a cabinet file, SAXFile.cab, that is signed by SoftArtisans, and the other set is found as a collection of individual dlls in the directory. It is the second set of individual files that is registered on the server. The following table lists the files installed with each XFile editon:

XFileSE | Description
SAXFile.cab | Cabinet file containing all XFile's dlls except SAXFShEx.dll.
SAXFile.dll | Non-visual file-transfer engine
XFClient.dll | HTTP client components
SAAXFile.dll | Visual upload and download controls
SAXFShEx.dll | Shell extension (not included in the SoftArtisans signed CAB file
SAArch.dll | Archive file creation/extraction component
SAFilMgr.dll | File management component

Why are there two different sets of dlls?
  1. In order to use the XFile server-side/ASP code samples, the dlls must be registered on the server. This requires that there exist at least one set of dlls that exist outside of a CAB file.

  2. In order to use the XFile client side/HTML code samples, the dlls must be available in a downloadable CAB file, or distributed and installed by some other method, client-side. Since internet distribution is the most common scenario, a signed CAB file has been provided so that the client-side/HTML code samples can be run immediately.

  3. To discourage malicious use of the CAB file that is signed by SoftArtisans, those dlls have been altered so that XFile will always warn the user before and upload or download, regardless of any browser security settings.

  4. The individual dlls that are not included in the CAB file do not warn the user before uploads and downloads. This allows for completely hidden and silent file transfer. If an application is to be developed with these dlls and distributed via the internet, they will need to be placed in their own CAB file and signed accordingly.
How does this pose special problems when the client and server are the same machine?

Since the XFile installation package already registered dlls on the machine, the browser will not attempt to download a CAB file*. You will not be reproducing the behavior the remote client will be experiencing. This means that the remote client may be receiving different dlls. The difference could be in the version number of the dlls. Likewise, the difference could be between the warning and non-warning dlls, or in rare circumstances of incomplete removal of an evaluation version, the difference could be between expiring and non-expiring versions of XFile. Other problems that could be masked might include an incorrect path to the CAB file or incorrect permissions on the file or it's directory.

The exception to this can occur when the version number is specified. For more information, see Upgrading SoftArtisans XFile.

How does the browser determine when dlls should be downloaded?

The browser will first check the <object> tag's clsid attribute and try to match that value in the registry. If it cannot be found, then it will attempt to download the CAB file from the path provided in the codebase.

<OBJECT classid="CLSID:230C3D02-DA27-11D2-8612-00A0C93EEA3C" id="AXFFile"
    codebase="/XFileSESamples/SAXFile.cab>

If that clsid can be found in the registry, the associated dll will provide the code that loads into the Web page, instead of the cab file that is referenced in the codebase attribute. Any time the clsid can be found in the registry, the browser will not attempt to download the CAB. The exception to this case can be created when the version of XFile is specified. This is convenient for forcing an upgrade of internet distributed dlls. For more information on this, see Upgrading SoftArtisans XFile.

Avoiding Confusion

There are two ways to prevent confusion when the client and server are the same machine.

  1. If you are planning to distribute XFile to your users using SoftArtisans (or your own) signed CAB file, then manually unregister the XFile dlls from the Web server so that the same machine may be used as a client for testing the client-side experience. For instructions, see Removing SoftArtisans XFile(Note: Do not delete the dlls if you still need them to create your own signed version of the cab file.) This will force the browser to download dlls from the cabinet file specified in the codebase attribute of the <object>tag in the Web page that instantiates XFile.

    It is also important to understand that if the dlls are no longer registered on the Web server, XFile cannot be instantiated server-side using Server.CreateObject for special server-side usage scenarios (server-to-server file transfer, cascading uploads).

  2. Test client-side behavior from a remote client on which XFile was not installed to compare behavior.

With either solution, it is important to understand that once XFile has been downloaded to the browser, those dlls will be registered on the client-machine via Internet Explorer. For repeated testing of the download process on the same client, it will be necessary to remove XFile from the client each time. For instructions on removing these files from Internet Explorer see Removing SoftArtisans XFile.


Signing XFile

Signing SAXFile

By signing your cab file, you are providing a statement of the code's authenticity. ActiveX security measures implemented in Internet Explorer are geared towards preventing the end user from downloading unsigned ActiveX controls. Because of this, you will need to distribute a signed version of the XFile cab file. SoftArtisans provides a SoftArtisans-signed cab file with built-in limitations, or you can create your own cab file with the fully-functional version of the XFile dlls and sign the cab file yourself.

XFile's automatic installation installs two sets of dlls. One set is wrapped in a cabinet file (SAXFile.cab in XFileSE and SAXFileEE.cab in XFileEE) that is signed by SoftArtisans, and the other set is a collection of individual dlls. XFile includes two sets of dlls (in a CAB file, and outside of a CAB file) for the following reasons:

  1. In order to use the XFile server-side/ASP code samples, the dlls must be registered on the server. This requires that there exist at least one set of dlls that exist outside of a CAB file.

  2. In order to use the XFile client side/HTML code samples, the dlls must be available in a downloadable CAB file, or distributed and installed by some other method, client-side. Since internet distribution is the most common scenario, a signed CAB file has been provided so that the client-side/HTML code samples can be run immediately.

  3. To discourage malicious use of the CAB file that is signed by SoftArtisans, those dlls have been altered so that they will always display a dialog asking if the user agrees to upload or download a file, regardless of any browser security settings.

  4. The individual dlls that are not included in the CAB file do not ask the user to accept uploads and downloads. This allows for completely hidden and silent file transfer. If an application is to be developed with these dlls and distributed via the internet, they will need to be placed in their own CAB file and signed accordingly.

The CAB file you receive with XFile (SAXFile.cab with XFileSEand SAXFileEE.cab with XFileEE) is signed by SoftArtisans. It will prompt the user in the case of a hidden upload through the visual upload control, or a hidden download through the visual download control. That is, if you try to transfer a file through the one of the visual controls without displaying the file name in the control (using AXFFile.XFRequest.AddFile or AXFFileDownload.XFRequest.AddFile), XFile will display a dialog asking the user to accept or refuse the upload or download.

Only the CAB version of SoftArtisans XFile will display the file-transfer confirmation dialog. If If the non-CAB version of XFile (the set of individual dlls) is installed on the user's machine, the dialog will not appear.

Signing your own CAB file allows you to,

  1. Prevent the display of the file-transfer confirmation box.
  2. Customize uploads through the Windows Explorer Shell Extension. To customize Shell Extension uploads, include SAXFShEx.dll in your CAB file.

The following table lists the files installed with each XFile editon:

XFileEE | XFileSE | Description
SAXFileEE.cab | SAXFile.cab | Cabinet file containing all XFile's dlls except SAXFShExEE.dll/SAXFShEx.dll.
SAXFileEE.dll | SAXFile.dll | Non-visual file-transfer engine
xfclient.dll | xfclient.dll
SAAXFileEE.dll | SAAXFile.dll | Visual upload and download controls
SAXFShExEE.dll | SAXFShEx.dll | Shell extension
SAArch.dll | SAArch.dll | Archive file creation/extraction component
SAFilMgr.dll | SAFilMgr.dll | File management component

You can sign one CAB including all six dlls, or separate CABs for the following modules.

SoftArtisans XFile Module | SAXFile.dll/SAXFileEE.dll, SAAXFile.dll/SAAXFileEE.dll, [SAXFShEx.dll/SAXFShExEE.dll], SAXFile.inf/SAXFileEE.inf Inclusion of SAXFShEx.dll/SAXFShExEE.dll is optional. Add it to the CAB if you want to Customize uploads through the Windows Explorer Shell Extension .
SoftArtisans Archive Module | SAArch.dll, SAXFile.inf/SAXFileEE.inf
SoftArtisans FileManager Module | SAFilMgr.dll, SAXFile.inf/SAXFileEE.inf

If you intend to sign a CAB containing only one of the modules listed above, create a CAB containing the module's files, and remove from SAXFile.inf all references to dlls you are not including. For example, to sign a SoftArtisans Archive CAB:

  1. Create a CAB including SAArch.dll and SAXFile.inf.
  2. Remove from SAXFile.inf all references to SAXFile.dll, SAAXFile.dll, SAFilMgr.dll, and SAFmgPws.dll.

When creating a CAB for SoftArtisans Archive or SoftArtisans FileManager, remove from SAXFile.inf all references to SAXFShEx.dll, as well as references to SAXFile.dll and SAAXFile.dll.

If you are creating a CAB including SoftArtisans XFile (with or without SoftArtisans Archive and SoftArtisans FileManager), and want to prevent the display of the download confirmation box,

  1. Create a directory and extract SAXFile.cab/SAXFileEE.cab to the new directory.
  2. Find saxfile.dll/saxfileee.dll and saaxfile.dll/saaxfileee.dll in XFile's installation directory (usually, c:\program files\softartisans\SoftArtisans XFile).
  3. Copy the installation directory's saxfile.dll/saxfileee.dll and saaxfile.dll/saaxfileee.dll over the extracted saxfile.dll/saxfileee.dll and saaxfile.dll/saaxfileee.dll.
  4. Create a new CAB from the files in the extracted CAB directory.

To sign XFile you will need:

  1. A Code Signing Certificate
    To sign the applet, you must obtain a standard RSA certificate from a Certificate Authority such as Versign or Thawte.

  2. A Code Signing Tool
    To sign a .cab file for Internet Explorer with Microsoft VM, use Signcode.exe [image].

  3. XFile's Unsigned Dlls Files
    These are the individual dlls in XFile's installation directory (the same directory that contains SAXFile.cab/SAXFileEE.cab). The installation directory is usually C:\Program Files\Software Artisans\XFile.
CAB Signing Steps
  1. Obtain a standard RSA certificate from Verisign or Thawte.

  2. Obtain the code signing tool Signcode.exe [image].

  3. Locate XFile's unsigned dll files. These are the individual dlls in XFile's installation directory (the same directory that contains SAXFile.cab/SAXFileEE.cab). The installation directory is usually C:\Program Files\Software Artisans\XFile.

  4. Follow the instructions in How to Package Components for Internet Distribution [image].


Client-Side Installation & Instantiation

Client-side Installation and Instantiation

CAB Installation in Non-Admin mode

As of version 2.5.1, XFile's CAB installation fully supports non-administrative ActiveX installation in Internet Explorer 8on platforms running Windows Vista and later. In prior versions of XFile, regardless of the version of Internet Explorer or Windows OS, the user needed to have administrative privileges to be able to install XFile through Internet Explorer. Now with version 2.5.1, on Windows Vista and later, a standard user can install XFile through IE8 in per-user mode, which does not require UAC elevation for administrative privileges and installs the control under the user's profile on the machine.

For non-admin mode installation, the user will just need to select the "Install This Add-on..." option from the information bar in IE8 when prompted for "This website wants to install the following add-on: 'SoftArtisans XFile' from 'Software Artisans, Inc'. If you trust the website and the add-on and want to install it, click here...". If the user selects the "Install This Add-on for All Users on This Computer..." option (which is the machine-wide install mode), then the user will be prompted a UAC dialog to enter an admin password.

Installation of XFile on the client is handled by the browser when it encounters a request to instantiate and XFile object. If the browser cannot locate the needed dlls, it will make a request to the server for the XFile cab, and install these dlls. All of this depends on proper use of the HTML <OBJECT> tag, which is used to instantiate XFile in the browser.

The <OBJECT> tag

To create client-side instances of XFile's main objects, SoftArtisans FileManager, or SoftArtisans Archive, use the HTML <object> tag with the appropriate classid.

classid

The classid specifies which control to create (the various classids are listed below). For example, to create an instance of XFileSE's visual upload control, use,

<OBJECT classid="CLSID:230C3D02-DA27-11D2-8612-00A0C93EEA3C" id="AXFFile"
      codebase="[path]/saxfile.cab#version=x,x,x,x">

id

The attribute id specifies a name for the object instance you create. You can supply any name as an id. Use the id to refer to the object in your script. For example, if you named your instance of the visual control "AXFFile," use the following to add a file to this object's file collection via script:

<script>
      ...
      AXFFile.AddFile "x:\filename.ext"
      ...
      </script>

codebase

The codebase attribute specifies the location of XFile's cab file on the webserver. If the classid of the object you are trying to instantiate is not found in the client registry, the browser will make a request to download a copy of the cabfile, register the dlls and then instantiate the object in your code.

codebase... #version

The version property of the codebase attribute should be specified in order to force the client to run the version of the object that you specify. If the version property is specified, the browser will check to make sure that the dll registered on the client is at least that version or higher. If the client has a lower version of the dll installed, the browser will make a fresh request for the cab file and register the newer dlls.

To find the version number for a control:

  1. Extract the appropriate file from the SAXFile.cab (see thetable below to match objects with appropriate dlls)
  2. Right-click on the dll.
  3. Choose "Properties"
  4. Select the "Version" tab
  5. Copy the dll version number to the codebase...#version attribute of the <OBJECT> tag, remembering to replace the period separators with comma separators to comply with <OBJECT> tag syntax.

Let's say the version number of the visual control (AXFFile object, SAAXFile.dll file) is 2.0.1.0. Add "version=2,0,1,0" to the codebase attribute:

<OBJECT classid="CLSID:230C3D02-DA27-11D2-8612-00A0C93EEA3C" id="AXFFile"
      codebase="/SAXFileSamples/saxfile.cab#version=2,0,1,0">

This will assure that your end users are running at least this version of the control. Please see Upgrading XFile for more information on this topic.

A Note on Proxy Servers:

Proxy servers may cache a copy of the cab file and return this cached copy to the browser. It is possible that although the browser detects an outdated version and requests a new copy of the cab file, the request may be fulfilled by the proxy, which may contain a copy of an outdated cab file. In this circumstance, you will not be able to force a client upgrade until the content expiration value of the cached copy of the cab file is reached. In order to prevent this kind of scenario, be sure to set the HTTP content expiration header of the cab file to expire immediately. These should be done as part of your application planning from the beginning. In order to do this:

  1. Open the IIS console on the webserver.
  2. Locate the XFile cab file in your web application directory.
  3. Right-click on the cab file, choose "Properties".
  4. On the "HTTP Headers" tab, check "Enable Content Expiration" then check "Expire Immediately"

The following tables list the objects you can create using the <object> tag, the dlls containing the objects, and their classids. Note that the objects of XFileSE and XFileEE have different classids. When setting an object's classid, be careful to set the classid for the version of XFile that you are using.

XFileEE

Object | Dll | Classid
XFRequest | XFileEE.dll | 8B3512EF-4FF5-4aa4-9CDE-56BB03E04B9F
AXFFile | SAAXFileEE.dll | 7B7929AB-E06A-4508-BE68-1CC7A6997808
AXFFileDownload | SAAXFileEE.dll | AD58C149-8AE2-4878-99DC-3A164E32F814
AXFFileProgress | SAAXFileEE.dll | 9C6E12BB-F8AE-44aa-9694-9912396B6033
XFResume | Resume.dll | 53B29E97-9753-44B4-AE57-D51322B2BD49
SoftArtisans Archive | SAArch.dll | D3400FEE-041F-11D3-B1C5-00A0C9B4587A
SoftArtisans FileManager | SAFilMgr.dll | E7B62F4E-82F4-11D2-BD41-00105A0A7E89

XFileSE

Object | Dll | Classid
XFRequest | SAXFile.dll | C3A57B60-C117-11D2-BD9B-00105A0A7E89
AXFFile | SAAXFile.dll | 230C3D02-DA27-11D2-8612-00A0C93EEA3C
AXFFileDownload | SAAXFile.dll | B82FA17C-F3A9-11D2-B5DD-0050041B7FF6
AXFFileProgress | SAAXFile.dll | C3EAF164-E06A-11D2-B5C9-0050041B7FF6
SoftArtisans Archive | SAArch.dll | D3400FEE-041F-11D3-B1C5-00A0C9B4587A
SoftArtisans FileManager | SAFilMgr.dll | E7B62F4E-82F4-11D2-BD41-00105A0A7E89


Removing SoftArtisans XFile

Because SoftArtisans XFile is typically distributed from the server and installed on the client, you will need to follow instructions for removing XFile from both locations.

Removing XFile from the Server

Automatic Removal

If you ran the SoftArtisans XFile installer package on the server, you can run the uninstaller to unregister the dlls and remove the Program Folder contents (samples, dlls, documentation).

  • Open the Control Panel and select Add/Remove programs
  • Select "SoftArtisans XFile"
  • Click Change/Remove to run the automatic removal
Manual Removal of XFileSE
  • Open a DOS prompt window.
  • Enter "net stop iisadmin /y" to stop the web server.
  • Enter "regsvr32 path\SAXFile.dll /u," and click "Ok."
  • Enter "regsvr32 path\xfclient.dll /u," and click "Ok."
  • Enter "regsvr32 path\SAAXFile.dll /u," and click "Ok."
  • Enter "regsvr32 path\SAXFShEx.dll /u," and click "Ok."
  • Enter "regsvr32 path\SAArch.dll /u," and click "Ok."
  • Enter "regsvr32 path\SAFilMgr.dll /u," and click "Ok."
  • To restart Web services, enter, "net start w3svc."
  • Delete SAXFile.dll, xfclient.dll, SAAXFile.dll, SAXFShEx.dll, SAArch.dll, and SAFilMgr.dll.
Manual Removal of XFileEE
  • Open a DOS prompt window.
  • Enter "net stop iisadmin /y" to stop the web server.
  • Enter "regsvr32 path\SAXFileEE.dll /u," and click "Ok."
  • Enter "regsvr32 path\xfclient.dll /u," and click "Ok."
  • Enter "regsvr32 path\SAAXFileEE.dll /u," and click "Ok."
  • Enter "regsvr32 path\SAXFShExEE.dll /u," and click "Ok."
  • Enter "regsvr32 path\SAArch.dll /u," and click "Ok."
  • Enter "regsvr32 path\SAFilMgr.dll /u," OR, "regsvr32 path\SAFmgPws.dll /u," and click "Ok."
  • To restart Web services, enter, "net start w3svc."
  • Delete SAXFileEE.dll, xfclient.dll, SAAXFileEE.dll, SAXFShExEE.dll, SAArch.dll, and SAFilMgr.dll.

Note: If you have ever used the web server as both client and server, you should proceed to "Removing SoftArtisans XFile from the Client", below.

Removing SoftArtisans XFile from the Client

The first time XFile is downloaded to the browser, Internet Explorer registers the XFile dlls on the client. To remove XFile from the client:

  1. Close all instances of Internet Explorer to remove XFile from memory.

  2. Open a new instance of Internet Explorer.

  3. From the Tools menu, select Internet Options.

  4. Under Temporary Internet Files, click Settings.

  5. Click View Objects.

  6. Select and delete any XFile controls that have been installed.

If these controls do not appear in the Internet Explorer Temporary Internet Files Folder after using XFile in a Web page on the client, then it is possible that the XFile dlls were registered directly with regsvr32, and must be removed using regsvr32. See "Manual Removal" above for instructions.

If the dlls were in memory, and you receive any errors about an incomplete removal, it may be necessary to restart the machine before attempting to download and register new dlls.


Upgrading SoftArtisans XFile

Upgrading XFile

Upgrading the Server Installation of XFile

If the SoftArtisans XFile installer package was run on the server, it is best to run the uninstaller before attempting to upgrade your server installation of XFile. Once this is complete, you can run the new installer package on the server.

If you have ever used your server as both the server and the client, you will want to follow instructions for removing XFile from the client, as well.

Upgrading XFile on the client

To upgrade XFile on the client, you must first locate your XFile web application on the webserver and remove the older version of the cab file. Replace it with the newer version that you want to use. Be certain to set up the new cab file in IIS so that the Content-Expiration header is set to "expire immediately". This will prevent proxy servers from caching a copy of this version of the cab file and possibly preventing future upgrades. For more information on how this is done, please see the Installation & Instatiation Section: Note on Proxy Servers

Once the new cab file is in place, you need to update your XFile HTML code so that the <OBJECT> tag's codebase attribute has the new version number specified. Specifying a version number will inform the browser that it must be running at least that version of the object. If the dlls registered on the client are older than the version specified, the browser will make a new request for the cab file, based on the location specified in the codebase attribute and register the dlls contained in the cab file. As long as the cab file at that location was replaced with the newer version, and as long as an older version of the cab is not cached on the proxy, the browser will upgrade the client automatically. You should use the version property on the codebase attribute of all of the XFile objects, including FileManager and Archive.

  1. Extract the appropriate file from the SAXFile.cab (see thetable below to match objects with appropriate dlls)
  2. Right-click on the dll.
  3. Choose "Properties"
  4. Select the "Version" tab
  5. Copy the dll version number to the codebase...#version attribute of the <OBJECT> tag, remembering to replace the period separators with comma separators to comply with <OBJECT> tag syntax.

Let's say the version number of the visual control (AXFFile object, SAAXFile.dll file) is 2.0.1.0. Add "version=2,0,1,0" to the codebase attribute:

<OBJECT classid="CLSID:230C3D02-DA27-11D2-8612-00A0C93EEA3C" id="AXFFile"
      codebase="/SAXFileSamples/saxfile.cab#version=2,0,1,0">

This will assure that your end users are running at least this version of the control.

XFileEE

Object | Dll | Classid
XFRequest | SAXFileEE.dll | 8B3512EF-4FF5-4aa4-9CDE-56BB03E04B9F
AXFFile | SAAXFile.dll | 7B7929AB-E06A-4508-BE68-1CC7A6997808
AXFFileDownload | SAAXFile.dll | AD58C149-8AE2-4878-99DC-3A164E32F814
AXFFileProgress | SAAXFile.dll | 9C6E12BB-F8AE-44aa-9694-9912396B6033
XFResume | SAAXFile.dll | 53B29E97-9753-44B4-AE57-D51322B2BD49
SoftArtisans Archive | SAArch.dll | D3400FEE-041F-11D3-B1C5-00A0C9B4587A
SoftArtisans FileManager | SAFilMgr.dll | E7B62F4E-82F4-11D2-BD41-00105A0A7E89

XFileSE

Object | Dll | Classid
XFRequest | SAXFileEE.dll | C3A57B60-C117-11D2-BD9B-00105A0A7E89
AXFFile | SAAXFile.dll | 230C3D02-DA27-11D2-8612-00A0C93EEA3C
AXFFileDownload | SAAXFile.dll | B82FA17C-F3A9-11D2-B5DD-0050041B7FF6
AXFFileProgress | SAAXFile.dll | C3EAF164-E06A-11D2-B5C9-0050041B7FF6
SoftArtisans Archive | SAArch.dll | D3400FEE-041F-11D3-B1C5-00A0C9B4587A
SoftArtisans FileManager | SAFilMgr.dll | E7B62F4E-82F4-11D2-BD41-00105A0A7E89


Client vs. Server

Understanding the Concepts

Client vs. Server: Understanding what functions where in a web application designed with SoftArtisans file transfer products

FileUp Standard Edition:

FileUp is a server-side component. It installs on the web server as a package of dlls that add the ability to parse through an upload request containing files with or without additional form elements. FileUp is instantiated in server-side script, such as in ASP or ASP.NET. It is designed to accept and RFC-1867 compliant HTTP post. It is not dependent on any specific client, rather it is dependent on receiving a properly formatted POST. Any client that can send an RFC-1867 compliant post is acceptable, whether it is a browser, ActiveX control or applet.

The only visual component to FileUp is the optional progress indicator, which shows server-side" progress, meaning the progress of the processing of an upload after the request has already reached the server.

What can I use as the client?

Anything that can send an RFC 1867-compliant HTTP post, such as the browser, an active-x control or applet can be used as a client.

What do the FileUp Standard Edition samples use as the client?

The FileUp Standard Edition samples use a "MULTIPART/FORM-DATA" encoded HTML form to post the upload request. Therefore, any browser can be used, such as Internet Explorer, Netscape or Firefox, provided that these browsers continue to support the RFC-1867 standard. (For an example of using an active x control as a client, see FileUp Professional Edition.)

Because FileUp is a server-side component, it cannot control any client-side behavior.It can only affect the upload request after it has reached the server.

What are the practical design considerations of this approach?

  • For every file you want to upload, you must provide an HTML input control of the type "file".
  • The user cannot select directories, but rather can only select one file for every control that is available.
  • HTML file input controls cannot be pre-populated via script. The user must select the file.
  • HTML file input controls provide very little control over their appearance.
  • Most browsers have a maximum upload request size limitation of 2 GB.
  • You will not be able to script any limitations on the upload request, such as types of files to be uploaded, or sizes of files. Any limitations that you want to provide need to happen server-side, after the files have already been received on the server.
  • The browser can download only one file per request.
  • All of the common browsers support HTML forms.
  • No additional software needs to installed client-side, other than the browser.

FileUp Professional Edition (FileUpSE + XFileSE)

FileUp Professional Edition is a package that includes FileUp Standard Edition in addition to XFile Standard Edition. FileUp Professional Edition differs from Standard Edition in that both client-side and server-side solutions are provided.

FileUp on the server:
(see description for FileUp Standard Edition)

XFile as the client:
FileUp requires that the client send an RFC-1867 compliant post. While this can be achieved using the browser and an HTML form, there are certain design limitations, as described above (link to a bookmark at FileUp SE: “What are the practical design considerations of this approach?�?)

XFile is an ActiveXcontrol that can be distributed automatically from your web server, but installs and functions client-side. XFile is instantiated in an HTML object tag in the browser. Even though the browser is required to render the HTML and load XFile as a control, XFile is used as the client instead of the browser. XFile is responsible for sending the Request and receiving the Response.

In addition to circumventing the browser, XFile provides a programmable interface and an optional Graphical User Interface (GUI).

What are the design considerations of this approach?

  • Active X is currently only supported by Internet Explorer
  • XFile provides a rich set of functionality, including the ability to upload folders, multiple files, programmatic control of the user’s visual experience, programmatic control of the types, sizes and amount of files. For a complete list of features supported by XFile, please see: [link to XFile feature list]
  • Upload limit of 2 GB; however smaller limits can easily be enforced before the request is even sent. XFileEE can be used in conjunction with FileUpEE {insert link here} to overcome this limitation.


Using XFile Events

What Transfer Events Are Available, and When Do They Occur?

  1. Events Representing Client-side Activity

    These events only represent client-side activity, meaning from the time XFile begins to send the Request, to when the Request has completely been sent by XFile. These events do not represent server-side events.

    Object Name | Event Name | Occurs
    XFRequest | TransferStart | When the data transfer is initiated
    TransferProgress
    • After the transfer of each 16 kilobytes or the value of the BufferSize property
    • At the beginning of the transfer of each file
    TransferComplete | After the Request has completely left the client
    TransferError | If an error occurs client-side while the Request is being made
    AXFFile | OnTransferComplete | After the Request has completely left the client
    OnTransferError | If an error occurs client-side while the Request is being made

  2. Events Representing Round-trip Activity

    This event was encompasses the round-trip, from client to server back to the client.

    Object Name | Code | Enumerator | Message
    XFRequest
    0 | Initializing | XFile is initializing
    1 | TransferStarting | Transfer is Starting
    3 | RequestStarting | A Request is being sent to the server
    4 | RequestComplete | Finished sending Request to the server
    5 | RetrievingResponse | Retrieving Response from the server
    6 | ResponseRetrieved | Response retrieved from the server
    7 | TransferComplete | Transfer is complete
    8 | TransferCancelled | Transfer has been cancelled
    9 | TransferError | An error occurred
    10 | TransferTimedOut | Transfer has timed out
    11 | TransferDataStarting | Transfering Form Elements to Server Starting
    12 | TransferDataComplete | Transfering Form Elements to Server Complete
    13 | TransferFilesStarting | Upload of the Files is Starting
    14 | TransferFilesComplete | Upload of the Files is Complete
    15 | TransferFileStarting | Upload of the File is Starting
    16 | TransferFileComplete | Upload of the File is Complete
    17 | Connecting | Connecting to server
    AXFFILE | Requires a routine to link to the XFRequest object's TransferStatusChange event.
    same codes as above | same enums as above | same messages as above

In What Order do the Events Occur?

The following table is generated by recording all of the events that are triggered by uploading two files with the XFRequest object. The table can be used to compare when the different events occur and in what order. The code for generating this table is available as an attachment to this article. A similar code sample is provided for the AXFFile object.

Round Trip Event Handlers Client Side Events
TransferStatusChange Event Code: 0, XFile is initializing
TransferStatusChange Event Code: 1, Transfer is Starting
TransferStatusChange Event Code: 17, Connecting to server
TransferStart Event POST 2 Files
TransferStatusChange Event Code: 3, A Request is being sent to the server
TransferStatusChange Event Code: 13, Upload of the Files is Starting
TransferStatusChange Event Code: 15, Upload of the File is Starting
TransferProgress Event
Current File: | C:\test1.txt
Bytes Transferred From This File: | 0
Total Bytes of This File: | 1436
Total Bytes Transferred: | 156
Total Bytes: | 3523
TransferProgress Event
Current File: | C:\test1.txt
Bytes Transferred From This File: | 1436
Total Bytes of This File: | 1436
Total Bytes Transferred: | 1592
Total Bytes: | 3523
TransferStatusChange Event Code: 16, Upload of the File is Complete
TransferStatusChange Event Code: 15, Upload of the File is Starting
TransferProgress Event
Current File: | c:\test2.txt
Bytes Transferred From This File: | 0
Total Bytes of This File: | 1719
Total Bytes Transferred: | 1750
Total Bytes: | 3523
TransferProgress Event
Current File: | c:\test2.txt
Bytes Transferred From This File: | 1719
Total Bytes of This File: | 1719
Total Bytes Transferred: | 3469
Total Bytes: | 3523
TransferStatusChange Event Code: 16, Upload of the File is Complete
TransferStatusChange Event Code: 14, Upload of the Files is Complete
TransferProgress Event
Current File: | c:\test2.txt
Bytes Transferred From This File: | 1719
Total Bytes of This File: | 1719
Total Bytes Transferred: | 3523
Total Bytes: | 3523
TransferProgress Event
Current File: | c:\test2.txt
Bytes Transferred From This File: | 1719
Total Bytes of This File: | 1719
Total Bytes Transferred: | 3523
Total Bytes: | 3523
TransferStatusChange Event Code: 4, Finished sending Request to the server
TransferComplete Event Indicates that the Request has completely left the client.
TransferStatusChange Event Code: 5, Retrieving Response from the server
TransferStatusChange Event Code: 6, Response retrieved from the server
TransferStatusChange Event Code: 7, Transfer is complete

How are the Events used?

The events are placed into your client-script in the following manner:

<SCRIPT language='vbs'>
Sub [XFile object name]_[Name of Event]([parameters])
...your code here ...
End Sub
</SCRIPT>

  • Demonstration: Use the TransferStatusChange Event to notify the User when the complete transfer is finished. XFile object used: Transfer-Engine only (XFRequest).

    • Instantiate the XFRequest object in the <BODY> tag of your HTML code.
    <OBJECT CLASSID="clsid:C3A57B60-C117-11D2-BD9B-00105A0A7E89"
codebase="http://DomainName/XFileApplicationDirectory/SAXFile.cab"
ID="XFILE">
</OBJECT>

    In a <SCRIPT> tag, provide the event handler for the TransferStatusChange event. Note, than since ID attribute of XFile's object tag has the value of "XFILE", your event handler will be pre-pended with "XFILE_".

    <SCRIPT language = 'vbs'>
    Sub XFILE_TransferStatusChange( ByVal code, ByVal Message )
    If code = 7 then
    msgbox Message
    End if
    </SCRIPT>
    End Sub

    In the above code snippet, if the TransferStatusChange event handler receives a status code of "7", it will display the associated message, "Transfer is complete" in a pop-up message box.

  • Demonstration: Use the StatusTransferChange Event to notify the User when the complete transfer is finished. XFile object used: Visual Upload Control/GUI (AXFFile).

    • The TransferStatusChange event represents work done by the Transfer Engine (the XFRequest object). XFile's visual control does not have direct access to this event, so you must call a method to add the event handler and create a subroutine that matches the signature of
    TransferStatusChange(Code As Integer, Message As String)
    that will be called by the XFRequest object when a TransferStatusChange event occurs.

    Instantiate the AXFFILE object in the <BODY> tag of your HTML code.

    <OBJECT classid="CLSID:230C3D02-DA27-11D2-8612-00A0C93EEA3C"
    height="200"
    codebase="http://DomainName/XFileApplicationDirectory/SAXFile.cab"
    id="GUI_XFILE"
    style="HEIGHT: 200px; LEFT: 0px; TOP: 0px; WIDTH: 400px"
    width="400"
    VIEWASTEXT>

        <!-- DISABLE the upload button so that we can create our own and run code off of it -->

    <PARAM NAME="EnableUploadButton" VALUE="0">
    </OBJECT>

    <INPUT Type=Button Name="UploadButton" value="Start Upload">

    Create a subroutine that will function as an event handler. It can be named as you choose, but it must be able to accept two parameters to accomodate the event code and event message.

    <SCRIPT language='vbs'>
          '--- This is the sub we will use to handle the XFRequest object's TransferStatusChange events.
          '--- This sub needs to be able to handle
          '--- the same parameters as that event it is linked to:
          '--- the code and the message returned from the XFRequest's
          '--- TransferStatusChange event

          Sub DisplayTheStatusChanges(code,message)
          If code = 7 then
          msgbox message
          End if
          End Sub
          </SCRIPT>

    Call the AddTransferStatusChangeEventHandler method of the XFRequest object. Pass it the name of the subroutine that will handle the events. By doing so, the events can now be reported even though the Start method is being called on the AXFFile object.

    <SCRIPT language = 'vbs'>
          Sub UploadButton_onClick()

          '--- Set the URL where we want to send the data by
          '--- using the CurrentURL property

          Dim XFILE
          Set XFILE = GUI_XFILE.XFRequest
          XFILE.AddTransferStatusChangeEventHandler(GetRef("DisplayTheStatusChanges"))
    ...other xfile code
    GUI_XFILE.Start
          End Sub
          </SCRIPT>


Understanding the Object Model

Understanding the XFILE object model

Choosing Between the Two Main Objects: XFRequest and AXFFile

XFile’s primary functionality lies in its transfer engine, the XFRequest object. It is responsible for performing the actions of the browser - sending a request containing files(uploading) or receiving a response containing files(downloading). The XFRequest object itself has no graphical user interface (GUI). The transfer engine is either used alone, and controlled through client-side script, or it receives instructions from the XFile GUI, the AXFFile object, when the end user interacts with the control.

The XFRequest object is always responsible for the file transfer, but it does not always need to be explicitly instantiated in an HTML <OBJECT> tag. If you are using the XFile GUI (AXFFile object) the XFRequest object is available as a child object of the AXFFile object. So if you are not providing a GUI for your end users, instantiate the XFRequest object with your HTML <OBJECT> tag. If you are providing a GUI, then instantiate the AXFFile object with the <OBJECT> tag. If you then need to access a method or property of the XFRequest object, it can be done so in script, as shown below:

Use XFile without a GUI:
<HTML>
<OBJECT CLASSID="clsid:C3A57B60-C117-11D2-BD9B-00105A0A7E89"
codebase="saxfile.cab"
ID="oXF">
</OBJECT>
<INPUT Type=Button Name="WhatVersionButton" value="Click to check version">

<SCRIPT>
Sub WhatVersionButton_onClick()
Msgbox oXF.Version
End Sub
</SCRIPT>

</HTML>

Use XFile with a GUI:
<HTML>
<OBJECT CLASSID="CLSID:230C3D02-DA27-11D2-8612-00A0C93EEA3C"
codebase="saxfile.cab"
ID="oAX">
</OBJECT>
<INPUT Type=Button Name="WhatVersionButton" value="Click to check version">

<SCRIPT>
Sub WhatVersionButton_onClick()
Msgbox oAX.XFRequest.Version
End Sub
</SCRIPT>

</HTML>

Understanding How to Access the Files:

There are two file collections available with XFile. One collection is associated with the Transfer Engine (XFRequest object). This file collection is the XFFileCollection. The other file collection is associated with the GUI (AXFFile object). This collection is the AXFileCollection. The collection associated with the Transfer Engine is the XFFileCollection.

The difference between these two collections is mostly an issue of visual representation. For example, if you wanted to automatically add a file to the XFile GUI so that the control would be "pre-loaded" for the end-user, you would add it to the AXFileCollection. If you wanted to add a file that would not be seen by the end user, you would add XFFileCollection.

With either file collection, when you need to access the methods or properties of a single file, you do this via the XFFile object.

Options for Progress Indication

Using XFile, you can provide client-side progress indication. This means that XFile is able to provide upload progress indication as the upload request is leaving the client. Likewise, XFile can show the progress of a download as it is being read in client-side.

If XFile is being used with FileUp on the server, you have the option to provide server-side progress indication instead. Server-side progress indication only shows the progress of the server reading in the upload request. FileUp’s progress indicator cannot be used in downloads.

Provided that delays in the transfer process are more likely to happen client-side (slow connections, dial-up support), client-side progress indication can often be the more useful of the two options for progress indication.

XFile provides two options for client-side progress indication:

  1. Use the XFile progress indicator object (AXFFileProgressIndication object) with either the transfer engine alone or with the GUI + transfer engine. XFile’s progress indicator object provides a GUI (See screenshot below) that only needs to be synchronized before the upload begins. You do not need to design any visual elements.

  2. Use XFile's progress indication event handler (TransferProgress Event) to design your own progress indicator. This approach allows you to create your own visual elements for progress indication. To understand more about how to use the Transfer Progress Event effectively, please see Using XFile Events.


Programmer's Guide

The Programmer's Guide contains a tutorial that will show you how to use SoftArtisans XFile.

Contents
  1. FileUp and FileUpEE
  2. A Simple Internet Explorer Upload
  3. A Simple ASP Upload
  4. A Simple Visual Basic Upload
  5. Adding a Progress Indicator
  6. Adding a Progress Indicator in Visual Basic
  7. Downloading a File
  8. Downloading a File in Visual Basic
  9. Uploading with the ActiveX Control
  10. Uploading with the ActiveX Control in Visual Basic
  11. Downloading with the ActiveX Control
  12. Downloading with the ActiveX Control in Visual Basic
  13. Resumable Uploading
  14. Resumable Downloading
  15. Using the Shell Extension
  16. Using SoftArtisans XFile Server-side
  17. Recursive Directory Upload
  18. Multilingual Support
  19. SoftArtisans Archive
  20. SoftArtisans FileManager
  21. Programmer's Samples


Server-side Processing: FileUp and FileUpEE

A file upload includes two parts:

  • Client-side file submission
  • Server-side upload processing

FileUp [image] and FileUp Enterprise Edition [image] (FileUpEE) are server-side file transfer controls. In most of the following upload examples, XFile performs the client-side file submission, and FileUp processes the upload on the server. The XFile scripts post to FileUp scripts included in the XFileSamples virtual directory. If FileUp is not installed on your server, and you do not want to change the sample scripts, download a free evaluation of FileUp from SoftArtisans. If you choose to use another component to accept the upload, modify the server-side scripts accordingly.

XFile Enterprise Edition (XFileEE) offers resumable uploading and downloading. To create a resumable upload application, you must use FileUpEE to handle the server-side file transfer processing.


A Simple Internet Explorer Upload

The following example uses XFile within an HTML page. The example demonstrates presetting two files to be uploaded, and posting these files to the server. The user will initiate the upload by hitting a button. The files are posted to an ASP page on the server called formresp.asp. Formresp.asp processes the upload using SoftArtisans FileUp. (For detailed information on SoftArtisans FileUp, review the tutorial included in the SoftArtisans FileUp documentation.)

Exercise: A Simple Internet Explorer Upload

Create an HTML document that includes the following lines of script.

<SCRIPT LANGUAGE="VBS">

    Sub UploadButton_OnClick()

    'Set the URL to which you want to send the data, using the CurrentURL property
    SAXFile.CurrentURL = "http://localhost/SAXFileSamples/asp/post/onefile/formresp.asp"

    'Set the files to be uploaded
    SAXFile.AddFile "C:\Boot.ini", "File1"
    SAXFile.AddFile "C:\AutoExec.bat", "File2"

    'Begin the transfer
    SAXFile.Start

    'Disable the upload button
    Document.All("UploadButton").Disabled = True

    End Sub

    </SCRIPT>

    <!-- Instructions for the user: -->
    To upload your autoexec.bat and boot.ini files to the server, click the Upload button.

    <!-- Create a button for upload submission -->
    <Input Type=Button Name="UploadButton" Value="Upload">

    <!-- Create an instance of XFile -->
    <OBJECT CLASSID="clsid:C3A57B60-C117-11D2-BD9B-00105A0A7E89"
    codebase="saxfile.cab"
    ID="SAXFile">
    </OBJECT>
    </BODY>
    </HTML>
Understanding the Script
  • The OBJECT tag creates an instance of the XFile object and gives it the ID of SAXFile for future reference. Any reference to XFile will be referring to the instance of the XFile object created by this tag.

    The objects of XFileSE and XFileEE have different classids. When setting an object's classid, be careful to set the classid for the version of XFile that you are using. The following table lists the classids for XFileSE and XFileEE:

    Object | Classid
    XFileSE | XFileEE
    XFRequest | C3A57B60-C117-11D2-BD9B-00105A0A7E89 | 8B3512EF-4FF5-4aa4-9CDE-56BB03E04B9F
    AXFFile | 230C3D02-DA27-11D2-8612-00A0C93EEA3C | 7B7929AB-E06A-4508-BE68-1CC7A6997808
    AXFFileDownload | B82FA17C-F3A9-11D2-B5DD-0050041B7FF6 | AD58C149-8AE2-4878-99DC-3A164E32F814
    AXFFileProgress | C3EAF164-E06A-11D2-B5C9-0050041B7FF6 | 9C6E12BB-F8AE-44aa-9694-9912396B6033
    XFResume | Not available in XFileSE | 53B29E97-9753-44B4-AE57-D51322B2BD49

  • When the user clicks the upload button, the UploadButton_OnClick procedure fires.

  • The UploadButton_OnClick procedure:

    • SAXFile.CurrentURL assigns the page to which the files will be posted. In this example, the files are posted to formresp.asp which uses SoftArtisans FileUp to process the upload.

    • The two SAXFile.AddFile lines preset files to upload. Addfile takes two parameters: the path and file name on the client, and an item name for reference to the file on the server.

    • SAXFile.Start begins the upload process.

    • Document.All("UploadButton").Disabled disables the button, for aesthetic purposes.


A Simple ASP Upload

In A Simple Internet Explorer Upload we created an instance of the XFile object on the client using HTML's OBJECT tag. When using XFile within an ASP page, create an instance of XFile on the serverusing Server.CreateObject. In this case, the client Button_OnClick event is not necessary to initiate the upload. In ASP, XFile can upload a file from the client with no user intervention.

Exercise: A Simple ASP Upload

Create an ASP page that includes the following lines of script.

<%
    '--- Create an instance of the XFRequest Object, XFile's principal object
    Set SAXFile = Server.CreateObject("SoftArtisans.XFRequest")

    '--- Set the Server to which you are uploading
    SAXFile.Server = "localhost"

    '--- Set the specific script to which you are uploading
    SAXFile.ObjectName = "/saxfilesamples/asp/post/onefile/formresp.asp"

    '--- Set a file to upload
    SAXFile.AddFile "C:\boot.ini", "File1"

    '--- Begin transferring the files
    SAXFile.Start

    '--- Display the response
    Response.Write( SAXFile.Response )
    %>
Understanding the Script
  • Server.CreateObject creates an instance of the XFRequest object on the server. XFRequest is XFile's principal object. XFRequest sends the HTTP request (Get, Post, or Put) to the server.

    The objects of XFileSE and XFileEE have different ProgIds. When creating a server-side instance of an XFile object, be careful to set the ProgId for the version of XFile that you are using. The following table lists the ProgIds for XFileSE and XFileEE:

    Object | ProgId
    XFileSE | XFileEE
    XFRequest | SoftArtisans.XFRequest | SoftArtisans.XFRequestEE
    XFResume | Not available in XFileSE | SoftArtisans.XFResumeEE

  • SAXFile.Server sets the domain to which the file will be posted. In this example we use "localhost." If we were posting through the Internet, we would use the format "www.domain.com."

  • SAXFile.ObjectName specifies the exact page to which our request will be posted. In this case, it is formresp.asp, located in /saxfilesamples/asp/post/onefile. Formresp.asp uses SoftArtisansFileUp to process the upload.

  • SAXFile.AddFile presets a file to upload. Addfile takes two parameters: the path and file name on the client, and an item name for reference to the file on the server.

  • SAXFile.Start initiates the file transfer.

  • Finally, we display the server response to our request, so that we can see the results of our upload attempt.


A Simple Visual Basic Upload

To use XFile from Visual Basic, add XFile to your list of VB references.

Exercise: A Simple Visual Basic Upload
  1. Create a new, standard, Visual Basic project.

  2. Open the Project menu, select References.

  3. If you are using XFileSE, check "SAXFile 2.0 Type Library". If you are using XFileEE, check "SAXFileEE 2.0 Type Library". (See, XFile Editions for information on the two editions.)

  4. Create a command button on your form, name it cmdSendFiles, and give it an appropriate caption (such as, "Upload").

  5. Enter the following code in the code section of your form.
    Private Sub cmdSendFiles_Click()

        '--- Create an instance of the XFRequest object, XFile's principal object
        Set XFile = New XFRequest

        '--- Set the Server to which you are uploading
        XFile.Server = "localhost"

        '--- Set the specific script to which you are uploading
        XFile.ObjectName = "/SAXFileSamples/asp/post/onefile/formresp.asp"

        '--- Set a file to upload
        XFile.AddFile "C:\boot.ini", "File1"

        '--- Begin transferring the files
        XFile.Start

        '--- Destroy the XFRequest Object
        Set XFile = Nothing

        End Sub
  6. Run the project and click on the upload button. Boot.ini will be uploaded to the local server.
Understanding the Script
  • Set XFile = New XFRequest creates an instance of the XFRequest object. XFRequest is XFile's principal object. XFRequest sends the HTTP request (Get, Post, or Put) to the server.

  • SAXFile.Server sets the domain to which the file will be posted. In this example we use "localhost." If we were posting through the Internet, we would use the format "www.domain.com."

  • SAXFile.ObjectName specifies the exact page to which our request will be posted. In this case, it is formresp.asp, located in /saxfilesamples/asp/post/onefile. Formresp.asp uses SoftArtisans FileUp to process the upload.

  • SAXFile.AddFile presets a file to upload. Addfile takes two parameters: the path and file name on the client, and an item name for reference to the file on the server.

  • SAXFile.Start initiates the file transfer.

  • Set XFile = Nothing destroys the project's instance of the XFRequest object. This prevents draining of your resources.


Adding a Progress Indicator

Using XFile's TransferProgress event, you can create a progress indicator that will allow the user to monitor the progress of a file upload. The TransferProgress event fires,

  • After the transfer of each 16 kilobytes (or the value of BufferSize)
  • At the beginning of the transfer of each file

We will create a window to display the progress of the upload. The progress indicator window will be updated every time XFile's TransferProgress Event fires. The window will display,

  • The name of the file currently being transferred
  • The URL to which the file is being uploaded
  • Bytes transferred so far, for the file currently being transferred
  • Total bytes transferred so far

We will be adding to the code we used in A Simple Internet Explorer Upload. New lines are in bold.

Progress Indication with XFileEE and FileUpEE
When using XFileEE with FileUpEE to create a 3-tier upload (client to Web server to file server), use either FileUpEE's server-side progress indicator or FileUpEE's streaming upload feature. If you use XFileEE's client-side progress indication in a 3-tier upload that is not streamed, the progress indicator will show that the upload is 100% complete when it reaches the Web server, and it will stay at 100% while the upload transfers to the file server. For more information on FileUpEE, see the FileUpEE documentation [image].
Exercise: Adding a Progress Indicator

Create an HTML page that includes the following lines of script.

<SCRIPT LANGUAGE="VBS">

      Sub UploadButton_OnClick()

      '--- Set the URL to which you want to send the data, using the CurrentURL property
      SAXFile.CurrentURL = "http://localhost/SAXFileSamples/asp/post/onefile/formresp.asp"

      '--- Set the files to be uploaded
      SAXFile.AddFile "C:\Boot.ini", "File1"
      SAXFile.AddFile "C:\AutoExec.bat", "File2"

      '--- Begin the transfer
      SAXFile.Start

      '--- Disable the upload button
      Document.All("UploadButton").Disabled = True

      End Sub

      '--- The following procedure is called through XFile's
        '--- TransferProgress event

        Sub SAXFile_TransferProgress(BytesTransfered, BytesTransferedThisFile, TotalBytes,_
        TotalBytesThisFile, CurrentFileName, bCancel, CurrentURL)

        If TotalBytesThisFile > 0 then

        '--- Create a progress indicator window displaying the name of the file currently being transferred,
        '--- the URL to which the file is being uploaded, bytes transferred so far, for the file
        '--- currently being transferred, and total bytes transferred so far.

        Set TransferWindow = window.open("","Transfer", "toolbar=no,location=no,directories=no,
        status=no,menubar=no,scrollbars=no,resizable=no,copyhistory=no,width=500,height=200")
        astr = "<HTML&gt;<HEAD><TITLE>" & "Transfer Status" & "</TITLE>"
        astr = astr & "</HEAD>"
        astr = astr & "<BODY><Font face='Arial narrow' size='-1'>"
        astr = astr & "<Table><TR><TD>"
        astr = astr & "Current Filename:</TD><TD>" & currentFileName & "</TD></TR>"
        astr = astr & "<TR><TD>Current Url:</TD><TD>" & currentUrl & "</TD></TR>"
        astr = astr & "<TR><TD>Bytes Transfered:</TD><TD>"& BytesTransferedThisFile & " of " & TotalBytesThisFile & "</TD></TR>"
        astr = astr & "<TR><TD>Total Bytes Transfered:</TD><TD>" & BytesTransfered & " of " & TotalBytes & "</TD></TR>"
        astr = astr & "</Table></Font></BODY></HTML>"

        Else

        End if

        If(isobject(transferwindow)) then
        transferwindow.document.open()
        transferwindow.document.write(astr)
        transferwindow.document.close()
        End if

        End Sub
      </SCRIPT>

      <!--- Instructions for the user --->
      To upload your autoexec.bat and boot.ini files to the server, press the Upload button.

      <!--- Create an upload button --->
      <Input Type=Button Name="UploadButton" Value="Upload">

      <!--- Create an instance of XFile --->
      <OBJECT CLASSID="clsid:C3A57B60-C117-11D2-BD9B-00105A0A7E89" codebase="saxfile.cab"
      ID="SAXFile"></OBJECT>
Understanding the Script
  • The TransferProgress event takes the following arguments.

    • BytesTransferred
      Number of bytes that have been transferred so far

    • BytesTransferredThisFile
      Number of bytes that have been transferred so far for the current file

    • TotalBytes
      Total size of the transfer, in bytes

    • TotalBytesThisFile
      Size of the current file, in bytes

    • CurrentFileName
      Name of the file currently being uploaded

    • bCancel
      Cancels the upload when set to True

    • CurrentURL
      The URL to which the file is being transferred

  • The SAXFile_TransferProgress procedure creates a progress indicator window containing an HTML table. SAXFile_TransferProgress gets the following values and assigns them to table cells:

    • The name of the file currently being transferred, from CurrentFileName

    • The URL to which the file is being uploaded, from CurrentUrl

    • Bytes transferred so far, for the file currently being transferred, from TotalBytesThisFile

    • Total bytes transferred so far, from TotalBytes


Adding a Progress Indicator in Visual Basic

Using XFile's TransferProgress event, you can create a progress indicator in Visual Basic that will allow the user to monitor the progress of a file upload. The TransferProgress event fires,

  • After the transfer of each 16 kilobytes
  • At the beginning of the transfer of each file

We will create form labels to display the progress of the upload. The labels will be updated every time XFile's TransferProgress event fires. The labels will display,

  • The name of the file currently being transferred
  • The percentage of the current file transferred
  • The percentage of all data transferred

Exercise 5: Adding a Progress Indicator with Visual Basic
  1. Create a new, standard, Visual Basic project.

  2. Open the Project menu, select References.

  3. If you are using XFileSE, and check "SAXFile 2.0 Type Library". If you are using XFileEE, and check "SAXFileEE 2.0 Type Library". (See, XFile Editions for information on the two editions.)

  4. Create a command button on your form, name it cmdSendFiles, and give it an appropriate caption (such as, "Upload").

  5. Add two labels to your form and name them TotalTrans and FileTrans. The first will display the progress of the total transfer, and the second will display the progress of the file currently being transferred. Label them appropriately.

  6. Enter the following code in the code section of your form. Note: the code below is based on the sample we used in A Simple Visual Basic Upload; new lines are in bold.
    Private WithEvents XFile As SAXFILELib.XFRequest

        Private Sub cmdSendFiles_Click()
        Dim XFiles As XFFileCollection

        '--- Create an instance of the XFRequest object, XFile's principal object
        Set XFile = New XFRequest

        '--- Set the server to which you are uploading
        XFile.Server = "localhost"

        '--- Set the specific script to which you are uploading
        XFile.ObjectName = "/SAXFileSamples/asp/post/onefile/formresp.asp"

        '--- Set a file to upload
        XFile.AddFile "C:\boot.ini", "FileName1"

        '--- Retrieve the Files collection
        Set XFiles = XFile.Files

        '--- Add a second file to the upload
        XFiles.Add "C:\config.sys", "FileName2"

        '--- Begin transferring the files
        XFile.Start

        '--- Display the transfer response to the user
        Form1.ResponseBox.Text = XFile.Response

        '--- Destroy the XFRequest Object
        Set XFile = Nothing

        End Sub

        Private Sub XFile_TransferProgress(ByVal BytesTransfered As Long, ByVal BytesTransferedThisFile As Long, ByVal TotalBytes As Long, ByVal TotalBytesThisFile As Long, ByVal CurrentFileName As String, bCancel As Boolean, ByVal CurrentURL As String)

        '--- Update the name of the file currently being transferred
        Form1.CurrentFileName.Caption = CurrentFileName
        Form1.CurrentFileName.Refresh

        '--- Update the transfer progress of the current file
        If TotalBytesThisFile > 0 Then
        Form1.FileTrans = Format(((BytesTransferedThisFile / TotalBytesThisFile) * 100), "###.00") & "%"
        End If

        '--- Update the transfer progress of the whole upload (all files)
        If TotalBytes > 0 Then
        Form1.TotalTrans = Format(((BytesTransfered / TotalBytes) * 100), "###.00") & "%"
        End If
        End Sub
  7. Run the script and hit the upload button. You will be able to monitor progress as boot.ini and config.sys are transferred to the local server.
Understanding the Script
  • Declaring the XFRequest object WithEvents enables the object to receive notification of events and to act on those events. Since we will be using the TransferProgress event to create a progress indicator, we must declare XFRequest WithEvents.

  • Form1.ResponseBox.Text = XFile.Response displays the response from the server.

  • The TransferProgress event takes the following arguments.

    • BytesTransferred - number of bytes that have been transferred so far

    • BytesTransferredThisFile - number of bytes that have been transferred so far for the current file

    • TotalBytes - total size of the transfer, in bytes

    • TotalBytesThisFile - size of the current file, in bytes

    • CurrentFileName - name of the file currently being uploaded

    • bCancel - cancels the upload when set to True

    • CurrentURL - the URL to which the upload is going

  • The declaration of the XFile_TransferProgress procedure must be precise, and include all of the parameters listed above.

  • The SAXFile_TransferProgress procedure gets the following values and assigns them to form labels.

    • The name of the file currently being transferred, from CurrentFileName. The label CurrentFileName displays this value.

    • The percentage of the current file transferred, using
      (BytesTransferedThisFile / TotalBytesThisFile) * 100. The label FileTrans displays this value.

    • The percentage of all data transferred, using
      (BytesTransfered / TotalBytes) * 100. The label TotalTrans displays this value.


Downloading a File

By default, XFile's RequestMethod property is set to "Post." To download a file, set RequestMethod to "Get."

Exercise: Downloading a File
  1. Create an HTML file, containing the following lines. Name the file saxfile_get.htm.

    Note: The objects of XFileSE and XFileEE have different classids. When creating the XFRequest's <object> tag select the appropriate classid for the version of XFile that you are using:

    XFRequest Classids
    XFileSE | C3A57B60-C117-11D2-BD9B-00105A0A7E89
    XFileEE | 8B3512EF-4FF5-4aa4-9CDE-56BB03E04B9F
    <SCRIPT LANGUAGE="VBS">
        Sub GetButton_OnClick()

        '--- Set the HTTP request method to GET.
        SAXFile.RequestMethod = "GET"

        '--- Set the server from which to dowload to the value of
        '--- the form field "Site."
        SAXFile.Server = document.all.form1("Site").value

        '--- Set the file to download to the root file on the server.
        SAXFile.ObjectName = "/"

        '--- Assign attributes to the results window, and open it.
        '--- This window will call back	to the object on this page.
        winstyle="height=500,width=500,status=no,toolbar=no,menubar=no,location=no,resizable=yes,scrollbars=yes"
        window.open "saxfile_getresults.htm",null,winstyle

        End Sub
        </SCRIPT>

        <H2>IE Based XFile "Get" Sample</H2>

        <!-- Create an HTML form that submits to this page. --><form action="saxfile_get.htm" method="post" id=form1 name=form1>

        <!-- Create an input field that allows the user to select a server
          from which to download. -->
        Enter a site to get content from: <INPUT name="Site" VALUE="localhost" >

        <!-- Create a download button. --><INPUT Type=button Name="GetButton" value="Get!">
        </form>

        <!-- Instructions for the user--><p> Click the "Get!" button to open the default page on the
        server you selected.

        <!-- Create an instance of the XFRequest object. --><OBJECT classid=clsid:C3A57B60-C117-11D2-BD9B-00105A0A7E89 codeBase=saxfile.cab
        id=SAXFile></OBJECT>
  2. Create an HTML file containing the following lines and name it saxfile_getresults.htm. Save saxfile_getresults.htm and saxfile_get.htm in the same directory.
    <HEAD>
        <TITLE>SoftArtisans IE Based XFile "Get" Sample Results Window</TITLE>
        <SCRIPT Language="JavaScript">
        Function ShowResults() {
        // Call back to the opening page and the XFile object
        // resident on it to start the transfer
        opener.document.all["SAXFile"].Start();
        // Write the response from the transfer to this window
        document.write(opener.document.all["SAXFile"].Response);
        }
        </SCRIPT>
        </HEAD>
        <BODY onload="ShowResults()">
        </BODY>
        </HTML>
Understanding the Script
  • The GetButton_OnClick procedure opens the file saxfile_getresults.htm. Saxfile_getresults.htm runs the ShowResults function upon loading, which starts the download procedure and loads the response within its own window.

  • SAXFile.RequestMethod = "GET" sets the HTTP request method to Get, that is, defines the data transfer as a download.

  • SAXFile.Server assigns the server from which to dowload.

  • SAXFile.ObjectName specifies the page to download.


Downloading a File in Visual Basic

To use XFile file in a Visual Basic application, add XFile to your list of VB references.

By default, XFile's RequestMethod property is set to "Post." To download a file, set RequestMethod to "Get."

Exercise: Downloading a File with Visual Basic
  1. Create a new, standard, Visual Basic project.

  2. Open the Project menu, select References.

  3. If you are using XFileSE, check "SAXFile 2.0 Type Library". If you are using XFileEE, check "SAXFileEE 2.0 Type Library". (See, XFile Editions for information on the two editions.)

  4. Create a command button on your form, name it cmdGet, and give it an appropriate caption (such as, "Download").

  5. Create a blank text box, name it txtSite, and label it "Site."

  6. Create a large text box, and name it "ResponseBox."

  7. Enter the following code in the code section of your form.
Private Sub cmdGet_Click()

    '--- Create an instance of the XFRequest object
    Set SAXFile = New XFRequest

    '--- Set the HTTP request method to Get
    SAXFile.RequestMethod = "GET"

    '--- Set the server from which to download to the value of the text box on the form
    SAXFile.Server = txtSite.Text

    '--- Set the file to download to the root file on the server.
    SAXFile.ObjectName = "/"

    '--- Start the download
    SAXFile.Start

    '--- Display the response to the user
    Form1.ResponseBox.Text = SAXFile.Response

    End Sub
Understanding the Script
  • SAXFile.RequestMethod = "GET" sets the HTTP request method to Get, that is, defines the data transfer as a download.

  • SAXFile.Server assigns the server from which to dowload.

  • SAXFile.ObjectName specifies the page to download.

  • Form1.ResponseBox.Text = SAXFile.Response displays the server response.


Uploading with the ActiveX Control

You can use XFile's powerful XFRequest object with your own user interface, or with XFile's visual ActiveX control. The ActiveX control can be used from Internet Explorer or Visual Basic. It provides an easy-to-use interface that supports both drag-and-drop and file browsing. The ActiveX control includes an accurate progress indicator that allows the user to monitor the progress of the file transfer.
Exercise: Uploading with the ActiveX Control
We will script a simple, one-file upload, using XFile's ActiveX control and its progress indicator. We will create two scripts: AXFFile.htm and AXFFileProgress.htm. The first will create an instance of the ActiveX control object (AXFFile), and the second will create an instance of the progress indicator object(AXFFileProgress).
XFile's ActiveX Control
  1. Create an HTML document containing the following lines of script. Name the file AXFFile.htm.
    <SCRIPT>
        '--- Create a function that will open the progress indicator window,
        '--- and disable the upload button.
        function StartUpload() {
        if (AXFFile.Count > 0){
        winstyle="height=300,width=400,status=no,toolbar=no,menubar=no,location=no";
        window.open("AXFFileProgress.htm",null,winstyle);
        document.all("button1").disabled = true
        }
        else {
        alert("There are no files to upload.");
        }
        }
        </SCRIPT>

        <!-- Create an instance of the ActiveX control  (the AXFFile object),
          and assign values to its properties. -->
        <OBJECT classid="CLSID:230C3D02-DA27-11D2-8612-00A0C93EEA3C" height="200"
        codebase="/SAXFileSamples/saxfile.cab" id="AXFFile"
        style="HEIGHT: 200px; LEFT: 0px; TOP: 0px; WIDTH: 400px" width="400" VIEWASTEXT>
        <PARAM NAME="_cx" VALUE="10583">
        <PARAM NAME="_cy" VALUE="5292">
        <PARAM NAME="Appearance" VALUE="0">
        <PARAM NAME="BackColor" VALUE="16777215">
        <PARAM NAME="BackStyle" VALUE="0">
        <PARAM NAME="BorderColor" VALUE="3452816845">
        <PARAM NAME="BorderStyle" VALUE="0">
        <PARAM NAME="Enabled" VALUE="-1">
        <PARAM NAME="ForeColor" VALUE="0">
        <PARAM NAME="TabStop" VALUE="-1">
        </OBJECT>

        <!-- Create an upload button that will call the StartUpload() function when clicked. --><INPUT id=button1 name=button1 type=button value="Start Upload" onclick = "startupload()">

        <script language="vbs">

        '--- Create an instance of the XFRequest object.
        set xfile = AXFFile.XFRequest

        '--- Set the upload's destination server.
        XFile.Server = "localhost"

        '--- Set the upload's destination file, that is, the script that
        '--- will process the upload on the server.
        XFile.ObjectName = "/saxfilesamples/formresp2.asp"

        '--- Set a file to upload.
        AXFFile.AddFile "c:\boot.ini"
        </script>
  2. Create an HTML document containing the following lines of script. Name the file AXFFileProgress.htm. Save AXFFile.htm and AXFFileProgress.htm in the same directory.
    <HEAD>
        <SCRIPT language="VBS">
        '--- Create a CallBack procedure that will execute when AXFFileProgress.htm is loaded.  The CallBack
        '--- procedure synchronizes the ActiveX control and its progress indicator, and initiates both.
        Sub Callback()

        '--- Assign the value of AXFFile's XFRequestStream property to AXFFileProgress's XFRequestStream
        '--- property.  The AXFFile object represents the ActiveX control, and the AXFFileProgress
        '--- object represents the progress indicator.
        document.all("AXFFileProgress").XFRequestStream = opener.document.all("AXFFile").XFRequestStream

        '--- Start the progress indicator.
        document.all("AXFFileProgress").ShowProgress

        '--- Start the file transfer.
        opener.document.all("AXFFile").Start

        '--- Close the progress window when the transfer is complete (that is, when the Start method
        '--- stops executing).
        window.close
        End Sub
        </SCRIPT>
        </HEAD>

        <BODY onload="callback()">

        <!-- Create an instance of the AXFFileProgress object (the ActiveX control's
          progress indicator). -->
        <OBJECT ID="AXFFileProgress" CLASSID="CLSID:C3EAF164-E06A-11D2-B5C9-0050041B7FF6"></OBJECT>

        <SCRIPT language = vbs>
        '--- Display a message box when the transfer is complete.  This will not work in Javascript.
        sub AXFFileProgress_TransferComplete()
        MsgBox "Transfer completed"
        end sub
        </SCRIPT>
Understanding the Script
  • AXFFile.htm

    • The startupload() function executes when the user clicks the "Start Upload" button.

      Startupload()

      • Assigns attributes to the progress window:
        winstyle="height=300,width=400,status=no,toolbar=no,menubar=no,location=no"

      • Opens the progress window:
        window.open("AXFFileProgress.htm",null,winstyle)

      • Disables the "Start Upload" button on AXFFile.htm (the specified document):
        document.all("button1").disabled = true

    • The OBJECT tag creates an instance of the AXFFile object and gives it the ID "AXFFile" for future reference. Any reference to AXFFile will be referring to the instance of the AXFFile object created by this tag.

      The objects of XFileSE and XFileEE have different classids. Select the appropriate AXFFile classid for the version of XFile you are using:

      AXFFile Classids
      XFileSE | 230C3D02-DA27-11D2-8612-00A0C93EEA3C
      XFileEE | 7B7929AB-E06A-4508-BE68-1CC7A6997808

    • The PARAM tags define the appearance of the ActiveX control.

    • Button1 triggers the startupload() function, when clicked.

    • Set xfile = AXFFile.XFRequest creates an instance of the XFRequest object. XFRequest is XFile's non-visual file-transfer engine. It is the XFRequest object that submits the HTTP request (Post, Get, or Put) from client to server.

    • XFile.Server sets the upload's destination server.

    • XFile.ObjectName sets the upload's destination file, that is, the script that will process the upload on the server. The specified script, formresp2.asp, contains an instance of SA-FileUp, the server-side component that will process the upload.

    • AXFFile.AddFile sets a file to upload.

  • AXFFileProgress.htm

    • The CallBack procedure executes when AXFFileProgress.htm is loaded.

      CallBack

      • Synchronizes the ActiveX control and its progress indicator:
        document.all("AXFFileProgress").XFRequestStream = opener.document.all("AXFFile").XFRequestStream

      • Starts the progress indicator:
        document.all("AXFFileProgress").ShowProgress

      • Starts the file upload:
        opener.document.all("AXFFile").Start

      • Closes the progress window when the transfer is complete:
        window.close

      Document refers to the current window object (AXFFileProgress.htm), and document.openerrefers to its parent window (AXFFile.htm).

    • The OBJECT tag creates an instance of the AXFFileProgress object (the progress indicator).

    • AXFFileProgress_TransferComplete() displays a message box when the transfer is complete.

      The objects of XFileSE and XFileEE have different classids. Select the appropriate AXFFileProgress classidfor the version of XFile that you are using:

      AXFFileProgress Classids
      XFileSE | C3EAF164-E06A-11D2-B5C9-0050041B7FF6
      XFileEE | 9C6E12BB-F8AE-44aa-9694-9912396B6033


Uploading with the ActiveX Control in Visual Basic

To use XFile's ActiveX upload control from Visual Basic,

  • Add SoftArtisans XFile to your list of VB references
  • Add SAAXFile to the components in your VB Toolbox
  • Add the AXFFile control to your VB form

Exercise: Uploading with the ActiveX Control in Visual Basic

We will create a simple, one-file upload in Visual Basic, using XFile's ActiveX control and its progress indicator. The project includes two forms: Form1 and Form2. Form1 contains the upload control AXFFile, and Form2 contains the progress indicator AXFFileProgress.

AXFFile in Visual Basic
  1. Create a new, standard, Visual Basic project.

  2. Open the Project menu, select References.

  3. If you are using XFileSE, and check "SAXFile 2.0 Type Library". If you are using XFileEE, and check "SAXFileEE 2.0 Type Library". (See, XFile Editions for information on the two editions.)

  4. Open the Project menu, select Components.

  5. If you are using XFileSE, and check "SAAXFile 2.0 Type Library". If you are using XFileEE, and check "SAAXFileEE 2.0 Type Library". (See, XFile Editions for information on the two editions.)

  6. From the VB Toolbox, select the control AXFFile and add it to Form1.

  7. Create a command button on Form1, name it Command1, and give it the caption "Upload."

  8. Create a second command button on Form1, name it Command2, and give it the caption "Close."

  9. Enter the following code in the code section of Form1.

    Private Sub Command1_Click()
        Dim XFile As Object
        Set XFile = AXFFile1.XFRequest
        XFile.Server = "localhost"
        XFile.ObjectName = "/saxfilesamples/formresp2.asp"
        Form2.Show
        End Sub

        Private Sub Command2_Click()
        Unload Me
        End Sub

        Private Sub Form_Load()
        AXFFile1.AddFile "c:\boot.ini"
        End Sub

        Private Sub Form_Unload(Cancel As Integer)
        Unload Form2
        End Sub
  10. Add a second form (Form2) to the project.

  11. From the VB Toolbox, select the control AXFFileProgress and add it to Form 2.

  12. Enter the following code in the code section of Form2.

    Private Sub Form_Load()
        Me.Show
        ShowProgress
        StartTransfer
        End Sub

        Private Sub ShowProgress()
        AXFFileProgress1.XFRequest = Form1.AXFFile1.XFRequest
        AXFFileProgress1.ShowProgress
        End Sub

        Private Sub StartTransfer()
        Form1.AXFFile1.Start
        End Sub
Understanding the Script
  • Form1

    • The Command1_Click() procedure

      • Creates an instance of the XFRequest object:
        Dim XFile As Object
        Set XFile = AXFFile1.XFRequest

      • Sets the server to which the file will be posted:
        XFile.Server = "localhost"

      • Specifies the page to which the request will be posted:
        XFile.ObjectName = "/saxfilesamples/formresp2.asp"
        The upload is posted to formresp2.asp, located in /saxfilesamples. Formresp2.asp uses SoftArtisans FileUp to process the upload.

      • Shows Form2, which contains the progress indicator:
        Form2.Show

    • The Command2_Click() procedure

      • Unloads Form1 when the user clicks the "Close" button:
        Unload Me

    • The Form_Load() procedure

      • Sets a file to upload:
        AXFFile1.AddFile "c:\boot.ini"

    • The Form_Unload(Cancel as Integer) procedure

      • Unloads the progress indicator window when the upload control is closed:
        Unload Form2

  • Form2

    • The Form_Load() procedure

      • Shows the progress indicator (Form2):
        Me.Show

      • Calls the ShowProgress() procedure:
        ShowProgress

      • Calls the StartTransfer() procedure:
        StartTransfer

    • The ShowProgress() procedure

      • Synchronizes the XFRequest object and the progress indicator, and starts the progress indicator:
        AXFFileProgress1.XFRequest = Form1.AXFFile1.XFRequest
        AXFFileProgress1.ShowProgress

    • The StartTransfer() procedure

      • Starts the upload:
        Form1.AXFFile1.Start


Downloading with the ActiveX Control

The ActiveX download control displays the URL of the file to download, and the local download destination. The ActiveX control can be used from Internet Explorer or Visual Basic, and includes an accurate progress indicator that allows the user to monitor the progress of the download.

To download with XFile's ActiveX download control, create an instance of the AXFFileDownload object.
Exercise: Downloading with the ActiveX Control in Internet Explorer
We will script a simple, two-file download, using XFile's ActiveX download control and its progress indicator. We will create two scripts: AXFFile_download.htm and AXFFileProgress.htm. The first will create an instance of the ActiveX download object (AXFFileDownload), and the second will create an instance of the progress indicator object(AXFFileProgress).
XFile's ActiveX Download Control
  1. Create an HTML document containing the following lines of script. Name the file AXFFile_download.htm.
    <!-- Create a function that will open the progress indicator window. --><SCRIPT>
        function	StartDownload() {
        winstyle="height=300,width=400,status=no,toolbar=no,menubar=no,location=no";
        window.open("AXFFileProgress.htm",null,winstyle);
        }
        </SCRIPT>

        <!-- Create an instance of the ActiveX download control  (the AXFFileDownload object),
          and assign values to its properties. -->
        <OBJECT classid="CLSID:B82FA17C-F3A9-11D2-B5DD-0050041B7FF6" codebase="/SAXFileSamples/saxfile.cab"
        height="200" id="AXFFileDownload" style="HEIGHT: 200px; LEFT: 0px; TOP: 0px; WIDTH: 400px"
        width="400" VIEWASTEXT>
        <PARAM NAME="_cx" VALUE="10583">
        <PARAM NAME="_cy" VALUE="5292">
        <PARAM NAME="Appearance" VALUE="0">
        <PARAM NAME="BackColor" VALUE="16777215">
        <PARAM NAME="ForeColor" VALUE="0">
        </OBJECT>

        <!-- Create a download button that will call the StartDownload() function when clicked. --><INPUT id=button1 name=button1 type=button value="Start Download" onclick = "startdownload()">

        <script language="vbs">

        '--- Create an instance of the XFRequest object.
        set xfile = AXFFileDownload.XFRequest

        '--- Set files to download.  AXFFileDownload.AddFile takes two parameters: the first is the download
        '--- destination path and file name, and the second is the URL of the file to download.
        AXFFileDownload.AddFile "c:\testone.txt", "http://localhost/saxfilesamples/vb/download/readme.txt"
        AXFFileDownload.AddFile "c:\testone.htm", "http://localhost/saxfilesamples/default.htm"

        </script>
  2. Create an HTML document containing the following lines of script. Name the file AXFFileProgress.htm. Save AXFFile_download.htm and AXFFileProgress.htm in the same directory.
    <!-- Create a CallBack procedure that will execute when AXFFileProgress.htm is loaded.  The CallBack
          procedure synchronizes the ActiveX control and its progress indicator, and initiates both. -->
        <SCRIPT language="VBS">
        Sub Callback()

        '--- Assign the value of AXFFileDownload's XFRequestStream property to AXFFileProgress's
        '--- XFRequestStream property.  The AXFFileDownload object represents the ActiveX control,
        '--- and the AXFFileProgress object represents the progress indicator.
        document.all("AXFFileProgress").XFRequestStream =  opener.document.all("AXFFileDownload").XFRequestStream

        '--- Start the progress indicator.
        document.all("AXFFileProgress").ShowProgress

        '--- Start the file transfer.
        opener.document.all("AXFFileDownload").Start

        '--- Close the progress window when the transfer is complete (that is, when the Start method
        '--- stops executing).
        window.close

        End Sub
        </SCRIPT>

        <!-- Execute the Callback procedure when AXFFileProgress.htm loads.--><BODY onload="Callback()">

        <!-- Create an instance of the AXFFileProgress object (the ActiveX control's
          progress indicator). -->
        <OBJECT ID="AXFFileProgress" CLASSID="CLSID:C3EAF164-E06A-11D2-B5C9-0050041B7FF6"></OBJECT>

        <!-- Display a message box when the transfer is complete.  This will not work in Javascript. --><SCRIPT language = vbs>
        'This will not work in Javascript
        sub AXFFileProgress_TransferComplete()
        MsgBox "Transfer completed"
        end sub
        </SCRIPT>
Understanding the Script
  • AXFFile_download.htm

    • The StartDownload() function executes when the user click the "Start Download" button.

      StartDownload()

      • Assigns attributes to the progress window:
        winstyle="height=300,width=400,status=no,toolbar=no,menubar=no,location=no"

      • Opens the progress window:
        window.open("AXFFileProgress.htm",null,winstyle)

    • The OBJECT tag creates an instance of the AXFFileDownload object and gives it the ID "AXFFileDownload" for future reference. Any reference to AXFFileDownload will be referring to the instance of the AXFFileDownload object created by this tag.

      The objects of XFileSE and XFileEE have different classids. When setting an object's classid, be careful to set the classid for the version of XFile that you are using. Select the appropriate AXFFileDownload classidfor the version of XFile that you are using:

      AXFFileDownload Classids
      XFileSE | B82FA17C-F3A9-11D2-B5DD-0050041B7FF6
      XFileEE | AD58C149-8AE2-4878-99DC-3A164E32F814

    • The PARAM tags define the appearance of the ActiveX control.

    • Button1 triggers the StartDownload() function, when clicked.

    • Set xfile = AXFFileDownload.XFRequest creates an instance of the XFRequest object. XFRequest is XFile's non-visual file-transfer engine. It is the XFRequest object that submits the HTTP request (Post, Get, or Put) from client to server.

    • AXFFileDownload.AddFile sets a file to download. AXFFileDownload.AddFile takes two parameters: Local File and URL. The first specifies the download's local destination path and file name, and the second specifies the URL of the file to download.

  • AXFFileProgress.htm

    • The CallBack procedure executes when AXFFileProgress.htm is loaded.

      CallBack

      • Synchronizes the ActiveX control and its progress indicator:
        document.all("AXFFileProgress").XFRequestStream = opener.document.all("AXFFileDownload").XFRequestStream

      • Starts the progress indicator:
        document.all("AXFFileProgress").ShowProgress

      • Starts the file download:
        opener.document.all("AXFFileDownload").Start

      • Closes the progress window when the transfer is complete:
        window.close

      Document refers to the current window object (AXFFileProgress.htm), and document.openerrefers to its parent window (AXFFileDownload.htm).

    • The OBJECT tag creates an instance of the AXFFileProgress object (the progress indicator).

    • AXFFileProgress_TransferComplete() displays a message box when the transfer is complete.

      The objects of XFileSE and XFileEE have different classids. When setting an object's classid, be careful to set the classid for the version of XFile that you are using. Select the appropriate AXFFileProgress classidfor the version of XFile that you are using:

      AXFFileProgress Classids
      XFileSE | C3EAF164-E06A-11D2-B5C9-0050041B7FF6
      XFileEE | 9C6E12BB-F8AE-44aa-9694-9912396B6033


Downloading with the ActiveX Control in Visual Basic

To use XFile's ActiveX download control from Visual Basic,

  • Add XFile to your list of VB references
  • Add SAAXFile to the components in your VB Toolbox
  • Add the AXFFileDownload control to your VB form

Exercise 11: Downloading with the ActiveX Control in Visual Basic

We will create a simple, one-file download in Visual Basic, using XFile's ActiveX control and its progress indicator. The project includes two forms: Form1 and Form2. Form1 contains the download control AXFFileDownload, and Form2 contains the progress indicator AXFFileProgress.

AXFFileDownload in Visual Basic
  1. Create a new, standard, Visual Basic project.

  2. Open the Project menu, select References.

  3. If you are using XFileSE, and check "SAXFile 2.0 Type Library". If you are using XFileEE, and check "SAXFileEE 2.0 Type Library". (See, XFile Editions for information on the two editions.)

  4. Open the Project menu, select Components.

  5. If you are using XFileSE, and check "SAAXFile 2.0 Type Library". If you are using XFileEE, and check "SAAXFileEE 2.0 Type Library". (See, XFile Editions for information on the two editions.)

  6. From the VB Toolbox, select the control AXFFileDownload and add it to Form1.

  7. Create a command button on Form1, name it Command1, and give it the caption "Download."

  8. Create a second command button on Form1, name it Command2, and give it the caption "Close."

  9. Enter the following code in the code section of Form1.

    Private Sub Command1_Click()
        Dim XFile As Object
        Set XFile = AXFFileDownload1.XFRequest
        Form2.Show
        End Sub

        Private Sub Command2_Click()
        Unload Me
        End Sub

        Private Sub Form_Load()
        AXFFileDownload1.AddFile "c:\temp\Pleasereadme.txt", "http://localhost/saxfilesamples/Readme.txt"
        End Sub

        Private Sub Form_Unload(Cancel As Integer)
        Unload Form2
        End Sub
  10. Add a second form (Form2) to the project.

  11. From the VB Toolbox, select the control AXFFileProgress and add it to Form 2.

  12. Enter the following code in the code section of Form2.

    Private Sub Form_Load()
        Me.Show
        ShowProgress
        StartTransfer
        End Sub

        Private Sub ShowProgress()
        AXFFileProgress1.XFRequest = Form1.AXFFileDownload1.XFRequest
        AXFFileProgress1.ShowProgress
        End Sub

        Private Sub StartTransfer()
        Form1.AXFFileDownload1.Start
        End Sub
Understanding the Script
  • Form1

    • The Command1_Click() procedure

      • Creates an instance of the XFRequest object:
        Dim XFile As Object
        Set XFile = AXFFileDownload1.XFRequest

      • Shows Form2, which contains the progress indicator:
        Form2.Show

    • The Command2_Click() procedure

      • Unloads Form1 when the user clicks the "Close" button:
        Unload Me

    • The Form_Load() procedure

      • Sets a file to download:
        AXFFileDownload1.AddFile "c:\temp\Pleasereadme.txt", "http://localhost/saxfilesamples/Readme.txt"
        AddFile takes two parameters: the destination path and file name, and the name and path of the file to download.

    • The Form_Unload(Cancel as Integer) procedure

      • Unloads the progress indicator window when the download control is closed:
        Unload Form2

  • Form2

    • The Form_Load() procedure

      • Shows the progress indicator window(Form2):
        Me.Show

      • Calls the ShowProgress() procedure:
        ShowProgress

      • Calls the StartTransfer() procedure:
        StartTransfer

    • The ShowProgress() procedure

      • Synchronizes the download control and the progress indicator, and starts the progress indicator:
        AXFFileProgress1.XFRequest = Form1.AXFFileDownload1.XFRequest
        AXFFileProgress1.ShowProgress

    • The StartTransfer() procedure

      • Starts the download:
        Form1.AXFFileDownload1.Start


Resumable Uploading

New in V2

*This feature is not available in XFileSE.

XFile Enterprise Edition (XFileEE) includes resumable uploading and resumable downloading. In a resumable upload, if the file transfer fails, the user will be able to resume the upload from the point at which it stopped.

When you create a resumable upload application with XFileEE, you must use FileUpEEto handle the server-side file transfer processing.

In a resumable upload, XFileEE stores upload data in a temporary directory on the client, before starting the upload. XFileEE's ResumeInfo.CacheRequestproperty allows you to specify whether XFileEE should cache the whole request - including the files to upload - or just store information about the upload. Caching the whole request guarantees the integrity of the request data when an upload is resumed.

On the server, FileUpEE saves information about the upload in a status database. When the upload is resumed, FileUpEE gets the status of the upload - the number of bytes uploaded to the server - from the status database. FileUpEE then sends the upload status to XFileEE, and XFileEE resumes the upload from the point at which it stopped. The upload status database FileUpEEWS.mdb is included in the XFileEE samples directory.

The following resumable upload example includes:

  1. An XFileEE script that submits the upload from the client,
  2. A FileUpEE script that processes the upload on the server,
  3. A FileUpEE status script that gets the status of a failed upload and sends it back to XFileEE, and
  4. An upload status database on the server.

The XFileEE Script

XFileEE's ResumeInfo object is used to enable resumable file transfers, and to set several properties that specify how XFileEE should handle a resumable transfer. The ResumeInfo object tells XFileEE that a file transfer is resumable, before the transfer begins. If a resumable transfer fails, the XFResume object is used to get information about the failed request, and to set properties that relate to the resumed transfer request.

To enable resumable uploading:

  1. Set a ResumeInfo object through the XFRequest object's ResumeInfo property, for example:
        Set XFileResumeInfo = SAXFile.ResumeInfo
  2. Set ResumeInfo's Resumable property to true to tell XFileEE that the upload is resumable, for example:
        XFileResumeInfo.Resumable = True
  3. Set ResumeInfo's StatusURL property, for example:
        XFileResumeInfo.StatusUrl = "http://localhost/xfilesamples/status.asp"
  4. Before resuming an upload, XFileEE gets status information about the failed upload - the number of bytes received on the server so far - from FileUpEE on the server. StatusURL specifies the URL of the FileUpEE script from which to get the status information.

  5. Set ResumeInfo's CacheRequest property to tell XFileEE whether to cache the whole request on the client before uploading, or to cache information about the upload only. Caching the whole request before uploading guarantees the integrity of a resumed upload request. To cache the whole request, set CacheRequest to true, for example:
        XFileResumeInfo.CacheRequest = True
    To cache only information about the upload, set CacheRequest to false, for example:
        XFileResumeInfo.CacheRequest = False
  6. Set ResumeInfo's TopFolder property to let XFileEE know where to cache the upload data that allows a failed upload to be resumed, for example:
        XFileResumeInfo.TopFolder = "C:\TopFolder\"
    If CacheRequest is set to true, the whole file transfer request will be stored in the folder specified by TopFolder. If CacheRequest is set to false, only information about the request will be stored.

  7. If you set CacheRequest to false, and you want to make sure that a failed upload is not resumed if the files to upload were modified since the initial upload request, set ResumeInfo's VerifyChecksumsproperty to true, for example:
        XFileResumeInfo.VerifyChecksums = True
  8. Create a message to display if the upload fails. The message should tell the user that the transfer failed and can be resumed.

  9. Create a "Resume" button that calls XFRequest . Resumeto resume a failed upload, for example:

  10. Sub ResumeButton_onClick()
        MsgBox "Resuming."
        document.all("ResumeButton").disabled = true

        '--- Call Resume and pass the current JobID to resume
        '--- the transfer.
        SAXFile.Resume SAXFile.ResumeInfo.JobId
        ...
        End sub

The following is a sample XFileEE resumable upload script. When the upload fails, the script gets information about the failed upload and displays it to the user. The information is retrieved from the request's RequestRecord, which is accessed through the XFResume object:

    Set XFResumeRecord = XFResume.GetRequestRecord(SAXFile.ResumeInfo.JobID)

To load the XFResume object into your page, use:

<object classid="clsid:53B29E97-9753-44B4-AE57-D51322B2BD49"
    id="XFResume" VIEWASTEXT></object>

</HEAD>
  <SCRIPT LANGUAGE="VBScript">
  '--- The subroutine to call when the
  '--- user clicks the "Upload button":
  Sub UploadButton_onClick()
  '--- Disable the "Upload" button once it's been clicked.
  document.all("UploadButton").disabled = true

  '--- Set the URL of the FileUpEE page on the server to
  '--- XFile should submit the upload.
  SAXFile.CurrentURL = "http://localhost/xfilesamples/resumeupload.asp"

  '--- Set files to upload.
  SAXFile.AddFile "c:\images\image.jpg", "fileOne"
  SAXFile.AddFile "c:\reports\report.doc", "fileTwo"

  '--- Set a ResumeInfo object.
  Set XFileResumeInfo = SAXFile.ResumeInfo

  '--- Turn on resumable uploading.
  XFileResumeInfo.Resumable = True

  '--- Tell XFile to cache the whole upload request on the
  '--- client.  This guarantees the integrity of a resumed
  '--- upload request.
  XFileResumeInfo.CacheRequest = True

  '--- Tell XFile where to cache the upload request on the
  '--- client.  (You can use FileManager's CreateFolder'--- method to create a directory on the client’s machine.)
  XFileResumeInfo.TopFolder = "C:\TopFolder\"

  '--- Set the URL of the FileUpEE page on the server that will
  '--- send the status information of a failed upload to XFile.
  XFileResumeInfo.StatusUrl = "http://localhost/xfilesamples/status.asp"

  '--- To demonstrate resumability, a failure must be forced.
  '--- This signals the Web server processing script to reject
  '--- the upload.  This should not be included in a production
  '--- application.
  If document.all("ForceFailureOn").checked Then
  SAXFile.AddRequestHttpHeader "X-Fail", "true"
  End If

  '--- Start the upload.
  SAXFile.Start

  '--- If the HTTP status from the server is not "200"
  '--- display a pop-up message to the user and show the
  '--- resume information in the Upload Status Messages
  '--- section on the XFile page.
  If Instr(SAXFile.ResponseStatus,"200") < 1 Then
  MsgBox "Your transfer has failed." & vbCrLf & _
  "The server returned status: " & SAXFile.ResponseStatus & vbCrLf & _
  "You may attempt to resume this transfer.",,"Transfer Failed"
  document.all("ResumeButton").disabled = False
  Call PopulateRequestData
  Else
  '--- If the HTTP status code is "200", the upload
  '--- was successful.
  MsgBox "Your transfer has completed succcessfully." & vbCrLf & _
  "The server returned status: " & SAXFile.ResponseStatus,,"Transfer Complete"
  UploadStatusTD.InnerHTML = "<H2>Response From Server</H2>" & SAXFile.Response
  End If
  End Sub

  '--- If the upload fails, this subroutine displays information
  '--- about the failed upload.
  Sub PopulateRequestData()

  '--- Get the record that holds information about the current
  '--- failed request.
  Set XFResumeRecord = XFResume.GetRequestRecord(SAXFile.ResumeInfo.JobID)

  '--- Create some output to show the user information about the failed transfer

  '--- Show a header.
  strOut = "Upload Failed.<br>"
  strOut = strOut & "Press ""Resume"" to resume the following transfer:<br>"

  '--- Show the JobID of the transfer.
  strOut = strOut & "JobID: " & XFResumeRecord.JobID & "<br>"

  '--- Show the total size of the attempted request.
  strOut = strOut & "Total Request KB: " & Round(XFResumeRecord.UploadRequestKBLength, 1) & "<br>"

  '--- Show the number of kilobytes received on the
  '--- server.
  strOut = strOut & "Total KB Sent" & Round(XFResumeRecord.KBytesTransferred, 1) & "<br>"

  '--- The number of retry attempts so far.
  strOut = strOut & "Retries: " & XFResumeRecord.RetryCount & "<br>"

  '--- List the files that are part of the failed transfer and show the client paths
  strOut = strOut & "Files in request: "
  For Each File In XFResumeRecord.Files
  strOut = strOut & "<br> & File.LocationOnClient
  Next
  strOut = strOut

  '--- Show the info in the Upload Status Messages section on the page
  UploadStatusTD.InnerHTML = strOut
  End Sub

  '--- When the Resume button is clicked, this subroutine will run:
  Sub ResumeButton_onClick()

  MsgBox "Resuming."

  '--- Disable the Resume button once it's been clicked.
  document.all("ResumeButton").disabled = true

  '--- This line is for this sample only!
  '--- Since a failure was forced on the server to demonstrate
  '--- resumability, this header is set to turn off the failure
  '--- to allow the resume to succeed. You will not need this
  '--- line in your actual application.
  SAXFile.AddRequestHttpHeader "Ignore-X-Fail", "true"

  '--- Call Resume and pass the current JobID to resume
  '--- the transfer.
  SAXFile.Resume SAXFile.ResumeInfo.JobId

  '--- Show the server response in the Upload Status Messages
  '--- section on the page.
  UploadStatusTD.InnerHTML = SAXFile.Response
  End sub

  '---
  '--- The following SubRoutines are ActiveX events called by XFile
  '---

  '--- XFile calls the SAXFile_TransferStart Subroutine
  '--- when a transfer is started
  Sub SAXFile_TransferStart(RequestMethod, TotalFiles)
  '--- Use this Sub for any code you would like to run when
  '--- a transfer starts
  MsgBox "Transfer Starting."
  End Sub

  '--- XFile calls the SAXFile_TransferProgress Subroutine
  '--- repeatedly throughout a transfer so that you can monitor
  '--- the transfer progress
  Sub SAXFile_TransferProgress(BytesTransferred, BytesTransferredThisFile, TotalBytes, TotalBytesThisFile, currentFileName, bCancel, CurrentURL)

  '--- Use this Sub to create your own custom progress indicator

  '--- Display the name of the current file being transferred
  CurrentFileNameTD.InnerText = currentFileName

  '--- Display the number of bytes transferred so far for the current file
  PercentTransferredTotalTD.InnerText = Round(100 * (BytesTransferred / TotalBytes)) & "%"

  '--- Show the percent compete per file
  If TotalBytesThisFile > 0 Then
  PercentTransferredThisFileTD.InnerText = Round(100 * (BytesTransferredThisFile / TotalBytesThisFile)) & "%"
  Else
  PercentTransferredThisFileTD.InnerText = "100%"
  End If

  '--- Refresh the table to show the current values
  ProgressTable.Refresh

  End Sub

  '--- XFile calls the SAXFile_TransferComplete Subroutine
  '--- when a transfer has completed
  Sub SAXFile_TransferComplete()
  '--- Use this Sub for any code you would like to run when
  '--- a transfer finishes
  MsgBox "Transfer Completed."
  End Sub
  </SCRIPT>
  </HEAD>
  <BODY>

  <table>
  <tr>
  <!-- This cell is the Transfer Control Panel.
    It contains radio buttons that tell the application
    whether or not to force an upload failure, an
    "Upload" button and a "Resume" button.
   -->
  <td valign="top">
  <TABLE align="center" border=0 width=250 ID="Table1">
  <tr>
  <td bgcolor="#c0c0c0" colspan="2" align="center" width=250><i><b>Transfer Control Panel</b></i></td>
  </tr>
  <TR>
  <TD align="right">Force transfer failure?<br>
  <i>(see note above)</i>
  </TD>
  <TD><input type="radio" name="ForceFailure" value="yes" ID="ForceFailureOn"> Yes<br>
  <input type="radio" name="ForceFailure" value="no" checked ID="ForceFailureOff"> No
  </TD>
  </TR>
  <tr>
  <td align="center" colspan="2">
  <Input Type=Button Name="UploadButton" value="Upload!" ID="Button1">
  <Input Type=Button Name="ResumeButton" value="Resume!" ID="Button2" disabled=true>
  </td>
  </tr>
  </table>
  </td>

  <!-- This cell displays the progress of the upload. -->
  <td valign="top">
  <TABLE border=0 ID=ProgressTable>
  <tr>
  <td bgcolor="#c0c0c0" colspan="2" align="center" width=250><i><b>Transfer Progress</b></i></td>
  </tr>
  <TR>
  <TD width=200 align=right><b>Current File:</b></TD>
  <TD width=50 ID=CurrentFileNameTD>n/a</TD>
  </TR>
  <TR>
  <TD width=200 align=right> <b>% Transferred:</b></TD>
  <TD width=50 ID=PercentTransferredThisFileTD>n/a</TD>
  </TR>
  <TR>
  <TD width=200 align=right><b>% Total Bytes Transferred: </b></TD>
  <TD width=50 ID=PercentTransferredTotalTD>n/a</TD>
  </TR>
  </TABLE>
  </td>
  </tr>
  <tr>
  <td colspan="2"><hr noshade></td>
  </tr>
  <tr>

  <!-- This cell is the Upload Status Messages section. -->
  <td colspan="2" bgcolor="#c0c0c0" align="center"><b><i>Upload Status Messages</i></b></td>
  </tr>
  <tr>

  <td colspan="2">
  <div id="UploadStatusTD">None.</div>
  </td>
  </tr>
  </table>

  <!-- This OBJECT tag loads the XFile and XFResume controls into the page. -->
  <!-- The CODEBASE attribute will change depending on where you deploy the saxfile.cab -->
  <OBJECT CLASSID="clsid:8B3512EF-4FF5-4aa4-9CDE-56BB03E04B9F" ID="SAXFile" CODEBASE="SAXFile.cab" VIEWASTEXT></OBJECT>
  <object classid="clsid:53B29E97-9753-44B4-AE57-D51322B2BD49" id="XFResume" VIEWASTEXT></object>
  </BODY>
  </HTML>

The FileUpEE Upload Processing Script

When you create a resumable upload application with XFileEE, you must use FileUpEE to handle the server-side file transfer processing. For complete instructions on creating a FileUpEE upload processing page, see the FileUpEE documentation. To enable XFileEE to FileUpEE resumable uploading, include the following in your FileUpEE script, before calling FileUpEE's ProcessRequest method:

  1. Set FileUpEE's Resumable(saWebServer) property to true.
  2. Set FileUpEE's ResumeConnectionString(saWebServer) property to the connection string for the upload status database on the Web server.

To demonstrate a resumable upload, the following FileUpEE script forces a transfer failure if XFileEE sent the header "HTTP_X_FAIL" with the transfer request. The XFileEE script above will send this header if you select the "Force failure" radio button when submitting the upload request. If the header was sent, FileUpEE's MaxKBytesToCancel is set to a low value to force an upload failure:

oFileUpEE.MaxKBytesToCancel(saWebServer) = 999999
      If Request.ServerVariables("HTTP_X_FAIL") = "true" Then
      If Request.ServerVariables("HTTP_IGNORE_X_FAIL") <> "true" Then
      oFileUpEE.MaxKBytesToCancel(saWebServer) = 51
      End If
      End If
What is MaxKBytesToCancel?
MaxKBytesToCancel is a property of FileUpEE. FileUpEE will abort a file upload when the size of the transfer reaches the value of MaxKBytesToCancel. No data will be written to the server's hard disk, the connection will be terminated, and the browser will display a "Page not found" message.
Are MaxKBytesToCancel and HTTP_X_FAIL required in a resumable upload?
No. MaxKBytesToCancel and HTTP_X_FAIL are use in this sample script to demonstrate a failed and resumed upload.

The following lines are from a FileUpEE resumable upload script. A complete resumable upload application is included in the XFileEE samples directory.

<%Set oFileUpEE = Server.CreateObject("SoftArtisans.FileUpEE")
  oFileUpEE.TransferStage = saWebServer

  '-----------------------------------------------------------------------------------------------
  '--- Set these properties to activate Client-to-WebServer resumability for XFile
  '-----------------------------------------------------------------------------------------------
  oFileUpEE.Resumable(saWebServer) = True
  oFileUpEE.CopyFiles(saWebServer) = False
  '--- Set the connection string for the webserver's resume database
  oFileUpEE.ResumeConnectionString(saWebServer) ="Provider=Microsoft.Jet.OLEDB.4.0;" & _
  "Persist Security Info=False;Data Source=" & _
  Server.MapPath("../FileUpEEWS.mdb")
  '-----------------------------------------------------------------------------------------------

  '--- Here we read the value of the header we sent along with the post
  '--- from XFile to force a failure for the purposes of this demonstration.
  '--- This will set the MaxKBytesToCancel to fail at 51KB on the webserver
  '--- This is in the sample to force a failure in order to demonstrate
  '--- resumability.  You will not need this in your application.
  oFileUpEE.MaxKBytesToCancel(saWebServer) = 999999
  If Request.ServerVariables("HTTP_X_FAIL") = "true" Then
  If Request.ServerVariables("HTTP_IGNORE_X_FAIL") <> "true" Then
  oFileUpEE.MaxKBytesToCancel(saWebServer) = 51
  End If
  End If

  '--- The following lines receive the resumed upload, name the uploaded file,
  '--- and save it on the server.
  oFileUpEE.ProcessRequest Request, False, False
  oFileUpEE.DestinationDirectory = Server.MapPath("../temp")
  For Each oFile In oFileUpEE.Files
  oFile.DestinationFileName = oFile.ClientFileName
  oFile.Save
  Next

  Response.Write "<H2 align="center">Upload results</H2>"
  '--- If SAResult is saAllProcessed, then all of the files were processed correctly
  If intSAResult = saAllProcessed Then
  Response.Write "<H3>FileUpEE Processed All Files Successfully</H3>"
  Else
  Response.Write "<H3>There was an error processing one or more files</H3>"
  End If
  ...%>

The FileUpEE Status Script

When the user clicks the "Resume" button in the XFileEE page above, the Resume method is called. To resume the upload, XFileEE sends a status request to the FileUpEE status page specified by XFileEE's ResumeInfo . StatusURLproperty. The status page calls FileUpEE's ReturnStatus method, which sends the number of bytes received on the server back to XFileEE. XFileEE then resumes the upload from the point at which it stopped.

The following lines are from a FileUpEE status script. A complete resumable upload application is included in the XFileEE samples directory.

<%
  Set oFileUpEE = Server.CreateObject("SoftArtisans.FileUpEE")
  oFileUpEE.TransferStage = saWebServer

  oFileUpEE.ResumeConnectionString(saWebServer) ="Provider=Microsoft.Jet.OLEDB.4.0;" & _
  "Persist Security Info=False;Data Source=" & _
  Server.MapPath("./FileUpEEWS.mdb")

  '--- Call ReturnStatus() to send the status back to XFile.
  '--- This tells XFile the number of bytes that were received
  '--- on the server, so that XFile can resume the upload from
  '--- the point at which it stopped.
  oFileUpEE.ReturnStatus Request, Response

  Response.End
  %>

The Upload Status Database

When a resumable XFileEE to FileUpEE upload fails, FileUpEE saves information about the upload in a status database on the server. When the user tries to resume the upload, FileUpEE gets the status of the upload - the number of bytes uploaded to the file server - from the status database. FileUpEE's ReturnStatus method returns this information to JFile, and JFile resumes the upload from the point at which it stopped. The upload status database FileUpEEWS.mdb is included in the JFile samples directory.

Top


Resumable Downloading

New in V2

*This feature is not available in XFileSE.

XFile Enterprise Edition (XFileEE) includes resumable downloading and resumable uploading. In a resumable download, if the file transfer fails, the user will be able to resume the download from the point at which it stopped. XFileEE's ResumeInfo object is used to enable resumable file transfers.

To enable resumable downloading:

  1. Set a ResumeInfo object through the XFRequest object's ResumeInfo property, for example:
        Set XFileResumeInfo = XFileEE.ResumeInfo
  2. Set ResumeInfo's Resumable property to true to tell XFileEE that the download is resumable, for example:
        XFileResumeInfo.Resumable = True
  3. Create a message to display if the download fails. The message should tell the user that the transfer failed and can be resumed, for example:
        If instr(XFileEE.ResponseStatus, "200") > 0 then
      Msgbox("Download Completed")
    else
      '--- Display a message to the user with the reason for failure. Ask if
      '--- the user wants to Resume the transfer.
      sMsg = "The download attempt failed. " & vbCrLf
      sMsg = sMsg & "Reason: " & XFileEE.ResponseStatus & vbCrLf & vbCrLf
      sMsg = sMsg & "Would you like to resume the download?"
      ...
  4. If the user chooses to resume the download, call the XFRequest object's Resume method, for example:
        If MsgBox(sMsg, vbYesNo) = vbYes then

      '--- Resume the transfer specified by the following JobId.
      XFileEE.Resume XFileResumeInfo.JobId
      ...
    In a resumable file transfer request, XFile generates a unique JobId for each transfer request (not for each file). To resume a download, pass the download's JobId to the Resume method.

In the following download example, resumable downloading is enabled. To demonstrate resumable downloading, the example forces a download failure by setting XFile's TimeOut property to 2 seconds. If the user chooses to resume the download, TimeOut is reset to a value that will allow a download to complete.

<HTML>
<HEAD>
    <TITLE>SoftArtisans XXFileEE Resumable Download Sample</TITLE>
</HEAD>
<BODY>
<SCRIPT LANGUAGE="VBScript">
'--- This subroutine is called when the user clicks
'--- the download button.
Sub GetButton_onClick()

    '--- Declarations:
    Dim XFileEE
    Dim sMsg

    '--- Disable the download button.
    document.all("GetButton").disabled = true

    '--- Set the request method to GET.
    XFileEE.RequestMethod = "GET"

    '--- Set a ResumeInfo object.
    Set XFileResumeInfo = XFileEE.ResumeInfo

    '--- Enable resumable downloading.
    XFileResumeInfo.Resumable = True

    XFileEE.addfile "c:\downloads\report.doc", "http://localhost/reports/report.doc"
    XFileEE.addfile "c:\downloads\image.jpg", "http://localhost/images/image.jpg"

    '--------- This line is for demonstation only -----------
    '--- Set the TimeOut to 2, so the download will fail
    '--- (this will cause a timeout exception).
    XFileEE.TimeOut = 2
    '------------------------------------------------------------

    '--- Turn default error handling off.
    On error resume next

    '--- Start the download.
    XFileEE.Start

    '--- Check the ResponseStatus.
    If instr(XFileEE.ResponseStatus, "200") > 0 then
        Msgbox("Download Completed")
    else
        '--- Display a message to the user with the reason for failure. Ask if
        '--- the user wants to Resume the transfer.
        sMsg = "The download attempt failed. " & vbCrLf
        sMsg = sMsg & "Reason: " & XFileEE.ResponseStatus & vbCrLf & vbCrLf
        sMsg = sMsg & "Would you like to resume the download?"

        If MsgBox(sMsg, vbYesNo) = vbYes then
            '--------- This line is for demonstation only -----------
            '--- To force a download failure, XFile's TimeOut property was set to 2.
            '--- Before calling resume, reset TimeOut to a value that will allow the
            '--- transfer to succeed.
            XFileEE.Timeout = 90
            '-------------------------------------------------------------

            '--- Resume the transfer specified by the following JobId.
            XFileEE.Resume XFileResumeInfo.JobId

            '--- Check the response
            If instr(XFileEE.ResponseStatus, "200") > 0 OR instr(XFileEE.ResponseStatus, "206") > 0 then
                Msgbox("Resume Completed")
            Else
                Msgbox("Download Failed")
            End If
        Else
            Msgbox("Download Failed")
        End if
    End if

End Sub
</SCRIPT>

<H2>XFileEE Resumable Download Sample</H2>

<p>This sample demonstrates resuming a failed download.
Using XFileEE on the client, this sample will
attempt to download multiple files from the server.
The first attempt will fail, then the reason for the failure will
be displayed and you will be given the opportunity to resume the
download.</p>

<form id="form1" name="form1">
    <INPUT Type=button Name="GetButton" value="Get Files!" ID="Button1">
</form>

<OBJECT id="XFileEE" classid="clsid:8B3512EF-4FF5-4aa4-9CDE-56BB03E04B9F" codebase="saxfile.cab" VIEWASTEXT></OBJECT>
</BODY>
</HTML>

Top


Uploading through the Windows Explorer Shell Extension

XFile enables upload through the Windows Explorer Shell Extension, meaning that you can upload any file on your machine directly from its location. You can customize uploading through the Shell Extension by resetting one or more parameters.

Exercise: Using the Windows Explorer Shell Extension

To upload a file through the Windows Explorer Shell Extension,

  • Right-click the file icon and select "Upload Files Using SAXFile..."

  • Enter a destination URL. Note: make sure that you are uploading to a script that can process the upload (using SoftArtisansFileUp, or another upload component).

  • If the URL to which you are uploading requires authentication, enter the optional user name and password.

  • Click "Ok."

Customizing Uploads through the Shell Extension

You can customize uploads through the Shell Extension by resetting one or more parameters in the file SAXFile.inf. SAXFile.inf is located in SAXFile.cab.

To customize Shell Extension parameters, modify SAXFile.inf, add SAXFShEx.dll to SAXFile.cab, and sign SAXFile.cab.

The Shell Extension parameters you can customize are,

  • SofwareName
    Long software name displayed in some dialog boxes. Default: "XFile Shell Extension"

  • SoftwareShortName
    Short name for XFile displayed in dialog titles. Default: "SAXFile"

  • UploadContextMenuText
    Menu option displayed when a user right-clicks a file icon. Default: "&Upload Files Using SAXFile..."

  • UploadContextMenuHelp
    Status string in Internet Explorer when "Upload Files Using SAXFile..." is selected. Default: "Upload selected files using SAXFile"

  • CompanyName
    Appears in some dialog box titles. Default: "SoftArtisans"

  • ShowURLDialog
    When ShowURLDialog is set to 0 (0x00000000), XFile will not display the dialog box containing URL, User Name, and Password. This dialog box will appear when ShowURLDialog is set to 1 (0x00000001). Default: [0x00010001],0x00000001. DO NOT change the first of the two default parameters (0x00010001).

  • DefaultURL
    URL to which XFile will upload the file, if the user does not provide a different URL. Default: "http://localhost/safileupsamples/UploadSamples/Simple/formresp.asp"

  • DefaultUserName
    User name that XFile will use if the user does not provide a different user name. Default: ""

  • DefaultPassword
    Password that XFile will use if the user does not provide a different password. Default: ""

To set the Shell Extension parameters,

  1. Open SAXFile.inf (included in SAXFile.cab).

  2. Find the following section.
    [AddSoftwareRegistry]
          HKLM,"SOFTWARE\SoftArtisans\XFile\Parameters","SoftwareName",,"XFile Shell Extension"
          HKLM,"SOFTWARE\SoftArtisans\XFile\Parameters","SoftwareShortName",,"SAXFile"
          HKLM,"SOFTWARE\SoftArtisans\XFile\Parameters","UploadContextMenuText",,"&Upload Files Using SAXFile..."
          HKLM,"SOFTWARE\SoftArtisans\XFile\Parameters","UploadContextMenuHelp",,"Upload selected files using SAXFile"
          HKLM,"SOFTWARE\SoftArtisans\XFile\Parameters","CompanyName",,"SoftArtisans"
          HKLM,"SOFTWARE\SoftArtisans\XFile\Parameters","ShowURLDialog",0x00010001,0x00000001
          HKLM,"SOFTWARE\SoftArtisans\XFile\Parameters","DefaultURL",,"http://localhost/safileupsamples/UploadSamples/Simple/formresp.asp"
          HKLM,"SOFTWARE\SoftArtisans\XFile\Parameters","DefaultUserName",,""
          HKLM,"SOFTWARE\SoftArtisans\XFile\Parameters","DefaultPassword",,""
  3. For each parameter you would like to change, replace the default value with another value. For example, if you want to change the menu option XFile displays when the user uploads a file, go to
    HKLM,"SOFTWARE\SoftArtisans\XFile\Parameters","UploadContextMenuText",,"&Upload Files Using SAXFile..."
    and replace the string "&Upload Files Using SAXFile..." with your own text.

  4. Add SAXFShEx.dll to SAXFile.cab. SAXFShEx.dll is located in the XFile installation directory (usually, c:\program files\softartisans\XFile).

  5. Sign SAXFile.cab.


Using SoftArtisans XFile Server-side

Using XFile Server-side

In A Simple ASP Upload we created an instance of XFile on the server using Server.CreateObject, and uploaded a file from client to server without user intervention. When used server-side, XFile can also,

  • Transfer files from server to server
  • Perform a cascaded upload, from client to server to server

Exercise: Cascaded Upload

We will create four short scripts to produce a cascaded upload:

  • AXFFile.htm
    A client-side script containing XFile's visual ActiveX control

  • AXFFileProgress.htm
    The ActiveX progress indicator

  • Formresp.asp
    A server-side script containing an instance of SoftArtisans FileUp, and a server-side instance of XFile. SoftArtisans FileUp receives the uploaded file on the server, and XFile transfers the file to a second server.

  • Formresp2.asp
    A second server-side script containing an instance of SoftArtisans FileUp. SoftArtisans FileUp receives the file on the second server
  1. Create an HTML script containing the following lines. Save the file as AXFFile.htm. (See Uploading with the ActiveX Control for a complete explanation of AXFFile.htm.)

    The objects of XFileSE and XFileEE have different classids. When creating the AXFFile's <object> tag select the appropriate classid for the version of XFile that you are using:

    AXFFile Classids
    XFileSE | 230C3D02-DA27-11D2-8612-00A0C93EEA3C
    XFileEE | 7B7929AB-E06A-4508-BE68-1CC7A6997808
    <SCRIPT language="Javascript>
        function startupload() {
        if (AXFFile.Count > 0){
        winstyle="height=300,width=400,status=no,toolbar=no,menubar=no,location=no";
        window.open("AXFFileProgress.htm",null,winstyle);
        document.all("button1").disabled = true
        }
        else {
        alert("There are no files to upload.");
        }
        }
        </SCRIPT>

        <OBJECT classid="CLSID:230C3D02-DA27-11D2-8612-00A0C93EEA3C" height="200" codebase="/SAXFileSamples/saxfile.cab"
        id="AXFFile" style="HEIGHT: 200px; LEFT: 0px; TOP: 0px; WIDTH: 400px" width="400" VIEWASTEXT>
        <PARAM NAME="BackColor" VALUE="16777215">
        <PARAM NAME="BackStyle" VALUE="0">
        <PARAM NAME="Enabled" VALUE="-1">
        <PARAM NAME="TabStop" VALUE="-1">
        </OBJECT>

        <INPUT id=button1 name=button1 type=button value="Start Upload" onclick = "startupload()">

        <script language="Javascript">
        var XFile = AXFFile.XFrequest;
        XFile.Server = "server1";
        XFile.ObjectName = "/SAXFileCascade/formresp.asp";
        AXFFile.AddFile("c:\\boot.ini");
        </script>
  2. Create a second HTML script containing the following lines. Save the file as AXFFileProgress.htm. (See Uploading with the ActiveX Control for a complete explanation of AXFFileProgress.htm.)
    <SCRIPT language="VBS">
        Sub Callback()
        document.all("AXFFileProgress").XFRequestStream =  opener.document.all("AXFFile").XFRequestStream
        document.all("AXFFileProgress").ShowProgress
        opener.document.all("AXFFile").Start
        opener.document.all("Response").InnerHtml = opener.document.all("AXFFile").XFRequest.Response
        window.close
        End Sub
        </SCRIPT>

        </HEA>
        <BODY onload="callback()">
        <OBJECT ID="AXFFileProgress" CLASSID="CLSID:C3EAF164-E06A-11D2-B5C9-0050041B7FF6"></OBJECT>
        <SCRIPT language = vbs>
        'This will not work in Javascript
        sub AXFFileProgress_TransferComplete()
        MsgBox "Transfer completed"
        end sub
        </SCRIPT>
  3. Create an ASP script containing the following lines. Save the file as formresp.asp in a virtual directory called /SAXFileCascade on the first server.
    <%
        '--- Create an instance of SoftArtisans FileUp.
        Set upl = Server.CreateObject("SoftArtisans.FileUp")

        '--- Set the upload destination on the server.
        upl.Path = "c:\temp"

        '--- Save the uploaded file.
        upl.Save

        '--- Display an upload confirmation for the first server.
        Response.Write("SERVER 1: Upload saved successfully to " & upl.ServerName)

        '--- Create an instance of XFile.
        Set SAXFObj = Server.CreateObject("SoftArtisans.XFRequest")

        '--- Set the second server to which to transfer the uploaded file.
        SAXFObj.Server = "server2"
        SAXFObj.ObjectName = "/XFileCascade/formresp2.asp"
        SAXFobj.addfile upl.servername, "file1"
        SAXFObj.Start
        Response.Write (SAXFObj.Response)
        %>
  4. Create an ASP script containing the following lines. Save the file as formresp2.asp in a virtual directory called /SAXFileCascade on the second server.
    <%
        '--- Create an instance of SoftArtisans FileUp.
        Set upl = Server.CreateObject("SoftArtisans.FileUp")

        '--- Set the transfer destination on the second server.
        upl.Path = "c:\temp"

        '--- Save the transferred file on the second server.
        upl.Save

        '--- Display a transfer confirmation for the second server.
        Response.Write ("SERVER 2: File transferred successfully to " & upl.ServerName)
        %>
Understanding the Script
  • AXFFile.htm and AXFFileProgress.htm
    See Uploading with the ActiveX Control for a complete explanation of AXFFile.htm and AXFFileProgress.htm.

  • Formresp.asp
    • Set upl = Server.CreateObject("SoftArtisans.FileUp")creates an instance of SoftArtisans FileUp, the server-side file-transfer component that will receive and save the upload.

    • upl.Path sets the upload destination on the server.

    • upl.Save saves the uploaded file on the server.

    • Response.Write("SERVER 1: Upload saved successfully to " & upl.ServerName)displays an upload confirmation. upl.ServerName contains the uploaded file's path and name on the server.

    • Set SAXFObj = Server.CreateObject("SoftArtisans.XFRequest")creates an instance of XFile.

      The objects of XFileSE and XFileEE have different ProgIds. When creating a server-side instance of an XFile object, be careful to set the ProgId for the version of XFile that you are using. The following table lists the ProgIds for XFileSE and XFileEE:

      Object | ProgId
      XFileSE | XFileEE
      XFRequest | SoftArtisans.XFRequest | SoftArtisans.XFRequestEE
      XFResume | Not available in XFileSE | SoftArtisans.XFResumeEE

    • SAXFObj.Server sets the server to which to transfer the uploaded file.

    • SAXFObj.ObjectName sets the file on the second server to which to transfer the uploaded file.

    • SAXFobj.AddFile sets the file to transfer to the second server. upl.ServerNamecontains the uploaded file's path and name on the first server.

    • SAXFObj.Start initiates the transfer to the second server.

    • Response.Write (SAXFObj.Response) displays the response from the second server.

  • Formresp2.asp
    • Set upl = Server.CreateObject("SoftArtisans.FileUp")creates an instance of SoftArtisans FileUp, the server-side file-transfer component that will receive and save the upload.

    • upl.Path sets the transfer destination on the second server.

    • upl.Save saves the transferred file on the second server.

    • Response.Write ("SERVER 2: File transferred successfully to " & upl.ServerName)displays a transfer confirmation for the second server.


Recursive Directory Upload

XFile can upload a directory and its subdirectories, maintaining the original directory structure. To upload a directory and its subdirectories, use the method AddDirectoryRecursive. When uploading a directory using AddDirectoryRecursive, use SoftArtisans FileUp's SaveRecursive method in your response script, as in the following example.

Exercise: Recursive Directory Upload

We will create two ASP scripts:

  • RecurXFile.asp
    Sends a directory to the server using XFile's AddDirectoryRecursive method.

  • RecurXFileResp.asp
    Saves the uploaded file on the server using SoftArtisans FileUp's SaveRecursive method.
  1. Create a physical folder called "RecursiveUpload."

  2. Create a virtual directory called "RecursiveUpload" and map it to the physical "RecursiveUpload" folder you created in step 1. To create the virtual directory,

    1. Open the Microsoft Management Console for Internet Information Services (IIS).
    2. Right-click "Default Web Site."
    3. Select "New" -> "Virtual Directory." The Virtual Directory Creation Wizard will open.
    4. Click "Next."
    5. In the "Alias" box enter RecursiveUpload.
    6. Browse to the physical folder RecursiveUpload, and click "Ok."
    7. Check the permissions "Read" and "Run Scripts."

  3. Create an ASP page containing the following lines of script. Save it as RecurXFile.asp in the folder RecursiveUpload.

    Note: The objects of XFileSE and XFileEE have different classids. When creating the XFRequest's <object> tag select the appropriate classid for the version of XFile that you are using:

    XFRequest Classids
    XFileSE | C3A57B60-C117-11D2-BD9B-00105A0A7E89
    XFileEE | 8B3512EF-4FF5-4aa4-9CDE-56BB03E04B9F
    <SCRIPT LANGUAGE="VBS">

          '--- Create an upload procedure that will execute when the user clicks the upload button.
          Sub UploadButton_onClick()

          '--- Set the script to which to upload the directory.
          SAXFile.CurrentURL = "http://localhost/RecursiveUpload/RecurXfileresp.asp"

          '--- Set the directory to upload.
          SAXFile.AddDirectoryRecursive( "x:\folder\subfolder" )

          '--- Start the upload.
          SAXFile.Start

          '--- Disable the upload button.
          document.all("UploadButton").disabled = true

          end Sub

          '--- Display a message box when the transfer begins.
          sub SAXFile_TransferStart()
          MsgBox "Transfer Starting."
          end sub

          '--- Display a message box when the transfer begins.
          sub SAXFile_TransferComplete()
          MsgBox "Transfer Completed."
          end sub
          </SCRIPT>>

          <!-- Instructions for the user -->
          To upload the preset directory press the "Upload!" button.

          <!-- Upload button -->
          <Input Type=Button Name="UploadButton" value="Upload!">

          <!-- Create an instance of XFRequest, using the Object tag -->
          <OBJECT CLASSID="clsid:C3A57B60-C117-11D2-BD9B-00105A0A7E89"
          codebase="/saxfilesamples/saxfile.cab" ID="SAXFile">
          </OBJECT>
  4. Create an ASP page containing the following lines of script. Save it as RecurXFileResp.asp in the folder RecursiveUpload.
    <%
          '--- Create an instance of SoftArtisans FileUp.
          Set upl = Server.CreateObject("SoftArtisans.FileUp")

          '--- Set the destination path for the upload.
          upl.Path = "C:\Temp"

          '--- Save the uploaded directory.
          upl.SaveRecursive()
          %>

Understanding the Script
  • RecurXFile.asp

    • The UploadButton_onClick() procedure

      • SAXFile.CurrentURL sets the URL to which to upload the directory.

      • SAXFile.AddDirectoryRecursive adds the specified directory and its subdirectories to the upload.

      • SAXFile.Start starts the upload.

      • document.all("UploadButton").disabled = true disables the upload button.

    • The SAXFile_TransferStart() procedure displays a message box when the upload starts.

    • The SAXFile_TransferComplete() procedure displays a message box when the upload is complete.

    • The <Input Type=Button> tag creates an upload button.

    • The <object> tag creates an instance of XFile.

  • RecurXFileResp.asp

    • Set upl = Server.CreateObject("SoftArtisans.FileUp") creates an instance of SoftArtisans FileUp, the component that processes the upload on the server.

    • upl.Path = "C:\Temp" sets the upload destination on the server.

    • upl.SaveRecursive() saves the uploaded directory and its subdirectories. SaveRecursive maintains the user's original file and folder names and the original directory structure.


Multilingual Support

Internally, computers store all characters (letters, numbers, and symbols) as numbers. In the past, each language used one or more encoding system to assign a unique number to each character. The various single-language encoding systems are not consistent. For example, two encoding systems may assign two different numeric values to the same letter, or assign the same numeric value to two different letters. Since the various encoding systems conflict with each other, data is easily corrupted when passed between language platforms.

Unicode is a single encoding standard for all languages. Unicode assigns a unique number to each character, and the same number to identical characters in different languages. For example, the letter h has the same Unicode value for each character set (language) that contains it.

SoftArtisans XFile is Unicode compliant, enabling the transfer of data between systems, regardless of language, without the risk of data corruption. By setting XFile's Codepage property, you will be able to preserve file names in their original language.

Codepage and Charset

To preserve file names when transferring files between language platforms, set the following properties.

  • Codepage
    XFile's Codepage property contains a Unicode language code for correctly storing the file name internally.

  • Charset
    The HTML <META> tag's Charset attribute specifies a Unicode language code for correctly displaying the file name. To set Charset, set the HTTP-EQUIV attribute to "Content-Type" and set the Content attribute to the appropriate character set identifier, as in the example below.

If, for example, you are uploading a file with a Japanese name,

  1. In your XFile request script, set

    • <META HTTP-EQUIV="Content-Type" content="text/html; charset=iso-2022-jp">, and,
    • objXFile.codepage = 50220

  2. In your FileUp response script, set

    • <META HTTP-EQUIV="Content-Type" content="text/html; charset=iso-2022-jp">, and,
    • objFileUp.codepage = 50220

For a complete list of Codepage and Charset values, see Microsoft's Character Set Recognitionreference.


SoftArtisans Archive

You received SoftArtisans Archive™ free with your purchase of XFile. SoftArtisans Archive is a sophisticated component for the creation and extraction of Zip and Cab archives.

With SoftArtisans Archive you can,

  • Create a Zip or Cab archive
  • Add files to an archive
  • Delete files from an archive
  • Enumerate the contents of an archive
  • Extract files from an archive
  • Sign the archive using Microsoft Authenticode (for .cab and .exe files only)

Using Archive in conjunction with XFile, you can compress several files and upload or download the archive file. You can then use Archive to extract the uploaded files on the server, or the downloaded files on the client.

Exercise 15: Using SoftArtisans Archive on the Client

Create an HTML script, containing the following lines.

<script language="vbs">
      Sub CreateArchive_OnClick()
      // Set the archive format
      // 1 - Zip format
      // 2 - Cab format
      arch.ArchiveType = 1

      // Create the Zip file
      arch.CreateArchive "c:\temp\ZipArch.zip"

      // Add files to the Zip file
      arch.AddFile "c:\report.doc"
      arch.AddFile "c:\image.jpg"
      arch.CloseArchive
      End Sub
      </script>

      <Input Type=Button Name="CreateArchive" Value="Create Archive">

      <Object Classid="clsid:D3400FEE-041F-11D3-B1C5-00A0C9B4587A" Codebase="localhost/SAXFileSamples/saxfile.cab"
      ID="arch">
      </Object>

Understanding the Script
  • CreateArchive_OnClick() executes when the user clicks the "Create Archive" button.

    • The ArchiveType property specifies whether the archive format will be Zip or Cab. Set ArchiveType to 1 to create a Zip file, or 2 to create a Cab file.

    • The CreateArchive method creates a new archive file. CreateArchive takes one parameter, the archive name. The archive name should include both the file path and file name.

    • The AddFile method adds a file or folder to the archive. Use AddFile after CreateArchiveor OpenArchive (see Programmer's Reference). AddFile takes two parameters, the file or folder path and name, and the optional parameter bRecursive. When bRecursive is set to True, Archive will add any sub-directories to the archive, maintaining the original directory structure. The default value of bRecursive is False.

    • The CloseArchive method closes the archive. Use CloseArchive to save any file additions or deletions. If you do not close the archive, all changes will be lost.

  • The <Input> tag creates a "Create Archive" button. When the user clicks this button, the CreateArchive_OnClick() procedure will execute.

  • The <Object> tag creates an instance of SoftArtisans Archive. Classid specifies Archive's unique class id, clsid:D3400FEE-041F-11D3-B1C5-00A0C9B4587A. Codebase specifies the location of saxfile.cab, which contains SAArch.dll (Archive's dll). ID assigns a name to the created instance of SoftArtisans Archive.
Using SoftArtisans Archive on the Server

Exercise 15 demonstrated creating an instance of SoftArtisans Archive on the client, using the <object>tag. You can also use Archive on the server, within an ASP script.

To create an instance of Archive within an ASP script, use Server.CreateObject, as follows.

Set objArchive = Server.CreateObject("Softartisans.Archive")


SoftArtisans FileManager

You received SoftArtisans FileManager™ free with your purchase of XFile. SoftArtisans FileManager answers all of your file management needs in a single, easy-to-use control.

SoftArtisans FileManager is 100% script compatible with Microsoft's Scripting.FileSystemObject, while offering numerous advantages:

  • Security Features
    • File encryption
    • Access control list manipulation
    • File ownership
    • LogonUser / RevertToSelf
    • Shows security context of current thread

  • File Manipulation Enhancements
    • Binary file Read, Write, and Fill
    • INI file manipulation
    • Database BLOB import/export

  • Other Features
    • DLL registration
    • Fully scriptable by Active Server Pages (ASP)
    • Can be used in any COM client including Visual Basic, C++, etc.
    • Many features can be disabled via Registry settings

Exercise: Using SoftArtisans FileManager on the Client

The following example demonstrates deleting a file using SoftArtisans FileManager.

Create an HTML script, containing the following lines.

<object classid="clsid:E7B62F4E-82F4-11D2-BD41-00105A0A7E89"
      codebase="localhost/SAXFileSamples/saxfile.cab" id="FileMgr">
      </object>

      <script language="vbs">
      Sub DeleteFile_onClick()
      FileMgr.DeleteFile "c:\x.txt"
      End Sub
      </script>

      <input Type=Button Name="DeleteFile" value="Delete File">

Understanding the Script
  • The <object> tag creates an instance of SoftArtisans FileManager. Classid specifies FileManager's unique class id, clsid:E7B62F4E-82F4-11D2-BD41-00105A0A7E89. Codebase specifies the location of saxfile.cab, which contains SAFilMgr.dll (FileManager's dll). Id assigns a name to the created instance of SoftArtisans FileManager.

  • DeleteFile_onClick() executes when the user clicks the "Delete File" button.

  • The DeleteFile method deletes the specified file. When setting a file to delete, include the the complete file path and name. In addition to the file name, DeleteFiletakes the optional parameter Force. If Force is set to True, FileManager will delete a file even if it is marked "Read only." By default, Force is set to False.

  • The <input> tag creates a "Delete File" button. When the user clicks this button, the DeleteFile_OnClick() procedure will execute.
Using SoftArtisans FileManager on the Server

Exercise 16 demonstrates creating an instance of SoftArtisans FileManager on the client, using the <object> tag. You can also use FileManager on the server, within an ASP script.

To create an instance of FileManager within an ASP script, use Server.CreateObject, as follows.

Set objFileManager = Server.CreateObject("SoftArtisans.FileManager")


Programmer's Samples

SoftArtisans XFile includes numerous working script samples. You will find the samples in the virtual directory localhost/SAXFileSamples, created during the automatic installation.

If you installed SoftArtisans XFile manually, create the virtual directory /SAXFileSamples and point it to SoftArtisans XFile's physical "Samples" directory, as follows.

  1. Open the Microsoft Management Console for Internet Information Services (IIS).
  2. Right-click "Default Web Site."
  3. Select "New" -> "Virtual Directory." The Virtual Directory Creation Wizard will open.
  4. Click "Next."
  5. In the "Alias" box enter SAXFileSamples.
  6. Browse to the folder SoftArtisans XFile\Samples, and click "Ok."
  7. Check the permissions "Read" and "Run Scripts."

Note on SoftArtisans FileUp

XFile's upload samples use SoftArtisans FileUpto process the upload on the server. The XFile sample scripts post to FileUp scripts included in the SAXFileSamples virtual directory. If FileUp is not installed on your server, and you do not want to change the sample scripts, download a free evaluation of SoftArtisans FileUp from Softartisans.


Programmer's Reference

  • SoftArtisans XFile
  • SoftArtisans Archive
  • SoftArtisans FileManager

SoftArtisans XFile

SoftArtisans XFile's Request Object and Sub-objects

SoftArtisans XFile's principal object is the XFRequest object. XFRequest is a non-visual file-transfer engine. It is the XFRequest object that submits the HTTP request (Post, Get, or Put) from client to server. The XFRequest object creates several sub-objects, each of which represents a part of the HTTP request (files, form elements, etc.).

  • XFRequest Object
    • XFFileCollection Object
    • XFFile Object
    • XFHTTPHeaderCollection Object
    • XFHTTPHeader Object
    • XFFormCollection Object
    • XFFormElement Object

The ActiveX Control

You can use the XFRequest object with your own user interface, or with SoftArtisans XFile's visual ActiveX Control. The ActiveX Control includes the following objects.

  • AXFFile Object
  • AXFFileDownload Object
  • AXFFileProgress Object
  • AXFileCollection Object

The explorer-like
file selection controls:
AXFFile for uploads &
AXFFileDownload for
downloads
The progress indicator,
AXFFileProgress

SoftArtisans XFile's data-transfer
engine, XFRequest

SoftArtisans Archive

SoftArtisans Archive provides programmers with a tool to create and extract archives in both ZIP and Microsoft Cabinet format. Using SoftArtisans Archive, you can,

  • Create a new archive
  • Add, extract, or delete files from an existing archive
  • Enumerate the contents of an archive
  • Sign the archive using Microsoft Authenticode (for .CAB or .EXE files only)

SoftArtisans Archive has three objects:

  • Archive Object
  • ArchiveItemCollection Object
  • ArchiveItem Object

SoftArtisans FileManager

SoftArtisans FileManager provides all your file management needs in a single, easy-to-use component. SoftArtisans FileManager is 100% script compatible with the Microsoft Scripting.FileSystemObject.

SoftArtisans FileManager has seven objects:

  • SoftArtisans FileManager Object
  • BinaryStream Object
  • Drive Object
  • File Object
  • Folder Object
  • TextStream Object
  • PermItem Object


The XFRequest Object

The XFRequest object is XFile's principal object. XFRequest is a non-visual file-transfer engine. It is the XFRequest object that submits the HTTP request (Post, Get, or Put) from client to server.

To create a server-side instance of the XFRequest object, use ASP's Server.CreateObject, as follows.

<% Set SAXFile = Server.CreateObject("SoftArtisans.XFRequest") %>

When creating a server-side instance of the XFRequest object, be careful to set the ProgId for the version version of XFile that you are using:

XFRequest ProgIds
XFileSE | SoftArtisans.XFRequest
XFileEE | SoftArtisans.XFRequestEE

To create a client-side instance of the XFRequest object, use HTML's <object> tag, as follows.

<OBJECT CLASSID="clsid:C3A57B60-C117-11D2-BD9B-00105A0A7E89" codebase="saxfile.cab" ID="SAXFile">

Classid specifies XFRequest's unique class id. The objects of XFileSE and XFileEE XFileSE and XFileEE have different classids. When setting the XFRequest object's classid, be careful to set the appropriate classidfor the version of XFile that you are using:

XFRequest Classids
XFileSE | C3A57B60-C117-11D2-BD9B-00105A0A7E89
XFileEE | 8B3512EF-4FF5-4aa4-9CDE-56BB03E04B9F

Codebase specifies the location of saxfile.cab, which contains saxfile.dll (XFRequest's dll). Id assigns a name to the created instance of XFRequest.

The XFRequest object automatically creates several sub-objects, each of which represents a part of the HTTP request (files, form elements, etc.). These objects are, XFFileCollection, XFFile Object, XFHTTPHeaderCollection Object, XFHTTPHeader Object, XFFormCollection Object, and XFFormElement Object.

XFRequest Reference Contents
  • XFRequest Events
  • XFRequest Methods
  • XFRequest Properties

    • Copyright © 2010 SoftArtisans, Inc. All rights reserved.


TransferComplete

TransferComplete Event

Object: XFRequest
Syntax: TransferComplete()
Description: The TransferComplete event fires upon completion of data transfer. The TransferComplete event contains no arguments.
Example: The following lines will display a message box when the transfer is complete.
sub SAXFile_TransferComplete()
    MsgBox "Transfer complete."
end sub


TransferError

TransferError Event

Object: XFRequest
Syntax: TransferError()
Description: The TransferError event fires if an error occurs during file transfer.
Example: The following lines will display a message box if an error occurs during transfer.
sub SAXFile_TransferError()
    MsgBox "Error occurred."
end sub


TransferProgress

TransferProgress Event

Object: XFRequest
Syntax: Event TransferProgress(ByVal BytesTransfered As Double, ByVal BytesTransferedThisFile As Double, ByVal TotalBytes As Double, ByVal TotalBytesThisFile As Double, ByVal currentFilename As String, bCancel As Boolean, ByVal CurrentURL As String)
Description: The TransferProgress event fires,
  • After the transfer of each 16 kilobytes or the value of the BufferSize property
  • At the beginning of the transfer of each file

Using the TransferProgress event, you can create a progress indicator that will allow the user to monitor the progress of a file upload or download.

TransferProgress takes seven arguments:

  • BytesTransferred
    Number of bytes transferred so far
  • BytesTransferredThisFile
    Number of bytes transferred so far for the current file
  • TotalBytes
    Total size of the transfer, in bytes
  • TotalBytesThisFile
    Size of the current file, in bytes
  • CurrentFileName
    Name of the file currently being uploaded
  • bCancel
    Cancels the upload when set to True
  • CurrentURL
    The upload's destination URL


TransferStart

TransferStart Event

Object: XFRequest
Syntax: TransferStart(RequestMethod As String, TotalFiles As Long)
Description: The TransferStart event fires when the data transfer is initiated. TransferStart takes two arguments:
  • RequestMethod
    The HTTP request method (Post, Get, or Put), which is the value of XFRequest's RequestMethod property.

  • TotalFiles
    The total number of files being transferred.
Example: The following lines will display a message box when the transfer begins.
sub SAXFile_TransferStart(RequestMethod, TotalFiles)
    MsgBox "Transfer starting."
end sub


TransferStatusChange Event

Object: XFRequest
Syntax: TransferStatusChange(Code As Integer, Message As String)
Description: The TransferStatusChange event fires at several stages during the file transfer. TransferStatusChange is the only event that encompasses a transfer from client to server and back to the client.

Status Code | Status Name | Message
0 | Initializing | XFile is initializing
1 | TransferStarting | Transfer is Starting
3 | RequestStarting | A Request is being sent to the server
4 | RequestComplete | Finished sending Request to the server
5 | RetrievingResponse | Retrieving Response from the server
6 | ResponseRetrieved | Response retrieved from the server
7 | TransferComplete | Transfer is complete
8 | TransferCancelled | Transfer has been cancelled
9 | TransferError | An error occurred
10 | TransferTimedOut | Transfer has timed out
11 | TransferDataStarting | Transfering Form Elements to Server Starting
12 | TransferDataComplete | Transfering Form Elements to Server Complete
13 | TransferFilesStarting | Upload of the Files is Starting
14 | TransferFilesComplete | Upload of the Files is Complete
15 | TransferFileStarting | Upload of the File is Starting
16 | TransferFileComplete | Upload of the File is Complete
17 | Connecting | Connecting to server
Examples:

Using TransferStatusChange with the Non-visual Transfer Engine

To notify the user when the transfer is complete using the transfer engine (XFRequest) and the TransferStatusChange event:

Create an instance of the XFRequest object in the <BODY> tag of your HTML code.

<OBJECT CLASSID="clsid:C3A57B60-C117-11D2-BD9B-00105A0A7E89"
    codebase="http://DomainName/XFileApplicationDirectory/SAXFile.cab" ID="XFILE">
</OBJECT>

In a <SCRIPT> tag, provide the event handler for the TransferStatusChange event. Note, than since ID attribute of XFile's object tag has the value of "XFILE", your event handler will be pre-pended with "XFILE_".

<SCRIPT language = 'vbs'>
    Sub XFILE_TransferStatusChange( ByVal code, ByVal Message )
        If code = 7 then
            msgbox Message
        End if
    End Sub
</SCRIPT>

In the code example above, if the TransferStatusChange event handler receives a status code of "7", it will display the associated message "Transfer is complete" in a pop-up message box.

Using TransferStatusChange with the Visual Upload Control

To notify the user when the transfer is complete using the visual upload control (AXFFile) and the TransferStatusChange event:

Create an instance of the AXFFILE object in the <BODY> tag of your HTML code.

    <OBJECT classid="CLSID:230C3D02-DA27-11D2-8612-00A0C93EEA3C" height="200"
        codebase="http://DomainName/XFileApplicationDirectory/SAXFile.cab"
        id="GUI_XFILE" style="HEIGHT: 200px; LEFT: 0px; TOP: 0px; WIDTH: 400px" width="400" VIEWASTEXT>

        <!-- DISABLE the upload button so that we can create our own and run code off of it -->
        <PARAM NAME="EnableUploadButton" VALUE="0">
    </OBJECT>
    <INPUT Type=Button Name="UploadButton" value="Start Upload">

Create a sub-routine that will function as an event handler. It can be named as you choose, but it must be able to accept two parameters to accomodate the event code and event message.

<SCRIPT language='vbs'>
    Sub DisplayTheStatusChanges(code,message)
        If code = 7 then
            msgbox message
        End if
    End Sub
</SCRIPT>

Call the AddTransferStatusChangeEventHandler method of the XFRequest object. Pass it the name of the sub-routine that will handle the events. By doing so, the events can now be reported even though the Start method is being called on the AXFFile object.

<SCRIPT language = 'vbs'>
    Sub UploadButton_onClick()

        '--- Set the URL where we want to send the data by
        '--- using the CurrentURL property
        Dim XFILE
        Set XFILE = GUI_XFILE.XFRequest
        XFILE.AddTransferStatusChangeEventHandler(GetRef("DisplayTheStatusChanges"))

        '--- ...other xfile code

        GUI_XFILE.Start
    End Sub
</SCRIPT>


AddDirectory

AddDirectory Method

Object: XFRequest
Syntax: AddDirectory dirName As String
Description: Adds the contents of a directory to the file-transfer request. AddDirectory does not add the contents of subdirectories. To transfer a directory with its subdirectories, use AddDirectoryRecursive.
Example: The directory C:\Documents contains file1.doc, file2.doc, and the folder OldFiles. The following lines will transfer file1.doc and file2.doc, but not the folder OldFiles.
saxfile.CurrentURL = "http://localhost/XFile Samples/formresp.asp"
saxfile.AddDirectory "C:\Documents"
saxfile.Start
Note: When uploading a directory using AddDirectory or AddDirectoryRecursive, use SA-FileUp's SaveRecursive method in your response script, as in the following example.
Set upl = Server.CreateObject("SoftArtisans.FileUp")
upl.Path = "C:\Temp"
upl.SaveRecursive()


AddDirectoryRecursive

AddDirectoryRecursive Method

Object: XFRequest
Syntax: AddDirectoryRecursive dirName As String
Description: Adds a specified directory and its contents, including subdirectories, to the file-transfer request.
Example:
SAXFile.CurrentURL = "http://localhost/XFile Samples/RecurXfileresp.asp"
SAXFile.AddDirectoryRecursive "c:\Documents"
SAXFile.Start
Note: When uploading a directory using AddDirectory or AddDirectoryRecursive, use SA-FileUp's SaveRecursive method in your response script, as in the following example.
Set upl = Server.CreateObject("SoftArtisans.FileUp")
upl.Path = "C:\Temp" upl.SaveRecursive()


AddEncryptedRequestHTTPHeader

AddEncryptedRequestHTTPHeader Method

Object: XFRequest
Syntax: AddEncryptedRequestHttpHeader Name As String, Value As String, [Append As Boolean]
Description: AddEncryptedRequestHTTPHeader adds an HTTP header of the specified encrypted Name and Value to the Request. The Name parameter must be encrypted by the Encryption.Encrypt() method available in SoftArtisans FileUpEE. AddEncryptedRequestHTTPHeader's third parameter, Append, is optional. If Append is set to True, the value will be appended to any header with same name. Otherwise, the specified value will replace the existing value of a header with the same name. The Append argument is set to False by default. For further details about the AddEncryptedRequestHTTPHeader method, see the following KB article: Session loss in ASP.NET 2.0 using XFileEE with FileUpEE.
Example:
XFile.AddEncryptedRequestHttpHeader("headerName", '<%= SoftArtisans.Net.Utilities.Encryption.Encrypt("headerValue") %>', True)


AddFile Method

Object: XFRequest
Syntax: AddFile FileName As String, Name As String
Description: This method adds a file to the file-transfer request. AddFile takes two parameters:
  • FileName As String
    The file path and name on the client.

  • Name As String
    In an upload, set this parameter to an item name for reference to the file on the server. In a download, set this parameter to the URL of the file to download, or of a server-side script that processes the download.
Note: In a file download, the FileName parameter may be either a complete path or a file name, when AddFile is used in conjunction with the properties SaveLocationPromptType and DefaultSavePath.
Upload Example:

'--- Set CurrentURL to the server-side
'--- script that processes the upload.
SAXFile.CurrentURL = "http://localhost/SAXFileSamples/asp/post/onefile/formresp.asp"

'--- The first parameter of AddFile sets the
'--- file on the client to upload to the server.
'--- The second parameter specifies an item
'--- name for reference to the file in the server-
'--- side script.
SAXFile.AddFile "C:\boot.ini", "File1"
SAXFile.Start
Download Example:

XFRequest.RequestMethod = "GET"

'--- The first parameter of AddFile specifies a default
'--- path for the downloaded file on the client. The
'--- second parameter is the URL of the file to get from
'--- the server.
XFRequest.AddFile "C:\Downloads\file.txt", "http://localhost/file.txt"
XFRequest.Start


AddFormElement Method

Object: XFRequest
Syntax: AddFormElement Name As String, Value As String
Description: This method adds a form element to the request. AddFormElement takes two parameters:
  • Name As String
    Name of the form field

  • Value As String
    Value of the form field

The XFRequest object does not automatically add form elements to the request. In order to pass form values from the file transfer page to the server, they must be added to the XFRequest object using the AddFormElement method. This includes the hidden _VIEWSTATE property, which is used to preserve viewstate in ASP.NET.
Example:

Set SAXFile = Server.CreateObject("SoftArtisans.XFRequest")
SAXFile.Server = "localhost"
SAXFile.ObjectName = "/SAXFileSamples/ASP/post/formdata/formresp.asp"

'--- Add form elements to the transfer with name/value pairs
'--- Turn off Anonymous user access to get a value for this Server Variable
SAXFile.AddFormElement "UserName", Request.ServerVariables("LOGON_USER")
SAXFile.AddFormElement "URL", Request.ServerVariables("HTTP_REFERER")
SAXFile.AddFormElement "DateTime", Now()

'--- Begin transfering the form data SAXFile.Start
'--- Write the response from the transfer (results from object name ASP file)
Response.Write SAXFile.Response


AddRequestHTTPHeader

AddRequestHTTPHeader Method

Object: XFRequest
Syntax: AddRequestHttpHeader Name As String, Value As String, [Append As Boolean]
Description: AddRequestHTTPHeader adds an HTTP header of the specified Name and Value to the Request. AddRequestHTTPHeader's third parameter, Append, is optional. If Append is set to True, the value will be appended to any header with same name. Otherwise, the specified value will replace the existing value of a header with the same name. The Append argument is set to False by default.
Example:
SAXFile.AddRequestHttpHeader "Company", "Softartisans"


Cancel

Cancel Method

Object: | XFRequest
Syntax: | XFRequest.Cancel
Return Value: | None
Description: | Cancels the current file transfer request.


Resume Method

Object: XFRequest
Syntax: XFRequest.Resume (RequestRecord as Object or JobId as String, [optional StartAsynch as Boolean = False])
Parameters:
  • RequestRecord or JobId
  • (optional) a boolean value for whether the resume is asynchronous or not (False by default)
Return Value: None
Description: Resumes the failed file transfer request specified by the RequestRecord or JobId.
Example:

'--- Subroutine to run when the user clicks a Resume button:
Sub ResumeButton_onClick()
    MsgBox "Resuming."

    '--- Disable the Resume button once it's been clicked
    document.all("ResumeButton").disabled = true

    '--- Call Resume and pass the current JobID to resume
    '--- the file transfer.
    SAXFile.Resume SAXFile.ResumeInfo.JobId

    '--- Show the server response in the Upload Status Messages
    '--- section on the page.
    UploadStatusTD.InnerHTML = SAXFile.Response
end sub


Start

Start Method

Object: XFRequest
Syntax: XFRequest.Start (optional StartAsynch as Short)
Description: Sends the HTTP Request and begins the data transfer.

Start takes one optional parameter, StartAsynch. When StartAsynchis set to 0, the request will be synchronous, that is, the client application (such as, Internet Explorer or Visual Basic) will not be able to start another task until the request is complete. When StartAsynch is set to 1, the request will be asynchronous, that is, the client application will be able to begin another task while the request is executing.

StartAsynch is set to 0 by default, except in the case of Windows Explorer Shell Extension uploads. Uploads through the Shell Extension are asynchronous (StartAsynch = 1) by default, allowing the user to perform other tasks in Windows Explorer while the request is executing.
Example:
SAXFile.CurrentURL = "http://localhost/SAXFileSamples/asp/post/onefile/formresp.asp"
SAXFile.AddFile "C:\boot.ini", "File1"
SAXFile.Start


AllDownloadsSuccessful

AllDownloadsSuccessful Property

Object: | XFRequest
Syntax: | XFRequest.AllDownloadsSuccessful
Type: | Boolean
Read/Write: | Read Only
Description: | AllDownloadsSuccessful returns false if an error occurred during the download of one or more files. AllDownloadsSuccessful returns true if all files were downloaded without error.


BoundaryLine Property

Object: | XFRequest
Syntax: | XFRequest.BoundaryLine
Type: | String
Read/Write: | Read/Write
Description: | Sets or returns the MIME boundary of the HTTP file upload. When an HTTP file upload reaches the server, its parts (that is, the various form elements, including files) are separated by MIME boundaries like -----------------18456798332. To set or retrieve a MIME boundary value, use XFRequest.BoundaryLine.


BufferSize Property

Object: XFRequest
Syntax: XFRequest.BufferSize [=Buffer Size as Long]
Type: Long
Read/Write: Read/Write
Description: Sets or returns the size, in bytes, of two client-side buffers:
  • The Send Buffer
    By default, XFile sends its request stream to the server 16K by 16K. 16K is the default Send Buffer.

  • The Read Buffer
    By default, XFile reads data from the Internet (downloads) 2K by 2K. 2K is the default Read Buffer.
When you set BufferSize, you set the size of both the Send and the Read buffers. BufferSize is adjustable in the range of 0.5K - 63K.

Use BufferSize to set your progress indicator's update frequency. The frequency of XFile's TransferProgressevents depends on the value of BufferSize, since TransferProgress fires every time a buffer is filled and sent or read. The smaller the value of BufferSize, the more frequently TransferProgress will fire.

Decreasing the value of BufferSize will increase the frequency of TransferProgress events, but will decrease the speed of your data transfer.


Canceled Property

Object: | XFRequest
Syntax: | XFRequest.Canceled
Type: | Boolean
Read/Write: | Read only
Description: | Canceled returns True, if the file transfer was canceled. Check the value of Canceled to determine whether the transfer was canceled.


CertInfo Property

Object: XFRequest
Syntax: XFRequest.CertInfo [=Certificate Index as Long]
Type: Long
Read/Write: Read/Write
Description:

The CertInfo property takes a zero-based index of the client certificate that should be used.

Proper use of the CertInfo depends on the number of certificates installed on the client.
# of Certificates | Behavior
1 | CertInfo does not need to be populated. XFile will automatically return the only certificate available, should it be required by the server.
2 or more

If the CertInfo property has not been populated to designate a specific certificate, XFile will return an error stating that a client certificate is required. The XFile log will report "A certificate is required to complete client authentication".

If the CertInfo property has been populated with a value, XFile will return the certificate specifed. This property uses a zero-based index as a value. In a case where the client has two certificates installed, valid values are 0 and 1.


Codepage Property

Object: XFRequest
Syntax: objXFRequest.Codepage [=Language Code as Long]
Type: Long
Read/Write: Read/Write
Description: Sets or returns the language of the file(s) or folder(s) being transferred. On Windows NT 4.0 and higher, SoftArtisans XFile is Unicode compliant, enabling the transfer of data between systems, regardless of language, without the risk of data corruption. By setting XFile's Codepage property, you will be able to preserve file names in their original language.

XFile's Codepage property specifies a Unicode language code for correctly storing the file name internally. To display the filename correctly, set the HTML <meta> tag's Charset attribute as well.

SoftArtisans recommends using XFile with SoftArtisans FileUp, which is Unicode compliant.

When client and server share the same language platform, you do not need to set Codepage. For heterogeneous language support, use Codepage 65001 and charset UTF-8 (Unicode).

For a complete list of Codepage values, see Microsoft's Character Set Recognition reference.
Example: If you are uploading a Japanese file with a Japanese file name, include the following in your XFile request script.

...
<META HTTP-EQUIV="Content-Type" content="text/html; charset=iso-2022-jp">
...
objXFile.Codepage = 50220 '--- Japanese
In the FileUp response script, include,

...
<!--META HTTP-EQUIV="Content-Type" content="text/html; charset=iso-2022-jp"-->
...
objFileUp.codepage = 50220


CurrentURL Property

Object: XFRequest
Syntax: XFRequest.CurrentURL [= URL as String]
Type: String
Read/Write: Read/Write
Description: Sets or returns the URL to which the upload will be posted.
Example:
SAXFile.CurrentURL = "http://localhost/SAXFileSamples/asp/post/onefile/formresp.asp"
SAXFile.AddFile "C:\boot.ini", "File1"
SAXFile.Start


DebugLevel Property

Object: XFRequest
Syntax: XFRequest.DebugLevel [=DebugLevel as Long]
Type: Long
Read/Write: Read/Write
Description: When DebugLevel is set to 1 or 2, XFile will save debugging information in a log file. DebugLevel is set to zero (disabled) by default. Enabling DebugLevel is recommended only for debugging, and not for production use.

When DebugLevel is set to 1, every byte of the request/response is logged, slowing the transfer process considerably.

When DebugLevel is set to 2, the body of the upload and the body of the response are not logged.

Use the property DebugLog to specify the name and path of the log file.
Example: The following will enable DebugLevel, and save a log file at D:\temp\XFileLog.txt.
SAXFile.DebugLevel = 1
SAXFile.DebugLog = "D:\temp\XFileLog.txt"


DebugLog Property

Object: XFRequest
Syntax: XFRequest.DebugLog [=Log File Path as String]
Type: String
Read/Write: Read/Write
Description: Sets or returns the name and path of an XFile log file, containing debugging information. By default, DebugLog is set to "C:\temp\xfile.log."

XFile will record debugging information in a log file when DebugLevel is enabled.
Example: The following will save a log file at D:\temp\XFileLog.txt.
SAXFile.DebugLevel = 1
SAXFile.DebugLog = "D:\temp\XFileLog.txt"


DefaultSaveLocation Property

Object: XFRequest
Syntax: XFRequest.DefaultSaveLocation [=Path as String]
Type: String
Read/Write: Read/Write
Description:

In a download, when SaveLocationPromptType is set to 2, XFile will use DefaultSaveLocation as the default destination directory for downloaded files. If a file's AddFile call specifies a destination path, XFile will not use DefaultSaveLocation for the file. If a file's AddFile call does not specify a destination path, XFile will use the location specified by DefaultSaveLocation as the default destination for the file.

Example:

XFile.RequestMethod = "GET"
XFile.AddFile "report.doc", "http://localhost/reports/report.doc"
XFile.AddFile "c:\downloads\image.jpg", "http://localhost/images/image.jpg"

'--- If SaveLocationPromptType is set to 2, the user will be prompted
'--- to select a destination folder for each file in the download.
XFile.SaveLocationPromptType = 2

'--- This path is used as the default destination for a downloaded
'--- file if the file's AddFile call does not specify a destination
'--- directory. In this example, the first AddFile call does not
'--- specify a destination. Therefore, XFile will use "d:\reports"
'--- as the default destination for "report.doc".
XFile.DefaultSaveLocation = "d:\reports"
XFile.Start


DirectoryFilter Property

Object: XFRequest
Syntax: XFRequest.DirectoryFilter [= Directory as String]
Type: String
Read/Write: Read/Write
Description: Use this property to filter files when uploading with AddDirectory or AddDirectoryRecursive. By default, DirectoryFilter is set to "*", and will accept all files.
Example: The following will allow the upload of ".doc" files only.
SAXFile.DirectoryFilter = "*.doc"


DiscardResponse Property

Object: XFRequest
Syntax: XFRequest.DiscardResponse [=Boolean]
Type: Boolean
Read/Write: Read/Write
Description: When DiscardResponse is set to True, XFile will discard the server response, and will not display a response in the browser when the data transfer is complete. DiscardResponse is set to False by default.
Example: The following will discard the server response.
SAXFile.DiscardResponse = True


EventForEachFile Property

Object: XFRequest
Syntax: XFRequest.EventForEachFile
Type: Boolean
Read/Write: Read/Write
Description: In a multiple file download where RequestMethodis set to "Get," XFile's TransferStart, TransferProgress, and TransferComplete events will fire for the whole download by default. If EventForEachFile is set to True, these events will fire for each file in the download.
Example:
Set SAXFile = Server.CreateObject("SoftArtisans.XFRequest")
SAXFile.RequestMethod = "Get"
SAXFile.EventForEachFile = True

Previous Page Next Page


Files Property

Object: XFRequest
Syntax: XFRequest.Files
Type: XFFileCollection
Read/Write: Read Only
Description: Returns the collection of files in an upload or download.
Example: Add files to an upload using the XFFileCollection's Add method:
Set SAXFile = Server.CreateObject("SoftArtisans.XFRequest")
Set XFFiles = SAXFile.Files
XFFiles.Add "C:\boot.ini", "FileName1"
XFFiles.Add "C:\config.sys", "FileName2"
SAXFile.Start


FormElements Property

Object: XFRequest
Syntax: XFRequest.FormElements
Type: XFFormCollection
Read-Only Read-Only
Description: Returns an XFFormCollection containing the form elements that have been added to XFRequest using the XFRequest.AddFormElement() method.
Example:
formCollection = XFRequest.FormElements;


FormEncType Property

Object: XFRequest
Syntax: XFRequest.FormEncType [=EncryptionType as String]
Type: String
Read/Write: Read/Write
Description: Sets or returns the encryption type of the HTTP request. XFile supports the encryption types "multipart/form-data" and "application/x-www-form-urlencoded."

By default, FormEncType is set to "multipart/form-data." If you set PostData or PostDataFile, XFile will set FormEncType to "application/x-www-form-urlencoded."

When you submit URL encoded data, using PostDataor PostDataFile, formulate the URL encoded posting stream according to the value of FormEncType. For Example, if you submit a name text box containing the value Jones, the posting stream sent to the server will vary according to FormEncType, as follows.
application/x-www-form-urlencoded multipart/form-data
"name=Jones" -----------------15246987382242
Content-Disposition:form-data; name="name"

Jones
In the case of "application/x-www-form-urlencoded," the value you assign to PostData, or save in PostDataFile, should be the same as the posting stream sent to the server. When FormEncType is "multipart/form-data," assign to PostData a URL encoded simulation of the data sent to the server. For the example above, the simulation would be, "-----------------15246987382242&vbCRLF&"Content-Disposition:form-data;name="name""&vbCRLF&vbCRLF"Jones"".


IgnoreCertDateInvalid Property

Object: XFRequest
Syntax: XFRequest.IgnoreCertDateInvalid [=Boolean]
Type: Boolean
Read/Write: Read/Write
Description: When IgnoreCertDateInvalid is set to True, XFile will ignore an invalid date on a user's server certificate. By default, IgnoreCertDateInvalid is set to False.
Example: To enable IgnoreCertDateInvalid, use,
SAXFile.IgnoreCertDateInvalid = True


IsActive Property

Object: XFRequest
Syntax: XFRequest.IsActive
Type: Boolean
Read/Write: Read Only
Description:

XFile can be used synchronously or asynchronously (this is determined by the value of the Start method's Asynch parameter). When you use XFile asynchronously, if you change an XFile property, call a method, or try to start a transfer before the previous transfer is complete, an error or an unexpected event may occur. The IsActive property allows you to synchronize XFile's operations when it is used asynchronously.

IsActive returns True if XFile is busy (for example, if XFile is transferring a file), and False if it is not.

Example:

<OBJECT classid="CLSID:C3A57B60-C117-11D2-BD9B-00105A0A7E89" codebase=""
    id="XFile" VIEWASTEXT>
</OBJECT>
<P>
    <INPUT Name="UploadBtn" type=button value="Start Upload">
</P>
<SCRIPT language="VBScript" defer>

    '--- Programmatically add files using the AddFile method.
    XFile.AddFile "C:\temp\test.txt", "File1"
    XFile.AddFile "C:\temp\test2.txt", "File2"
    bDone = False

    sub XFile_TransferComplete()
        MsgBox "Transfer Complete"
        If Not bDone Then

            '--- Upload the files to the second server.
            StartTransfer("http://server2/uploadscript2.asp")
            bDone = True
        End If
    end sub Sub

    UploadBtn_OnClick
        document.all("UploadBtn").disabled = True

        '--- Upload the files to the first server.
        StartTransfer("http://server1/uploadscript1.asp")
    End Sub

    Sub StartTransfer(sUrl)
        '--- Since this subroutine is called twice and XFile is running asynchronously
        '--- we need to make sure the engine is not already in use.
        If Not XFile.IsActive Then

            '--- Set XFRequest property CurrentUrl to the
            '--- URL where the upload will be sent
            if Len(sUrl) > 0 Then
                XFile.CurrentUrl = sUrl
            End if
            XFile.Start 1
        else

            '--- Wait a second and try again.
            hTimeout = Window.SetTimeout("StartTransfer(""" & sUrl & """)",1000)
        end if
    End Sub
    ...
</SCRIPT>


MaxFiles Property

Object: XFRequest
Syntax: XFRequest.MaxFiles [=Number of Files as Long]
Type: Long
Read/Write: Read/Write
Description: Sets or returns the maximum number of files that can be included in an upload. By default, MaxFiles is set to 0, that is, there is no limit on the number of files a user can upload.
Example: The following limits the number of files in an upload to 10.
xSAXFile.MaxFiles = 10


MaxFileSize Property

Object: XFRequest
Syntax: XFRequest.MaxFileSize [=File Size in Bytes as Long]
Type: Long
Read/Write: Read/Write
Description: Sets or returns the maximum file size allowed for upload. By default, MaxFileSize is set to 0, that is, there is no limit on the size of file a user can upload.
Example: The following prevents the upload of files that are larger than 100 bytes.
SAXFile.MaxFileSize = 100


MaxTransferSize Property

Object: XFRequest
Syntax: XFRequest.MaxTransferSize [=Transfer Size in Bytes as Long]
Type: Long
Read/Write: Read/Write
Description: Sets or returns the maximum size allowed for upload, in bytes. By default, MaxTransferSize is set to 0, that is, there is no limit on the total size of an upload.
Example: The following prevents uploads that are larger than 5000 bytes.
SAXFile.MaxFileSize = 5000


MinFiles Property

Object: XFRequest
Syntax: XFRequest.MinFiles [=Number of Files as Long]
Type: Long
Read/Write: Read/Write
Description: Sets returns the minimum number of files allowed in an upload. By default, MinFiles is set to 0, that is, there is no minimum number of files permitted for upload.
Example: The following prevents uploads that contain less than two files.
SAXFile.MinFiles = 2


MinFileSize Property

Object: XFRequest
Syntax: XFRequest.MinFileSize [=File Size in Bytes as Long]
Type: Long
Read/Write: Read/Write
Description: Sets or returns the minimum file size allowed for upload. By default, MinFileSize is set to 0, that is, there is no minimum file size permitted for upload.
Example: The following prevents uploads that contain files smaller than 100 bytes.
SAXFile.MinFileSize = 100


ObjectName Property

Object: XFRequest
Syntax: XFRequest.ObjectName [= Virtual Path and File Name as String]
Type: String
Read/Write: Read/Write
Description: Sets or returns the name of the page to which XFile will post a request. ObjectName includes both the name of the object page and its virtual path.
Use ObjectName in conjunction with the Serverproperty.
Example:
Set SAXFile = Server.CreateObject("SoftArtisans.XFRequest")
SAXFile.Server = "www.activeserverpages.com"
SAXFile.ObjectName = "/upload/formresp.asp"
SAXFile.AddFile "C:\boot.ini", "File1"
SAXFile.Start


OpenAfterDownload Property

Object: | XFRequest
Syntax: | XFRequest.OpenAfterDownload [= Boolean]
Type: | Boolean
Read/Write: | Read/Write
Description: | If OpenAfterDownload is set to true XFile will open each downloaded file. It will not open potentially dangerous files (such as, .exe, .bat, .cmd, .com, .scr, .pif, .vbs, .js).
Note: | This property is not available in the XFile dlls that are included in the SoftArtisans-signed cab file. To use this property, you must use the "non-warning" dlls and create and sign your own cab file.


OpenAfterDownloadIndex Property

Object: XFRequest
Syntax: XFRequest.OpenAfterDownloadIndex [=Long]
Type: Long
Read/Write: Read/Write
Description:

Use this property to specify whether XFile should open one or more files after download. Set OpenAfterDownloadIndex to 0, -1, or n:

Value | Description
0 (Default) | Open all files until an error occurs.
-1 | Open all files, excluding any file for which an error occurs.
n | Open only file n. The index is 1-based.
Example:
XFile.RequestMethod = "GET"
XFile.AddFile "c:\downloads\report.doc", "http://localhost/reports/report.doc"
XFile.AddFile "c:\downloads\image.jpg", "http://localhost/images/image.jpg"
XFile.OpenAfterDownloadIndex = -1
XFile.Start
See Also: OpenAfterDownload


Password Property

Object: XFRequest
Syntax: XFRequest.Password [= Password as String]
Type: String
Read/Write: Read/Write
Description: Sets or returns a password for user authenitication. Use in conjunction with the UserName property.

The Password property works with Basic Authentication, but not with NT Challenge/Response.


PerfRespCompleteTime Property

Object: XFRequest
Syntax: XFRequest.PerfRespCompleteTime
Type: Long
Read/Write: Read Only
Description: One of four XFRequest properties that return performance data; see also, PerfRespHeadTime, PerfSendTime, and PerfTotalTime.

PerfRespCompleteTime returns the response completion time, as the time between when the response was sent from the server and when it was received completelyon the client.

When using the GET method to download multiple files, XFile calculates PerfRespCompleteTime for each file, not for the whole transfer.
Example: The following displays the value of PerfRespCompleteTime.
Response.Write ("PerfRespCompleteTime: " & saxfile.PerfRespCompleteTime)


PerfRespHeadTime Property

Object: XFRequest
Syntax: XFRequest.PerfRespHeadTime
Type: Long
Read/Write: Read Only
Description: One of four XFRequest properties that return performance data; see also, PerfRespCompleteTime, PerfSendTime, and PerfTotalTime.

PerfRespHeadTime returns the time between when the request was completely sent and the response header was received.
Example: The following displays the value of PerfRespHeadTime.
Response.Write ("PerfRespHeadTime: " & saxfile.PerfRespHeadTime)


PerfSendTime Property

Object: XFRequest
Syntax: XFRequest.PerfSendTime
Type: Long
Read/Write: Read Only
Description: One of four XFRequest properties that return performance data; see also, PerfRespCompleteTime, PerfRespHeadTime, and PerfTotalTime.

PerfSendTime returns the time it took for the request to reach the server.
Example: The following displays the value of PerfSendTime.
Response.Write ("PerfSendTime:" & saxfile.PerfSendTime)


PerfTotalTime Property

Object: XFRequest
Syntax: XFRequest.PerfTotalTime
Type: Long
Read/Write: Read Only
Description: One of four XFRequest properties that return performance data; see also, PerfRespCompleteTime, PerfRespHeadTime, and PerfSendTime.

PerfTotalTime returns the time from request initiation until response completion.

When using the GET method to download multiple files, XFile calculates PerfRespCompleteTime for each file, not for the whole transfer.
Example: The following displays the value of PerfTotalTime.
Response.Write ("PerfTotalTime: " & saxfile.PerfTotalTime)


Port Property

Object: | XFRequest
Syntax: | XFRequest.Port [=Server HTTP Port as Long]
Type: | Long
Read/Write: | Read/Write
Description: | Sets or returns the server's HTTP port. By default, Port is set to 80.


PostData Property

Object: XFRequest
Syntax: XFRequest.PostData [= URL Encoded Data as String]
Type: String
Read/Write: Read/Write
Description: PostData sets or returns URL encoded data to send to the server. PostData (like PostDataFile) is an alternative to XFRequest's various Add methods.

When you set PostData, XFile will set FormEncTypeto "application/x-www-form-urlencoded."

PostData does not work in conjunction with XFRequest's Add methods.
Example: To submit a form containing a user's name and age, you could use,
SAXFile.AddFormElement "Name", "Jane"
SAXFile.AddFormElement "Age", "30"

To submit the same data using PostData, replace the AddFormElement lines with,
objXFRequest.PostData = "name=Jane&age=30"
When you set PostData, XFile will set FormEncType to "application/x-www-form-urlencoded." If you set FormEncType to "multipart/form-data," construct your URL encoded posting stream accordingly. See FormEncTypefor details.


PostDataFile Property

Object: XFRequest
Syntax: XFRequest.PostDataFile [= File Name and Path as String]
Type: String
Read/Write: Read/Write
Description: Sets or returns the name of a local file containing URL encoded data to send to the server. PostDataFile (like PostData) is an alternative to XFRequest's various Add methods. To use PostDataFile, you must construct a URL encoded posting stream, save it to a file, and assign the file name to PostDataFile.

When you set PostDataFile, XFile will set FormEncType to "application/x-www-form-urlencoded."

PostDataFile does not work in conjunction with XFRequest's Add methods.
Example: To submit a form containing a user's name and age, you could use,

SAXFile.AddFormElement "Name", "Jane"
SAXFile.AddFormElement "Age", "30"
To submit the same data using PostDataFile, you could,
  1. Save the URL encoded posting stream "name=jane&age=30" in a file, for example, c:\postdatafile.txt.

    When you set PostDataFile, XFile will set FormEncType to "application/x-www-form-urlencoded." If you set FormEncType to "multipart/form-data," construct your URL encoded posting stream accordingly. See FormEncTypefor details.

  2. Add the following line to your XFile request script.
    objXFRequest.PostDataFile = "c:\postdatafile.txt"


Proxy Property

Object: XFRequest
Syntax: XFRequest.Proxy [=Proxy Name as String]
Type: String
Read/Write: Read/Write
Description: Sets or returns the name of the client network's proxy, if one exists.
The Proxy property will overwrite UseDefaultProxy.
Example:
Set SAXFile = Server.CreateObject("SoftArtisans.XFRequest")
SAXFile.Server = "www.activeserverpages.com"
SAXFile.ObjectName = "/upload/formresp.asp"
SAXFile.AddFile "C:\boot.ini", "FileName1"
SAXFile.Proxy = "ProxyX"
SAXFile.ProxyPort = 80
SAXFile.Start


ProxyPassword Property

Object: XFRequest
Syntax: XFRequest.ProxyPassword [=Proxy Password as String]
Type: String
Read/Write: Read/Write
Description: Sets or returns the password to use to connect through the proxy server. ProxyPassword is usually used in conjunction with the ProxyUserName property.
Example:
Set SAXFile = Server.CreateObject("SoftArtisans.XFRequest")
SAXFile.Server = "www.activeserverpages.com"
SAXFile.ObjectName = "/upload/formresp.asp"
SAXFile.AddFile "C:\boot.ini", "FileName1"
SAXFile.Proxy = "ProxyX"
SAXFile.ProxyPort = 80
SAXFile.ProxyUserName = "JohnS"
SAXFile.ProxyPassword = "OpenSesame"
SAXFile.Start


ProxyPort Property

Object: XFRequest
Syntax: XFRequest.ProxyPort [=Proxy Port Number]
Type: Long
Read/Write: Read/Write
Description: Sets or returns the HTTP port number of the client's network proxy. Port is set to 80 by default.
Example:
Set SAXFile = Server.CreateObject("SoftArtisans.XFRequest")
SAXFile.Server = "www.activeserverpages.com"
SAXFile.ObjectName = "/upload/formresp.asp"
SAXFile.AddFile "C:\boot.ini", "FileName1"
SAXFile.Proxy = "ProxyX"
SAXFile.ProxyPort = 80
SAXFile.Start


ProxyUserName Property

Object: XFRequest
Syntax: XFRequest.ProxyUserName [=Proxy User Name as String]
Type: String
Read/Write: Read/Write
Description: Sets or returns the user name to use to connect through the proxy server. ProxyUserName is usually used in conjunction with the ProxyPassword property.
Example:
Set SAXFile = Server.CreateObject("SoftArtisans.XFRequest")
SAXFile.Server = "www.activeserverpages.com"
SAXFile.ObjectName = "/upload/formresp.asp"
SAXFile.AddFile "C:\boot.ini", "FileName1"
SAXFile.Proxy = "ProxyX"
SAXFile.ProxyPort = 80
SAXFile.ProxyUserName = "JohnS"
SAXFile.ProxyPassword = "OpenSesame"
SAXFile.Start


RequestHTTPHeaders

RequestHTTPHeaders Property

Object: XFRequest
Syntax: XFRequest.RequestHTTPHeaders
Type: XFHTTPHeaderCollection
Read/Write: Read Only
Description: Returns an XFHTTPHeaderCollectionobject, representing the collection of HTTP request headers.
Example: To add a header to the request, use the XFHTTPHeaderCollection's Add method:
SAXFile.RequestHTTPHeaders.Add "HTTP_HeaderName", "HeaderValue"


RequestMethod Property

Object: XFRequest
Syntax: XFRequest.RequestMethod [=Request Method as String]
Type: String
Read/Write: Read/Write
Description: Sets or returns the HTTP request method. RequestMethod may be Post, Get, or Put. RequestMethod is set to Post by default.
Example: To download a file, set RequestMethod to "Get:"
Set SAXFile = Server.CreateObject("SoftArtisans.XFRequest")
SAXFile.RequestMethod = "Get"


Response Property

Object: XFRequest
Syntax: XFRequest.Response ([type])
Type: String (default), Array of variants, or Array of bytes
Read/Write: Read Only
Description: Returns the server response to an XFile request. Depending on the value of the optional parameter type, Response returns a string, an array of bytes, or an array of variants:
Value of type parameter | Returns
0 (default) | String
1 | Array of variants
2 | Array of bytes
Example:
Set SAXFile = Server.CreateObject("SoftArtisans.XFRequest")
SAXFile.Server = "www.activeserverpages.com"
SAXFile.ObjectName = "/upload/formresp.asp"
SAXFile.AddFile "C:\boot.ini", "FileName1"
SAXFile.Start
Response.Write(SAXFile.Response)


ResponseFile Property

Object: XFRequest
Syntax: XFRequest.ResponseFile [=Response File Path and Name as String]
Type: String
Read/Write: Read/Write
Description: Sets or returns a file containing the server response to XFile's request. When ResponseFile is set, the response will not be displayed in the browser.
ResponseFile cannot be used in conjunction with the Response property.
Example:
saxfile.responsefile = "c:\temp\response.doc"


ResponseHTTPHeaders Property

Object: XFRequest
Syntax: XFRequest.ResponseHTTPHeaders
Type: XFHTTPHeaderCollection
Read/Write: Read Only
Description: Returns an XFHTTPHeaderCollectionobject, representing the collection of HTTP response headers.
Example: The following will display the values of all HTTP response headers.
For each item in SAXFile.ResponseHttpHeaders
    Response.Write item.name & ":" & item.value
Next


ResponseSize Property

Object: | XFRequest
Syntax: | XFRequest.ResponseSize
Type: | Long
Read/Write: | Read Only
Description: | Returns the size of the server response, in bytes.


ResponseStatus Property

Object: XFRequest
Syntax: XFRequest.ResponseStatus
Type: String
Read/Write: Read Only
Description: Returns a message containing the status of the server response.
Examples:
  • If the request and response completed successfully, the value of ResponseStatus will be "200 OK."
  • If the response page is not found, ResponseStatus will be "404 NOT FOUND."


ResumeInfo Property

Object: XFRequest
Syntax: XFRequest.ResumeInfo
Type: ResumeInfo object
Read/Write: Read only
Description: In a resumable file transfer request, ResumeInfo gets the request's ResumeInfo object, which is used to set properties related to resuming a failed file transfer.
Example:

...
'--- Set a ResumeInfo object to access properties related to
'--- resuming a failed file transfer.
Set XFileResumeInfo = SAXFile.ResumeInfo

'--- Set Resumable to True to allow the upload to be resumed.
XFileResumeInfo.Resumable = True

'--- If CacheRequest is set to True XFile will save copies of the
'--- files to upload before sending the upload request. In a resumable
'--- upload, enabling CacheRequest guarantees the integrity of
'--- a resumed request.
XFileResumeInfo.CacheRequest = True

'--- StatusUrl specifies the URL of the FileUpEE status script
'--- to which XFile will send the upload status request, when
'--- resuming an upload.
XFileResumeInfo.StatusUrl = "http://localhost/XFileResumeUpload/status.asp"
...


SaveLocationPromptType Property

Object: XFRequest
Syntax: XFRequest.SaveLocationPromptType [=Prompt Type as Long]
Type: Long
Read/Write: Read/Write
Description:

In a download, SaveLocationPromptType lets you specify whether XFile should prompt the user to select a destination directory for the downloaded files. Set SaveLocationPromptType to O, 1, or 2:

Value | Description
0 (Default) | XFile will not prompt the user to select a destination directory. XFile will save each downloaded file according to the AddFile method's FileName parameter. If SaveLocationPromptType is set to 0, AddFile's FileName parameter must include a full path and file name.
1 | XFile will prompt the user once to select a destination directory. All files in the download will be saved to this directory. XFile will save each file with the name specified by the file's AddFile call; the path specified in the AddFile call will be ignored.
2 | XFile will prompt the user to choose a destination directory and a file name for each file in the download. The file name defaults to the name specified by the file's AddFile call. The destination directory defaults to the path specified by the file's AddFile call.
Example:

XFile.RequestMethod = "GET"
XFile.AddFile "c:\downloads\report.doc", "http://localhost/reports/report.doc"
XFile.AddFile "c:\downloads\image.jpg", "http://localhost/images/image.jpg"

'--- If SaveLocationPromptType is set to 1, the user will be prompted once
'--- to select a destination folder for both files in the download. Each
'--- file will be saved with the name specified by the first parameter of
'--- the file's AddFile call.
XFile.SaveLocationPromptType = 1
XFile.Start
See Also: DefaultSavePath


SaveOnDownloadError

SaveOnDownloadError Property

Object: | XFRequest
Syntax: | XFRequest.SaveOnDownloadError [=Boolean]
Type: | Boolean
Read/Write: | Read/Write
Description: | If SaveOnDownloadError is set to false, XFile will not save a downloaded file if an error occurs. If the property is set to true, XFile will save a downloaded file if an error occurs. SaveOnDownloadErroris set to true by default.


Server Property

Object: XFRequest
Syntax: XFRequest.Server [=Server as String]
Type: String
Read/Write: Read/Write
Description: Sets or returns the server to which XFile will post a request.
Use Server in conjunction with the ObjectNameproperty.
Example:
Set SAXFile = Server.CreateObject("SoftArtisans.XFRequest")
SAXFile.Server = "www.activeserverpages.com"
SAXFile.ObjectName = "/upload/formresp.asp"
SAXFile.AddFile "C:\boot.ini", "FileName1"
SAXFile.Start


Timeout Property

Object: XFRequest
Syntax: XFRequest.Timeout [=Timeout in Seconds as Long]
Type: Long
Read/Write: Read/Write
Description: Sets or returns a timeout value for the request, in seconds. Timeout is set to 90 seconds by default. To enable large uploads through a slow connection, set a higher Timeout value.

If the Timeout is set to -1, the timeout value is infinite and the request will not time out.

To determine the necessary value of Timeout, use the following formula.
FileSize/ModemSpeed = MinimumUploadTime
For example, to determine the minimum upoad time for a 1 MB (megabyte) file through a 56Kbps (Kilobits per second) modem, use,
1 MB / (56 Kilobits/8)
Note: Divide 56 Kilobits by 8 to convert bits to bytes (1 byte = 8 bits).
Example:
saxfile.Timeout = 200


TransferEncoding Property

Object: XFRequest
Syntax: XFRequest.TransferEncoding [=TransferEncoding as Long]
Type: Long
Read/Write: Read/Write
Description: The TransferEncoding property allows you to send a chunked transfer-encoded upload request. A chunked file transfer is sent as a series of chunks, each preceded by its own size indicator. A chunked transfer request does not include a content-length header for the whole request.

Chunked transfer-encoding allows XFileEE (when used with FileUpEE on the server) to bypass the upload size limit in IIS 6. IIS 6 does not accept requests larger than 4-GB, and gets the size of a request from the request's content-length header. Since a chunked request does not include a content-length header, IIS 6 will find no reason to reject it, regardless of the request's size. With chunked-transfer encoding, no matter how large the upload, it will not be rejected by IIS 6. When you send a chunked request from XFileEE to FileUpEE, remember to set FileUpEE's TransferEncoding property to 1.

TransferEncoding Values
0 (default value) | No encoding
1 | Chunked transfer-encoding


UseDefaultProxy Property

Object: XFRequest
Syntax: XFRequest.UseDefaultProxy [=Boolean]
Type: Boolean
Read/Write: Read/Write
Description: If UseDefaultProxy is set to True, XFile will use the system's default proxy server. If UseDefaultProxy is set to false, XFile will not use the default proxy. By default, UseDefaultProxy is set to True.
The Proxy property will overwrite UseDefaultProxy.
Example:
saxfile.UseDefaultProxy = False


UserAgent Property

Object: | XFRequest
Syntax: | XFRequest.UserAgent [= User Agent as String]
Type: | String
Read/Write: | Read/Write
Description: | Sets or returns the value of the request header HTTP_USER_AGENT. HTTP_USER_AGENT specifies the agent that sent the request. The default value of UserAgent is "SoftArtisans XFile ActiveX Control (1.0) for Windows."


UserName Property

Object: XFRequest
Syntax: XFRequest.UserName [=User Name as String]
Type: String
Read/Write: Read/Write
Description: Sets or returns a UserName for user authentication. Use in conjunction with the Password property.

UserName works with Basic Authentication, but not with NT Challenge/Response.


UseSSL Property

Object: XFRequest
Syntax: XFRequest.UseSSL [=Boolean]
Type: Boolean
Read/Write: Read/Write
Description: When UseSSL is set to True, XFile will use the Secure Sockets Layer (SSL) during transfer. By default, UseSSL is set to False.
Example:
SAXFile.UseSSL = True


UseWinInet Property

Object: XFRequest
Syntax: XFRequest.UseWinInet [= Boolean]
Type: Boolean
Read/Write: Read/Write
Description: When UseWinInet is set to True, XFile will use the WinInet API for the HTTP request. By default, UseWinInet is set to True.

WinInet will not be used (even if UseWinInet enabled) if:
  1. TransferEncoding is set to 1 (chunked transfer-encoding), or

  2. The request is larger than 4-GB.


UseXLastModified Property

Object: XFRequest
Syntax: XFRequest.UseXLastModified [= Boolean]
Type: Boolean
Read/Write: Read/Write
Description:

When UseXLastModified is set to True, XFile will send the "Last Modified" date of the transferred files, in the HTTP header.

X-Last-Modified: Fri Dec 04 10:29:02 GMT 1998

Which can be defined as follows:
date-time = day date time 4DIGIT ; Dow Mmm dd hh:mm:ss zzz yyyy
day = "Mon" / "Tue" / "Wed" / "Thu" / "Fri" / "Sat" / "Sun"
date = month 2DIGIT ; month day
month = "Jan" / "Feb" / "Mar" / "Apr" / "May" / "Jun" / "Jul" / "Aug" / "Sep" / "Oct" / "Nov" / "Dec"
time = hour zone ; ANSI
hour = 2DIGIT ":" 2DIGIT ":" 2DIGIT ; 00:00:00 - 23:59:59
zone = "UT" / "GMT" ; Universal Time

The file modification date is always sent in GMT format to account for time zone differences between the browser and server.

If you are using XFile in conjunction with FileUp, you can use FileUp's object model to retrieve this information from the Request headers:

  1. Set FileUp's UseDateLastModified property to True

  2. Retrieve the date using one of the following propertes
    • FileUp object
      • FileUp.DateLastModified
      • FileUp.DateLastModifiedUTC
    • File object
      • File.DateLastModified
      • File.DateLastModifiedUTC


Version Property

Object: | XFRequest
Syntax: | XFRequest.Version
Type: | String
Read/Write: | Read Only
Description: | Returns the version of the saxfile.dll file, which is the source of the XFRequest object.


WinInetDontCache Property

Object: | XFRequest
Syntax: | XFRequest.WinInetDontCache [= Boolean]
Type: | Boolean
Read/Write: | Read/Write
Description: | When WinInetDontCache is set to True, the local browser will not cache data received from the server.


WinInetForceReload Property

Object: | XFRequest
Syntax: | XFRequest.WinInetForceReload [= Boolean]
Type: | Boolean
Read/Write: | Read/Write
Description: | When set to True, WinInetForceReload forces the request to reload, rather than use cached information.


WinInetUseExistingConnect Property

Object: | XFRequest
Syntax: | XFRequest.WinInetUseExistingConnect [=Boolean]
Type: | Boolean
Read/Write: | Read/Write
Description: | When WinInetUseExistingConnect is set to True, XFile will use an existing connection, if possible, rather than establish a new connection.


XFRequestStream Property

Object: XFRequest
Syntax: XFRequest.XFRequestStream
Type: IStream
Read/Write: Read Only
Description:

Returns an object representing the HTTP request stream.
Example: To synchronize the upload control and its progress indicator, assign AXFFile's
XFRequestStream value to the AXFFileProgress object's XFRequestStream
property:
 document.all("AXFFileProgress").XFRequestStream = opener.document.all("AXFFile").XFRequestStream
Document refers to the AXFFileProgress window object, and document.openerrefers to the AXFFile window.
See Also: The AXFFileProgress object's XFRequestStreamproperty.


The XFFileCollection Object

XFFileCollection is a collection of XFFile objects. XFFileCollection represents the set of files in an XFile file transfer. When you create an instance of XFRequest, the XFRequest object automatically creates an instance of the XFFileCollection object.

  • XFFileCollection Methods
  • XFFileCollection Properties


Add

Add Method

Object: XFFileCollection
Syntax: Add File Name As String, Name As String
Description: Adds a file to the file-transfer request. Add takes two parameters:
  • FileName As String
    The file path and name on the client

  • Name As String
    An item name for reference to the file on the server
Example:
Set SAXFile = Server.CreateObject("SoftArtisans.XFRequest")
SAXFile.CurrentURL = "http://localhost/SAXFileSamples/formresp.asp"
Set XFFiles = SAXFile.Files
XFFiles.Add "C:\boot.ini", "FileName1"
XFFiles.Add "C:\config.sys", "FileName2"
SAXFile.Start


Remove

Remove Method

Object: XFFileCollection
Syntax: XFFileCollection.Remove(Name)
Description: Removes the specified file from the list of files to transfer.
Example: The following example adds two files to the upload, and removes the first if ConditionX is True.
Set XFFileCollection = SAXFile.Files
XFFileCollection.Add "C:\boot.ini", "File1"
XFFileCollection.Add "C:\config.sys", "File2"
If ConditionX = True Then
    XFFileCollection.Remove "boot.ini"
End If
SAXFile.Start


RemoveAll

RemoveAll Method

Object: | XFFileCollection
Syntax: | XFFileCollection.RemoveAll
Description: | Removes all files from the set of files to upload.


XFFileCollection Properties

  • Count
  • Item
  • MaxFiles
  • MaxFileSize
  • MinFileSize
  • RequestMethod


Count

Count Property

Object: | XFFileCollection
Syntax: | XFFileCollection.Count
Type: | Long
Read/Write: | Read Only
Description: | Returns the number of files in the XFFileCollection, that is, the number of files set to upload.


Item

Item Property

Object: | XFFileCollection
Syntax: | XFFileCollection.Item(Key)
Type: | XFFile
Read/Write: | Read Only
Description: | Returns a single file in an XFFileCollection.


MaxFiles

MaxFiles Property

Object: | XFFileCollection
Syntax: | XFFileCollection.MaxFiles [= Number of Files as Long]
Type: | Long
Read/Write: | Read/Write
Description: | Sets or returns the maximum number of files that can be included in an XFFileCollection. By default, MaxFiles is set to 0, that is, there is no limit on the number of files a user can transfer.


MaxFileSize

MaxFileSize Property

Object: XFFileCollection
Syntax: XFFileCollection.MaxFileSize [= File Size in Bytes as Long]
Type: Long
Read/Write: Read/Write
Description: Sets or returns the maximum file size allowed for upload. By default, MaxFileSize is set to 0, that is, there is no limit on the size of file a user can upload.
Example: The following prevents the upload of files that are larger than 100 bytes.
FileCollection.MaxFileSize = 100


MinFileSize

MinFileSize Property

Object: XFFileCollection
Syntax: XFFileCollection.MinFileSize [= File Size in Bytes as Long]
Type: Long
Read/Write: Read/Write
Description: Sets or returns the minimum file size allowed for upload, in bytes. By default, MinFileSize is set to 0, that is, there is no minimum file size permitted for upload.
Example: The following prevents uploads that contain files smaller than 100 bytes.
SAXFile.MinFileSize = 100


RequestMethod

RequestMethod Property

Object: | XFFileCollection
Syntax: | XFFileCollection.RequestMethod [= Request Method as String]
Type: | String
Read/Write: | Read/Write
Description: | Sets or returns the HTTP request method. RequestMethod may be Post, Get, or Put. RequestMethod is set to Post by default

Previous Page Next Page


The XFFile Object

The XFFile Object represents a single file in an upload or download. When you create an instance of XFRequest, the XFRequest object automatically creates an instance of the XFFile object.

XFFile Properties


OpenInApplication Method

Object: | XFFile
Syntax: | XFFile.OpenInApplication
Description: | Opens the specified file after download in the appropriate application.


DateLastModified Property

Object: | XFFile
Syntax: | XFFile.DateLastModified
Type: | Variant
Read/Write: | Read Only
Description: | Returns the "Last Modified" date of the file, if available.


DownloadError Property

Object: XFFile
Syntax: XFFile.DownloadError
Type: DownloadError object
Read/Write: Read Only
Description: DownloadError returns a DownloadError object which represents an error that occurred during a download.


FileName Property

Object: | XFFile
Syntax: | XFFile.FileName
Type: | String
Read/Write: | Read Only
Description: | Returns the name of the file to upload or download.


FileSize Property

Object: | XFFile
Syntax: | XFFile.FileSize
Type: | Long
Read/Write: | Read Only
Description: | Returns the size of the file to upload or download, in bytes.


ImageColor

ImageColor Property

Object: XFFile
Syntax: XFFile.ImageColor
Type: Long
Read/Write: Read Only
Description: Returns the color of an image file.
Example: The following adds a form element to the request containing an image file's color.
SAXFile.AddFormElement "ImageColor", XFfiles(1).ImageColor


ImageHeight

ImageHeight Property

Object: XFFile
Syntax: XFFile.ImageHeight
Type: Long
Read/Write: Read Only
Description: Returns the height of an image file.
Example: The following adds a form element to the request containing an image file's height.
SAXFile.AddFormElement "ImageHeight", XFfiles(1).ImageHeight


ImageWidth

ImageWidth Property

Object: XFFile
Syntax: XFFile.ImageWidth
Type: Long
Read/Write: Read Only
Description: Returns the width of an image file.
Example: The following adds a form element to the request containing an image file's width.
SAXFile.AddFormElement "ImageWidth", XFfiles(1).ImageWidth


MIMEType Property

Object: XFFile
Syntax: XFFile.MIMEType [= Mime Type as String]
Type: String
Read/Write: Read/Write
Description: Sets or returns a file's MIME type.
Example: The following adds a form element to the request containing a file's MIME type.
SAXFile.AddFormElement "MIMEType", XFfiles(1).MIMEType


RelativeName

RelativeName Property

Object: | XFFile
Syntax: | XFFile.RelativeName
Type: | String
Read/Write: | Read Only
Description: | RelativeName returns a relative file name for files uploaded using AddDirectoryRecursive.
Example: | The directory "c:\documents" contains the file "c:\documents\jan2001\report2.doc." If you upload "c:\documents" using AddDirectoryRecursive (SAXFile.AddDirectoryRecursive "c:\documents"), report2.doc's RelativeName will be "jan2001\report2.doc."


RemoteName Property

Object: XFFile
Syntax: XFFile.RemoteName
Type: String
Read/Write: Read Only
Description:

Returns a destination name for the transferred file.

When a file is uploaded, its RemoteName is the item name assigned to it for reference on the server. That is, in the case of an upload, RemoteName is equivalent to the second parameter of the AddFile method.

When a file is downloaded, RemoteName is the file's URL on the remote server.


The XFHTTPHeaderCollection Object

XFHTTPHeaderCollection is a collection of XFHTTPHeader objects. XFHTTPHeaderCollection represents the set of HTTP headers in a single request or response.

When you create an instance of XFRequest, the XFRequest object automatically creates an instance of the XFHTTPHeaderCollection object.

  • XFHTTPHeaderCollection Methods

  • XFHTTPHeaderCollection Properties


Add Method

Object: | XFHTTPHeaderCollection
Syntax: | Add Name As String, Value As String, [Append As Boolean]
Description: | Adds an HTTP header of the specified Name and Value to the XFHTTPHeaderCollection. Add's third parameter, Append, is optional. If Append is set to True, the value will be appended to any header with same name. Otherwise, the specified value will replace the existing value of a header with the same name. The Append argument is set to False by default.


Remove Method

Object: XFHTTPHeaderCollection
Syntax: Remove Name As String
Description: Removes the specified HTTP header from the XFHTTPHeaderCollection.
Example:
SAXFile.RequestHTTPHeaders.Remove "HTTP_NAME"


Count Property

Object: | XFHTTPHeaderCollection
Syntax: | XFHTTPHeaderCollection.Count
Type: | Long
Read/Write: | Read only
Description: | Returns the number of HTTP headers in an XFHTTPHeaderCollection.


Item Property

Object: | XFHTTPHeaderCollection
Syntax: | XFHTTPHeaderCollection.Item(Key)
Read/Write: | Read Only
Description: | Returns an XFHTTPHeader object.


The XFHTTPHeader Object

XFHTTPHeader represents a single HTTP header. When you create an instance of XFRequest, the XFRequest object automatically creates an instance of XFHTTPHeader.

  • XFHTTPHeader Properties


Name Property

Object: | XFHTTPHeader
Syntax: | XFHTTPHeader.Name [= Header Name as String]
Type: | String
Read/Write: | Read/Write
Description: | Sets or returns the name of an HTTP header.


Value Property

Object: | XFHTTPHeader
Syntax: | XFHTTPHeader.Value [= Header Value as String]
Type: | String
Read/Write: | Read/Write
Description: | Sets or returns the value of an HTTP header.


The XFFormCollection Object

XFFormCollection is a collection of XFFormElement objects, that is, XFFormCollection represents the set of form elements that XFile will submit to the server. When you create an instance of XFRequest, the XFRequest object automatically creates an instance of XFFormCollection.

  • XFFormCollection Methods

  • XFFormCollection Properties


Add Method

Object: XFFormCollection
Syntax: XFFormCollection.Add Field Name as String, Value As String
Description: Adds a form element to the XFFormCollection. Add takes two parameters: the name of the form field, and the value contained in the form field.
Example:
Set SAXFile = Server.CreateObject("SoftArtisans.XFRequest")
Set FormCollection = SAXFile.FormElements
FormCollection.Add "Color", "Red"


Remove Method

Object: XFFormCollection
Syntax: XFFormCollection.Remove Field Name as String
Description: Removes the specified form element from the XFFormCollection.
Example: The following will remove the UserName field from the form.
Set SAXFile = Server.CreateObject("SoftArtisans.XFRequest")
Set FormCollection = SAXFile.FormElements
FormCollection.Remove "UserName"


RemoveAll

RemoveAll Method

Object: XFFormCollection
Syntax: XFFormCollection.RemoveAll
Description: Removes all form fields from the XFFormCollection.
Example: The following will remove all fields from the form.
Set SAXFile = Server.CreateObject("SoftArtisans.XFRequest")
Set FormCollection = SAXFile.FormElements
FormCollection.RemoveAll


Count Property

Object: | XFFormCollection
Syntax: | XFFormCollection.Count
Type: | Long
Read/Write: | Read Only
Description: | Returns the number of form elements in the XFFormCollection.


Item Property

Object: | XFFormCollection
Syntax: | XFFormCollection.Item(Key)
Read/Write: | Read Only
Description: | Returns an XFFormElement object.


The XFFormElement Object

XFFormElement represents a single form field in an XFile request. Each XFFormElement is a member of an XFFormCollection. When you create an instance of XFRequest, the XFRequest object automatically creates an instance of XFFormElement.

  • XFFormElement Properties


Name Property

Object: | XFFormElement
Syntax: | XFFormElement.Name [= Field Name as String]
Type: | String
Read/Write: | Read/Write
Description: | Sets or returns the name of a form element.


Value Property

Object: | XFFormElement
Syntax: | XFFormElement.Value [= Form Value as String]
Type: | String
Read/Write: | Read/Write
Description: | Sets or returns the value of a form element.


The AXFFile Object

AXFFile is XFile's ActiveX upload control.

To create an instance of the AXFFile object, use the <OBJECT> tag, as follows.

<OBJECT classid="CLSID:230C3D02-DA27-11D2-8612-00A0C93EEA3C" height="200" codebase="/SAXFileSamples/saxfile.cab"
        id="AXFFile" style="HEIGHT: 200px; LEFT: 0px; TOP: 0px; WIDTH: 400px" width="400" VIEWASTEXT>%>

  • AXFFile Events
  • AXFFile Methods
  • AXFFile Properties


AXFFile Events

OnDrop

OnTransferComplete

OnTransferError

Previous Page Next Page


OnDrop

OnDrop Event

Object: AXFFile
Syntax: OnDrop()
Description: The OnDrop event fires when a file is dragged and dropped into the ActiveX control. The OnDrop event contains no arguments.
Example:
sub AXFFile_OnDrop()
    MsgBox "File Dropped."
end sub


OnTransferComplete

OnTransferComplete Event

Object: AXFFile
Syntax: OnTransferComplete()
Description: The OnTransferComplete event fires upon completion of a file transfer. The OnTransferComplete event contains no arguments.
Example: The following will display a message box when the file transfer is complete.
sub AXFFile_OnTransferComplete()
    MsgBox "Transfer Complete."
end sub


OnTransferError

OnTransferError Event

Object: AXFFile
Syntax: OnTransferError()
Description: The OnTransferError event fires if an error occurs during file transfer.
Example: The following lines will display a message box if an error occurs during file transfer.
sub AXFFile_OnTransferError()
    MsgBox "Error occurred."
end sub


AXFFile Methods

AboutBox

AddFile

Remove

Reset

Start

Previous Page Next Page


AboutBox

AboutBox Method

Object: AXFFile
Syntax: AXFFile.AboutBox()
Description: Displays an About box containing information about XFile's ActiveX control (version, legal information, etc.).
Example: The following will display an About box.
AXFFile.AboutBox()


AddFile

AddFile Method

Object: AXFFile
Syntax: AXFFile.AddFile File Name as String
Description: Adds a file to the upload. The file name, path, and size will be displayed in the ActiveX control window.
Example: The following adds C:\boot.ini to the upload.
AXFFile.AddFile "c:\boot.ini"


AddFileSelectorFilter

AddFileSelectorFilter Method

Object: AXFFile
Syntax: AXFFile.AddFileSelectorFilter(FilterDescription As String, FilterPattern As String)
Returns: Nothing
Description:

When the user clicks the visual upload control's "Add Files" button, a file selector dialog opens. AddFileSelectorFilter adds a filter to the file selector's "Files of Type" drop-down. The filters will be displayed in the order added.

The method's first parameter - FilterDescription - is a display string that describes the filter (for example "Text Files"). The second parameter - FilterPattern- specifies the file pattern (for example, "*.txt" or "*.*"). A pattern string can be a combination of valid file name characters and the wildcard character (*). A pattern string should not include spaces. To specify multiple filter patterns for a single display string, use a semicolon to separate patterns (for example, "*.txt"; *.doc").

Example:
<OBJECT classid="CLSID:7B7929AB-E06A-4508-BE68-1CC7A6997808" codebase="/XFileEESamples/saxfileEE.cab"
    id="AXFFile" style="LEFT: 0px; TOP: 0px" VIEWASTEXT>
<script language="vbs">
    Set XFile = AXFFile.XFrequest
    XFile.Server = "localhost"
    XFile.ObjectName = "/XFileEESamples/formresp.asp"
    AXFFile.AddFile "c:\file.txt"
    AXFFile.AddFileSelectorFilter("Text Files","*.txt")
</script>
See Also: ClearFileSelectorFilters


ClearFileSelectorFilters

ClearFileSelectorFilters Method

Object: AXFFile
Syntax: AXFFile.ClearFileSelectorFilters()
Returns: Nothing
Description:

When the user clicks the visual upload control's "Add Files" button, a file selector dialog opens. By default the file selector's "Files of Type" drop-down contains one filter - "All Files(*.*)". The method AddFileSelectorFilterallows you to add other filters to the drop-down. Use ClearFileSelectorFilters to clear all filters except "All Files(*.*)".

Example:
<OBJECT classid="CLSID:7B7929AB-E06A-4508-BE68-1CC7A6997808" codebase="/XFileEESamples/saxfileEE.cab"
    id="AXFFile" style="LEFT: 0px; TOP: 0px" VIEWASTEXT>
<script language="vbs">
    Set XFile = AXFFile.XFrequest
    XFile.Server = "localhost"
    XFile.ObjectName = "/XFileEESamples/formresp.asp"
    AXFFile.AddFile "c:\file.txt"
    AXFFile.AddFileSelectorFilter("Text Files","*.txt")
    ...
    AXFFile.ClearFileSelectorFilters()
    ...
</script>
See Also: AddFileSelectorFilter


Remove

Remove Method

Object: AXFFile
Syntax: AXFFile.Remove File Name as String
Description: Removes the specified file from the list of files to upload.
Example:
AXFFile.Remove "c:\boot.ini"


RemoveAll

RemoveAll Method

Object: AXFFile
Syntax: AXFFile.RemoveAll
Description: Removes all files from the list of files to upload.
Example: The following will remove all preset files from the list of files to upload, when the user drags a new file into the upload control.
Sub AXFFile_OnDrop()
    AXFFile.RemoveAll
End sub


Reset

Reset Method

Object: | AXFFile
Syntax: | AXFFile.Reset
Description: | Resets the ActiveX control to its original state. Reset restores the original file list and establishes a new Internet connection.


ShowAddFilesDialog

ShowAddFilesDialog Method

Object: | AXFFile
Syntax: | AXFFile.ShowAddFilesDialog
Description: | ShowAddFilesDialog displays the "Add Files" dialog, as if the user had clicked the visual upload control's “Add Files�? button.


Start

Start Method

Object: AXFFile
Syntax: AXFFile.Start()
Description: Starts an ActiveX control file upload.
Example: The following will initiate a file upload.
AXFFile.Start()


AXFFile Properties

AddButtonText

BackColor

BackStyle

Count

EnableAddButton

Enabled

EnableRemoveButton

EnableUploadButton

Files

RemoveButtonText

TabStop

UploadButtonText

XFRequest

XFRequestStream

Previous Page Next Page


AddButtonText Property

Object: AXFFile
Type: String
Read/Write: Read/Write
Description: AddButtonText sets the text displayed on the visual upload control's "Add Files" button.
Example:
'--- Set AddButtonText using the PARAM tag:
<PARAM NAME="AddButtonText" VALUE="Add">
Note: AddButtonText is a parameter, not a scriptable property. Use the PARAM tag to set this parameter; do not use the syntax AXFFile.AddButtonText. AddButtonText cannot be set dynamically at runtime.


BackColor

BackColor Property

Object: AXFFile
Syntax: AXFFile.BackColor [= Color as RGB Value]
Type: OLE_Color
Read/Write: Read/Write
Description: Sets or returns the background color of the upload control.
Example: To set the background color of the upload control to yellow, use,
AXFFile.BackColor = RGB(255,255,0)


BackStyle

Backstyle Property

Object: AXFFile
Syntax: AXFFile.BackStyle [= Background Style as Long]
Type: Long
Read/Write: Read/Write
Description: Sets or returns the background style of the upload control. XFile supports three BackStyle values:

0 | Transparent
1 | Opaque
2 | System Dialog
Example: To set BackStyle to System Dialog, use,
AXFFile.BackStyle = 2


Count

Count Property

Object: | AXFFile
Syntax: | AXFFile.Count
Type: | Long
Read/Write: | Read Only
Description: | Returns the number of files set to upload to the server.


EnableAddButton Property

Object: AXFFile
Type: Boolean
Read/Write: Read/Write
Description: When EnableAddButton is set to True, the visual upload control's "Add Files" button will be visible. When EnableAddButton is set to False, the button will not be displayed. EnableAddButton is set to True by default.
Example:

'--- Set EnableAddButton using the PARAM tag:
<PARAM NAME="EnableAddButton" VALUE="0">
Note: EnableAddButton is a parameter, not a scriptable property. Use the PARAM tag to set this parameter; do not use the syntax AXFFile.EnableAddButton. EnableAddButton cannot be set dynamically at runtime.


Enabled

Enabled Property

Object: | AXFFile
Syntax: | AXFFile.Enabled [= Boolean]
Type: | Boolean
Read/Write: | Read/Write
Description: | When Enabled is set to True, the upload control can respond to user-generated events. When Enabled is set to False, the upload control will not respond to user-generated events.


EnableRemoveButton

EnableRemoveButton Property

Object: AXFFile
Type: Boolean
Read/Write: Read/Write
Description: When EnableRemoveButton is set to True, the visual upload control's "Remove Files" button will be visible. When EnableRemoveButton is set to False, the button will not be displayed. EnableRemoveButton is set to True by default.
Example:
--- Set EnableRemoveButton using the PARAM tag:
<PARAM NAME="EnableRemoveButton" VALUE="0">
Note: EnableRemoveButton is a parameter, not a scriptable property. Use the PARAM tag to set this parameter; do not use the syntax AXFFile.EnableRemoveButton. EnableRemoveButton cannot be set dynamically at runtime.


EnableUploadButton Property

Object: AXFFile
Type: Boolean
Read/Write: Read/Write
Description: When EnableUploadButton is set to True, the visual upload control's "Start Upload" button will be visible. When EnableUploadButton is set to False, the button will not be displayed. EnableUploadButton is set to True by default.
Example:
'--- Set EnableUploadButton using the PARAM tag:
<PARAM NAME="EnableUploadButton" VALUE="0">
Note: EnableUploadButton is a parameter, not a scriptable property. Use the PARAM tag to set this parameter; do not use the syntax AXFFile.EnableUploadButton. EnableUploadButton cannot be set dynamically at runtime.


FileNameColumnHeading

FileNameColumnHeading Property

Object: AXFFile
Syntax: AXFFile.FileNameColumnHeading [= String]
Type: String
Read/Write: Read/Write
Description: The visual upload control contains two columns: a file name column and a file size column. FileNameColumnHeading sets the text of the file name column heading.

Example:
<OBJECT classid="CLSID:7B7929AB-E06A-4508-BE68-1CC7A6997808" codebase="/XFileEESamples/saxfileEE.cab"
    id="AXFFile" style="LEFT: 0px; TOP: 0px" VIEWASTEXT>
<script language="vbs">
    Set XFile = AXFFile.XFrequest
    XFile.Server = "localhost"
    XFile.ObjectName = "/XFileEESamples/formresp.asp"
    AXFFile.AddFile "c:\file.txt"
    AXFFile.FileNameColumnHeading = "File Name"
    AXFFile.FileSizeColumnHeading = "File Size"
</script>
See Also: FileSizeColumnHeading


Files

Files Property

Object: AXFFile
Syntax: AXFFile.Files
Read/Write: Read Only
Description: Returns an AXFileCollection object, representing the set of files assigned for upload through the ActiveX control.
Example: The following will add "c:\sample.jpg" to the file upload.
AXFFile.Files.Add "c:\sample.jpg"


FileSelectorHeight

FileSelectorHeight Property

Object: AXFFile
Syntax: AXFFile.FileSelectorHeight [= Long]
Type: Long
Read/Write: Read/Write
Description: When the user clicks the visual upload control's "Add Files" button, a file selector dialog opens. FileSelectorHeight sets the height of the file selector dialog in pixels. FileSelectorHeight can be any value between 200 and 800. The default value is 250.
Example:
<OBJECT classid="CLSID:7B7929AB-E06A-4508-BE68-1CC7A6997808" codebase="/XFileEESamples/saxfileEE.cab"
    id="AXFFile" style="LEFT: 0px; TOP: 0px" VIEWASTEXT>
<script language="vbs">
    Set XFile = AXFFile.XFrequest
    XFile.Server = "localhost"
    XFile.ObjectName = "/XFileEESamples/formresp.asp"
    AXFFile.AddFile "c:\file.txt"
    AXFFile.FileViewType = 3
    AXFFile.FileSelectorHeight = 350
</script>


FileSelectorWidth

FileSelectorWidth Property

Object: AXFFile
Syntax: AXFFile.FileSelectorWidth [= Long]
Type: Long
Read/Write: Read/Write
Description: When the user clicks the visual upload control's "Add Files" button, a file selector dialog opens. FileSelectorWidth sets the width of the file selector dialog in pixels. FileSelectorWidth can be any value between 400 and 1200. The default value is 400.
Example:
<OBJECT classid="CLSID:7B7929AB-E06A-4508-BE68-1CC7A6997808" codebase="/XFileEESamples/saxfileEE.cab"
    id="AXFFile" style="LEFT: 0px; TOP: 0px" VIEWASTEXT>
<script language="vbs">
    Set XFile = AXFFile.XFrequest
    XFile.Server = "localhost"
    XFile.ObjectName = "/XFileEESamples/formresp.asp"
    AXFFile.AddFile "c:\file.txt"
    AXFFile.FileViewType = 3
    AXFFile.FileSelectorWidth = 800
</script>


FileSizeColumnHeading

FileSizeColumnHeading Property

Object: AXFFile
Syntax: AXFFile.FileSizeColumnHeading [= String]
Type: String
Read/Write: Read/Write
Description: The visual upload control contains two columns: a file name column and a file size column. FileSizeColumnHeading sets the text of the file size column heading.

Example:
<OBJECT classid="CLSID:7B7929AB-E06A-4508-BE68-1CC7A6997808" codebase="/XFileEESamples/saxfileEE.cab"
    id="AXFFile" style="LEFT: 0px; TOP: 0px" VIEWASTEXT>
<script language="vbs">
    Set XFile = AXFFile.XFrequest
    XFile.Server = "localhost"
    XFile.ObjectName = "/XFileEESamples/formresp.asp"
    AXFFile.AddFile "c:\file.txt"
    AXFFile.FileNameColumnHeading = "File Name"
    AXFFile.FileSizeColumnHeading = "File Size"
</script>
See Also: FileNameColumnHeading


FileViewType

FileViewType Property

Object: AXFFile
Syntax: AXFFile.FileViewType [= SAFileViewType]
Type: SAFileViewType
Read/Write: Read/Write
Description: When the user clicks the visual upload control's "Add Files" button, a file selector dialog opens. FileViewType sets the file view mode to use in the file selector. Set FileViewType to an SAFileViewType by name or number:

SAFileViewType Values
LargeIcons | 0
SmallIcons | 1
List | 2
Details | 3
Thumbnails | 4
Example:
<OBJECT classid="CLSID:7B7929AB-E06A-4508-BE68-1CC7A6997808" codebase="/XFileEESamples/saxfileEE.cab"
    id="AXFFile" style="LEFT: 0px; TOP: 0px" VIEWASTEXT>
<script language="vbs">
    Set XFile = AXFFile.XFrequest
    XFile.Server = "localhost"
    XFile.ObjectName = "/XFileEESamples/formresp.asp"
    AXFFile.AddFile "c:\file.txt"
    AXFFile.FileViewType = 3
</script>


RemoveButtonText

RemoveButtonText Property

Object: AXFFile
Syntax: AXFFile.RemoveButtonText [= String]
Type: String
Read/Write: Read/Write
Description: RemoveButtonText sets the text displayed on the visual upload control's "Remove Files" button.
Example:
'--- Set RemoveButtonText using the PARAM tag:
<PARAM NAME="RemoveButtonText" VALUE="Remove">
Note: RemoveButtonText is a parameter, not a scriptable property. Use the PARAM tag to set this parameter; do not use the syntax AXFFile.RemoveButtonText. RemoveButtonText cannot be set dynamically at runtime.


SuppressPopupTransferError

SuppressPopupTransferError Property

Object: AXFFile
Syntax: AXFFile.SuppressPopupTransferError [= Boolean]
Type: Boolean
Read/Write: Read/Write
Description: If SuppressPopupTransferError is set to True, XFile will not display pop-up transfer errors. By default, SuppressPopupTransferError is set to False, and XFile will display pop-up errors even if error handling is in place in the script.
Example:
AXFFile.SuppressPopupTransferError = True


TabStop

TabStop Property

Object: | AXFFile
Syntax: | AXFFile.TabStop [= Boolean]
Type: | Boolean
Read/Write: | Read/Write
Description: | When TabStop is set to True, the user can use the Tab key to change object focus. When TabStop is set to False, the user cannot use the Tab key to change object focus.


UploadButtonText

UploadButtonText Property

Object: AXFFile
Type: String
Read/Write: Read/Write
Description: UploadButtonText sets the text displayed on the visual upload control's "Start Upload" button.
Example:
'--- Set UploadButtonText using the PARAM tag:
<PARAM NAME="UploadButtonText" VALUE="Upload">
Note: UploadButtonText is a parameter, not a scriptable property. Use the PARAM tag to set this parameter; do not use the syntax AXFFile.UploadButtonText. UploadButtonText cannot be set dynamically at runtime.


XFRequest

XFRequest Property

Object: AXFFile
Syntax: AXFFile.XFRequest
Read/Write: Read Only
Description: Returns an XFRequest object.
Example:
Set SAXFile = AXFFile.XFRequest
SAXFile.Server = "localhost"
SAXFile.ObjectName = "/saxfilesamples/formresp2.asp"
AXFFile.AddFile "c:\boot.ini"
SAXFile.Start


XFRequestStream

XFRequestStream Property

Object: AXFFile
Syntax: AXFFile.XFRequestStream
Read/Write: Read Only
Description: XFRequestStream returns an object representing the HTTP request stream
sent by XFRequest.
Example: To synchronize AXFFile and its progress indicator, assign AXFFile's
XFRequestStream value to the AXFFileProgress object's XFRequestStream
property:
document.all("AXFFileProgress").XFRequestStream = opener.document.all("AXFFile").XFRequestStream

Document refers to the AXFFileProgress window object, and document.opener
refers to the AXFFile window.


The AXFFileProgress Object

  • Events
  • Methods
  • Properties


AXFFileProgress Events

TransferCancelled

TransferComplete

TransferError

Previous Page Next Page


TransferCancelled

TransferCancelled Event

Object: AXFFileProgress
Syntax: TransferCancelled()
Description: The TransferCancelled event fires when the user cancels a transfer by clicking the progress indicator's "Cancel" button. The TransferCancelled event contains no arguments.
Example: The following will display a message box if the user cancels a transfer.
sub AXFFileProgress_TransferCancelled()
    MsgBox "Transfer cancelled"
end sub


TransferComplete

TransferComplete Event

Object: AXFFileProgress
Syntax: TransferComplete()
Description: The TransferComplete event fires upon completion of a file transfer. The TransferComplete event contains no arguments.
Example: The following will display a message box when the file transfer is complete.
sub AXFFileProgress_TransferComplete()
    MsgBox "Transfer complete."
end sub


TransferError

TransferError Event

Object: AXFFileProgress
Syntax: TransferError()
Description: The TransferError event fires if an error occurs during file transfer. The TransferError event contains no arguments.
Example: The following will display a message box if an error occurs during transfer.
sub AXFFileProgress_TransferError()
    MsgBox "Error occurred"
end sub


AXFFileProgress Methods

AboutBox

ShowProgress

Previous Page Next Page


AboutBox

AboutBox Method

Object: AXFFileProgress
Syntax: AXFFileProgress.AboutBox()
Description: Displays an About box containing information about XFile's ActiveX progress indicator (version, legal information, etc.).
Example: The following will display an About box.
AXFFileProgress.AboutBox()


ShowProgress Method

Object: AXFFileProgress
Syntax: AXFFileProgress.ShowProgress
Description: The ShowProgress method initiates the progress indicator.
Example: The following procedure synchronizes the ActiveX control and its progress
indicator, and initiates both.
Sub Callback()
    '--- Synchronize the upload control and the progress indicator:
    document.all("AXFFileProgress").XFRequestStream = opener.document.all("AXFFile").XFRequestStream

    '--- Initiate the progress indicator.
    document.all("AXFFileProgress").ShowProgress

    '--- Start the file transfer.
    opener.document.all("AXFFile").Start

    '--- Close the progress window when the transfer is complete.
    window.close
End Sub


AXFFileProgress Properties

BackColor

BackStyle

CancelButtonText Property

EnableCancelButton Property

HideURL Property

XFRequestStream

Previous Page Next Page


BackColor Property

Object: AXFFileProgress
Syntax: AXFFileProgress.BackColor [= Color as RGB Value]
Type: OLE_Color
Read/Write: Read/Write
Description: Sets or returns the background color of the progress indicator.
Example:
AXFFileProgress.BackColor = RGB(255,255,0) '--- yellow


BackStyle

BackStyle Property

Object: AXFFileProgress
Syntax: AXFFileProgress.BackStyle [= Background Style as Long]
Type: Long
Read/Write: Read/Write
Description: Sets or returns the background style of the progress indicator. XFile supports three BackStyle values:

0 | Transparent
1 | Opaque
2 | System Dialog
Example: To set BackStyle to System Dialog, use,
AXFFileProgress.BackStyle = 2


CancelButtonText Property

Object: AXFFileProgress
Type: String
Read/Write: Read/Write
Description: CancelButtonText sets the text displayed on the progress indicator's "Cancel" button.
Example:
'--- Set CancelButtonText using the PARAM tag:
<PARAM NAME="CancelButtonText" VALUE="Cancel Upload">
Note: CancelButtonText is a parameter, not a scriptable property. Use the PARAM tag to set this parameter; do not use the syntax AXFFileProgress.CancelButtonText. CancelButtonText cannot be set dynamically at runtime.


DisableAnimatedGif

DisableAnimatedGif Property

Object: AXFFileProgress
Syntax: AXFFileProgress.DisableAnimatedGif [= Boolean]
Type: Boolean
Read/Write: Read/Write
Description: XFile's visual progress indicator includes an animated image. If you set DisableAnimatedGifto True, the image will not be displayed. The property is set to False by default.

Example:
<OBJECT ID="AXFFileProgress" CLASSID="CLSID:9C6E12BB-F8AE-44aa-9694-9912396B6033" VIEWASTEXT>
<SCRIPT language="vbs">
    AXFFileProgress.DisableAnimatedGif = True
    sub AXFFileProgress_TransferComplete()
        MsgBox "Transfer completed"
    end sub
</SCRIPT>


EnableCancelButton Property

Object: AXFFileProgress
Syntax: AXFFileProgress.EnableCancelButton [= Boolean]
Type: Boolean
Read/Write: Read/Write
Description: When EnableCancelButton is set to True, the progress indicator will include a "Cancel" button. When EnableCancelButton is set to False, the button will not be displayed. EnableCancelButton is set to True by default.
Example:
'--- Set EnableCancelButton using the PARAM tag:
<PARAM NAME="EnableCancelButton" VALUE="0">
Note: EnableCancelButton is a parameter, not a scriptable property. Use the PARAM tag to set this parameter; do not use the syntax AXFFileProgress.EnableCancelButton. EnableCancelButton cannot be set dynamically at runtime.


HideURL Property

Object: AXFFileProgress
Type: Boolean
Read/Write: Read/Write
Description: By default, the visual progress indicator will display an "Upload to" field that shows the URL of the upload processing page on the server. To hide the "Upload to" field, set HideURL to True.
Example:
'--- Set HideURL using the PARAM tag:
<PARAM NAME="HideURL" VALUE="1">
Note: HideURL is a parameter, not a scriptable property. Use the PARAM tag to set this parameter; do not use the syntax AXFFileProgress.HideURL. HideURL cannot be set dynamically at runtime.


XFRequest

XFRequest Property

Object: AXFFileProgress
Syntax: AXFFileProgress.XFRequest
Read/Write: Write Only
Description: Use XFRequest to pass the XFRequest object to the progress indicator, that is,
to set the request for AXFFileProgress to monitor. Alternatively, use XFRequestStream.
Example: To synchronize the upload control and its progress indicator, assign AXFFile's
XFRequest value to the AXFFileProgress object's XFRequest
property:
document.all("AXFFileProgress").XFRequest = opener.document.all("AXFFile").XFRequest
Document refers to the AXFFileProgress window object, and document.opener
refers to the AXFFile window.


XFRequestStream

XFRequestStream Property

Object: AXFFileProgress
Syntax: AXFFileProgress.XFRequestStream
Read/Write: Write Only
Description: XFRequestStream sets an HTTP request stream for AXFFileProgress. That is,
XFRequestStream sets the request to monitor.
Example: To synchronize the upload control and its progress indicator, assign AXFFile's
XFRequestStream value to the AXFFileProgress object's XFRequestStream
property:
 document.all("AXFFileProgress").XFRequestStream = opener.document.all("AXFFile").XFRequestStream
Document refers to the AXFFileProgress window object, and document.openerrefers to the AXFFile window.
See Also: The XFRequest object's XFRequestStreamproperty.


The AXFFileDownload Object

AXFFileDownload is XFile's ActiveX download control. To learn how to use AXFFileDownload, see, Downloading with the ActiveX Control and Downloading with the ActiveX Control in Visual Basic.

  • AXFFileDownload Events
  • AXFFileDownload Methods
  • AXFFileDownload Properties


AXFFileDownload Events

OnTransferComplete

OnTransferError

Previous Page Next Page


OnTransferComplete

OnTransferComplete Event

Object: AXFileDownload
Syntax: OnTransferComplete()
Description: The OnTransferComplete event fires upon download completion. The OnTransferComplete event contains no arguments.
Example: The following will display a message box when the download is complete.
sub AXFFileDownload_OnTransferComplete()
    MsgBox "Download complete."
end sub


OnTransferError

OnTransferError Event

Object: AXFileDownload
Syntax: OnTransferError()
Description: The OnTransferError event fires if an error occurs during download.
Example: The following will display a message box if an error occurs during download.
sub AXFFileDownload_OnTransferError()
    MsgBox "Error occurred."
end sub


AXFFileDownload Methods

AboutBox

AddFile

Remove

Reset

Start

Previous Page Next Page


AboutBox

AboutBox Method

Object: AXFFileDownload
Syntax: AXFFileDownload.AboutBox()
Description: Displays an About box containing information about XFile's ActiveX download control (version, legal information, etc.).
Example:
AXFFileDownload.AboutBox()


AddFile

AddFile Method

Object: AXFFileDownload
Syntax: AXFFileDownload.AddFile File Path and Name as String, URL as String
Description: Adds a file to the download. Addfile takes to parameters:
  • File Path and Name as String
    Destination of the downloaded file on the local machine

  • URL as String
    Complete URL of the file to download
Example:
AXFFileDownload.AddFile "c:\file.txt", "http://localhost/samples/sample.txt"


Remove

Remove Method

Object: AXFFileDownload
Syntax: AXFFileDownload.Remove URL as String
Description: Removes the specified file from the list of files to download.
Example:
AXFFileDownload.Remove "http://localhost/saxfilesamples//readme.txt"


RemoveAll

RemoveAll Method

Object: AXFFileDownload
Syntax: AXFFileDownload.RemoveAll
Description: Removes all files from the list of files to download.
Example: The following will remove all preset files from the list of files to download, when the download is complete.
Sub AXFFileDownload_OnTransferComplete()
    AXFFileDownload.RemoveAll
End sub


Reset

Reset Method

Object: | AXFFileDownload
Syntax: | AXFFileDownload.Reset
Description: | Resets the ActiveX download control to its original state. Reset restores the original file list and establishes a new Internet connection.


Start

Start Method

Object: AXFFileDownload
Syntax: AXFFileDownload.Start()
Description: Starts an ActiveX control file download.
Example:
AXFFileDownload.Start()


AXFFileDownload Properties

BackColor

Count

EnablePopUpMenu

Files

HideURL

XFRequest

XFRequestStream

Previous Page Next Page


BackColor Property

Object: AXFFileDownload
Syntax: AXFFileDownload.BackColor [= Color as RGB Value]
Type: OLE_Color
Read/Write: Read/Write
Description: Sets or returns the background color of the download control.
Example:
AXFFileDownload.BackColor = RGB(255,255,0) '--- yellow


Count

Count Property

Object: | AXFFileDownload
Syntax: | AXFFileDownload.Count
Type: | Long
Read/Write: | Read only
Description: | Returns the number of files set for download.


EnablePopUpMenu Property

Object: AXFFileDownload
Type: Boolean
Read/Write: Read/Write
Description: By default, when the user right-clicks the visual download control, a pop-up menu will be displayed. The menu contains the entries "Rename," "Remove," and "Remove All." To disable the pop-up menu, set EnablePopUpMenu to False.
Example:
'--- Set EnablePopUpMenu using the PARAM tag:
<PARAM NAME="EnablePopUpMenu" VALUE="0">
Note: EnablePopUpMenu is a parameter, not a scriptable property. Use the PARAM tag to set this parameter; do not use the syntax AXFFileDown.EnablePopUpMenu. EnablePopUpMenu cannot be set dynamically at runtime.


FileNameColumnHeading

FileNameColumnHeading Property

Object: AXFFileDownload
Syntax: AXFFileDownload.FileNameColumnHeading [= String]
Type: String
Read/Write: Read/Write
Description: The visual download control contains two columns: a file name column and a URL column. The file name column specifies the local destination path for the downloaded file. FileNameColumnHeading sets the text of the file name column heading.

Example:
<OBJECT classid="CLSID:AD58C149-8AE2-4878-99DC-3A164E32F814" codebase="/XFileEESamples/saxfileEE.cab" height="200"
    id="AXFFileDownload" style="HEIGHT: 200px; LEFT: 0px; TOP: 0px; WIDTH: 400px" width="400" VIEWASTEXT>
<script language="VBS">
    AXFFileDownload.AddFile "c:\testone.txt", "http://localhost/readme.txt"
    AXFFileDownload.AddFile "c:\testone.htm", "http://localhost/default.htm"
    AXFFileDownload.FileNameColumnHeading = "Download Destination"
    AXFFileDownload.URLColumnHeading = "Download Source"
</script>
See Also: URLColumnHeading
FileNameColumnWidth


FileNameColumnWidth

FileNameColumnWidth Property

Object: AXFFileDownload
Syntax: AXFFileDownload.FileNameColumnWidth [= Long]
Type: Long
Read/Write: Read/Write
Description:

The visual download control contains two columns: a file name column and a URL column. FileNameColumnWidth sets the width of the file name column as a percentage of the width of the download control. The default value of FileNameColumnWidthis 50.

Setting HideURLto True sets FileNameColumnWidth to 100.

Example:
<OBJECT classid="CLSID:AD58C149-8AE2-4878-99DC-3A164E32F814" codebase="/XFileEESamples/saxfileEE.cab" height="200"
    id="AXFFileDownload" style="HEIGHT: 200px; LEFT: 0px; TOP: 0px; WIDTH: 400px" width="400" VIEWASTEXT>
<script language="VBS">
    AXFFileDownload.AddFile "c:\testone.txt", "http://localhost/readme.txt"
    AXFFileDownload.AddFile "c:\testone.htm", "http://localhost/default.htm"
    AXFFileDownload.FileNameColumnHeading = "Download Destination"
    AXFFileDownload.URLColumnHeading = "Download Source"
    AXFFileDownload.FileNameColumnWidth = 30
</script>
See Also: URLColumnHeading
FileNameColumnHeading


Files

Files Property

Object: AXFFileDownload
Syntax: AXFFileDownload.Files
Read/Write: Read only
Description: Returns an AXFileCollection object representing the set of files to download.
Example: The following will remove all files from the download list when the download is complete.
sub AXFFileDownload_OnTransferComplete()
    AXFFileDownload.Files.RemoveAll
end sub


HideURL Property

Object: AXFFileDownload
Type: Boolean
Read/Write: Read/Write
Description: By default, the visual download control displays the URLs of the files to download. To hide the URLs, set HideURL to True.
Example:
'--- Set HideURL using the PARAM tag:
<PARAM NAME="HideURL" VALUE="0">
Note: HideURL is a parameter, not a scriptable property. Use the PARAM tag to set this parameter; do not use the syntax AXFFileDown.HideURL. HideURL cannot be set dynamically at runtime.


SuppressPopupTransferError

SuppressPopupTransferError Property

Object: AXFFile
Syntax: AXFFileDownload.SuppressPopupTransferError [= Boolean]
Type: Boolean
Read/Write: Read/Write
Description: If SuppressPopupTransferError is set to True, XFile will not display pop-up transfer errors. By default, SuppressPopupTransferError is set to False, and XFile will display pop-up errors even if error handling is in place in the script.
Example:
AXFFileDownload.SuppressPopupTransferError = True


URLColumnHeading

URLColumnHeading Property

Object: AXFFileDownload
Syntax: AXFFileDownload.URLColumnHeading [= String]
Type: String
Read/Write: Read/Write
Description: The visual download control contains two columns: a file name column and a URL column. The URL column specifies the URL of the file to download. URLColumnHeadingsets the text of the URL column heading.

Example:
<OBJECT classid="CLSID:AD58C149-8AE2-4878-99DC-3A164E32F814" codebase="/XFileEESamples/saxfileEE.cab" height="200"
    id="AXFFileDownload" style="HEIGHT: 200px; LEFT: 0px; TOP: 0px; WIDTH: 400px" width="400" VIEWASTEXT>
<script language="VBS">
    AXFFileDownload.AddFile "c:\testone.txt", "http://localhost/readme.txt"
    AXFFileDownload.AddFile "c:\testone.htm", "http://localhost/default.htm"
    AXFFileDownload.FileNameColumnHeading = "Download Destination"
    AXFFileDownload.URLColumnHeading = "Download Source"
</script>
See Also: FileNameColumnHeading
FileNameColumnWidth


XFRequest

XFRequest Property

Object: AXFFileDownload
Syntax: AXFFileDownload.XFRequest
Read/Write: Read only
Description: Returns an XFRequest object.
Example:
Set SAXFile = AXFFileDownload.XFRequest


XFRequestStream

XFRequestStream Property

Object: AXFFileDownload
Syntax: AXFFileDownload.XFRequestStream
Read/Write: Read only
Description: XFRequestStream returns an object representing the HTTP request stream sent by XFRequest.
Example: To synchronize AXFFileDownload and its progress indicator, assign AXFFileDownload's XFRequestStream value to the AXFFileProgress object's XFRequestStream property:
document.all("AXFFileProgress").XFRequestStream = opener.document.all("AXFFileDownload").XFRequestStream
Document refers to the AXFFileProgress window object, and document.opener
refers to the AXFFileDownload window.


The AXFileCollection Object

The AXFileCollection Object represents the set of files to transfer through the ActiveX control.

Methods

Properties


AXFileCollection Methods

Add

Remove

RemoveAll

Previous Page Next Page


Add

Add Method

Object: AXFileCollection
Syntax: AXFileCollection.Add File Name as String
Description: Adds the specified file to the collection of files to upload through the ActiveX control.
Example:
Set AXFiles = AXFFile.Files
AXFiles.Add "c:\boot.ini"


Remove

Remove Method

Object: AXFileCollection
Syntax: AXFileCollection.Remove File Name as String
Description: Removes the specified file from the set of files to upload.
Example: The following lines add boot.ini to the file upload, and remove boot.ini if the user drag-and-drops another file into the upload control.
Set AXFiles = AXFFile.Files
AXFiles.Add "c:\boot.ini"
sub AXFFile_OnDrop()
    AXFiles.remove
    "c:\boot.ini"
end sub


RemoveAll

RemoveAll Method

Object: AXFileCollection
Syntax: AXFileCollection.RemoveAll
Description: Removes all files from the list of files to upload.
Example: The following lines add boot.ini and sample.jpg to the file upload, and remove both if the user drag-and-drops another file into the upload control.
Set AXFiles = AXFFile.Files
AXFiles.Add "c:\boot.ini"
AXFiles.Add "c:\sample.jpg"
sub AXFFile_OnDrop()
    AXFiles.RemoveAll
end sub


AXFileCollection Properties

Count

Item

Previous Page Next Page


Count

Count Property

Object: | AXFileCollection
Syntax: | AXFileCollection.Count
Type: | Long
Read/Write: | Read only
Description: | Returns the number of files in the AXFileCollection, that is, the number of files set to upload.


Item

Item Property

Object: | AXFileCollection
Syntax: | AXFileCollection.Item(Key)
Read/Write: | Read only
Description: | Returns a single file in an AXFileCollection.


The XFResume Object

In a resumable file transfer, if the transfer fails, the XFResume object contains information about the failed request. Use this object to:

  • Get information about failed requests,
  • Update properties set by the ResumeInfo object, and
  • Resume failed transfers.

Through the methods and properties on XFResume, you can access the RequestRecord object, the RecordsCollection object, the FilesCollection object, and the File object.

To create an instance of the XFResume object, use the HTML <object> tag:

<object classid="clsid:53B29E97-9753-44B4-AE57-D51322B2BD49" id="XFResume"></object>

XFResume Methods

XFResume Properties


XFResume Object Methods

Close

DeleteRecord

GetRequestRecord

Open

Resume


Close

Close Method

Object: | XFResume
Syntax: | XFResume.Close
Parameters: | None
Return Value: | None
Description: | Closes the XFResume object.


DeleteRecord

DeleteRecord Method

Object: | XFResume
Syntax: | XFResume.DeleteRecord(JobId)
Parameter: | JobId
Return Value: | None
Description: | DeleteRecord takes a request's JobId and deletes the RequestRecord for the specified JobId from the XFResume object. DeleteRecord removes the request data stored on the user's system.


GetRequestRecord

GetRequestRecord Method

Object: XFResume
Syntax: XFResume.GetRequestRecord(JobId)
Parameter: JobId
ReturnValue: RequestRecord
Description: GetRequestRecord takes a request's JobIdand returns the RequestRecordfor the specified JobId.
Example:

To get the record that contains information about a failed request, pass the request's JobId to the GetRequestRecord method:

Set XFResumeRecord = XFResume.GetRequestRecord(SAXFile.ResumeInfo.JobId)


Open

Open Method

Object: XFResume
Syntax: XFResume.Open(TopFolder Location as String)
Parameter: String specifying the TopFolder location (the location on the client where the request data for resumable file transfers is stored). Set this location through ResumeInfo.TopFolder or XFResume.TopFolder.

The TopFolder parameter is not required if:
  1. ResumeInfo.TopFolder was not set when the initial request was made. In this case, XFile will use the user's temp directory.

  2. You set XFResume.TopFolder before calling Open.
ReturnValue: None
Description: Opens the XFResume object so that RequestRecords can be retrieved and their properties populated. You do not need to call Open to get a RequestRecord using GetRequestRecord, but you must call Open to get a RequestRecord through XFResume.RequestRecords.

If you call GetRequestRecord without calling Open first and ResumeInfo.TopFolder was set when the initial request was made, you must set XFResume.TopFolder.


Resume

Resume Method

Object: XFResume
Syntax: XFResume.Resume(JobId as String, [optional StartAsynch as Boolean = False])
Parameters:
  • JobId
  • (optional) a boolean value for whether the resume is asynchronous or not (False by default)
Return Value: XFRequestobject
Description: Resumes the RequestRecordfor the specified JobId, and returns the XFRequestobject used to resume the request.


XFResume Object Properties

CodePage

RequestRecords

StatusUrl

TimeOut

TopFolder

VerifyChecksums


CodePage

CodePage Property

Object: | XFResume
Syntax: | XFResume.CodePage [=Language Code as Long]
Type: | Long
Default Value: | Either the value of the XFRequest.CodePage property of the initial request or, if XFRequest.CodePage was not set, the default system CodePage.
Read/Write: | Read/Write
Description: | In a resumable file transfer, CodePage sets the language CodePage for the file(s) to transfer. XFile is Unicode compliant, enabling the transfer of data between systems, regardless of language, without the risk of file name corruption. Set XFResume.CodePage to preserve file names in their original language in a resumed upload. The CodePage property specifies a Unicode language code for correctly storing the file name internally. To display the file name correctly, set the HTML <meta> tag's Charset attribute as well. When client and server share the same language platform, you do not need to set CodePage. For heterogeneous language support, set CodePage to 65001 and charset to UTF-8 (Unicode). For a complete list of CodePage values, see Microsoft's Character Set Recognition [image] reference.


RequestRecords

RequestRecords Property

Object: | XFResume
Syntax: | XFResume.RequestRecords
Type: | RecordsCollection
Default Value: | None
Read/Write: | Read only
Description: | Returns the collection of RequestRecords for resumable file transfers.


StatusUrl

StatusUrl Property

Object: | XFResume
Syntax: | XFResume.StatusUrl
Type: | String
Default Value: | The value set by the ResumeInfo.StatusUrl property when the initial request took place.
Read/Write: | Read/Write
Description: | To create a resumable upload application, you must use FileUpEE to handle the server-side file transfer processing. FileUpEE saves information about the upload request in a database on the server. Before resuming a failed upload, XFile gets status information about the failed upload (the number of bytes received on the server so far) from FileUpEE. StatusUrl specifies the URL of the FileUpEE status script to which XFile will send the upload status request. The FileUpEE page specified by StatusUrl retrieves the upload status from the database, and sends it to XFile. By default, XFResume.StatusUrl is set to the value of the ResumeInfo.StatusUrl property when the initial request took place. If the status of the request should be retrieved from a different URL than the one originally set, set XFResume.StatusUrl.


TimeOut

TimeOut Property

Object: | XFResume
Syntax: | XFResume.TimeOut [=TimeOut in Seconds as Long]
Type: | Long
Default Value: | 90 seconds
Read/Write: | Read/Write
Description: | Sets a time, in seconds, for a resumed file transfer to execute before timing out.


TopFolder

TopFolder Property

Object: | XFResume
Syntax: | XFResume.TopFolder [=Folder Path]
Type: | String
Default Value: | None
Read/Write: | Read/Write
Description: | In a resumable file transfer, XFResume.TopFolder tells the XFResume object where RequestRecords were stored. That location is set by the property ResumeInfo.TopFolder. Set XFResume.TopFolder if ResumeInfo.TopFolder was set when the initial request was made, unless you call XFResume.Open and pass it the TopFolder parameter. If CacheRequest is set to true, the whole file transfer request will be stored in the folder specified by ResumeInfo.TopFolder. If CacheRequest is set to false, only information about the request will be stored. If ResumeInfo.TopFolder is not set, XFile will store request data in the user's temp directory.


VerifyChecksums

XFResume VerifyChecksums Property

Object: | XFResume
Syntax: | XFResume.VerifyChecksums [=Boolean]
Type: | Boolean
Default Value: | False
Read/Write: | Read/Write
Description: | In a resumable file transfer, if the request was not cached (that is, if CacheRequest is set to false), VerifyChecksums tells the XFRequest object to verify that the files to transfer were not modified, before resuming the file transfer. If the files were modified, an error will occur.


The ResumeInfo Object

The ResumeInfo object is used to tell XFile that a file transfer request is resumable, and how the resumable request should be handled. You can access the ResumeInfo object through XFRequest . ResumeInfo.

ResumeInfo Properties


ResumeInfo Object Properties

CacheRequest

JobId

Resumable StatusURL

StatusURL

TopFolder

VerifyChecksums


CacheRequest Property

Object: ResumeInfo
Syntax: oResumeInfo.CacheRequest [=Boolean]
Type: Boolean
Default Value: True
Read/Write: Read/Write
Description: In a resumable upload, CacheRequest tells the XFRequest object to either cache the entire request or just store information about the request.

If CacheRequest is set to true XFile will save copies of the files to upload before sending the upload request. In a resumable upload, enabling CacheRequest guarantees the integrity of the files and any form/post data in the resume request.

If CacheRequest is set to false, XFile will not pre-cache the files. The request may still be resumable, but the request data may be corrupt, if the files to transfer were altered.

CacheRequest is set to true by default.

When CacheRequest is enabled uploads will be slower and will require more disk space.
Example:

...
Set XFileResumeInfo = SAXFile.ResumeInfo

'--- Set Resumable to True to allow the upload to be resumed.
XFileResumeInfo.Resumable = True

'--- If CacheRequest is set to True XFile will save copies of the
'--- files to upload before sending the upload request. In a resumable
'--- upload, enabling CacheRequest guarantees the integrity of
'--- the resumed request.
XFileResumeInfo.CacheRequest = True

'--- StatusUrl specifies the URL of the FileUpEE status script
'--- to which XFile will send the upload status request, when
'--- resuming an upload.
XFileResumeInfo.StatusUrl = "http://localhost/XFileResumeUpload/status.asp"
...


JobId

JobId Property

Object: ResumeInfo
Syntax: oResumeInfo.JobId
Type: String
Default Value: None
Read/Write: Read only
Description: In a resumable file transfer request, XFile generates a unique JobIdfor each transfer request (not for each file). You can use this JobIdto:
  • Get the RequestRecord by passing JobId to the GetRequestRecordmethod.

  • Resume a request, by passing JobId to the Resume method
Examples:

To get the record that contains information about a failed request, pass the request's JobId to the GetRequestRecord method:

Set XFResumeRecord = XFResume.GetRequestRecord(SAXFile.ResumeInfo.JobID)

To resume a failed request, pass the Resume method either a RequestRecord or the request's JobId:

SAXFile.Resume SAXFile.ResumeInfo.JobId


Resumable Property

Object: ResumeInfo
Syntax: oResumeInfo.Resumable [=Boolean]
Type: Boolean
Default Value: False
Read/Write: Read/Write
Description: Resumable tells the XFRequest object if a file transfer request is resumable. If Resumable is set to true, the request is resumable and XFile will store the necessary data to be able to resume a failed file transfer.
Example:

...
Set XFileResumeInfo = SAXFile.ResumeInfo

'--- Set Resumable to True to allow the upload to be resumed.
XFileResumeInfo.Resumable = True

'--- If CacheRequest is set to True XFile will save copies of the
'--- files to upload before sending the upload request. In a resumable
'--- upload, enabling CacheRequest guarantees the integrity of
'--- the resumed request.
XFileResumeInfo.CacheRequest = True

'--- StatusUrl specifies the URL of the FileUpEE status script
'--- to which XFile will send the upload status request, when
'--- resuming an upload.
XFileResumeInfo.StatusUrl = "http://localhost/XFileResumeUpload/status.asp"
...


StatusURL Property

Object: ResumeInfo
Syntax: oResumeInfo.StatusUrl [=URL]
Type: String
Default Value: None
Read/Write: Read/Write
Description: To create a resumable upload application, you must use FileUpEE to handle the server-side file transfer processing. FileUpEE saves information about the upload request in a database on the server. Before resuming a failed upload, XFile gets status information about the failed upload (the number of bytes received on the server so far) from FileUpEE. StatusUrl specifies the URL of the FileUpEE status script to which XFile will send the upload status request. The FileUpEE page specified by StatusUrl retrieves the upload status from the database, and sends it to XFile.
Example:

...
Set XFileResumeInfo = SAXFile.ResumeInfo

'--- Set Resumable to True to allow the upload to be resumed.
XFileResumeInfo.Resumable = True

'--- If CacheRequest is set to XFile will save copies of the
'--- files to upload before sending the upload request. In a resumable
'--- upload, enabling CacheRequest guarantees the integrity of
'--- the resumed request.
XFileResumeInfo.CacheRequest = True

'--- StatusUrl specifies the URL of the FileUpEE status script
'--- to which XFile will send the upload status request, when
'--- resuming an upload.
XFileResumeInfo.StatusUrl = "http://localhost/XFileResumeUpload/status.asp"
...


TopFolder Property

Object: ResumeInfo
Syntax: oResumeInfo.TopFolder [=Folder Path]
Type: String
Default Value: None
Read/Write: Read/Write
Description: In a resumable file transfer, TopFolder specifies the folder in which to store request data before initiating a file transfer. If CacheRequest is set to true, the whole file transfer request will be stored in the folder specified by TopFolder. If CacheRequest is set to false, only information about the request will be stored.

If TopFolder is not set, XFile will store request data in the user's temp directory.

Note that there is a security risk involved in using the user's temp directory. If a user runs two Web applications that use XFile for resumable transfers, and both applications save data to the default client temp directory, each application will have access to the RequestRecord s of the other Web application. To keep your application's RequestRecords secure, set TopFolder. You can use FileManager's CreateFolder method to create a directory on the client’s machine.
Example:

...
Set XFileResumeInfo = SAXFile.ResumeInfo

'--- Set Resumable to True to allow the upload to be resumed.
XFileResumeInfo.Resumable = True

'--- If CacheRequest is set to true XFile will save copies of the
'--- files to upload before sending the upload request. In a resumable
'--- upload, enabling CacheRequest guarantees the integrity of
'--- the resumed request.
XFileResumeInfo.CacheRequest = True

'--- XFile stores request data in the folder specified by TopFolder.
'--- If CacheRequest is set to true, the whole upload request will
'--- be stored in the folder specified by TopFolder. If CacheRequest
'--- is set to false, only information about the request will be stored.
XFileResumeInfo.TopFolder = "C:\XFileResumeData\"

'--- StatusUrl specifies the URL of the FileUpEE status script
'--- to which XFile will send the upload status request, when
'--- resuming an upload.
XFileResumeInfo.StatusUrl = "http://localhost/XFileResumeUpload/status.asp"
...


VerifyChecksums Property

Object: ResumeInfo
Syntax: oResumeInfo.VerifyChecksums [=Boolean]
Type: Boolean
Default Value: False
Read/Write: Read/Write
Description: In a resumable file transfer, if the request was not cached (that is, if CacheRequest is set to false), VerifyChecksums tells the XFRequest object to verify that the files to transfer were not modified, before resuming the file transfer. If the files were modified, an error will occur.
Example:

...
Set XFileResumeInfo = SAXFile.ResumeInfo

'--- Set Resumable to True to allow the upload to be resumed.
XFileResumeInfo.Resumable = True

'--- If CacheRequest is set to false XFile will not save copies of the
'--- files to upload before sending the upload request. XFile will only
'--- save information about the upload.
XFileResumeInfo.CacheRequest = False

'--- If CacheRequest is false, enable VerifyChecksums to make sure
'--- that the files to upload were not modified between the initial
'--- upload request and the resume request.
XFileResumeInfo.VerifyChecksums = True

'--- StatusUrl specifies the URL of the FileUpEE status script
'--- to which XFile will send the upload status request, when
'--- resuming an upload.
XFileResumeInfo.StatusUrl = "http://localhost/XFileResumeUpload/status.asp"
...


The RecordsCollection Object

The RecordsCollection object represents the collection of RequestRecords in a resumable file transfer request. You can access the RecordsCollection object through XFResume . RequestRecords.

RecordsCollection Properties


RecordsCollection Object Properties

Item

Count


Count

Count Property

Object: | RecordsCollection
Syntax: | RecordsCollection.Count
Type: | Long
Read/Write: | Read only
Description: | Returns the number of RequestRecords in the RecordsCollection.


Item

Item Property

Object: | RecordsCollection
Syntax: | RecordsCollection.Item(Key)
Parameter: | Item takes a RequestRecord's key, which may be either the record's JobId or a 0-based index.
Type: | RequestRecord
Read/Write: | Read only
Description: | Returns the RequestRecord specified by the key.


The RequestRecord Object

RequestRecord is the main object of XFResume. Each RequestRecord object contains information about a resumable file transfer request. You can access the RequestRecord through:

  • XFResume . GetRequestRecord

    or

  • RecordsCollection . Item

To get a RequestRecord using RecordsCollection.Item, you must first call XFResume. Open.

FilesCollection Properties


RequestRecord Object Methods

Update


Update

Update Method

Object: | RequestRecord
Syntax: | RequestRecord.Update
Parameters: | None
Return Value: | None
Description: | In a resumable file transfer, if any changes are made to the request before it is resumed (for example, if the StatusUrl is changed), call Update to make sure that the RequestRecord's data is up-to-date.


RequestRecord Object Properties

ErrorDescription

Files

JobId

KBytesRemaining

KBytesTransferred

PostUrl

RequestType

RetryCount

Status

StatusUrl

UploadRequestKBLength

VerifyChecksums


ErrorDescription

ErrorDescription Property

Object: | RequestRecord
Syntax: | RequestRecord.ErrorDescription
Type: | String
Default Value: | None
Read/Write: | Read only
Description: | In a resumable file transfer, if the transfer fails, ErrorDescription returns a description of the error that occured.


Files

Files Property

Object: | RequestRecord
Syntax: | RequestRecord.Files
Type: | FilesCollectionobject
Read/Write: | Read only
Description: | Gets the collection of files in a resumable file transfer request.


JobId

JobId Property

Object: RequestRecord
Syntax: RequestRecord.JobId
Type: String
Default Value: None
Read/Write: Read only
Description: In a resumable file transfer request, XFile generates a unique JobIdfor each transfer request (not for each file). You can use this JobIdto:
  • Get the RequestRecord, by passing JobId to the GetRequestRecordmethod.

  • Resume a request, by passing JobId to the Resumemethod


KBytesRemaining

KBytesRemaining Property

Object: | RequestRecord
Syntax: | RequestRecord.KBytesRemaining
Type: | Double
Default Value: | None
Read/Write: | Read only
Description: | In a resumable upload, if the upload fails, KBytesRemaining returns the number of kilobytes that remain to be uploaded.


KBytesTransferred

KBytesTransferred Property

Object: | RequestRecord
Syntax: | RequestRecord.KBytesTransferred
Type: | Double
Default Value: | None
Read/Write: | Read only
Description: | In a resumable upload, if the upload fails, KBytesTransferred returns the number of kilobytes sent to the server so far. In a resumable download, if the download fails, KBytesTransferred returns the number of kilobytes received on the client.


PostUrl

PostUrl Property

Object: | RequestRecord
Syntax: | RequestRecord.PostUrl
Type: | String
Default Value: | None
Read/Write: | Read only
Description: | PostUrl returns the URL of the FileUpEE upload processing script on the server.


RequestType

RequestType Property

Object: | RequestRecord
Syntax: | RequestRecord.RequestType
Type: | String
Default Value: | None
Read/Write: | Read only
Description: | In a resumable file transfer, RequestType returns the type of file transfer request - upload or download. In an upload, RequestType returns saUploadRequest. In a download, RequestType returns saDownloadRequest.


RetryCount

RetryCount Property

Object: | RequestRecord
Syntax: | RequestRecord.RetryCount
Type: | Long
Default Value: | None
Read/Write: | Read only
Description: | In a resumable file transfer, RetryCount returns the number of times the user tried to resume the file transfer.


Status

Status Property

Object: | RequestRecord
Syntax: | RequestRecord.Status
Type: | String
Default Value: | None
Read/Write: | Read only
Description: | In a resumable upload, if the upload fails, Status returns the status of the request. Status usually returns an HTTP Status code.


StatusUrl

StatusUrl Property

Object: | RequestRecord
Syntax: | RequestRecord.StatusUrl [=URL]
Type: | String
Default Value: | None
Read/Write: | Read/Write
Description: | To create a resumable upload application, you must use FileUpEE to handle the server-side file transfer processing. FileUpEE saves information about the upload request in a database on the server. Before resuming a failed upload, XFile gets status information about the failed upload (the number of bytes received on the server so far) from FileUpEE. StatusUrl specifies the URL of the FileUpEE status script to which XFile will send the upload status request. The FileUpEE page specified by StatusUrl retrieves the upload status from the database, and sends it to XFile. If RequestRecord.StatusUrl is not set, this property will inherit the value of XFResume.StatusUrl.


UploadRequestKBLength

UploadRequestKBLength Property

Object: | RequestRecord
Syntax: | RequestRecord.UploadRequestKBLength
Type: | Double
Default Value: | None
Read/Write: | Read only
Description: | In a resumable upload, UploadRequestKBLength returns the size - in kilobytes - of the upload request.


VerifyChecksums

VerifyChecksums Property

Object: | RequestRecord
Syntax: | RequestRecord.VerifyChecksums [=Boolean]
Type: | Boolean
Default Value: | False
Read/Write: | Read/Write
Description: | In a resumable file transfer, if the request was not cached (that is, if CacheRequest is set to false), VerifyChecksums tells the XFRequest object to verify that the files to transfer were not modified, before resuming the file transfer. If the files were modified, an error will occur. If RequestRecord.VerifyChecksums is not set, this property will inherit the value of XFResume.VerifyChecksums.


The FilesCollection Object

The FilesCollection object represents the collection of files in a resumable file transfer request. You can access the FilesCollection object through RequestRecord . Files.

FilesCollection Properties


FilesCollection Object Properties

Count

Item


Count

Count Property

Object: | FilesCollection
Syntax: | FilesCollection.Count
Type: | Long
Read/Write: | Read only
Description: | Returns the number of files in a resumable file transfer request.


Item

Item Property

Object: | FilesCollection
Syntax: | FilesCollection.Item(Key)
Parameter: | Item takes a file's key, which may be either a 0-based index or the file's LocationOnClient.
Type: | File
Read/Write: | Read only
Description: | Returns the file specified by the key.


The File Object

Use the File object for file management. You can use it to manage files, look at attributes of files, set permissions for files, and to move files.

File Methods

File Properties


Checksum

Checksum Property

Object: SoftArtisans.SAFile
Syntax: Checksum
Type: String
Read/Write: Read only
Description:

FileUp generates an MD5 hash of each uploaded file, after it is received on the server. The Checksum property returns a string representing the specified file's MD5 hash. You can use this value to verify the integrity of the uploaded file, by comparing an MD5 hash generated on the client, and the MD5 hash generated by FileUp on the server.

Note: Note that FileUp generates an MD5 hash on the server, not the client. To verify data integrity, you will need a tool that can generate an MD5 hash on the client, such as SoftArtisans FileManager which is included free with FileUp.
See Also: FileManager Checksum Property

Examples:

ASP
'--- Instantiate the FileUp object
Set fileUpload = Server.CreateObject("SoftArtisans.FileUp")
...

'--- Get the client-side hash submitted by the form
clientHash = fileUpload.Form("fileHash")

'--- Now, make a server-side hash with FileUp
serverHash = fileUpload.Form("myFile").CheckSum

Response.Write("<B>Comparing hashes</B><BR>")
Response.Write("<B>Client hash:</B> " & clientHash & "<BR>")
Response.Write("<B>Server hash:</B> " & serverHash & "<BR>")

'--- Compare them to verify file integrity
If StrComp(clientHash, serverHash) = 0 Then
'--- The hashes are the same! File integrity is verified
fileUpload.Form("myFile").Save
Response.Write("... Hashes <B>OK!</B><HR NOSHADE>")
Response.Write("File integrity has been verified,_
and the file has been saved to: " &_
fileUpload.Form("myFile").ServerName & "<BR>")
Else
Response.Write("... Hashes <B>mismatch!</B><HR NOSHADE>")
Response.Write("File integrity cannot be verified " & _
"and will not be saved.")
End If
...
%>
VB.NET
'--- Process the upload
Private Sub ProcessUpload()

'--- Declare an object for FileUp
Dim fileUpload as FileUp

'--- This StringBuilder will be used to display results
Dim res As New System.Text.StringBuilder()

Try

'--- Instantiate FileUp
fileUpload = New FileUp (Context)

'--- When the HttpModule is used, the path property does not
'--- affect caching location. Instead it is merely used
'--- as a placeholder to store the path to the directory
'--- where the files will be saved.
fileUpload.Path = "C:\UploadDir

'--- Get a reference to the uploaded file field
Dim file As SaFile = CType (fileUpload.Form ("myFile"), SaFile)

'--- Check to be sure there was a file selected in the form
'--- If so, continue processing
If Not (file Is Nothing) Then
If Not (file.IsEmpty) Then

'--- Get the client-side hash submitted by the form
Dim clientHash As String
clientHash = fileUpload.Form("fileHash").ToString()

'--- Now, make a server-side hash with FileUp
Dim serverHash As String = file.Checksum

res.Append("Comparing hashes<BR>")
res.Append("Client hash: " + clientHash + "<BR>")
res.Append("Server hash: " + serverHash + "<BR>")

'--- Compare them to verify file integrity
If (String.Compare(clientHash, serverHash) = 0) Then

'--- File integrity is verified
file.Save()
res.Append ("... Hashes OK!")
res.Append ("File integrity has been verified, " + _
"and the file has been saved to: " + _
"file.ServerName + "<BR>")
Else

'--- If the hashes don't match, don't save the file
'--- Explicitly delete it
file.Delete()
res.Append ("... Hashes mismatch!")
res.Append ("File integrity cannot be verified " + _
"and therefore it will not be saved.")
End If

Else
'--- If IsEmpty is true, the file field was left empty
res.Append("There was no file submitted for upload.")
End If

Else
results.Append ("The referenced field does not exist " +_
"or is not of type=""file""")
End If

'--- Display the results on the webform
ltrUploadResults.Text = res.ToString()

Catch ex As System.Exception
'--- If an exception is caught, display the details
ltrUploadResults.Text = "An error has occurred:<br>" + _
ex.Message
Finally
'--- Always call FileUp.Dispose in the finally block
If Not (fileUpload Is Nothing) Then
fileUpload.Dispose()
fileUpload = Nothing
End If

End Try

End Sub
C#
//--- Process the upload
private void ProcessUpload()
{
//--- Declare an object for FileUp
FileUp fileUpload=null;

//--- This StringBuilder will be used to display results
System.Text.StringBuilder res = new System.Text.StringBuilder();

try
{
//--- Instantiate the FileUp object
fileUpload = new FileUp (Context);

//--- When the HttpModule is used, the path property does not
//--- affect caching location. Instead it is merely used
//--- as a placeholder to store the path to the directory
//--- where the files will be saved.
fileUpload.Path = "C:\\UploadDir";

//--- Get a reference to the uploaded file field
SaFile file = (SaFile)fileUpload.Form["myFile"];

//--- Check to be sure there was a file selected in the form
//--- If so, continue processing
if (file != null)
{
if (!file.IsEmpty)
{
//--- Get the client-side hash submitted by the form
string clientHash = fileUpload.Form["fileHash"].ToString();

//--- Now, make a server-side hash with FileUp
string serverHash = file.Checksum;

res.Append("Comparing hashes<BR>");
res.Append("Client hash: " + clientHash + "<BR>");
res.Append("Server hash: " + serverHash + "<BR>");

//--- Compare them to verify file integrity
if (String.Compare(clientHash, serverHash) == 0)
{
//--- File integrity is verified
file.Save();
res.Append ("... Hashes OK!");
res.Append ("File integrity has been verified, " +
"and the file has been saved to: " +
file.ServerName + "<BR>");
}
else
{
//--- If the hashes don't match, don't save the file
//--- Explicitly delete it
file.Delete();
res.Append ("... Hashes mismatch!");
res.Append ("File integrity cannot be verified " +
"and therefore it will not be saved.");
}

}
else
{
//--- If IsEmpty is true, the file field was left empty
res.Append ("There was no file submitted for upload.");
}
}
else
{
res.Append ("The referenced field does not exist " +
"or is not of type=\"file\"");
}

//--- Display the results on the webform
ltrUploadResults.Text = results.ToString();

}
catch(Exception ex)
{
//--- If an exception is caught, display the details
ltrUploadResults.Text = "An error has occurred:<br>" +
ex.Message;
}
finally
{
//--- Always call FileUp.Dispose in the finally block
if (fileUpload != null)
{
fileUpload.Dispose();
fileUpload = null;
}
}
}


Size

Size Property

Object: | File
Syntax: | Size
Type: | Long Integer
Read/Write: | Read Only
Description: | This property returns the size of the specified file in bytes.


URL

URL Property

Object: | File
Syntax: | File.URL
Type: | String
Read/Write: | Read only
Description: | In a resumable download, URL returns the URL from which to download the file. In a resumable upload, this property is not available.


The DownloadError Object

The DownloadError object represents an error that occurred during a download. You can access the DownloadError object through the XFFile . DownloadError property.

DownloadError Properties


DownloadError Properties

Description

Number

Source


Description Property

Object: DownloadError
Syntax: DownloadError.Description
Type: String
Read/Write: Read Only
Description: If an error occurred during a download, Description returns a description of the error.
Example:

...
If not XFileDownload.AllDownloadsSuccessful then
    MsgBox "Not all files were saved."
    sError = "Error Information" & vbCrLf
    for each file in XFileDownload.files

        '---If DownloadError.Number = 0, the file was downloaded
        '--- successfully.
        If file.DownloadError.Number <> 0 then
            sError = sError & "For " & file.FileName & ": " & vbCrLf
            sError = sError & " Source: " & file.DownloadError.Source & vbCrLf
            sError = sError & " Number: " & file.DownloadError.Number & vbCrLf
            sError = sError & " Description: " & file.DownloadError.Description
        end if
    next
End if
...


Number Property

Object: DownloadError
Syntax: DownloadError.Number
Type: Long
Read/Write: Read Only
Description: Number returns an error number if an error occurred during a download. If the error occurred on the server or during transfer, Number returns an HTTP status code. If the error occurred on the client, Number returns a Win32/COM error code.
Example:

...
If not XFileDownload.AllDownloadsSuccessful then
    MsgBox "Not all files were saved."
    sError = "Error Information" & vbCrLf
    for each file in XFileDownload.files

        '--- If DownloadError.Number = 0, the file was downloaded
        '--- successfully.
        If file.DownloadError.Number <> 0 then
            sError = sError & "For " & file.FileName & ": " & vbCrLf
            sError = sError & " Source: " & file.DownloadError.Source & vbCrLf
            sError = sError & " Number: " & file.DownloadError.Number & vbCrLf
            sError = sError & " Description: " &
            file.DownloadError.Description
        end if
    next
End if
...


Source Property

Object: DownloadError
Syntax: DownloadError.Source
Type: String
Read/Write: Read Only
Description: If an error occurred during a download, Source returns "Client" if the error occurred on the client, and "Server" if the error occurred on the server.
Example:

...
If not XFileDownload.AllDownloadsSuccessful then
    MsgBox "Not all files were saved."
    sError = "Error Information" & vbCrLf
    for each file in XFileDownload.files

        '--- If DownloadError.Number = 0, the file was downloaded
        '--- successfully.
        If file.DownloadError.Number <> 0 then
            sError = sError & "For " & file.FileName & ": " & vbCrLf
            sError = sError & " Source: " & file.DownloadError.Source & vbCrLf
            sError = sError & " Number: " & file.DownloadError.Number & vbCrLf
            sError = sError & " Description: " & file.DownloadError.Description
        end if
    next
End if
...


The Archive Object

The Archive object is SoftArtisans Archive's principal object. When you create an instance of the Archive object, Archive automatically creates instances of the sub-objects ArchiveItemCollection and ArchiveItem.

To create a server-side instance of the Archive object, use ASP's Server.CreateObject, as follows.

Set objArchive = Server.CreateObject("Softartisans.Archive")

To create a client-side instance of the Archive object, use HTML's <object>tag, as follows.

<Object Classid="clsid:D3400FEE-041F-11D3-B1C5-00A0C9B4587A" Codebase="localhost/SAXFileSamples/saxfile.cab"
      ID="arch"></Object>

Classid specifies Archive's unique class id, clsid:D3400FEE-041F-11D3-B1C5-00A0C9B4587A. Codebase specifies the location of saxfile.cab, which contains SAArch.dll (Archive's dll). Id assigns a name to the created instance of SoftArtisans Archive.

Methods

Properties


Archive Methods

This section contains the methods implemented by the Archive object.

AddFile Method
CloseArchive Method
CreateArchive Method
Extract Method
OpenArchive Method
RemoveFile Method


AddFile

AddFile Method

Object: Archive
Syntax: AddFile ([in] Filename, [in] bRecursive)
Description: This method adds files to the archive. Filename can contain the name of a file or a directory. Call OpenArchive or CreateArchive before using the AddFile Method.

If you set the optional bRecursive to True, any directories or folders are recursively added to the archive. The default value of bRecursive is False. To preserve a file's complete path in an archive, set bRecursive to True and set the PreservePath property to True. Note: to preserve paths when creating a Zip file, set ArchiveType to 3.
Example:
Set Arch = CreateObject("SoftArtisans.Archive") ArchiveName = "c:\temp\Arch.cab"
            '--- Set ArchiveType to Cabinet format Arch.ArchiveType = 2 '--- Save Path Information
            Arch.PreservePath = True '--- Create the Cabinet file Arch.CreateArchive ArchiveName
            '--- Add files to the cabinet file1 = "c:\folder\file1.txt" file2 = "c:\folder\file2.txt"
            file3 = "c:\folder\file3.txt" '--- Add the files to the archive. '--- To include
            a complete path '--- in the archive, set the second '--- parameter of AddFile to
            True. Arch.AddFile file1, True Arch.AddFile file2, True Arch.AddFile file3, True
            Arch.CloseArchive


CloseArchive

CloseArchive Method

Object: | Archive
Syntax: | CloseArchive
Description: | This method closes a currently opened archive. In most cases, you must use this method in order to s ave any additions or deletions to the archive. If you do not clsoe the archive, all changes will be lost


CreateArchive

CreateArchive Method

Object: | Archive
Syntax: | CreateArchive ([in] Filename)
Description: | This method creates a new archive with the name specified in Filename. Filename must be a valid filename. It can include a complete path.


Extract

Extract Method

Object: | Archive
Syntax: | Extract ([in] Filename)
Description: | This method extracts files from an archive. If no Filename is specified, this method extracts the entire contents of the archive.

Example:

<% Set Arch = Server.CreateObject("Softartisans.Archive") ... '--- '--- Set the
        path to which you want to extract files. Arch.ExtractPath = "C:\Temp\Extract" '---
        '--- Extract Files Arch.Extract() ... %>


OpenArchive

OpenArchive Method

Object: | Archive
Syntax: | OpenArchive ([in] filename)
Description: | This method opens an existing archive.


RemoveFile

RemoveFile Method

Object: | Archive
Syntax: | RemoveFile ([in] Filename)
Description: | This method removes the specified file from an archive.


SoftArtisans Archive Properties

This section contains the properties implemented by the Archive object.

ArchiveName Property
ArchiveType Property
EnableSigning Property
Entries Property
Exists Property
ExpirationDate Property
ExtractPath Property
Password Property
PreservePath Property
SelfExtractFile Property
SelfExtractHeaderFile Property
SignCode Property
TempPath Property
Version Property


ArchiveName

ArchiveName Property

Object: | Archive
Syntax: | ArchiveName
Type: | String
Read/Write: | Read Only
Description: | This property returns the name of the archive you're opening or creating.


ArchiveType

ArchiveType Property

Object: Archive
Syntax: ArchiveType
Type: Integer
Read/Write: Read/Write
Description:

This property indicates whether the Archive to open or create is in Zip or Microsoft Cabinet format (cab). Set ArchiveType before using the CreateArchive or OpenArchivemethods.

ArchiveType Values
1 | Zip If ArchiveType is set to 1, Archive can preserve directory structure when extracting a Zip file, but not when creating a Zip file.
2 | Cab If ArchiveType is set to 2, Archive can preserve directory structure both when extracting and when creating a Cab file.
3 | Zip If ArchiveType is set to 3, Archive can preserve directory structure both when extracting and when creating a Zip file.

To preserve paths when creating or extracting an archive file, set PreservePath to True.

Example:
Set Arch = CreateObject("SoftArtisans.Archive") ArchiveName = "c:\temp\Arch.cab"
            '--- Set ArchiveType to 3 to create a Zip '--- file, and to allow Archive to store
            paths '--- in the Zip. Arch.ArchiveType = 3 '--- Save Path Information Arch.PreservePath
            = True '--- Create the Cabinet file Arch.CreateArchive ArchiveName '--- Add files
            to the cabinet file1 = "c:\folder\file1.txt" file2 = "c:\folder\file2.txt" file3
            = "c:\folder\file3.txt" '--- Add the files to the archive. '--- To include a complete
            path '--- in the archive, set the second '--- parameter of AddFile to True. Arch.AddFile
            file1, True Arch.AddFile file2, True Arch.AddFile file3, True Arch.CloseArchive


EnableSigning

EnableSigning Property

Object: | Archive
Syntax: | EnableSigning
Type: | Boolean
Read/Write: | Read/Write
Description: | Use this property to indicate whether the Cab is going to be signed. If set to True, the Cab is going to be signed. The default value is False.

Example 1:

<%@ Language=VBScript%> <HTML> ... The EnableSigning property is set
        to: <%=Arch.EnableSigning%>. ... </HTML>

Example 2:

<% Set Arch = Server.CreateObject("Softartisans.Archive") ... '--- '--- Turn
        the EnableSigning Property On '--- Arch.EnableSigning = True ... %>


Entries

Entries Property

Object: | Archive
Syntax: | Entries
Type: | ArchiveItemCollection
Read/Write: | Read Only
Description: | This property returns the collection of archived items to be added to the archive when it's created or retrieved from the archive after it's opened. If you are opening an archive, this property returns a list of all files in the archive. For each ZIP format file, you can use the CompressedSize and UncompressedSize properties. For Microsoft Cabinet format files you can use only the UncompressedSize property. See also the Name and Path properties.


Exists

Exists Property

Object: | Archive
Syntax: | Exists (Filename)
Type: | Boolean
Description: | This property returns True or False, indicating whether a file exists within the current archive. The specified Filename must be complete, with name and relative path of the file inside the archive.


ExpirationDate

ExpirationDate Property

Object: | Archive
Syntax: | ExpirationDate
Type: | Date
Read/Write: | Read Only
Description: | This property returns the expiration date of the current evaluation version. A full, non-evaluation version returns an empty expiration date.

Example:

<%@ Language=VBScript%> <HTML> ... This evaluation version of SoftArtisans
        Archive expires on <%=Arch.ExpirationDate%>. ... </HTML>


ExtractPath

ExtractPath Property

Object: | Archive
Syntax: | ExtractPath
Type: | String
Read/Write: | Read/Write
Description: | This property returns the complete path for the destination of the extracted archive. You can also use this property to set the path of the extracted archive -- the archive's content will be extracted to the specified directory. See the Extract method for more information.

Example 1:

<%@ Language=VBScript%> <HTML> ... The directory to which SoftArtisans
        Archive will extract files is: <%=Arch.ExtractPath%>. ... </HTML>

Example 2:

<% Set Arch = Server.CreateObject("Softartisans.Archive") ... '--- '--- Set the
        path to which you want to extract files. Arch.ExtractPath = "C:\Temp\Extract" '---
        '--- Extract Files Arch.Extract() ... %>


Password

Password Property

Object: | Archive
Syntax: | Password
Type: | String
Read/Write: | Write Only
Description: | This property works for ZIP format only.

Example:

<% Set Arch = Server.CreateObject("Softartisans.Archive") ... '--- '--- Set the
        password for the ZIP file. Arch.Password = "Password" ... %>


PreservePath

PreservePath Property

Object: Archive
Syntax: PreservePath
Type: Boolean
Read/Write: Read/Write
Description: When PreservePath is set to True, Archive will preserve file paths when extracting or creating an archive file.

When creating an archive, to preserve a file's complete path in an archive, set PreservePath to True and set the second parameter of the AddFile method to True. If you are creating a zip file, set ArchiveType to 3.
Example:
Set Arch = CreateObject("SoftArtisans.Archive") ArchiveName = "c:\temp\Arch.cab"
            '--- Set ArchiveType to Cabinet format Arch.ArchiveType = 2 '--- Save Path Information
            Arch.PreservePath = True '--- Create the Cabinet file Arch.CreateArchive ArchiveName
            '--- Add files to the cabinet file1 = "c:\folder\file1.txt" file2 = "c:\folder\file2.txt"
            file3 = "c:\folder\file3.txt" '--- Add the files to the archive. '--- To include
            a complete path '--- in the archive, set the second '--- parameter of AddFile to
            True. Arch.AddFile file1, True Arch.AddFile file2, True Arch.AddFile file3, True
            Arch.CloseArchive


SelfExtractFile

SelfExtractFile Property

Object: | Archive
Syntax: | SelfExtractFile
Type: | String
Read/Write: | Write Only
Description: | When creating ZIP format archives, use this property to provide the name of a self-extractable file. A self-extractable file is created. Self-extracting files are executable files with a .EXE extension. When the user launches the file, all files in the archives are extracted. See also the SelfExtractHeaderFile property.

Example:

<% Set Arch = Server.CreateObject("Softartisans.Archive") ... '--- '--- Set the
        path and filename of the self-extracting file that is going to be created. Arch.SelfExtractFile
        = "C:\temp\Extract.exe" '--- '--- Set the path and filename of the header file that
        is required to create self-extracting files. Arch.SelfExtractHeaderFile = "C:\Program
        Files\Software Artisans\Archive\seazip.exe" ... %>


SelfExtractHeaderFile

SelfExtractHeaderFile Property

Object: | Archive
Syntax: | SelfExtractHeaderFile
Type: | String
Read/Write: | Write Only
Description: | This property works with the SelfExtractFile property. It returns the pathname of the seazip.exe file, which is distributed with SoftArtisans Archive.This header file is required to create self-extracting files.

Example:

<% Set Arch = Server.CreateObject("Softartisans.Archive") ... '--- '--- Set the
      path and filename of the self-extracting file that is going to be created. Arch.SelfExtractFile
      = "C:\temp\Extract.exe" '--- '--- Set the path and filename of the header file that
      is required to create self-extracting files. Arch.SelfExtractHeaderFile = "C:\Program
      Files\Software Artisans\Archive\seazip.exe" ... %>


SignCode

SignCode Property

Object: Archive
Syntax: SignCode
Type:
Read/Write:
Description: This property indicates the pathname of the signcode.exe file. This property is for Microsoft Cabinet format only.

In the following table, the columns contain the following information:
  • Property. The name of the property you use to set the value of the parameter listed in the third column. Note that the property should not include the switch listed in the second column.
  • Switch. The switch evoked in signcode.exe by using the property (listed in the first column).
  • Parameter. Parameter for signcode.exe.
  • Description. Description of parameter

 | Maps to SignCode Information
Property | Switch | Parameter | Description
SPCFile | -spc | <file> | SPC file containing software publishing certificates.
PFKFile | -v | <pvkfile> | PVK file containing the private key.
KeyName | -k | <KeyName> | Key container name.
SignedFileTextName | -n | <name> | Text name representing content of the file to be signed.
Info | -i | <info> | Location to find more information about content (usually a URL).
Provider | -p | <provider> | Name of the cryptographic provider on the system.
Cryptype | -y | <type> | Cryptographic provider type to use.
KeyType | -ky | <keytype> | Key type. <signature|exchange|<integer>>
Authority | -$ | <authority> | Signing authority of the certificate. <individual|commercial> Default to using certificate's highest capability.
Algorithm | -a | <algorithm> | Hashing algorithm for signing. <md5|sha1> Defaults to md5.
TimeStampURL | -t | <URL> | TimeStamp server's http address.
TimeStampTrialCount | -tr | <number> | The number of timestamp trials until succeeds. Defaults to 1.
TimeSTampTrialDelay | -tw | <number> | The number of seconds delay between each timestamp. Defaults to 0.
DllNameSignature | -j | <dllName > | Name of the dll that provides attributes of the signature.
DllSignatureParam | -jp | <param> | Parameter to be passed to the dll.
X509File | -c | <file> | X509 file containing encoded software publishing certificate.
StoreCert | -s | <store> | Cert store containing certs. Default to my store.
Location | -r | <location> | Location of the cert store in the registry. <localMachine|currentUser> Defaults to currentUser.
Policy | -sp | <policy> | Add all the certificates in the chain or add until one cert in the chain is from the spc store. <chain|spcstore> Defaults to spcstore.
CommonName | -cn -x | <name> | The common name of the certificate. Do not sign the file. Only Timestamp the file.

Note: To sign with a SPC file, the required options are -spc and -v if your private key is in a PVK file. If your private key is in a registry key container, the required options are -spc and -k.

Example:

<% Set Arch = Server.CreateObject("Softartisans.Archive") ... '--- '--- Set the
      executable path for the Signcode program. '--- Arch.SignCode = "C:\SDK-java.31\bin\packsign\signcode.exe"
      ... %>


TempPath

TempPath Property

Object: Archive
Syntax: TempPath
Type: String
Read/Write: Read/Write
Description:

This property defines the temporary directory for storing files. If this property is not set, SoftArtisans Archive will use the system's temporary path to store the temporary files that it generates.

This property should be set immediately after creating an instance of SoftArtisans Archive.

The anonymous (IUSR_machinename) or authenticated user for SoftArtisans Archive must have Read, Write and Delete priviledges for this directory.

Example 1:

<%@ Language=VBScript%> <HTML> ... The temporary directory for SoftArtisans
        Archive files is <%=Arch.TempPath%>. ... </HTML>

Example 2:

<% Set Arch = Server.CreateObject("Softartisans.Archive") '--- '--- Set the temporary
        path to store extracted files. '--- This should be set immediately after creating
        an instance. Arch.TempPath = "C:\Temp" ... %>


Version

Version Property

Object: | Archive
Syntax: | Version
Type: | String
Read/Write: | Read Only
Description: | This property returns the current version number of SoftArtisans Archive.

Example:

<%@ Language=VBScript%> <HTML> ... The version of SoftArtisans Archive
        is <%=Arch.Version%>. ... </HTML>


The ArchiveItemCollection Object

The ArchiveItemCollection object represents the collection of files in an archive. When you create an instance of the Archive object, Archive automatically creates an instance of the ArchiveItemCollection object.

ArchiveItemCollection Methods

ArchiveItemCollection Properties


ArchiveItemCollection Methods

This section contains the methods implemented by the ArchiveItemCollection object.

Add Method

Remove Method


Add

Add Method

Object: | ArchiveItemCollection
Syntax: | Add
Description: | This method adds a file to the collection of files in an archive.


Remove

Remove Method

Object: | ArchiveItemCollection
Syntax: | Remove
Description: | This method removes a file from the collection of files in an archive.


ArchiveItemCollection Properties

This section contains the properties implemented by the ArchiveItemCollection object.

Count Property

Item Property


Count

Count Property

Object: ArchiveItemCollection
Syntax: Count
Type: Long Integer
Read/Write: Read Only
Description: This property displays the total number of files in the current archive.

Use this property while opening an archive to display the total number of files in it.

When appending to an existing archive, this property will display the total number of files in the resulting archive.
Example:
Set Arch = Server.CreateObject("SoftArtisans.Archive") ArchiveName = "c:\folder1\file.zip"
            ExtractPath = "c:\folder2" Arch.ArchiveType = 1 Arch.OpenArchive ArchiveName Response.Write
            ("File.zip contains " & Arch.Entries.Count & ":") Dim item For Each item
            in Arch.Entries Response.Write "<br>" & item.name Next Arch.ExtractPath
            = ExtractPath Arch.Extract() Arch.CloseArchive Set Arch = Nothing


Item

Item Property

Object: ArchiveItemCollection
Syntax: Item
Type: Archive Item
Read/Write: Read Only
Description: This property returns an ArchiveItem object, which represents a single file in an archive.
Example:
Set Arch = Server.CreateObject("SoftArtisans.Archive") ArchiveName = "c:\folder1\file.zip"
            ExtractPath = "c:\folder2" Arch.ArchiveType = 1 Arch.OpenArchive ArchiveName Response.Write
            ("File.zip contains " & Arch.Entries.Count & ":") Dim item For Each item
            in Arch.Entries Response.Write "<br>" & item.name Next Arch.ExtractPath
            = ExtractPath Arch.Extract() Arch.CloseArchive Set Arch = Nothing


ArchiveItem Object

The ArchiveItem object represents a single file in an archive, that is, an item in an ArchiveItemCollection. When you create an instance of the Archive object, Archive automatically creates an instance of the ArchiveItem object.

ArchiveItem Methods

ArchiveItem Properties


ArchiveItem Methods

This section contains the methods implemented by the ArchiveItem object.

Extract Method

Remove Method


Extract

Extract Method

Object: | ArchiveItem
Syntax: | Extract
Description: | This method extracts an item from an archive.


Remove

Remove Method

Object: | ArchiveItem
Syntax: | Remove
Description: | This method removes an item from an archive.


ArchiveItem Properties

This section contains the properties implemented by the ArchiveItem object.

CompressedSize Property

Name Property

Path Property

UnCompressedSize Property


CompressedSize

CompressedSize Property

Object: | ArchiveItem
Syntax: | CompressedSize
Type: |
Read/Write: |
Description: | This property returns the compressed size of the file, in bytes, when you open an archive. This property is not available for Microsoft Cabinet format files.


Name

Name Property

Object: | ArchiveItem
Syntax: | Name
Type: | String
Read/Write: | Read Only
Description: | This property returns the filename for each file you are going to add to the archive you are creating.


Path

Path Property

Object: | ArchiveItem
Syntax: | Path
Type: | String
Read/Write: | Read Only
Description: | This property returns the directory path (not including the file's name) for each file you are going to add to the archive you are creating.


UncompressedSize

UncompressedSize Property

Object: | ArchiveItem
Syntax: | UncompressedSize
Type: |
Read/Write: |
Description: | This property returns the uncompressed size of the file, in bytes, when you open an archive.


The FileManager Object

To create a server-side instance of the FileManager object, use ASP's Server.CreateObject, as follows.

Set objFileManager = Server.CreateObject("SoftArtisans.FileManager")

To create a client-side instance of the FileManager object, use HTML's <object>tag, as follows.

<object classid="clsid:E7B62F4E-82F4-11D2-BD41-00105A0A7E89" codebase="localhost/SAXFileSamples/saxfile.cab"
        id="objFileManager"> </object>

Classid specifies FileManager's unique class id, clsid:E7B62F4E-82F4-11D2-BD41-00105A0A7E89. Codebase specifies the location of saxfile.cab, which contains SAFilMgr.dll (FileManager's dll). Id assigns a name to the created instance of SoftArtisans FileManager.

The FileManager object automatically creates several sub-objects:

BinaryStream, Drive, File, Folder, PermItem, and TextStream.
FileManager Reference Contents
  • FileManager Methods
  • FileManager Properties


FileManager Methods

BuildPath
CopyFile
CopyFolder
CreateBinaryFile
CreateFile
CreateFolder
CreateTextFile
CreateUniqueFile
DecryptFile
DeleteFile
DeleteFolder
DriveExists
EncryptFile
ExportToBlob
FileExists
FolderExists
GetAbsolutePathname
GetBaseName
GetDrive
GetDriveName
GetExtensionName
GetFile
GetFileName
GetFolder
GetParentFolderName
GetSpecialFolder
GetTempName
ImportFromBlob
INIDeleteKey
INIDeleteSection
INIReadBoolean
INIReadInteger
INIReadString
INIWriteBoolean
INIWriteInteger
INIWriteString
LogonUser
MoveFile
MoveFolder
OpenBinaryFile
OpenTextFile
RegisterDLL
RevertToSelf


BuildPath

BuildPath Method

Object: | FileManager
Syntax: | BuildPath ([in] Path, [in] Name)
Description: | This method appends a name to an existing path. The path argument specifies the path to which the name is appended. The path listed may be either absolute or relative.


CopyFile

CopyFile Method

Object: | FileManager
Syntax: | CopyFile ([in] Source, [in] Destination, [in, optional] OverWrite)
Description: | This method copies a file from the source to the destination location. By default, it overwrites the destination file. Set OverWrite to False to not overwrite the destination file.


CopyFolder

CopyFolder Method

Object: | FileManager
Syntax: | CopyFolder ([in] SourceDirectory, [in] DestinationDirectory, [in, optional] OverWrite)
Description: | This method copies the source folder, sub-folders, and files to another location. If OverWrite is True, all similarly named files are overwritten. It is True by default. Set OverWrite to False to not overwrite the destination files.


CreateBinaryFile

CreateBinaryFile Method

Object: | FileManager
Syntax: | CreateBinaryFile ([in] Name, [in] OverWrite)
Returns: | A BinaryStream object
Description: | This method creates a new file and returns a BinaryStream object so you can read and write the contents of the file. You must specify the complete path of the file. If you want to create a file in the current directory, use the CreateBinaryFile method of the Folder object. If OverWrite is True, and the file already exists, it will be overwritten. It is True by default.


CreateFile

CreateFile Method

Object: | FileManager
Syntax: | CreateFile ([in] Filename, [in, optional] OverWrite)
Description: | This method creates the specified file. By default, it will overwrite the destination file. Set OverWrite to False to not overwrite the destination file.


CreateFolder

CreateFolder Method

Object: | FileManager
Syntax: | CreateFolder ([in] FolderName)
Returns: | A Folder object
Description: | This method creates the specified folder. You must specify the complete path of the folder.


CreateTextFile

CreateTextFile Method

Object: | FileManager
Syntax: | CreateTextFile ([in] Name, [in] OverWrite, [in] Unicode)
Returns: | A TextStream object
Description: | This method creates a new file in the current folder and returns a TextStream object so you can read and write the contents of the file. You must specify the complete path of the file. If you want to create a file in the current directory, use the Folder object. If OverWrite is True, and the file already exists, it will be overwritten. It is True by default. If Unicode is True, the file will be created in Unicode format. It is False by default.


CreateUniqueFile

CreateUniqueFile Method

Object: | FileManager
Syntax: | CreateUniqueFile ([in] Directory, [in] Prefix)
Returns: | A string containing the name of the newly created file
Description: | This method creates a uniquely named file in the specified directory, with the specified Prefix. For example, if the directory is c:\temp and the Prefix is ab, this method creates a file named c:\temp\abNNN.tmp where NNN is unique and different from any other file in the same directory.


DecryptFile

DecryptFile Method

Object: FileManager
Syntax: objFileManager.DecryptFile ([in] InFilename, [in] OutFileName, [in] Password, [in, optional, defaultvalue(1)] saEncType)
Description: This method decrypts the file specified by InFileNameand saves the result to the OutFileNamelocation. If the password is incorrect, the file will be saved as OutFileNamebut the decryption will fail.

FileManager allows you to select either TwoFish or RSAencryption. TwoFish encryption is 128-bit. RSA encryption is either 40-bit or 128-bit, depending on the system. To determine whether the system supports 128-bit encryption, check Internet Explorer's "About" (in IE's Help menu).

DecryptFile Parameters
InFileName | The encrypted file
OutFileName | FileManager will save the decrypted file to this location
Password | The password set by Encrypt or EncryptFile. If the password is incorrect, the file will be saved as OutFileNamebut the decryption will fail.
saEncType The encryption type, which may be either TwoFish encryption, or CryptoAPI. Assign saEncTypeby name or number:

1 | SARSA
2 | SATWOFISH
3 | SARSAHIGH
4 | SARSALOW


DeleteFile

DeleteFile Method

Object: | FileManager
Syntax: | DeleteFile ([in] Filename, [in, optional] Force)
Description: | This method deletes a file from the web server's hard disk. The filename must contain the entire valid path. If Force is True, the file is deleted, even if it is marked as read-only. By default, Force is False.


DeleteFolder

DeleteFolder Method

Object: | FileManager
Syntax: | DeleteFolder ([in] FolderName, [in] Force)
Description: | This method deletes the specified folder, sub-folders, and files. If Force is True, read-only files will be deleted as well. By default, Force is False.


DriveExists

DriveExists Method

Object: | FileManager
Syntax: | DriveExists ([in] Drivename)
Returns: | True or False
Description: | This method determines whether a specified Drive exists.


EncryptFile

EncryptFile Method

Object: FileManager
Syntax: objFileManager.EncryptFile ([in] InFilename, [in] OutFilename, [in] Password, [in, optional, defaultvalue(1)] saEncType)
Description:

This method encrypts the file specified by InFileNameand saves the result to the OutFileNamelocation.

FileManager allows you to select either TwoFish or RSAencryption. TwoFish encryption is 128-bit. RSA encryption is either 40-bit or 128-bit, depending on the system. To determine whether the system supports 128-bit encryption, check Internet Explorer's "About" (in IE's Help menu).

EncryptFile Parameters
InFileName | The file to encrypt
OutFileName | FileManager will save the encrypted file to this location.
Password Use this password to decrypt the file with either DecryptFile or Decrypt.

Important! Remember the password. You will not be able to recover the file without it.
saEncType The encryption type, which may be either RSA encryption or TwoFish encryption. Assign saEncTypeby name or number:

1 | SARSA
2 | SATWOFISH
3 | SARSAHIGH
4 | SARSALOW


ExportToBlob

ExportToBlob Method

Object: | FileManager
Syntax: | ExportToBlob ([in] Source, [in] recordset("column-name"))
Description: | This method writes a Binary Large OBject (BLOB) into a database from a source file in the specified location. The object is saved into the field specified in the column-name argument. The recordset argument must specify a valid ADO recordset.


FileExists

FileExists Method

Object: | FileManager
Syntax: | FileExists ([in] Filename)
Returns: | True or False
Description: | This method determines if a specified file exists. It is useful to check if a file exists before attempting to execute the GetFile method.


FolderExists

FolderExists Method

Object: | FileManager
Syntax: | FolderExists ([in] DirectoryName)
Returns: | True or False
Description: | This method determines if a specified directory exists. It is useful to check if a folder exists before attempting to execute the GetFolder method .


GetAbsolutePathname

GetAbsolutePathname Method

Object: | FileManager
Syntax: | GetAbsolutePathname ([in] Pathspec)
Returns: | A string containing a complete and unambiguous path derived from the PathSpecargument
Description: | This method returns a string containing a complete and unambiguous path that is derived from the PathSpec argument. The path is considered complete and unambiguous if it contains a complete reference from the root of the drive.


GetBaseName

GetBaseName Method

Object: | FileManager
Syntax: | GetBaseName ([in] Pathspec)
Returns: | A string containing the base name of a file or folder, minus any file extension, from a specified path specification
Description: | This method returns a string containing the base name of a file or folder, which is derived from the PathSpec argument.


GetDrive

GetDrive Method

Object: | FileManager
Syntax: | GetDrive ([in] DriveSpec)
Returns: | A drive object corresponding to the drive in the DriveSpec argument
Description: | This method returns a drive object corresponding to the drive in the DriveSpec argument. The DriveSpec argument can be a drive letter (c), a drive letter with a colon appended (c:), a drive letter with a colon and path separator appended (c:\), or any network share specification (\\computer2\share1).


GetDriveName Method

Object: | FileManager
Syntax: | GetDriveName ([in] DriveSpec)
Returns: | A string containing the name of the drive for a specified path
Description: | This method returns a string containing the name of the drive for a specified path.


GetExtensionName

GetExtensionName Method

Object: | FileManager
Syntax: | GetExtensionName ([in] Path)
Returns: | A string containing the file extension
Description: | This method returns the file extension. For example, if the complete path for a file is c:\temp\file.doc, this method returns doc.


GetFile

GetFile Method

Object: | FileManager
Syntax: | GetFile ([in] Filename)
Returns: | A file object
Description: | This method returns an individual file object. You can use the file object to perform many other file-specific operations.


GetFileName

GetFileName Method

Object: | FileManager
Syntax: | GetFileName ([in] Path)
Returns: | Returns the file name
Description: | This method returns the file name. For example if the complete path is c:\temp\file.doc, this method returns file.doc. If the Path argument does not end with the name of a file or folder, GetFileName returns an empty string.


GetFolder

GetFolder Method

Object: | FileManager
Syntax: | GetFolder ([in] DirectoryName)
Returns: | A Folder object
Description: | This method returns an individual Folder (directory) object. You can use the folder object to perform many other folder-specific operations. The DirectoryName must refer to a valid directory, not a file.


GetParentFolderName

GetParentFolderName Method

Object: | FileManager
Syntax: | GetParentFolderName ([in] Path)
Returns: | Returns a string containing the name of the parent folder of the file in a specified path.
Description: | This method returns the name of the parent folder of the file or folder in a specified path. For example if the complete path is c:\temp\file.doc, this method returns c:\temp. If there is no parent folder for the file or folder specified in the Path argument, the GetParentFolderName method returns a zero-length string.


GetSpecialFolder

GetSpecialFolder Method

Object: FileManager
Syntax: GetSpecialFolder ([in] folderspec)
Returns: A Folder object
Description: This method returns the special folder specified by the folderspec argument.

The folderspec argument can have any of the following values:

Constant | Value | Description
WindowsFolder | 0 | The Windows folder contains files installed by the Windows operating system.
SystemFolder | 1 | The System folder contains libraries, fonts, and device drivers.
TemporaryFolder | 2 | The Temp folder is used to store temporary files. Its path is found in the TMP environment variable.


GetTempName

GetTempName Method

Object: | FileManager
Syntax: | GetTempName
Returns: | Returns a randomly generated string that can be used as a temporary file or folder name.
Description: | The GetTempName method can be very useful in circumstances where it is necessary to generate a temporary file or folder. The GetTempName method requires no arguments.


ImportFromBlob

ImportFromBlob Method

Object: | FileManager
Syntax: | ImportFromBlob ([in] recordset("column-name"), [in] Destination)
Description: | This method extracts a Binary Large OBject (BLOB) from a database and writes to a file specified by the Destination argument. It overwrites the destination file if one with that name already exists.


INIDeleteKey

INIDeleteKey Method

Object: | FileManager
Syntax: | INIDeleteKey ([in] Filename, [in] Section, [in] Key)
Description: | This method deletes the specified key from the INI file.


INIDeleteSection

INIDeleteSection Method

Object: | FileManager
Syntax: | INIDeleteSection ([in] Filename, [in] Section)
Description: | This method deletes the specified section from the INI file.


INIReadBoolean

INIReadBoolean Method

Object: | FileManager
Syntax: | INIReadBoolean ([in] Filename, [in] Section, [in] Key, [in, optional] DefaultValue)
Returns: | True or False)
Description: | This method reads the value of the key from the specified section. If the key is not available, it returns the DefaultValue. If no default is specified, it returns False.


INIReadInteger

INIReadInteger Method

Object: | FileManager
Syntax: | INIReadInteger ([in] Filename, [in] Section, [in] Key, [in, optional] DefaultValue)
Returns: | Integer
Description: | This method reads the value of the key from the specified section. If the key is not available, it returns the Default Value. If no default is specified, it returns (-1).


INIReadString

INIReadString Method

Object: | FileManager
Syntax: | INIReadString ([in] Filename, [in] Section, [in] Key, [in, optional] DefaultValue)
Returns: | String
Description: | This method reads the value of the key from the specified section. If the key is not available, it returns the Default Value. If no default is specified, it returns "".


INIWriteBoolean

INIWriteBoolean Method

Object: | FileManager
Syntax: | INIWriteBoolean ([in] Filename, [in] Section, [in] Key, [in] Value)
Description: | This method writes the value of the key in the specified section.


INIWriteInteger

INIWriteInteger Method

Object: | FileManager
Syntax: | INIWriteInteger ([in] Filename, [in] Section, [in] Key, [in] Value)
Description: | This method writes the value of the key in the specified section.


INIWriteString

INIWriteString Method

Object: | FileManager
Syntax: | INIWriteString ([in] Filename, [in] Section, [in] Key, [in] Value)
Description: | This method writes the value of the key in the specified section.


LogonUser

LogonUser Method

Object: FileManager
Syntax: LogonUser ([in] DomainName, [in] Username, [in] Password, [in] LogonType)
Description: LogonUser is a very powerful method. While a given ASP page is executing, you can use it to switch user contexts, so the rest of the page executes as the specified user. To return to the previous user context, use the RevertToSelf method.

LogonUser calls cannot be nested. Every LogonUser must have a RevertToSelf before issuing another LogonUser.

LogonUser allows you to become a different user, perform some privileged file manipulations, and then return the previous security context of the execution thread.

Every LogonUser should have a corresponding RevertToSelf.

The password will be supplied in clear-text, so you must be particularly vigilant about either:
  • protecting the ASP source code from malicious users, or
  • using SSL to get a password from a user

LogonType can be one of the following:

Constant | Value | Description
saLogon_Interactive | 2 | Interactive Logon. This is the default.
saLogon_Network | 3 | Network Logon.
saLogon_Batch | 4 | Batch Logon.
saLogon_Service | 5 | Logon as a service.

These constants can be found using the IIS 4 or later TypeLibrary feature, or by viewing the vbFileManagerInclude.asp file contained in the .\Samples\directory.

You may get an error in the following situation: When an application is run out of process, the IWAM_<Machine Name> account is used for authentication. IWAM_<Machine Name> does not have the right to "Act as part of the operating system."

To correct this, either:
  • Use SA-FileManager in process only.
Or:
  • Grant the IWAM_<Machine Name> account the right to "Act as part of the operating system":

    1. Open "User Manager for Domains" ("User Manager" if you are using a Workgroup network).
    2. Select User Rights from the Policies Menu.
    3. Enable the "Show advance user rights" checkbox.
    4. Select "Act as part of the Operating System" from the dropdown list of rights.
    5. Add the IWAM_<Machine Name> account to this list.
    6. Click OK and close the User Manager.


MoveFile

MoveFile Method

Object: | FileManager
Syntax: | MoveFile ([in] Source, [in] Destination, [in, optional] OverWrite)
Description: | This method moves, or renames, a file from the source to the destination location. By default, it overwrites the destination file. Set OverWrite to False to not overwrite the destination file.


MoveFolder

MoveFolder Method

Object: | FileManager
Syntax: | MoveFolder ([in] SourceDirectory, [in] DestinationDirectory)
Description: | This method moves, or renames, the source folder, sub-folders, and files to another location. If the folder already exists in the destination directory, the MoveFolder method fails.


OpenBinaryFile

OpenBinaryFile Method

Object: FileManager
Syntax: OpenBinaryFile ([in] Filename, [in] IOMode, [in] Create)
Returns: A BinaryStream object
Description: This method opens a file and returns a BinaryStream object so you can read and write the contents of the file.

You must specify the complete path of the file.

If Create is True, the file will be created. By default, it is False.

IOMode can be one of the following:

Constant | Value | Description
ForReading | 1 | To read the file. This is the default.
ForWriting | 2 | To write to the file.
ForAppending | 8 | To append to the file.

These constants can be found using the IIS 4 or later TypeLibrary feature, or by viewing the vbFileManagerInclude.asp file contained in the .\Samples\directory.


OpenTextFile

OpenTextFile Method

Object: FileManager
Syntax: OpenTextFile ([in] Filename, [in] IOMode, [in] Create, [in] Format)
Returns: A TextStream object
Description: This method opens a file and returns a TextStream object so you can read and write the contents of the file.

You must specify the complete path of the file.

If Create is True, the file will be created. By default, it is False.

IOMode can be one of the following:

Constant | Value | Description
ForReading | 1 | To read the file. This is the default.
ForWriting | 2 | To write to the file.
ForAppending | 8 | To append to the file.

Format can be one of the following:

Constant | Value | Description
TristateTrue | -1 | Open the file as UNICODE.
TristateFalse | 0 | Open the file as ANSI. This is the default.
TristateUseDefault | -2 | Examine the file to determine if it should be opened as UNICODE or ANSI, and open the file appropriately.

These constants can be found using the IIS 4 or later TypeLibrary feature, or by viewing the vbFileManagerInclude.asp file contained in the .\Samples\directory.


RegisterDLL

RegisterDll Method

Object: | FileManager
Syntax: | RegisterDLL ([in] Filename, [in, optional] Register)
Description: | This method registers a DLL in the system registry, similar to the command-line REGSVR32 program. The filename must contain the entire valid path, and must correspond to a self-registering DLL. If Register is True, the DLL will be registered. This is the default. If Register is False, the DLL will be unregistered. You can disable this method by using a registry setting. See Disabling SA-FileUpFeatures . By default, it is enabled.


RevertToSelf

RevertToSelf Method

Object: | FileManager
Syntax: | RevertToSelf ()
Description: | RevertToSelf restores the security context prior to executing LogonUser method. Every LogonUser should have a corresponding RevertToSelf.


FileManager Properties

CurrentUser
Drives
ProcessUser


CurrentUser

CurrentUser Property

Object: | FileManager
Syntax: | CurrentUser
Type: | String
Read/Write: | Read Only
Description: | This property returns the currently impersonated user of the thread. This is very useful if you are using Active Server Pages and testing various authentication mechanisms. It will report the ComputerName\AccountName currently in use, such as WEBSERVER1\IUSR_WEBSERVER1. If, for example, NT Challenge / Response Authentication is currently in use, it will return DomainName\Username such as COMPANY1\JOE. If you are using LogonUser or RevertToSelf, this is also a useful means of determining that the login in use is what you expect it to be.


Drives

Drives Property

Object: | FileManager
Syntax: | Drives
Type: | A collection of Drive objects
Read/Write: | Read Only
Description: | This property returns a collection of all drives on the current system.


ProcessUser

ProcessUser Property

Object: | FileManager
Syntax: |
Type: | String
Read/Write: | Read Only
Description: | This property returns the current process's user name in DOMAIN\USER format.


The BinaryStream Object

The BinaryStream object works with binary data. Use it to manipulate and administer binary data or information about binary data.

BinaryStream Methods

BinaryStream Properties


BinarySteam Methods

Close
Fill
Read
ReadAll
ReadVar
ReadVarAll
Skip
Write


Close

Close Method

Object: | BinaryStream
Syntax: | Close ()
Description: | This method closes the currently open file.


Fill

Fill Method

Object: | BinaryStream
Syntax: | Fill ([in] Byte, [in] numBytes)
Description: | From the current location in the file, this method fills the file with specified byte a total of 'numBytes' times.


Read

Read Method

Object: | BinaryStream
Syntax: | Read ([in] numBytes)
Returns: | An array of binary characters
Description: | From the current location in the file, this method reads numBytes from the file and returns an array of binary characters. In Automation terms, this is a VT_UI1 | VT_ARRAY type. You can also check the AtEndOfStream property to determine if you've reached the end of file.


ReadAll

ReadAll Method

Object: BinaryStream
Syntax: ReadAll ()
Returns: An array of binary characters
Description: This method reads the entire contents of the file into an array of binary characters. In Automation terms, this is a VT_UI1 | VT_ARRAY type.

Note: For performance purposes, it is not recommended that you read very large files into memory on a Web Server, as this may significantly tax server resources.


ReadVar

ReadVar Method

Object: BinaryStream
Syntax: ReadVar (long numBytes)
Returns: An array of variants
Description: From the current location in the file, this method reads numBytes from the file and returns an array of variants. This allows you to manipulate individual bytes within a script.

Note: For performance purposes, it is not recommended that you read large files into memory on a Web Server, as this may significantly tax server resources.

Example:

Set oFM = CreateObject("SoftArtisans.FileManager") Set oBS = oFM.OpenBinaryFile(
      fileName ) dim a dim b Do While Not oBS.AtEndOfStream a = oBS.ReadVar(5) ' You can
      go through each single element b = Chr(a(1)) loop oBS.Close Set oFM = nothing


ReadVarAll

ReadVarAll Method

Object: BinaryStream
Syntax: ReadVarAll ()
Returns: An array of variants
Description: This method reads the entire contents of the file into an array of variants. This allows you to manipulate individual bytes within a script.

Note: For performance purposes, it is not recommended that you read large files into memory on a Web Server, as this may significantly tax server resources.

Example:

Set oFM = CreateObject("SoftArtisans.FileManager") Set oBS = oFM.OpenBinaryFile(
      fileName ) dim a dim b a = oBS.ReadVarAll b = Chr(a(1)) oBS.Close Set oFM = nothing


Skip

Skip Method

Object: | BinaryStream
Syntax: | Skip ([in] numBytes)
Description: | This method moves the file cursor ahead the specified number of bytes.


Write

Write Method

Object: | BinaryStream
Syntax: | Write ([in] string)
Description: | This method writes the specified binary string to the file at the current file cursor location.


BinaryStream Properties

AtEndOfStream


AtEndOfStream

AtEndofStream Property

Object: | BinaryStream
Syntax: | AtEndOfStream ()
Type: | Boolean
Description: | This property is True if the file cursor is at the end of the file. It is False if the cursor is at the beginning or middle of the file.


The Drive Object

The Drive object allows you to look at hard drives and virtual drives. The Drive object can provide a listing of all drives on the server. It cal also provide a means of getting drive information from the source machine or server.

The Drive Object does not contain methods, only properties.

Drive Properties


Drive Methods

The Drive Object does not contain methods, only properties.


Drive Properties

All properties are read-only unless otherwise noted.

AvailableSpace
DriveLetter
DriveType
FileSystem
FreeSpace
IsReady
Path
RootFolder
SerialNumber
ShareName
TotalSize
VolumeName (Read / Write)


AvailableSpace

AvailableSpace Property

Object: | Drive
Syntax: | AvailableSpace ()
Type: | Double precision floating point
Read/Write: | Read only
Description: | This property returns the number of bytes on the drive available to this user. This is usually the same as the FreeSpace property, except when user quotas are in use.


DriveLetter

DriveLetter Property

Object: | Drive
Syntax: | DriveLetter ()
Type: | String
Read/Write: | Read Only
Description: | This property returns the letter of the current drive, e.g., Cfor the C: drive.


DriveType

DriveType Property

Object: Drive
Syntax: DriveType ()
Type: String
Read/Write: Read Only
Description: This property returns the type of the current drive.

DriveType can be one of the following:

Constant | Value | Description
Unknown | 0 | Unable to determine drive type.
Removable | 1 | Removable drive, i.e., floppy.
Fixed | 2 | Non-removable drive, i.e., regular hard disk.
Remote | 3 | Network mounted drive or share.
CDRom | 4 | Drive is a CD-ROM.
RAMDisk | 5 | Drive is a volatile disk RAM.

These constants can be found using the IIS 4 or later TypeLibrary feature, or by viewing the vbFileManagerInclude.asp file contained in the .\Samples\directory.


FileSystem

FileSystem Property

Object: | Drive
Syntax: | FileSystem ()
Type: | String
Read/Write: | Read Only
Description: | This property returns the FileSystem of the specified drive, e.g., FAT, NTFS, etc.


FreeSpace

FreeSpace Property

Object: | Drive
Syntax: | FreeSpace ()
Type: | Double precision floating point
Read/Write: | Read Only
Description: | This property returns the number of unused bytes on the drive for all users. This is usually the same as the AvailableSpace property, except when user quotas are in use.


IsReady

IsReady Property

Object: | Drive
Syntax: | IsReady ()
Type: | Boolean
Read/Write: | Read Only
Description: | This property returns True if the drive is ready for access. It returns False if the drive is unavailable.


Path

Path Property

Object: | Drive
Syntax: | Path ()
Type: | String
Read/Write: | Read Only
Description: | This property returns the path of the current drive, e.g., C:.


RootFolder

RootFolder Property

Object: | Drive
Syntax: | RootFolder ()
Type: | A Folder object
Read/Write: | Read Only
Description: | This property returns a Folder object that corresponds to the root folder of the current drive, e.g., C:\.


SerialNumber

SerialNumber Property

Object: | Drive
Syntax: | SerialNumber ()
Type: | String
Read/Write: | Read Only
Description: | This property returns the serial number of the current drive, if available.


ShareName

ShareName Property

Object: | Drive
Syntax: | ShareName ()
Type: | String
Read/Write: | Read Only
Description: | This property returns the name of the share for the current drive in UNC format, e.g., \\SERVER1\SHARE1.


TotalSize

TotalSize Property

Object: | Drive
Syntax: | TotalSize ()
Type: | Double precision floating point
Read/Write: | Read Only
Description: | This property returns the size of the current drive, in bytes.


VolumeName

VolumeName Property

Object: | Drive
Syntax: | VolumeName ()
Type: | String
Read/Write: | Read/Write
Description: | This property returns or sets the name of the current volume. You must have sufficient privileges to change the name of a volume.


File Methods

AllowAccess
Copy
Decrypt
Delete
DenyAccess
Encrypt
Move
OpenAsBinaryStream
OpenAsTextStream
RevokeAllowance
OrderPermissions
RevokeDenial


AllowAccess

AllowAccess Method

Object: File
Syntax: AllowAccess ([in] AccountName, [in] Permissions)
Description: This method creates an Access Control Entry (ACE) for the current file that allows specific access.

The AccountName must resolve to a valid NT account in the domain.

The Permissions can have any of the following values or any logical combination of the following values:

Constant | Value | Description
saNoAccess | 1 | All Access is denied.
saRead | 2 | The file can be read.
saWrite | 4 | The file can be written.
saExecute | 8 | The file can be executed.
saDelete | 16 | The file can be deleted.
saPermissions | 32 | Permissions on the file can be changed.
saOwner | 64 | Allows taking ownership of the file.
saFull | 126 | Allows all of the above permissions (except NoAccess).
saReadExecute (Windows 2000 only) | 512 | The file can be read and executed.
saModify (Windows 2000 only) | 1024 | The file can be modified.

These constants can be found using the IIS 4 or later TypeLibrary feature, or by viewing the vbFileManagerInclude.asp file contained in the .\Samples\FileManagerSamplesdirectory.


Copy

Copy Method

Object: | File
Syntax: | Copy ([in] Filename, [in, optional] OverWrite)
Description: | This method copies the current file to another location. By default, it overwrites the destination file. To not overwrite the destination file, set OverWrite to False.


Decrypt

Decrypt Method

Object: File
Syntax: objFile.Decrypt ([in]OutFileName, [in]Password, [in, optional, defaultvalue(1)] saEncType)
Description:

This method decrypts the current file and saves the result to the location specified by the OutFileNameparameter.

FileManager allows you to select either TwoFish or RSAencryption. TwoFish encryption is 128-bit. RSA encryption is either 40-bit or 128-bit, depending on the system. To determine whether the system supports 128-bit encryption, check Internet Explorer's "About" (in IE's Help menu).

Decrypt Parameters
OutFileName | FileManager will save the decrypted file to this location
Password | The password set by EncryptFile or Encrypt. If the password is incorrect, the file will be saved as OutFileNamebut the decryption will fail.
saEncType The encryption type, which may be either TwoFish encryption, or CryptoAPI. Assign saEncTypeby name or number:

1 | SARSA
2 | SATWOFISH
3 | SARSAHIGH
4 | SARSALOW


Delete

Delete Method

Object: | File
Syntax: | Delete ([in, optional] Force)
Description: | This method deletes the current file. If Force is True, read-only files are also deleted. By default, Force is False.


DenyAccess

DenyAccess Method

Object: File
Syntax: DenyAccess ([in] AccountName, [in] Permissions)
Description: This method creates an Access Control Entry (ACE) for the current file that denies specific access rights.

The AccountName must resolve to a valid NT account in the domain.

The Permissions can have any of the following values or any logical combination of the following values:

Constant | Value | Description
saNoAccess | 1 | All Access is denied.
saRead | 2 | The file can be read.
saWrite | 4 | The file can be written.
saExecute | 8 | The file can be executed.
saDelete | 16 | The file can be deleted.
saPermissions | 32 | Permissions on the file can be changed.
saOwner | 64 | Allows taking ownership of the file.
saFull | 126 | Allows all of the above permissions (except NoAccess).
saReadExecute (Windows 2000 only) | 512 | The file can be read and executed.
saModify (Windows 2000 only) | 1024 | The file can be modified.

These constants can be found using the IIS 4 or later TypeLibrary feature, or by viewing the vbFileManagerInclude.asp file contained in the .\Samples\FileManagerSamplesdirectory.


Encrypt

Encrypt Method

Object: File
Syntax: objFile.Encrypt ([in] OutFilename, [in] Password, [in, optional, defaultvalue(1)] saEncType)
Description:

This method encrypts the current file and saves the result to the location specified by the OutFileNameparameter. Use the Decrypt method to decrypt the file.

FileManager allows you to select either TwoFish or RSAencryption. TwoFish encryption is 128-bit. RSA encryption is either 40-bit or 128-bit, depending on the system. To determine whether the system supports 128-bit encryption, check Internet Explorer's "About" (in IE's Help menu).

Encrypt Parameters
OutFileName FileManager will save the encrypted file to this location
Password Use this password to decrypt the file with either DecryptFile or Decrypt.

Important! Remember the password. You will not be able to recover the file without it.
saEncType The encryption type, which may be either RSA Encryption or TwoFish encryption. Assign saEncTypeby name or number:

1 | SARSA
2 | SATWOFISH
3 | SARSAHIGH
4 | SARSALOW


Move

Move Method

Object: | File
Syntax: | Move ([in] Filename, [in, optional] OverWrite)
Description: | This method moves, or renames, the current file to another location. By default, it overwrites the destination file. To not overwrite the destination file, set OverWrite to False.


OpenAsBinaryStream

OpenAsBinaryStream Method

Object: File
Syntax: OpenAsBinaryStream ([in] IOMode)
Returns: A BinaryStream object
Description: This method opens a file and returns a BinaryStream object so that you can read and write the contents of the file.

IOMode can be one of the following:

Constant | Value | Description
ForReading | 1 | To read the file. This is the default.
ForWriting | 2 | To write to the file.
ForAppending | 8 | To append to the file.

These constants can be found using the IIS 4 or later TypeLibrary feature, or by viewing the vbFileManagerInclude.asp file contained in the .\Samples\directory.


OpenAsTextStream

OpenAsTextStream Method

Object: File
Syntax: OpenAsTextStream ([in] IOMode, [in] Format)
Returns: A TextStream object
Description:

This method opens a file and returns a TextStream object so you can read and write the contents of the file.

IOMode can be one of the following:

Constant | Value | Description
ForReading | 1 | To read the file. This is the default.
ForWriting | 2 | To write to the file.
ForAppending | 8 | To append to the file.

Format can be one of the following:

Constant | Value | Description
TristateTrue | -1 | Open the file as UNICODE.
TristateFalse | 0 | Open the file as ANSI. This is the default.
TristateUseDefault | -2 | Examine the file to determine if it should be opened as UNICODE or ANSI, and open the file appropriately.

These constants can be found using the IIS 4 or later TypeLibrary feature, or by viewing the vbFileManagerInclude.asp file contained in the .\Samples\directory.


OrderPermissions

OrderPermissions Method

Object: | File
Syntax: | OrderPermissions ()
Description: | This method correctly orders the ACEs in the file's DACL. It does not need to be called after AllowAccess() or DenyAccess(), but it can be called by the client to order a DACL which has been modified externally. The complete SA-FileManagersource code is available for purchase from http://www.SoftArtisans.com.


RevokeAllowance

RevokeAllowance Method

Object: | File
Syntax: | RevokeAllowance ([in] AccountName)
Description: | This method deletes all allowed Access Control Entries (ACE) of the specified account for the current file. In other words, if a specific account has been granted an affirmative ACE on this file, this method will remove that affirmation. The AccountName must resolve to a valid NT account in the domain.


RevokeDenial

RevokeDenial Method

Object: | File
Syntax: | RevokeDenial ([in] AccountName)
Description: | This method deletes all denied Access Control Entries (ACE) of the specified account for the current file. In other words, if a specific account has been granted an negative ACE on this file (i.e., "you are not allowed to write to this file"), this method will remove that denial. The AccountName must resolve to a valid NT account in the domain.


prog_ref_file_properties

Accessible
Attributes
Checksum
DateCreated
DateLastAccessed
DateLastModified
Drive
FileSystem
ImageColor Property
ImageHeight Property
ImageWidth Property
MimeType
Name
Owner
ParentFolder
Path
Permissions
ShortName
ShortPath
Size
Type


Accessible

Accessible Property

Object: File
Syntax: objFile.Accessible
Type: Boolean
Read/Write: Read Only
Description:

This property returns TRUE if the current security context allows access to information about the file (such as its size).

Note: To prevent errors, check the value of Accessiblebefore trying to access file information.


Attributes

Attributes Property

Object: File
Syntax: Attributes
Type: Long Integer
Read/Write: Read/Write (depending on the attribute)
Description: This property returns the file attributes listed below.

The attributes can have any of the following values or any logical combination of the following values:

Constant | Value | Description
saNormal | 0 | Normal file. No attributes are set.
saReadOnly | 1 | Read-only file. Attribute is read/write.
saHidden | 2 | Hidden file. Attribute is read/write.
saSystem | 4 | System file. Attribute is read/write.
saVolume | 8 | Disk drive volume label. Attribute is read-only.
saDirectory | 16 | Folder or directory. Attribute is read-only.
saArchive | 32 | File has changed since last backup. Attribute is read/write.
saAlias | 64 | Link or shortcut. Attribute is read-only.
saCompressed | 2048 | Compressed file. Attribute is read-only.

These constants can be found using the IIS 4 or later TypeLibrary feature, or by viewing the vbFileManagerInclude.asp file contained in the .\Samples\FileManagerSamplesdirectory.


Checksum

Object: File
Syntax: File.Checksum
Type: String
Read/Write: Read only
Description:

The Checksum property returns a string representing the specified file's MD5 hash. You can use this value to verify that a file was not corrupted (during an upload, for example), by comparing before and after MD5 hashes.

Use FileManager's Checksum property to generate an MD5 hash on the client before uploading or after downloading with SoftArtisans FileUp. Then, compare FileManager's MD5 hash with the MD5 hash that FileUp generated on the server.

See Also: FileUp Checksum Property
Example:
<!-- Generate a file's MD5 hash:--> <script language="javascript">
            function getMD5(file) { var hash; var file; file_mgr = new ActiveXObject("SoftArtisans.FileManager");
            file = file_mgr.GetFile(file) hash = file.Checksum return hash } </script>
            <!-- You can use the generated hash to populate a form element:--><input type=button value="Generate Checksum" onclick="Checksum.value = getMD5(FILE1.value)">
            Checksum: <input type=text name=Checksum size=40>


DateCreated

DateCreated Property

Object: | File
Syntax: | DateCreated
Type: | Date
Read/Write: | Read Only
Description: | This property returns the date and time that the specified file was created.


DateLastAccessed

DateLastAccessed Property

Object: | File
Syntax: | DateLastAccessed
Type: | Date
Read/Write: | Read Only
Description: | This property returns the date that the specified file was created. If used with an NTFS partition, the time is also returned.


DateLastModified

DateLastModified Property

Object: | File
Syntax: | DateLastModified
Type: | Date
Read/Write: | Read Only
Description: | This property returns the date and time that the specified file was last modified.


Drive

Drive Property

Object: | File
Syntax: | Drive
Type: | A Drive object
Read/Write: | Read Only
Description: | This property returns a Drive object that corresponds to the drive where this file is located.


FileSystem

FileSystem Property

Object: File
Syntax: objFile.FileSystem
Type:

saFileSystemType

saFileSystemType
Constant | Value | Description
SAFILESYSTEM_NTFS | 1 | NTFS drive.
SAFILESYSTEM_FAT32 | 2 | FAT32 drive.
SAFILESYSTEM_FAT | 3 | Other FAT type.
Read/Write: Read Only
Description:

This property returns the file system of the drive of the current file.

Note: Security information is only applicable on NTFS drives.


ImageColor

ImageColor Property

Object: File
Syntax: objFile.ImageColor
Type: Long
Read/Write: Read Only
Description: Returns the color count of GIF, JPEG, BMP, and PNG format image files.
Example:
<% Set objFileManager = Server.CreateObject("Softartisans.FileManager") Path
            = Server.MapPath("image.gif") Set File = objFileManager.GetFile(Path) Response.Write
            "<Center><Table border=1 CELLSPACING=2 CELLPADDING=5>" Response.Write
            "<TR><TH colspan=2>File name = " & File.Name & "</TH><TR>"
            Response.Write "<TR><TD>Image Height</TD><TD>" & File.ImageHeight
            & "</TD></TR>" Response.Write "<TR><TD>Image Width</TD><TD>"
            & File.ImageWidth & "</TD></TR>" Response.Write "<TR><TD>Image
            Color</TD><TD>" & File.ImageColor & "</TD></TR>"
            Response.Write "<TR><TD colspan=2><IMG src='" & Path & "'></TD></TR>"
            Response.Write "</Table></Center>" %>


ImageHeight

ImageHeight Property

Object: File
Syntax: objFile.ImageHeight
Type: Long
Read/Write: Read Only
Description: Returns the height of an image. ImageHeight can read the height of GIF, JPEG, BMP, and PNG format images.
Example:
<% Set objFileManager = Server.CreateObject("Softartisans.FileManager") Path
            = Server.MapPath("image.gif") Set File = objFileManager.GetFile(Path) Response.Write
            "<Center><Table border=1 CELLSPACING=2 CELLPADDING=5>" Response.Write
            "<TR><TH colspan=2>File name = " & File.Name & "</TH><TR>"
            Response.Write "<TR><TD>Image Height</TD><TD>" & File.ImageHeight& "</TD></TR>" Response.Write "<TR><TD>Image Width</TD><TD>"
            & File.ImageWidth & "</TD></TR>" Response.Write "<TR><TD>Image
            Color</TD><TD>" & File.ImageColor & "</TD></TR>" Response.Write
            "<TR><TD colspan=2><IMG src='" & Path & "'></TD></TR>"
            Response.Write "</Table></Center>" %>


ImageWidth

ImageWidth Property

Object: File
Syntax: objFile.ImageWidth
Type: Long
Read/Write: Read Only
Description: Returns the width of an image. ImageWidth can read the width of GIF, JPEG, BMP, and PNG format images.
Example:
<% Set objFileManager = Server.CreateObject("Softartisans.FileManager") Path
            = Server.MapPath("image.gif") Set File = objFileManager.GetFile(Path) Response.Write
            "<Center><Table border=1 CELLSPACING=2 CELLPADDING=5>" Response.Write
            "<TR><TH colspan=2>File name = " & File.Name & "</TH><TR>"
            Response.Write "<TR><TD>Image Height</TD><TD>" & File.ImageHeight
            & "</TD></TR>" Response.Write "<TR><TD>Image Width</TD><TD>"
            & File.ImageWidth & "</TD></TR>" Response.Write "<TR><TD>Image
            Color</TD><TD>" & File.ImageColor & "</TD></TR>" Response.Write
            "<TR><TD colspan=2><IMG src='" & Path & "'></TD></TR>"
            Response.Write "</Table></Center>" %>


MimeType

MimeType Property

Object: | File
Syntax: | MimeType
Type | String
Read/Write: | Read Only
Description: | This property returns the MIME Type of the specified file. For example, a file with an extension of ".txt" will have a MIME Type of "text/plain". This can be useful when using SA-FileUp's.TransferFile property to set the MIME type appropriately. The MIME Type is also sometimes known as the ContentType, as in the IIS 4 or later documentation.


Name

Name Property

Object: | File
Syntax: | Name
Type: | String
Read/Write: | Read/Write
Description: | This property returns or sets the name of the specified file.


Owner

Owner Property

Object: | File
Syntax: | Owner
Type: | String
Read/Write: | Read/Write
Description: | This property returns or sets the owner of the specified file. It is only possible to take ownership of a file. You cannot arbitrarily set ownership of a file to someone else. To take ownership of a file, you must execute LogonUser first, and set the owner of the file to yourself.


ParentFolder

ParentFolder Property

Object: | File
Syntax: | ParentFolder
Type: | String
Read/Write: | Read Only
Description: | This property returns the parent folder of the specified file.


Path

Path Property

Object: | File
Syntax: | Path
Type: | String
Read/Write: | Read Only
Description: | This property returns the path for the specified file.


Permissions

Permissions Property

Object: | File
Syntax: | Permissions
Type: | A PermItem collection for the file
Read/Write: | Read Only
Description: | This property contains a PermItem collection for the file.


ShortName

ShortName Property

Object: | File
Syntax: | ShortName
Type: | String
Read/Write: | Read Only
Description: | This property returns the short name of the specified file. The ShortName method uses the 8.3 naming convention.


ShortPath

ShortPath Property

Object: | File
Syntax: | ShortPath
Type: | String
Read/Write: | Read Only
Description: | This property returns the short path of the specified file. The ShortPath method uses the 8.3 naming convention.


Type

Type Property

Object: | File
Syntax: | Type
Type: | String
Read/Write: | Read Only
Description: | This property returns a description of a specified file. For example, for files ending in .HTM, "Microsoft HTML Document 4.0" may be returned.


The Folder Object

The Folder object represents a single folder. You can use it to manage folders, look at attributes of folders, set permissions for folders, and to move folders.

Methods Properties


Folder Methods

AllowAccess
Copy
CreateBinaryFile
CreateTextFile
Delete
DenyAccess
Move
OrderPermissions
RevokeAllowance
RevokeDenial


AllowAccess

AllowAccess Method

Object: Folder
Syntax: AllowAccess ([in] AccountName, [in] Permissions [PermissionType])
Description: This method creates an Access Control Entry (ACE) for the current folder that allows specific access.

The AccountName must resolve to a valid NT account in the domain.

The Permissions can have any of the following values or any logical combination of the following values:

Constant | Value | Description
saNoAccess | 1 | All Access is denied.
saRead | 2 | The file can be read.
saWrite | 4 | The file can be written.
saExecute | 8 | The file can be executed.
saDelete | 16 | The file can be deleted.
saPermissions | 32 | Permissions on the file can be changed.
saOwner | 64 | Allows taking ownership of the file.
saFull | 126 | Allows all of the above permissions (except NoAccess).
saList (Windows 2000 only) | 256 | Folder content list can be viewed.
saReadExecute (Windows 2000 only) | 512 | The file can be read and executed.
saModify (Windows 2000 only) | 1024 | The file can be modified.

These constants can be found using the IIS 4 or later TypeLibrary feature, or by viewing the vbFileManagerInclude.asp file contained in the .\Samples\FileManagerSamplesdirectory.

PermissionType is an optional parameter. By default, its value is 3. If set to 1, permission is for files. If set to 2, permission is for directories. If 3, permission is for both files and directories.


CreateBinaryFile

CreateBinaryFile Method

Object: | Folder
Syntax: | CreateBinaryFile ([in] Name, [in] OverWrite)
Returns: | A BinaryStream
Description: | This method creates a new file in the current folder and returns a BinaryStream object so you can read and write the contents of the file. If OverWrite is True, and the file already exists, it will be overwritten. It is True by default.


CreateTextFile

CreateTextFile Method

Object: | Folder
Syntax: | CreateTextFile ([in] Name, [in] OverWrite, [in] Unicode)
Returns: | A TextStream object
Description: | This method creates a new file in the current folder and returns a TextStream object so you can read and write the contents of the file. If OverWrite is True, and the file already exists, it will be overwritten. It is True by default. If Unicode is True, the file will be created in Unicode format. It is False by default.


Copy

Copy Method

Object: | Folder
Syntax: | Copy ([in] DestinationDirectory, [in, optional] OverWrite)
Description: | This method copies the current folder, sub-folders and files to another location. If OverWrite is True, all similarly named files will be overwritten. It is True by default. Set OverWrite to False to not overwrite any existing destination files.


Delete

Delete Method

Object: | Folder
Syntax: | Delete ([in] Force)
Description: | This method deletes the current folder, including all sub-folders and files. If Force is True, then read-only files will be deleted as well. By default, Force is False.


DenyAccess

DenyAccess Method

Object: Folder
Syntax: DenyAccess ([in] AccountName, [in] Permissions)
Description: This method creates an Access Control Entry (ACE) for the current folder that denies specific access rights.

The AccountName must resolve to a valid NT account in the domain.

The Permissions can have any of the following values or any logical combination of the following values:

Constant | Value | Description
saNoAccess | 1 | All Access is denied.
saRead | 2 | The file can be read.
saWrite | 4 | The file can be written.
saExecute | 8 | The file can be executed.
saDelete | 16 | The file can be deleted.
saPermissions | 32 | Permissions on the file can be changed.
saOwner | 64 | Allows taking ownership of the file.
saFull | 126 | Allows all of the above permissions (except NoAccess).
saReadExecute (Windows 2000 only) | 512 | The file can be read and executed.
saModify (Windows 2000 only) | 1024 | The file can be modified.

These constants can be found using the IIS 4 or later TypeLibrary feature, or by viewing the vbFileManagerInclude.asp file contained in the .\Samples\FileManagerSamplesdirectory.


Move

Move Method

Object: | Folder
Syntax: | Move ([in] DestinationDirectory)
Description: | This method moves, or renames, the current folder, sub-folders and files to another location. If the folder already exists in the destination directory, the Move method fails.


OrderPermissions

OrderPermissions Method

Object: | Folder
Syntax: | OrderPermissions ()
Description: | This method correctly orders the ACEs in the folder's DACL. It does not need to be called after AllowAccess() or DenyAccess(), but it can be called by the client to order a DACL which has been modified externally. The complete FileManagersource code is available for purchase from http://www.SoftArtisans.com.


RevokeAllowance

RevokeAllowance Method

Object: | Folder
Syntax: | RevokeAllowance ([in] AccountName)
Description: | This method deletes all allowed Access Control Entries (ACE) of the specified account for the current folder. In other words, if a specific account has been granted an affirmative ACE on this file, this method will remove that affirmation. The AccountName must resolve to a valid NT account in the domain.


RevokeDenial

RevokeDenial Method

Object: | Folder
Syntax: | RevokeDenial ([in] AccountName)
Description: | This method deletes all denied Access Control Entries (ACE) of the specified account for the current folder. In other words, if a specific account has been granted a negative ACE on this folder (i.e., "you are not allowed to write to this folder"), this method will remove that denial. The AccountName must resolve to a valid NT account in the domain.


Folder Properties

Accessible
Attributes
DateCreated
DateLastAccessed
DateLastModified
Drive
Files
FileSystem
IsRootFolder
Name
Owner
ParentFolder
Path
Permissions
SearchWildCard
ShortName
ShortPath
Size
SubFolders
Type


Accessible

Accessible Property

Object: Folder
Syntax: objFolder.Accessible
Type: Boolean
Read/Write: Read Only
Description:

This property returns TRUE if the current security context allows access to information about the folder (such as its size).

Note: To prevent errors, check the value of Accessiblebefore trying to access folder information.


Attributes

Attributes Property

Object: Folder
Syntax: Attributes
Type: Long Integer
Read/Write: Read/Write (depending on the attribute)
Description: Returns the file/folder attributes listed below.

The Attributes can have any of the following values or any logical combination of the following values:

Constant | Value | Description
saNormal | 0 | Normal directory. No attributes are set.
saReadOnly | 1 | Read-only directory. Attribute is read/write.
saHidden | 2 | Hidden directory. Attribute is read/write.
saSystem | 4 | System directory. Attribute is read/write.
saVolume | 8 | Disk drive volume label. Attribute is read-only.
saDirectory | 16 | Folder or directory. Attribute is read-only.
saArchive | 32 | Directory has changed since last backup. Attribute is read/write.
saAlias | 64 | Link or shortcut. Attribute is read-only.
saCompressed | 2048 | Compressed directory. Attribute is read-only.

These constants can be found using the IIS4 or later TypeLibrary feature, or by viewing the vbFileManagerInclude.asp file contained in the .\Samples\FileManagerSamplesdirectory.


DateCreated

DateCreated Property

Object: | Folder
Syntax: | DateCreated
Type: | Date
Read/Write: | Read Only
Description: | This property returns the date and time that the specified folder was created.


DateLastAccessed

DateLastAccessed Property

Object: | Folder
Syntax: | DateLastAccessed
Type: | Date
Read/Write: | Read Only
Description: | This property returns the date that the specified folder was created. If you use this property with an NTFS partition, the time is also returned.


DateLastModified

DateLastModified Property

Object: | Folder
Syntax: | DateLastModified
Type: | Date
Read/Write: | Read Only
Description: | This property returns the date and time that the specified folder was last modified.


Drive

Drive Property

Object: | Folder
Syntax: | Drive
Type: | A Drive object
Read/Write: | Read Only
Description: | This property returns a Drive object that corresponds to the drive where this folder is located.


Files

Files Property

Object: | Folder
Syntax: | Files
Type: | A collection of file objects
Read/Write: | Read Only
Description: | This property returns a collection of file objects. The collection is determined by the SearchWildCard property. You can use the collection of file objects to perform many other file-specific operations.


FileSystem

FileSystem Property

Object: Folder
Syntax: FileSystem
Type: SAFileSystemType
Read/Write: Read Only
Description: This property returns the file system of the drive of the current folder.

Note: Security information is only applicable on NTFS drives.

SAFileSystemType
Constant | Value | Description
SAFILESYSTEM_NTFS | 1 | NTFS drive.
SAFILESYSTEM_FAT32 | 2 | FAT32 drive.
SAFILESYSTEM_FAT | 3 | Other FAT type.


IsRootFolder

IsRootFolder Property

Object: | Folder
Syntax: | IsRootFolder
Type: | Boolean
Read/Write: | Read Only
Description: | This property returns True if the specified folder is the root folder, or False if it is not.


Name

Name Property

Object: | Folder
Syntax: | Name
Type: | String
Read/Write: | Read/Write
Description: | This property returns or sets the name of the specified folder.


Owner

Owner Property

Object: | Folder
Syntax: | Owner
Type: | String
Read/Write: | Read/Write
Description: | This property returns or sets the owner of the specified folder. It is only possible to take ownership of a folder or file. You cannot arbitrarily set ownership of a folder or file to someone else. To take ownership of a folder or file, you must execute LogonUser first, and set the owner of the folder or file to yourself.


ParentFolder

ParentFolder Property

Object: | Folder
Syntax: | ParentFolder
Type: | String
Read/Write: | Read Only
Description: | This property returns the parent folder of the current folder.


Path

Path Property

Object: | Folder
Syntax: | Path
Type: | String
Read/Write: | Read Only
Description: | This property returns the path for the specified folder.


Permissions

Permissions Property

Object: | Folder
Syntax: | Permissions
Type: | A PermItem collection for the folder
Read/Write: | Read Only
Description: | This property contains a PermItem collection for the folder.


SearchWildCard

SearchWildCard Property

Object: | Folder
Syntax: | SearchWildCard
Type: | String
Read/Write: | Read/Write
Description: | This property sets the wildcard search pattern for the .Subfolders or .Files collections. This property uses the standard Microsoft wildcard patterns, such as *.*, *.txt, h*.*, etc.
Example: | The following code will list all files in the C:\WinNT that have a bmp extension.
dim oFM dim oFolder dim oFile Set oFM = CreateObject("SoftArtisans.FileManager")
      Set oFolder = oFM.GetFolder("C:\WinNT") oFolder.SearchWildCard = "*.bmp" For Each
      oFile in oFolder.Files Response.Write oFile.Name & "<br>" Next


ShortName

ShortName Property

Object: | Folder
Syntax: | ShortName
Type: | String
Read/Write: | Read Only
Description: | This property returns the short name of the specified folder. The ShortName property uses the 8.3 naming convention.


ShortPath

ShortPath Property

Object: | Folder
Syntax: | ShortPath
Type: | String
Read/Write: | Read Only
Description: | This property returns the short path of the specified folder. The ShortPath property uses the 8.3 naming convention.


Size

Size Property

Object: Folder
Syntax: Size
Type: Long Integer
Read/Write: Read Only
Description: This property returns the size of the current folder and all sub-folders.

Note: This is potentially a very expensive method call, as the only way to reliably determine the size of all sub-folders involves recursively examining each sub-folder individually.


SubFolders

Subfolders Property

Object: | Folder
Syntax: | Subfolders ()
Returns: | A collection of Folder objects
Description: | This property returns a collection of Folder objects. The collection is determined by the SearchWildCard property. You can use the collection of Folder objects to perform many other folder-specific operations. You can also use the subfolder collection to recursively walk a complete directory tree. See the example in the .\Samples\FileManagerSamples directory.


Type

Type Property

Object: | Folder
Syntax: | Type
Type: | String
Read/Write: | Read Only
Description: | This property returns a description of a specified folder. For example, for an ordinary file folder, "File Folder" may be returned.


The TextStream Object

The TextStream object works with text data. Use it to manipulate and administer text data. It is similar to the Microsoft Scripting.FileSystem object.

Methods Properties


TextSteam Methods

Close
Read
ReadAll
ReadLine
Skip
SkipLine
Write
WriteBlankLines
WriteLine


Close

Close Method

Object: | TextStream
Syntax: | Close ()
Description: | This method closes the currently open file.


Read

Read Method

Object: | TextStream
Syntax: | Read ([in] numBytes)
Returns: | An array of text characters
Description: | This method reads numBytes from the file, starting at the current location, and returns an array of text characters. A conversion is attempted from any binary characters to legible text characters. In Automation terms, this is a VT_BSTRtype. You can also check the AtEndOfStream property to determine if you've reached the end of file.


ReadAll

ReadAll Method

Object: TextStream
Syntax: ReadAll ()
Returns: An array of text characters
Description: This method reads the entire contents of the file into an array of text characters. In Automation terms, this is a VT_BSTR type.

Note: For performance purposes, it is not recommended to read very large files into memory on a web server, as this may significantly tax server resources.


ReadLine

ReadLine Method

Object: | TextStream
Syntax: | ReadLine ()
Returns: | A single line of the file
Description: | This method reads a single line of the file into an array of text characters starting from the current cursor location. In automation terms, this is a VT_BSTRtype. A line is terminated by a <CR><LF>.


Skip

Skip Method

Object: | TextStream
Syntax: | Skip ([in] numBytes)
Description: | This method moves the file cursor ahead the specified number of bytes.


SkipLine

SkipLine Method

Object: | TextStream
Syntax: | SkipLine ()
Description: | This method moves the file cursor ahead one line. A line is terminated by a <CR><LF>.


Write

Write Method

Object: | TextStream
Syntax: | Write ([in] string)
Description: | This method writes the specified text string to the file at the current file cursor location.


WriteBlankLines

WriteBlankLines Method

Object: | TextStream
Syntax: | WriteBlankLines ([in] numLines)
Description: | This method writes the specified number of blank lines to the file at the current file cursor location.


WriteLine

WriteLine Method

Object: | TextStream
Syntax: | WriteLine ([in, optional] string)
Description: | This method writes the specified text string, followed by a <CR><LF>, to the file at the current file cursor location. If no string is specified, a single blank line is written to the file.


TextStream Properties

AtEndOfLine
AtEndOfStream
Column
Line


AtEndOfFile

AtEndOfFile Property

Object: | TextStream
Syntax: | AtEndOfFile ()
Type: | Boolean
Description: | This property returns True if the file cursor is at the end of the file. It returns False if the cursor is at the beginning or middle of the file.


AtEndOfLine

AtEndOfLine Property

Object: | TextStream
Syntax: | AtEndOfLine ()
Type: | Boolean
Read/Write: | Read Only
Description: | This property returns True if the file cursor is at the end of a line in the current file. It returns False if the cursor is at the beginning or middle of a line.


AtEndOfStream

AtEndOfStream Property

Object: | TextStream
Syntax: | AtEndOfStream ()
Type: | Boolean
Read/Write: | Read Only
Description: | This property returns True if the file cursor is at the end of the file. It returns False, if the cursor is at the beginning or middle of the file.


Column

Column Property

Object: | TextStream
Syntax: | Column ()
Type: | Integer
Read/Write: | Read Only
Description: | This property returns the current column number, numbered from 1-n.


Line

Line Property

Object: | TextStream
Syntax: | Line ()
Type: | Integer
Read/Write: | Read Only
Description: | This property returns the current line number, numbered from 1-n.


The PermItem Object

The PermItem object represents a single trustee's permissions on a single securable object.

PermItem Methods

PermItem Properties


PermItem Methods

RemoveEntry


RemoveEntry

RemoveEntry Method

Object: | PermItem
Syntax: | RemoveEntry ()
Description: | This method removes this entry from the ACL.


PermItem Properties

AccessRights
Delete
Execute
FullControl2
ListContents2
Modify2
NoAccess
Ownership
Permissions
Read
Read2
ReadExecute2
RightsType
Trustee
Write
Write2


AccessRights

AccessRights Property

Object: PermItem
Syntax: AccessRights
Type: Long
Read/Write: Read Only
Description: This property indicates the combined rights of a file or directory.

The SAPermissionsRights can have any of the following values:

Constant | Value | Description
SANoAccess | 1 | All Access is denied.
SARead | 2 | The file can be read.
SAWrite | 4 | The file can be written.
SAExecute | 8 | The file can be executed.
SADelete | 16 | The file can be deleted.
SAPermissions | 32 | Permissions on the file can be changed.
SAOwner | 64 | Allows taking ownership of the file.
SAFull | 126 | Allows all of the above permissions (except NoAccess).
saList (Windows 2000 only) | 256 | Folder content list can be viewed.
saReadExecute (Windows 2000 only) | 512 | The file can be read and executed.
saModify (Windows 2000 only) | 1024 | The file can be modified.


Delete

Delete Property

Object: | PermItem
Syntax: | Delete
Type: | Boolean
Read/Write: | Read Only
Description: | This property indicates that the trustee can delete the file.


Execute

Execute Property

Object: | PermItem
Syntax: | Execute
Type: | Boolean
Read/Write: | Read Only
Description: | This property indicates that execute access is available.


FullControl2

FullControl2 Property

Object: PermItem
Syntax: FullControl2
Type: SAAccessType
Read/Write: Read Only
Description: This property is for use on Windows 2000 systems only. It indicates that the trustee has permissions equivalent to "Full Control" in the Windows 2000 access control property page.

SAAccessType
Constant | Value | Description
SAALLOW | 1 | This privilege is granted.
SADENY | 2 | This privilege is not granted.
SANOTSET | 3 | This privilege is set.


ListContents2

ListContents2 Property

Object: PermItem
Syntax: ListContents2
Type: SAAccessType
Read/Write: Read Only
Description: This property is for use on Windows 2000 systems only. It indicates that the trustee has permissions equivalent to "List Folder" Contents in the Windows 2000 access control property page.

SAAccessType
Constant | Value | Description
SAALLOW | 1 | This privilege is granted.
SADENY | 2 | This privilege is not granted.
SANOTSET | 3 | This privilege is set.


Modify2

Modify2 Property

Object: PermItem
Syntax: Modify2
Type: SAAccessType
Read/Write: Read Only
Description: This property is for use on Windows 2000 systems only. It indicates that the trustee has permissions equivalent to "Modify" in the Windows 2000 access control property page.

SAAccessType
Constant | Value | Description
SAALLOW | 1 | This privilege is granted.
SADENY | 2 | This privilege is not granted.
SANOTSET | 3 | This privilege is set.


NoAccess

NoAccess Property

Object: | PermItem
Syntax: | NoAccess
Type: | Boolean
Read/Write: | Read Only
Description: | This property indicates that no access right is available for this trustee.


Ownership

Ownership Property

Object: | PermItem
Syntax: | Ownership
Type: | Boolean
Read/Write: | Read Only
Description: | This property indicates that the trustee has rights to change the ownership of the file.


Permissions

Permissions Property

Object: | PermItem
Syntax: | Permissions
Type: | Boolean
Read/Write: | Read Only
Description: | This property indicates that the trustee has rights to changes the permissions.


Read

Read Property

Object: | PermItem
Syntax: | Read
Type: | Boolean
Read/Write: | Read Only
Description: | This property indicates that read access is available.


Read2

Read2 Property

Object: PermItem
Syntax: Read2
Type: SAAccessType
Read/Write: Read Only
Description:

This property is for use on Windows 2000 systems only. It indicates that the trustee has permissions equivalent to "Read" in the Windows 2000 access control property page.

SAAccessType
Constant | Value | Description
SAALLOW | 1 | This privilege is granted.
SADENY | 2 | This privilege is not granted.
SANOTSET | 3 | This privilege is set.


ReadExecute2

ReadExecute2 Property

Object: PermItem
Syntax: ReadExecute2
Type:

SAAccessType

SAAccessType
Constant | Value | Description
SAALLOW | 1 | This privilege is granted.
SADENY | 2 | This privilege is not granted.
SANOTSET | 3 | This privilege is set.
Read/Write: Read Only
Description: This property is for use on Windows 2000 systems only. It indicates that the trustee has permissions equivalent to "Read & Execute" in the Windows 2000 access control property page.


RightsType

RightsType Property

Object: PermItem
Syntax: RightsType
Type: Long
Read/Write: Read Only
Description: This property indicates the rights type for either a file or a directory.

The SAPermissionsRightsTypes can have any of the following values:

Constant | Value | Description
SAFileRights | 1 | Permissions apply to files.
SADirRights | 2 | Permissions apply to directories.
SADirFileRights | 3 | Permissions apply to both files and directories.


Trustee

Trustee Property

Object: | PermItem
Syntax: | Trustee
Type: | String
Read/Write: | Read Only
Description: | This property returns the trustee's name in the DOMAIN\USER or DOMAIN\GROUPformat.


Write

Write Property

Object: | PermItem
Syntax: | Write
Type: | Boolean
Read/Write: | Read Only
Description: | This property indicates that write access is available.


Write2

Write2 Property

Object: PermItem
Syntax: Write2
Type: SAAccessType
Read/Write: Read Only
Description:

This property is for use on Windows 2000 systems only. It indicates that the trustee has permissions equivalent to "Write" in the Windows 2000 access control property page.

SAAccessType
Constant | Value | Description
SAALLOW | 1 | This privilege is granted.
SADENY | 2 | This privilege is not granted.
SANOTSET | 3 | This privilege is set.


Legal Information

Information in this document is subject to change without notice. No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose, without the express written permission of Software Artisans, Inc. If, however, your only means of access is electronic, permission to print one copy is hereby granted.

Copyright © 2000 - 2010 Software Artisans, Inc. All rights reserved.

Software Artisans, the Software Artisans logo, SA-FileUp, SoftArtisans FileUp, SoftArtisans FileUp Standard Edition, SoftArtisans FileUp Professional Edition, SoftArtisans FileUpEE, SoftArtisans FileUp Enterprise Edition, SA-JFile, SoftArtisans JFile, SA-XFile, SoftArtisans XFile, SA-Archive, SoftArtisans Archive, SA-SMTPmail, SoftArtisans SMTPmail, SA-FileManager, SoftArtisans FileManager, SA-Admin, SoftArtisans Admin, SoftArtisans ImgWriter, SoftArtisans ExcelWriter, SoftArtisans ExcelWriterEE, SoftArtisans ExcelWriterSE, SoftArtisans ExcelWriterLE, SoftArtisans ExcelWriter Desktop, SoftArtisans WordWriter, SA-FileManagerTX, SoftArtisans FileManagerTX, SA-SessionPro, SoftArtisans SessionPro, SA-Check, and SoftArtisans Check are all trademarks of Software Artisans, Inc. in the United States and/or other countries.

SoftArtisans and the SoftArtisans logo are registered trademarks of Software Artisans, Inc.

Microsoft, MS-DOS, MS, Windows, Windows NT, ActiveX, JScript, Microsoft Press, Visual Basic, Visual C++, Visual J++, Win32, and Win32s are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.

Alpha AXP is a trademark of Digital Equipment Corporation.

Pentium is a registered trademark of Intel Corporation.

Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries.

Netscape, Netscape Navigator, and the Netscape N logo are registered trademarks of Netscape Communications Corporation in the United States and other countries.

Other product and company names mentioned herein may be the trademarks of their respective owners.


Large Uploads in ASP.NET

  • FileUp's HttpModule
  • Connection Timeout
  • MaxClientRequestBuffer
  • .NET Settings
ASP.NET Samples
FileUp includes many sample ASP.NET applications in both C# and VB.NET. To run the samples, open a browser window and enter the URL http://localhost/SAFileUpSamples. The sample code is in the folder FileUp\Samples.
The HttpModule

FileUp's HttpModule intercepts selected requests to overcome ASP.NET's inefficient memory utilization and to allow accurate progress indication. The HttpModule intercepts an upload request, reads all the data, and writes it to a temp file chunk by chunk, before forwarding the request to ASP.NET.

For performance reasons, the HttpModule will not intercept all ASP.NET requests. It will intercept ASP.NET requests for files with the extension .uplx. Files with the extension .aspx will not be processed by the filter, and will be sent directly to ASP.NET. This prevents burdening the server with unnecessary use of the HttpModule. So, to use the HttpModule, name your ASP.NET scripts FileName.uplx.

FileUp's automatic installation package will install the HttpModule for FileUp's samples, and create the script mappings for the .uplx extension. See Installing the HttpModule for instructions on installing the HttpModule at the application level or in the Global Assembly Cache.

Upload Size on the Client
While FileUp can process uploads of up to 4-GB, most browsers support uploads of up to 2-GB. Larger uploads must be generated by a client-side control that can handle very large transfers, such as SoftArtisans XFile [image].
Progress Indication in ASP.NET
Under ASP.NET, FileUp's progress indicator is handled by the HttpModule. Therefore, to display accurate progress indication in ASP.NET, upload to a file with the .uplx extension.

Top

ConnectionTimeout

IIS's Connection Timeout property sets a time in seconds at which the server will disconnect an inactive connection. The default value is 900 seconds. To allow very large uploads to complete it may be necessary to increase this value. To reset Connection Timeout:

  1. In IIS, right-click Default Web Site and select Properties.

  2. Select the Web Site tab.

  3. In the Connection Timeout box, enter a new value.

Top

.NET Settings

In the .NET configuration file for your Web application - web.config or machine.config- there are several attributes that can affect the performance of large uploads. To set these attributes at the machine level, modify machine.config (located in [windows directory]\Microsoft.NET\Framework\[.NET Version Directory]\CONFIG). To set the attributes at the application level, modify your application's web.config file.

You will find the following values in the httpRuntime node of machine.config:

  • executionTimeout
    Time in seconds before a request is timed out.

  • maxRequestLength
    Maximum request size in kilobytes that ASP.NET will accept.

  • appRequestQueueLimit
    Maximum number of requests queued for an ASP.NET application. The default value of appRequestQueueLimit is 100. If your server will be handling more than 100 concurrent requests, increase the value of appRequestQueueLimit.

The following attributes are in the processModel node of machine.config:

  • responseDeadlockInterval
    Specifies the time interval, in the format HH:MM:SS, after which the process will be restarted if the following conditions are met:
    • There are queued requests.
    • There has not been a response during this interval.
    The default value of responseDeadlockInterval is 3 minutes. To allow very large uploads, you may have to increase this value. This property must be set in machine.config, not at the application level in web.config. It will affect any response deadlock in ASP.NET and should be used with caution.

  • responseRestartDeadlockInterval

    • Specifies the time, in the format HH:MM:SS, that must elapse after the last restart to cure a deadlock before the process is restarted to cure a deadlock again. This prevents thrashing on processes that require a relatively long startup time. The default value of responseRestartDeadlockInterval is 9 minutes. To allow very large uploads, you may have to increase this value. This property must be set in machine.config, not at the application level in web.config. It will affect any response deadlock in ASP.NET and should be used with caution.

  • maxIoThreads

    • Maximum number of IO threads per CPU in the thread pool. The default value of maxIoThreads is 25. Increasing this value will increase the number of concurrent executing requests, significantly reducing the amount of time it takes to process concurrent requests. This value is particularly important for large uploads using the HttpModule. If you expect many concurrent uploads to your site, you should set maxIoThreads to the number of concurrent uploads that you wish to support.

Top


Adding a Server-Side Progress Indicator

FileUp includes a server-side progress indicator that can be displayed to the user using HTML. The server-side progress indicator lets you know how much of the entire upload has arrived at the server. In an upload from the browser to an ASP page, include the progress indicator in a separate page. In this page, you can get and display to the user:

  • The Percentageof the upload that has reached the server.
  • TotalBytesin the upload.
  • TransferredBytesso far.

You can use HTML techniques to customize the output effect, and display a counter or a progress bar.

EnableSessionState Directive

The progress indicator needs to operate outside of the current session in order to refresh properly. In order to maintain session state, ASP must serialize all requests for that session. To allow the progress indicator to execute outside of a session, the following directive must be added to the progress indicator page:

<%@ ENABLESESSIONSTATE=False %>

Setting the EnableSessionState directive to False allows the progress indicator page's request to be processed on a separate thread. This allows the progress indicator to update itself while the upload continues to be processed on another thread. If this directive is not set, or is set to true, then the progress indicator is queued until the upload finishes. At this point, the progress indicator can now be updated, but the upload is complete, so the indicator jumps immediately from 0% to 100%.

The upload form and processing page can participate in the session as usual.

Example

The following lines are from an application that contains three scripts: form.asp, formresp.asp and progress.asp. Form.asp submits the file to the upload processing page formresp.asp. Progress.asp contains the progress indicator.

Form.asp
...
<%
'--- Instantiate the FileUpProgress object.
Set progress = Server.CreateObject("SoftArtisans.FileUpProgress")

'--- Get the next available progress ID.
'--- The progress ID is how the progress indicator and FileUp
'--- sychronize with each other.
intProgressID = progress.NextProgressID
%>
...
<head>
<script language="javascript">
<i>/*
This function makes sure that the progress indicator and server-side
processing page receive the new progress ID we just created. Also, it pops up the
progress window.
*/</i>
function startupload() {
winstyle="height=150,width=500,status=no,_       toolbar=no,menubar=no,location=no";
window.open("progress.asp?progressid=<%=intProgressID%>",_       "_blank",winstyle);
document.theForm.action="formresp.asp?progressid=<%=intProgressID%>";
}
</script>
</head>
<body>
...
<form onSubmit="startupload();" id="theForm"
name="theForm" action="formresp.asp"
enctype="multipart/form-data" method="post">
<p>Enter Filename:</p>
<input type="file" id="myFile" name="myFile" />
<p>Click "Browse" to select a file to upload</p>
<input type="submit" id="sub1" name="sub1" value="Upload File" />
</form>
...

Formresp.asp
<%
'--- Instantiate the FileUp object
Set fileUpload = Server.CreateObject("SoftArtisans.FileUp")

'--- Assign the same progress ID that we assigned to the progress object
fileUpload.ProgressID = CInt(Request.QueryString("progressid"))

fileUpload.Path = "C:\temp"
...
fileUpload.Form("myFile").Save
...
%>

Progress.asp
<%@ language=VBScript ENABLESESSIONSTATE=False %>
<%
'-----------------------------------------------------------------------
'--- This is the progress indicator itself. It refreshes every second
'--- to re-read the file progress properties, which are updated thoughout
'--- the upload.
'-----------------------------------------------------------------------
'--- Declarations
Dim progress
Dim intProgressID
Dim intPercentComplete
Dim intBytesTransferred
Dim intTotalBytes
Dim bDone

intPercentComplete = 0
intBytesTransferred = 0
intTotalBytes = 0

'--- Instantiate the FileUpProgress object
Set progress = Server.CreateObject("Softartisans.FileUpProgress")

'--- Set the ProgressID with the value we submitted from the form page
progress.ProgressID = CInt(Request.QueryString("progressid"))

'--- Read the values of the progress indicator's properties
intPercentComplete = progress.Percentage
intBytesTransferred = progress.TransferredBytes
intTotalBytes = progress.TotalBytes

%>
<html>
<head>
<%
'--- If the upload isn't complete, continue to refresh
If intPercentComplete < 100 Then
bDone = False
Response.Write("<meta http-equiv=""Refresh"" content=1>")
Else
bDone = True
End If
%>
</head>
<body>
<table border="1">
<tr>
<td colspan="3"><b>FileUp Progress Indicator</b></td>
<td colspan="2"><b>Status:
<%
If bDone Then
Response.Write("Complete!")
Else
Response.Write("Sending")
End If
%>
</b></td>
</tr>
<tr>
<td>Progress ID </td>
<td>Graphic Indicator</td>
<td>Transferred Bytes</td>
<td>Total Bytes</td>
<td>Transferred Percentage</td>
</tr>
<tr>
<td align="left"><%=progress.progressid%></td>
<td>
<table bordercolor="black" border="1" cellspacing="0"
align="left" width="<%=intPercentComplete%>%">
<tr>
<td align="right" width="100%" bgcolor="blue">
<B><%=intPercentComplete%></b></td>
</tr>
</table>
<%
Response.Write("</td>")
Response.Write "<td align="center">" & intBytesTransferred & "</td>"

If progress.TotalBytes > 0 Then
Response.Write("<td align="center">" & intTotalBytes & "</td>" & _
"<td align="center">" & intPercentComplete & "%</td>" )
Else
Response.Write ("<td align="center">" & "N/A" & "</td>" & _
"<td align="center">" & "N/A" & "</td>")
End If

%>
</tr>
</table>
</body>
</html>

Top


Adding a Server-Side Progress Indicator

This sample builds on the concepts taught in the "Getting Started" chapter, in the example, "A Simple Upload in ASP.NET". It assumes that you already understand how to configure your application and that you know how to perform at least a simple upload.

FileUp includes a server-side progress indicator that can be displayed to the user using HTML. The server-side progress indicator lets you know how much of the entire upload has arrived at the server. In an upload from the browser to an ASP.NET page, include the progress indicator in a separate page. In this page, you can get and display to the user:

  • The Percentage of the upload that has reached the server.
  • TotalBytes in the upload.
  • TransferredBytes so far.

You can use HTML techniques to customize the output effect, and display a counter or a progress bar.

Progress Indication in ASP.NET
Under ASP.NET, FileUp's progress indication is handled by the HttpModule. Therefore, to display accurate progress indication in ASP.NET, upload to a file with the .uplx extension.
Example

The complete code for the following example is available in the "Progress Indicator" sample included in the "FileUp/Samples/UploadSamples" installation directory. This sample contains the following pages:

Page Name | Function
ProgressUpload.uplx | Contains the display HTML for the form and will display the response. Also responsible for opening the progress indicator window.
ProgressUpload.uplx.[vb|cs] | Code-behind of ProgressUpload.uplx: Contains the logic that will accept the request on the server, save out the files and coordinate progress indication.
ProgressIndicator.aspx | Contains the display HTML for the progress indicator.
ProgressIndicator.aspx.[vb|cs] | Code-behind for ProgressIndicator.aspx: Instantiates the FileUp Progress Indicator object and provides logic for progress indication display.

There are 5 steps to this process:

  1. Obtain a ProgressID on the Server before rendering the HTML for the upload form.
  2. Provide the HTML form as usual, but attach a script to start progress on the "onsubmit" event of the form.
  3. Provide a graphical representation of progress with HTML.
  4. Provide the logic to drive the progress display in the code-behind[ProgressIndicator.aspx.[vb|cs] of the Progress Indicator page.
  5. Set up ProgressUpload.uplx.[vb|cs] to synchronize with the progress indicator before parsing the request.
Step One: Obtain a ProgressID on the Server before rendering the HTML for the upload form.

A Progress ID must be obtained from the FileUp Progress Indicator object as the first step to an upload request that will provide progress indication. This Progress ID will be used to synchronize the progress indication display code and the FileUp upload processing code, even though they exist in separate pages, on separate threads. This progress ID must be obtained from the Progress Indicator object's NextProgressId() function. It should not be "set" as a value in any other way (do not provide your own values). The progress indicator provides an identifier to distinguish a particular upload's progress indication from any other progress indication occuring in other upload requests being handled by FileUp on the same webserver.

In the code behind of ProgressUpload.uplx, instantiate the FileUp Progress object on the Page_Load event.

C# protected void Page_Load(object sender, EventArgs e)
{
   //--- When the page is first loaded, generate a new progress id
   if (!Page.IsPostBack)
   {
      //--- FileUpProgress.NextProgressId generates a new progress id
      FileUpProgress progress = new FileUpProgress();
      progressid = progress.NextProgressId();
   }
}
VB.NET Protected Sub Page_Load(sender As Object, e As EventArgs)

   '--- When the page is first loaded, generate a new progress id
   If Not (Page.IsPostBack) Then
      '--- FileUpProgress.NextProgressId generates a new progress id
      Dim progress As New FileUpProgress()
      progressid = progress.NextProgressId()
   End If

End Sub
Step Two: Provide the HTML form as usual, but attach a script to start progress on the "onsubmit" event of the form.

This HTML form is identical to the form used in the Simple Upload in ASP.NET example, except that we will attach a function to the "onsubmit" event of the form. This function will open a new window for the progress indicator, passing it the Progress ID in the querystring. Likewise, the action attribute of the HTML form will be updated to include the Progress ID in its querystring.

The HTML Form (in ProgressUpload.uplx)
<html>
<head>
<title>SoftArtisans FileUp ASP.NET Progress Indicator Sample</title>

<script language="javascript">
/*
This small function makes sure that the progress indicator and server-side
processing page receive the new progress ID we just created in the CodeBehind class.
Also, it pops up the progress window.
*/
function startUpload()
{
   winStyle = "height=200,width=550,status=no,scrollbars=no,toolbar=no,"       "menubar=no,location=no";
   if(theForm.myFile.value != "")
      window.open("ProgressIndicator.aspx?progressid=<%=progressid%>", "_blank", winStyle);
   theForm.action = theForm.action + "?progressid=" + <%=progressid%>;
}
</script>
</head>
<body>
<form onSubmit="startUpload();" id="theForm" runat="server"
   enctype="multipart/form-data" method="post">
   Enter Filename: <input type="file" id="myFile" name="myFile" />
   Click "Browse" to select a file to upload
   <input runat="server" OnServerClick="UploadBtn_Click" id="UploadBtn"
      type="submit" value="Upload File" />
   <asp:literal id="ltrUploadResults" runat="server" />
</form>
</body>
</html>

Adding a Server-Side Progress Indicator

This sample builds on the concepts taught in the "Getting Started" chapter, in the example, "A Simple Upload in ASP.NET". It assumes that you already understand how to configure your application and that you know how to perform at least a simple upload.

FileUp includes a server-side progress indicator that can be displayed to the user using HTML. The server-side progress indicator lets you know how much of the entire upload has arrived at the server. In an upload from the browser to an ASP.NET page, include the progress indicator in a separate page. In this page, you can get and display to the user:

  • The Percentage of the upload that has reached the server.
  • TotalBytes in the upload.
  • TransferredBytes so far.

You can use HTML techniques to customize the output effect, and display a counter or a progress bar.

Progress Indication in ASP.NET
Under ASP.NET, FileUp's progress indication is handled by the HttpModule. Therefore, to display accurate progress indication in ASP.NET, upload to a file with the .uplx extension.
Example

The complete code for the following example is available in the "Progress Indicator" sample included in the "FileUp/Samples/UploadSamples" installation directory. This sample contains the following pages:

Page Name | Function
ProgressUpload.uplx | Contains the display HTML for the form and will display the response. Also responsible for opening the progress indicator window.
ProgressUpload.uplx.[vb|cs] | Code-behind of ProgressUpload.uplx: Contains the logic that will accept the request on the server, save out the files and coordinate progress indication.
ProgressIndicator.aspx | Contains the display HTML for the progress indicator.
ProgressIndicator.aspx.[vb|cs] | Code-behind for ProgressIndicator.aspx: Instantiates the FileUp Progress Indicator object and provides logic for progress indication display.

There are 5 steps to this process:

  1. Obtain a ProgressID on the Server before rendering the HTML for the upload form.
  2. Provide the HTML form as usual, but attach a script to start progress on the "onsubmit" event of the form.
  3. Provide a graphical representation of progress with HTML.
  4. Provide the logic to drive the progress display in the code-behind[ProgressIndicator.aspx.[vb|cs] of the Progress Indicator page.
  5. Set up ProgressUpload.uplx.[vb|cs] to synchronize with the progress indicator before parsing the request.
Step One: Obtain a ProgressID on the Server before rendering the HTML for the upload form.

A Progress ID must be obtained from the FileUp Progress Indicator object as the first step to an upload request that will provide progress indication. This Progress ID will be used to synchronize the progress indication display code and the FileUp upload processing code, even though they exist in separate pages, on separate threads. This progress ID must be obtained from the Progress Indicator object's NextProgressId() function. It should not be "set" as a value in any other way (do not provide your own values). The progress indicator provides an identifier to distinguish a particular upload's progress indication from any other progress indication occuring in other upload requests being handled by FileUp on the same webserver.

In the code behind of ProgressUpload.uplx, instantiate the FileUp Progress object on the Page_Load event.

C# protected void Page_Load(object sender, EventArgs e)
{
   //--- When the page is first loaded, generate a new progress id
   if (!Page.IsPostBack)
   {
      //--- FileUpProgress.NextProgressId generates a new progress id
      FileUpProgress progress = new FileUpProgress();
      progressid = progress.NextProgressId();
   }
}
VB.NET Protected Sub Page_Load(sender As Object, e As EventArgs)

   '--- When the page is first loaded, generate a new progress id
   If Not (Page.IsPostBack) Then
      '--- FileUpProgress.NextProgressId generates a new progress id
      Dim progress As New FileUpProgress()
      progressid = progress.NextProgressId()
   End If

End Sub

Step Two: Provide the HTML form as usual, but attach a script to start progress on the "onsubmit" event of the form.

This HTML form is identical to the form used in the Simple Upload in ASP.NET example, except that we will attach a function to the "onsubmit" event of the form. This function will open a new window for the progress indicator, passing it the Progress ID in the querystring. Likewise, the action attribute of the HTML form will be updated to include the Progress ID in its querystring.

The HTML Form (in ProgressUpload.uplx)
<html>
<head>
<title>SoftArtisans FileUp ASP.NET Progress Indicator Sample</title>

<script language="javascript">
/*
This small function makes sure that the progress indicator and server-side
processing page receive the new progress ID we just created in the CodeBehind class.
Also, it pops up the progress window.
*/
function startUpload()
{
   winStyle = "height=200,width=550,status=no,scrollbars=no,toolbar=no," &
      "menubar=no,location=no";
   if(theForm.myFile.value != "")
      window.open("ProgressIndicator.aspx?progressid=<%=progressid%>", "_blank", winStyle);
   theForm.action = theForm.action + "?progressid=" + <%=progressid%>;
}
</script>
</head>
<body>
<form onSubmit="startUpload();" id="theForm" runat="server"
   enctype="multipart/form-data" method="post">
   Enter Filename: <input type="file" id="myFile" name="myFile" />
   Click "Browse" to select a file to upload
   <input runat="server" OnServerClick="UploadBtn_Click" id="UploadBtn"
      type="submit" value="Upload File" />
   <asp:literal id="ltrUploadResults" runat="server" />
</form>
</body>
</html>

Step Three: Provide a graphical representation of progress with HTML

The FileUp Progress Indicator does not provide it's own GUI. Instead, it provides information on progress indication so that you can develop your own custom represenatation of progress. In this sample, we are using an HTML table and an <hr> element to function as a progress meter.

ProgressIndicator.aspx
<html>
<body>
<h3>Upload Progress:</h3>
<!--
This table holds cells that are used to display
the upload progress for the progress indicator
-->
<asp:Table id="UploadTable"
   GridLines="Both"
   HorizontalAlign="Center"
   Font-Name="Verdana"
   Font-Size="8pt"
   CellPadding="15"
   CellSpacing="0"
   runat="server"<

   <asp:tablerow>
      <asp:tablecell><b>Progress ID</b></asp:tablecell>
      <asp:tablecell width="300"><b>Graphic</b></asp:tablecell>
      <asp:tablecell><b>Transferred Bytes</b></asp:tablecell>
      <asp:tablecell><b>Total Bytes</b></asp:tablecell>
      <asp:tablecell><b>Percentage</b></asp:tablecell>
   </asp:tablerow>
   <asp:tablerow>
      <asp:tablecell runat="server" id="cellProgressID" text="0" />
      <asp:tablecell runat="server" id="cellGraphic">
         <HR align="left" style="color:blue" size="10" width="<%=strPercent%>" />
      </asp:tablecell>
      <asp:tablecell runat="server" id="cellTransferredBytes" />
      <asp:tablecell runat="server" id="cellTotalBytes" />
      <asp:tablecell runat="server" id="cellPercentage" />
   </asp:tablerow>
</asp:table>
</body>
</html>

Step Four: Provide the logic to drive the progress display in the code-behind ProgressIndicator.aspx.[vb|cs] of the Progress Indicator page.

Here you will instantiate the FileUp Progress Indicator object and retrieve the ProgressID from the querystring. Once the ID has been assigned to the Progress Indicator object, the Percentage property is checked. The page will continue to refresh, updating the display graphics until it reaches 100%.

C#
public class ProgressIndicator : System.Web.UI.Page
{
   //--- Declare a string and controls used on the webform
   //--- to display the upload progress
   protected string strPercent = String.Empty;
   protected System.Web.UI.WebControls.TableCell cellProgressID;
   protected System.Web.UI.WebControls.TableCell cellTransferredBytes;
   protected System.Web.UI.WebControls.TableCell cellTotalBytes;
   protected System.Web.UI.WebControls.TableCell cellPercentage;

   protected void Page_Load()
   {
      //--- Each time the page is loaded, update the upload progress
      UpdateProgress();
   }

   private void UpdateProgress()
   {
      //--- Delare an object for the FileUp progress object
      FileUpProgress progress = null;

      try
      {
         //--- Instantiate the FileUpProgress object
         progress = new FileUpProgress();

         //--- Get the Progress ID from the query string
         int intProgressId = Convert.ToInt32(Request.QueryString["progressid"]);

         //--- Important: Assign the progress ID to the object to monitor
         //--- the upload
         progress.ProgressId = intProgressId;

         //--- If the upload isn't complete, continue to refresh the page
         //--- to display the progress
         if(progress.Percentage < 100)
            Page.Response.Write("<meta http-equiv=\"Refresh\" content="1" />");

         //--- Update the progress table below with the current information
         cellProgressID.Text = progress.ProgressId.ToString();
         strPercent = progress.Percentage.ToString("N") + "%";
         cellTransferredBytes.Text = progress.TransferredBytes.ToString();
         cellTotalBytes.Text = progress.TotalBytes.ToString();
         cellPercentage.Text = progress.Percentage.ToString("N");
      }
      catch (Exception ex)
      {
         cellProgressID.Text = "<b>An exception has occurred</b><br>" +
            ex.Message;
      }
      finally
      {
         //--- Always call Dispose in the finally block
         if (progress != null)
      {
         progress.Dispose();
         progress = null;
      }
   }
}
VB.NET
Public Class ProgressIndicator : Inherits System.Web.UI.Page

   '--- Declare a string and controls used on the webform
   '--- to display the upload progress
   Protected strPercent As String = String.Empty
   Protected cellProgressID As System.Web.UI.WebControls.TableCell
   Protected cellTransferredBytes As System.Web.UI.WebControls.TableCell
   Protected cellTotalBytes As System.Web.UI.WebControls.TableCell
   Protected cellPercentage As System.Web.UI.WebControls.TableCell

   Protected Sub Page_Load(sender As Object, e As EventArgs)
      '--- Each time the page is loaded, update the upload progress
      UpdateProgress()
   End Sub

   Private Sub UpdateProgress()

      Dim progress As FileUpProgress
      Try

         '--- Instantiate the FileUpProgress object
         progress = New FileUpProgress()

         '--- Get the Progress ID from the query string
         Dim intProgressId As Integer
         intProgressId = Convert.ToInt32(Request.QueryString("progressid"))

         '--- Important: Assign the progress ID to the object to monitor
         '--- the upload
         progress.ProgressId = intProgressId

         '--- If the upload isn't complete, continue to refresh the page
         '--- to display the progress
         If progress.Percentage < 100 Then
            Page.Response.Write("<meta http-equiv=""Refresh"" content="1" />")
         End If

         '--- Update the progress table below with the current information
         cellProgressID.Text = progress.ProgressId.ToString()
         strPercent = progress.Percentage.ToString("N") + "%"
         cellTransferredBytes.Text = progress.TransferredBytes.ToString()
         cellTotalBytes.Text = progress.TotalBytes.ToString()
         cellPercentage.Text = progress.Percentage.ToString("N")
      Catch ex As System.Exception
         cellProgressID.Text = "<b>An exception has occurred</b><br>" + _
            ex.Message
      Finally
         If Not (progress Is Nothing) Then
            progress.Dispose()
            progress = Nothing
         End If
       End Try
   End Sub

End Class

Top

Copyright © 2010 SoftArtisans, Inc. All rights reserved.

Step Three: Provide a graphical representation of progress with HTML

The FileUp Progress Indicator does not provide it's own GUI. Instead, it provides information on progress indication so that you can develop your own custom represenatation of progress. In this sample, we are using an HTML table and an <hr> element to function as a progress meter.

ProgressIndicator.aspx
<html>
<body>
<h3>Upload Progress:</h3>
<!--
This table holds cells that are used to display
the upload progress for the progress indicator
-->
<asp:Table id="UploadTable"
   GridLines="Both"
   HorizontalAlign="Center"
   Font-Name="Verdana"
   Font-Size="8pt"
   CellPadding="15"
   CellSpacing="0"
   runat="server"<

   <asp:tablerow>
      <asp:tablecell><b>Progress ID</b></asp:tablecell>
      <asp:tablecell width="300"><b>Graphic</b></asp:tablecell>
      <asp:tablecell><b>Transferred Bytes</b></asp:tablecell>
      <asp:tablecell><b>Total Bytes</b></asp:tablecell>
      <asp:tablecell><b>Percentage</b></asp:tablecell>
   </asp:tablerow>
   <asp:tablerow>
      <asp:tablecell runat="server" id="cellProgressID" text="0" />
      <asp:tablecell runat="server" id="cellGraphic">
         <HR align="left" style="color:blue" size="10" width="<%=strPercent%>" />
      </asp:tablecell>
      <asp:tablecell runat="server" id="cellTransferredBytes" />
      <asp:tablecell runat="server" id="cellTotalBytes" />
      <asp:tablecell runat="server" id="cellPercentage" />
   </asp:tablerow>
</asp:table>
</body>
</html>

Step Four: Provide the logic to drive the progress display in the code-behind ProgressIndicator.aspx.[vb|cs] of the Progress Indicator page.

Here you will instantiate the FileUp Progress Indicator object and retrieve the ProgressID from the querystring. Once the ID has been assigned to the Progress Indicator object, the Percentage property is checked. The page will continue to refresh, updating the display graphics until it reaches 100%.

C#
public class ProgressIndicator : System.Web.UI.Page
{
   //--- Declare a string and controls used on the webform
   //--- to display the upload progress
   protected string strPercent = String.Empty;
   protected System.Web.UI.WebControls.TableCell cellProgressID;
   protected System.Web.UI.WebControls.TableCell cellTransferredBytes;
   protected System.Web.UI.WebControls.TableCell cellTotalBytes;
   protected System.Web.UI.WebControls.TableCell cellPercentage;

   protected void Page_Load()
   {
      //--- Each time the page is loaded, update the upload progress
      UpdateProgress();
   }

   private void UpdateProgress()
   {
      //--- Delare an object for the FileUp progress object
      FileUpProgress progress = null;

      try
      {
         //--- Instantiate the FileUpProgress object
         progress = new FileUpProgress();

         //--- Get the Progress ID from the query string
         int intProgressId = Convert.ToInt32(Request.QueryString["progressid"]);

         //--- Important: Assign the progress ID to the object to monitor
         //--- the upload
         progress.ProgressId = intProgressId;

         //--- If the upload isn't complete, continue to refresh the page
         //--- to display the progress
         if(progress.Percentage < 100)
            Page.Response.Write("<meta http-equiv=\"Refresh\" content="1" />");

         //--- Update the progress table below with the current information
         cellProgressID.Text = progress.ProgressId.ToString();
         strPercent = progress.Percentage.ToString("N") + "%";
         cellTransferredBytes.Text = progress.TransferredBytes.ToString();
         cellTotalBytes.Text = progress.TotalBytes.ToString();
         cellPercentage.Text = progress.Percentage.ToString("N");
      }
      catch (Exception ex)
      {
         cellProgressID.Text = "<b>An exception has occurred</b><br>" +
            ex.Message;
      }
      finally
      {
         //--- Always call Dispose in the finally block
         if (progress != null)
      {
         progress.Dispose();
         progress = null;
      }
   }
}
VB.NET
Public Class ProgressIndicator : Inherits System.Web.UI.Page

   '--- Declare a string and controls used on the webform
   '--- to display the upload progress
   Protected strPercent As String = String.Empty
   Protected cellProgressID As System.Web.UI.WebControls.TableCell
   Protected cellTransferredBytes As System.Web.UI.WebControls.TableCell
   Protected cellTotalBytes As System.Web.UI.WebControls.TableCell
   Protected cellPercentage As System.Web.UI.WebControls.TableCell

   Protected Sub Page_Load(sender As Object, e As EventArgs)
      '--- Each time the page is loaded, update the upload progress
      UpdateProgress()
   End Sub

   Private Sub UpdateProgress()

      Dim progress As FileUpProgress
      Try

         '--- Instantiate the FileUpProgress object
         progress = New FileUpProgress()

         '--- Get the Progress ID from the query string
         Dim intProgressId As Integer
         intProgressId = Convert.ToInt32(Request.QueryString("progressid"))

         '--- Important: Assign the progress ID to the object to monitor
         '--- the upload
         progress.ProgressId = intProgressId

         '--- If the upload isn't complete, continue to refresh the page
         '--- to display the progress
         If progress.Percentage < 100 Then
            Page.Response.Write("<meta http-equiv=""Refresh"" content="1" />")
         End If

         '--- Update the progress table below with the current information
         cellProgressID.Text = progress.ProgressId.ToString()
         strPercent = progress.Percentage.ToString("N") + "%"
         cellTransferredBytes.Text = progress.TransferredBytes.ToString()
         cellTotalBytes.Text = progress.TotalBytes.ToString()
         cellPercentage.Text = progress.Percentage.ToString("N")
      Catch ex As System.Exception
         cellProgressID.Text = "<b>An exception has occurred</b><br>" + _
            ex.Message
      Finally
         If Not (progress Is Nothing) Then
            progress.Dispose()
            progress = Nothing
         End If
       End Try
   End Sub

End Class
Step Five: Set up ProgressUpload.uplx.[vb|cs] to synchronize with the progress indicator before parsing the request.

The upload request processing code must first be preceeded by code that synchronizes progress indication by instantiating the Progress Indicator object and passing it the ProgressID for this upload. After this synchronization, the rest of the upload processing code is written as usual.

C#
protected void UploadBtn_Click(object sender, EventArgs e)
{
   //--- Hide the form after the upload button is clicked
   theForm.Visible = false;
   ProcessUpload();
}

//--- Process the upload request
private void ProcessUpload()
{
   //--- Declare an object for FileUp
   FileUp fileUpload = null;

   //--- Decalre an object for the file
   SaFile file = null;

   try
   {
      //--- Instantiate the FileUp object
      fileUpload = new FileUp(Context);

      //--- Get the progress id from the querystring
      int intProgressID = Convert.ToInt32(Request.QueryString["progressid"]);
      fileUpload.ProgressID = intProgressID;

      //--- This StringBuilder will be used to display the results of the upload
      System.Text.StringBuilder results = new System.Text.StringBuilder();

      fileUpload.Path = "C:\\Temp"

      //--- Check to be sure there was a file selected in the form
      //--- If so, continue processing

      //--- Get a reference to the uploaded file field
      file = (SaFile)fileUpload.Form["myFile"];

      if (file != null)
      {
         if (!file.IsEmpty)
         {

            file.Save();

            //--- Display information about the saved file
            results.Append("<h3>FileUp Saved the File Successfully</h3>");
            //--- More results code can be placed here (see full sample)

         }
         else
         {
            //--- If SaFile.IsEmpty is true, the file field was left empty
            results.Append("There was no file submitted in the form field.");
         }
      }
      else
      {
         results.Append("The referenced field does not exist or is not " &
            "of type=\"file\"");
      }

      //--- Display the results on the webform
      ltrUploadResults.Text = results.ToString();
   }
   catch (Exception ex)
   {
      //--- If an exception is caught, display the results
      ltrUploadResults.Text = "<b>An error has occurred:</b><br />" +
         ex.Message;
   }
   finally
   {
      //--- Always call Dispose in the finally block
      if (fileUpload != null)
   {
      fileUpload.Dispose();
      fileUpload = null;
   }
}
VB.NET
Protected Sub UploadBtn_Click(sender As Object, e As EventArgs)

   '--- Hide the form after the upload button is clicked
   theForm.Visible = False
   ProcessUpload()

End Sub

'--- Process the upload request
Private Sub ProcessUpload()

   '--- Declare an object for FileUp
   Dim fileUpload As FileUp

   '--- Declare an object for the file
   Dim file As SaFile

   Try

      '--- Instantiate the FileUp object
      fileUpload = New FileUp(Context)

      '--- Get the progress id from the querystring
      Dim intProgressID As Integer = _
         Convert.ToInt32(Request.QueryString("progressid"))
      fileUpload.ProgressID = intProgressID

      '--- This StringBuilder will be used to display the results of the upload
      Dim results As New System.Text.StringBuilder()

      fileUpload.Path = "C:\temp"

      '--- Check to be sure there was a file selected in the form
      '--- If so, continue processing

      '--- Get a reference to the uploaded file field
      file = CType(fileUpload.Form("myFile"), SaFile)

      If Not (file Is Nothing) Then
         If Not (file.IsEmpty) Then

            file.Save()

            '--- Display information about the saved file
            results.Append("<h3>FileUp Saved the File Successfully</h3>")
            '---- More results code can be placed here (see full sample code)

         Else
            '--- If SaFile.IsEmpty is true, the file field was left empty
            results.Append("There was no file submitted in the form field.")
         End If
      Else
         results.Append("The referenced field does not exist or is not " + _
            "of type=""file""")
      End If

      '--- Display the results on the webform
      ltrUploadResults.Text = results.ToString()

   Catch ex As System.Exception
      '--- If an exception is caught, display the results
      ltrUploadResults.Text = "<b>An error has occurred:</b><br />" + _
         ex.Message
   Finally
      '--- Always call FileUp.Dispose in the finally block
      If Not (fileUpload Is Nothing) Then
         fileUpload.Dispose()
         fileUpload = Nothing
      End If
   End Try

End Sub

Top


Client-Side Installation

If you are testing your application by using your development machine as both the server and the client, the default installation of XFile may not be ideal for reproducing the client-side experience. This is because two sets of deliberately different dlls are provided with XFile, and the set of dlls that are registered on the server may not be the same set of dlls that are ultimately distributed and registered on the client.

Which dlls are registered on my server by default?

In a typical installation of XFile to a Web server, two sets of dlls are copied to the following directory: C:\Program Files\Software Artisans\SA-XFile. One set is wrapped in a cabinet file SAXFile.cab in XFileSE and SAXFileEE.cab in XFileEE) that is signed by SoftArtisans, and the other set is found as a collection of individual dlls in the directory. It is the second set of individual files that is registered on the server. The following table lists the files installed with each XFile editon:

XFileEE | XFileSE | Description
SAXFileEE.cab | SAXFile.cab | Cabinet file containing all XFile's dlls except SAXFShExEE.dll/SAXFShEx.dll.
SAXFileEE.dll | SAXFile.dll | Non-visual file-transfer engine
xfclient.dll | xfclient.dll
SAAXFileEE.dll | SAAXFile.dll | Visual upload and download controls
SAXFShExEE.dll | SAXFShEx.dll | Shell extension (not included in the SoftArtisans signed CAB file
SAArch.dll | SAArch.dll | Archive file creation/extraction component
SAFilMgr.dll | SAFilMgr.dll | File management component

Why are there two different sets of dlls?
  1. In order to use the XFile server-side/ASP code samples, the dlls must be registered on the server. This requires that there exist at least one set of dlls that exist outside of a CAB file.

  2. In order to use the XFile client side/HTML code samples, the dlls must be available in a downloadable CAB file, or distributed and installed by some other method, client-side. Since internet distribution is the most common scenario, a signed CAB file has been provided so that the client-side/HTML code samples can be run immediately.

  3. To discourage malicious use of the CAB file that is signed by SoftArtisans, those dlls have been altered so that XFile will always warn the user before and upload or download, regardless of any browser security settings.

  4. The individual dlls that are not included in the CAB file do not warn the user before uploads and downloads. This allows for completely hidden and silent file transfer. If an application is to be developed with these dlls and distributed via the internet, they will need to be placed in their own CAB file and signed accordingly.
How does this pose special problems when the client and server are the same machine?

Since the XFile installation package already registered dlls on the machine, the browser will not attempt to download a CAB file*. You will not be reproducing the behavior the remote client will be experiencing. This means that the remote client may be receiving different dlls. The difference could be in the version number of the dlls. Likewise, the difference could be between the warning and non-warning dlls, or in rare circumstances of incomplete removal of an evaluation version, the difference could be between expiring and non-expiring versions of XFile. Other problems that could be masked might include an incorrect path to the CAB file or incorrect permissions on the file or it's directory.

The exception to this can occur when the version number is specified. For more information, see Upgrading SoftArtisans XFile.

How does the browser determine when dlls should be downloaded?

The browser will first check the <object> tag's clsid attribute and try to match that value in the registry. If it cannot be found, then it will attempt to download the CAB file from the path provided in the codebase.

<OBJECT classid="CLSID:230C3D02-DA27-11D2-8612-00A0C93EEA3C" id="AXFFile"
    codebase="/SAXFileSamples/saxfile.cab>

<OBJECT classid="CLSID:230C3D02-DA27-11D2-8612-00A0C93EEA3C"

If that clsid can be found in the registry, the associated dll will provide the code that loads into the Web page, instead of the cab file that is referenced in the codebase attribute. Any time the clsid can be found in the registry, the browser will not attempt to download the CAB. The exception to this case can be created when the version of XFile is specified. This is convenient for forcing an upgrade of internet distributed dlls. For more information on this, see Upgrading SoftArtisans XFile.

Solution

There are two ways to prevent confusion when the client and server are the same machine.

  1. If you are planning to distribute XFile to your users using SoftArtisans (or your own) signed CAB file, then manually unregister the XFile dlls from the Web server so that the same machine may be used as a client for testing the client-side experience. For instructions, see Removing SoftArtisans XFile(Note: Do not delete the dlls if you still need them to create your own signed version of the cab file.) This will force the browser to download dlls from the cabinet file specified in the codebase attribute of the <object>tag in the Web page that instantiates XFile.

    It is also important to understand that if the dlls are no longer registered on the Web server, XFile cannot be instantiated server-side using Server.CreateObject for special server-side usage scenarios (server-to-server file transfer, cascading uploads).

  2. Test client-side behavior from a remote client on which XFile was not installed to compare behavior.

With either solution, it is important to understand that once XFile has been downloaded to the browser, those dlls will be registered on the client-machine via Internet Explorer. For repeated testing of the download process on the same client, it will be necessary to remove XFile from the client each time. For instructions on removing these files from Internet Explorer see Removing SoftArtisans XFile.


Disabling SoftArtisans FileUp Features

SoftArtisans FileUpallows an ISP or sophisticated web administrator to disable specific FileUpfeatures via the registry.

There are several registry settings that can be used to disable certain features. By default, all features are enabled. Setting a value to '1' in the registry will disable that particular feature.

  • In HKEY_LOCAL_MACHINE\SOFTWARE\Software Artisans\SA-FileManager\Parameters
    • DisableACL disables all ACL modifications.
    • DisableLogonUser disables the LogonUser method.
    • DisableRegisterDLL disables registration of DLLs.
    • DisableDelete disables the FileManager.DeleteFile, File.Delete, and FileUp.Delete methods, preventing file deletion. It is still possible to use the FileUp.Delete method without any parameters to delete the currently uploaded file. This registry entry prevents deletion of any arbitrary file from the file system.

  • In HKEY_LOCAL_MACHINE\SOFTWARE\Software Artisans\FileUp\Parameters
    • DisableTransferFile disables the TransferFile / File Download function.
    • OnlyAllowVirtual allows only the SaveInVirtual method. Disables .Save and .SaveAs.


Delete Method

Object: SoftArtisans.FileUp
Syntax: Delete([in,optional] Filename As String)
Description:

This method deletes a file from the web server's hard disk.

If you specify a Filename, it must contain the entire valid path.

If you do not specify a Filename, the current uploaded file is deleted. This allows you to effectively cancel an upload. If there is more than one file being uploaded in a single page, only the first one is deleted.

To delete multiple files in a single upload, there is an equivalent method for each file object, i.e., fileUpload.Form("File1").Delete. Please see SAFile.Delete().

Examples:
ASP <%
fileUpload.Delete Server.MapPath("Uploads\UploadedFile.txt")
%>
C# | fileUpload.Delete(Server.MapPath("Uploads\\UploadedFile.txt"));
VB.NET | fileUpload.Delete(Server.MapPath("Uploads\UploadedFile.txt"))

ASP <%
fileUpload.SaveAs strFileName
If Err = 0 Then
Response.Write("Upload saved successfully to " &_
fileUpload.ServerName & "<br />")

'--- Perform some other processing here,
'--- such as writing to a database.
'--- Assume some error occurred
'--- delete the uploaded file.
fileUpload.Delete

If Err <> 0 Then
Response.Write("An error occurred when attempting " & _
to delete the uploaded file.<br />")
Else
Response.Write("Uploaded file has been deleted.<br />")
End If

End If
%>
C# fileUpload.SaveAs(strFileName);
results.Append("Upload saved successfully to " +
fileUpload.ServerName & "<br />");

//--- Perform some other processing here,
//--- such as writing to a database.

try
{
//--- Assume some error occurred
//--- delete the uploaded file.
fileUpload.Delete();
Results.Append("Uploaded file has been deleted.<br />");
}
catch (Exception e)
{
Results.Append("An error occurred when attempting " +
"to delete the uploaded file.<br />");
}
VB.NET fileUpload.SaveAs(strFileName)
results.Append("Upload saved successfully to " + _
fileUpload.ServerName & "<br />")

'--- Perform some other processing here,
'--- such as writing to a database.

Try
//--- Assume some error occurred
//--- delete the uploaded file.
fileUpload.Delete()
Results.Append("Uploaded file has been deleted.<br />")
Catch (Exception e)
Results.Append("An error occurred when attempting " + _
"to delete the uploaded file.<br />")
End Try


Items Collection

The Items Collection object is the container for all of the Progress Items currently executing. Progress Items for any transfers not yet started or already completed will not be part of the collection.

Note: This collection is not available in ASP.NET.

The Items Collection contains the following properties:

Count

Item


Count Property

Object: SoftArtisans.FileUpProgress Items Collection
Syntax: Count
Type: Long
Read/Write: Read Only
Description:

Returns the number of FileUpProgress Items in the collection.

Note: This property is not available in ASP.NET.
Examples:
ASP | <% Response.Write("There are currently " & progress.Items.Count & " progress items.") %>
ASP.NET | N/A


Percentage Property

Object: SoftArtisans.FileUpProgress Item
Syntax: Percentage
Type: Decimal
Read/Write: Read Only
Description:

This property returns what percentage of the transfer is complete. This is determined by the following formula:

TransferredBytes = ---------------- * 100 Total
Note: This property is not available in ASP.NET.
Examples:
ASP <% Set inProgressUpload = progress.Items(1)
Response.Write("Percentage complete of upload: " & _
inProgressUpload.Percentage) %>
ASP.NET N/A


ProgressID Property

Object: SoftArtisans.FileUpProgress Item
Syntax: ProgressID
Type: Integer
Read/Write: Read/Write
Description:

This property sets or gets the ID of the current upload. This lets you track the progress of the current upload.

To view the progress of a specific upload, you must assign a ProgressID to it. Then create a SoftArtisans.FileUpProgress object and use the same ProgressID. The FileUpProgress object has properties that update in real-time to reflect the current and total bytes to be uploaded.

To get the next unused ProgressID, use the NextProgressID method .

The ID must be between 1 and 500. The ID is guaranteed to be unique at any one time, but it is not guaranteed to be unique for the duration of IIS's execution.

SoftArtisans assumes that Web servers will not use more than 500 simultaneous uploads. Since ASP has a fixed maximum number of concurrent pages that can be executed (25 in Windows 2000, 10 in IIS 4), even an 8-processor machine would handle a maximum of 200 uploads if all processors were totally dedicated to uploads. The maximum of 500 is easily changed, so if you have higher volume than this, please contact us .

Note: This property is not available in ASP.NET.
Examples:
ASP <% Set inProgressUpload = progress.Items(1)
Response.Write("Progress ID of upload: " & _
inProgressUpload.ProgressID) %>
ASP.NET N/A


TotalBytes Property

Object: SoftArtisans.FileUpProgress Item
Syntax: TotalBytes
Type: Integer
Read/Write: Read Only
Description:

This property returns the total number of bytes to be transferred for this ProgressID.

Note: This property is not available in ASP.NET.
Examples:
ASP <% Set inProgressUpload = progress.Items(1)
Response.Write("Total Bytes of upload: " & _
inProgressUpload.TotalBytes) %>
ASP.NET N/A


TransferredBytes Property

Object: SoftArtisans.FileUpProgress Item
Syntax: TransferredBytes
Type: Integer
Read/Write: Read Only
Description:

This property returns the number of bytes that have been received by the server.

Note: This property is not available in ASP.NET.
Examples:
ASP <% Set inProgressUpload = progress.Items(1)
Response.Write("Transferred Bytes of upload: " & _
inProgressUpload.TransferredBytes) %>
ASP.NET N/A


FileUpProgress Object

The SoftArtisans.FileUpProgress object contains various methods and properties that let you monitor the progress of the upload.

It also contains the Items object that returns a collection of Progress Items.

Instantiating the Progress Object:

ASP Set prg = Server.CreateObject("SoftArtisans.FileUpProgress")
C# FileUpProgress progress = null;

try
{
//--- Instantiate the FileUpProgress object
progress = new FileUpProgress();
...
}
catch
{
...
}
finally
{
//--- Always call Dispose in the finally block
if (progress != null)
{
progress.Dispose();
progress = null;
}
}
VB.NET Dim progress As FileUpProgress

Try
'--- Instantiate the FileUpProgress object
progress = New FileUpProgress()
...
Catch
...
Finally
'--- Always call Dispose in the finally block
If Not (progress Is Nothing) Then
progress.Dispose()
progress = Nothing
End If
End Try

After that, all methods and properties are available to you.

Methods

Properties


FileUpProgress Items Collection

Object: FileUpProgress Items Collection
Syntax: Item
Type: ProgressItem
Read/Write: Read Only
Description:

Returns a single ProgressItem object in a FileUpProgress Items collection.

Note: This collection is not available in ASP.NET.

The ProgressItem object has four properties:

Percentage

ProgressID

TotalBytes

TransferredBytes

Examples:
ASP | <% Set inProgressUpload = progress.Items(1) %>
ASP.NET | N/A


FileUpProgress Methods

This section contains the methods implemented by the FileUpProgress object.

NextProgressID Method


NextProgressID Property

Object: SoftArtisans.FileUpProgress
Syntax: NextProgressID
Description:

This method returns the next unused ProgressID. See the ProgressID property for more information.

Examples:

Loop through the form elements using the item indexer:

ASP <%
fileUpload.ProgressID = fileUpload.NextProgressID
%>
C# | fileUpload.ProgressID = fileUpload.NextProgressID();
VB.NET | fileUpload.ProgressID = fileUpload.NextProgressID()

Because progress indication requires the coordination of several scripts, please see the appropriate Programmer's Guide for a complete sample the demonstrates the use of the FileUp ProgressID property.

  • Programmer's Guide for ASP: Adding a Server-Side Progress Indicator
  • Programmer's Guide for ASP.NET: Adding a Server-Side Progress Indicator


Percentage Property

Object: SoftArtisans.FileUpProgress
Syntax: Percentage
Type: Decimal
Read/Write: Read Only
Description:

This property returns what percentage of the transfer is complete. This is determined by the following formula:

TransferredBytes = ---------------- * 100 Total
Examples:
ASP <%
intPercentComplete = progress.Percentage
%>
C# | string strPercent = progress.Percentage.ToString("N") + "%";
VB.NET | Dim strPercent As String = progress.Percentage.ToString("N") + "%"

Because progress indication requires the coordination of several scripts, please see the appropriate Programmer's Guide for a complete sample the demonstrates the use of the FileUp ProgressID property.

  • Programmer's Guide for ASP Adding a Server-Side Progress Indicator
  • Programmer's Guide for ASP.NET: Adding a Server-Side Progress Indicator


ProgressID Property

Object: SoftArtisans.FileUpProgress
Syntax: ProgressID
Type: Integer
Read/Write: Read/Write
Description:

This property sets or gets the ID of the current upload. This lets you track the progress of the current upload.

To view the progress of a specific upload, you must assign a ProgressID to it. Then create a SoftArtisans.FileUpProgress object and use the same ProgressID. The FileUpProgress object has properties that update in real-time to reflect the current and total bytes to be uploaded.

Pass the ProgressID from page to page in the query string or in a cookie. You cannot pass the ProgressID as a form value. The example in Adding a Server-Side Progress Indicator demonstrates passing the ProgressID in the query string.

To get the next unused ProgressID, use the NextProgressID method .

The ID must be between 1 and 500. The ID is guaranteed to be unique at any one time, but it is not guaranteed to be unique for the duration of IIS's execution.

SoftArtisans assumes that Web servers will not use more than 500 simultaneous uploads. Since ASP has a fixed maximum number of concurrent pages that can be executed (25 in Windows 2000, 10 in IIS 4), even an 8-processor machine would handle a maximum of 200 uploads if all processors were totally dedicated to uploads. The maximum of 500 is easily changed, so if you have higher volume than this, please contact us .

Examples:
ASP <%
fileUpload.ProgressID = CInt(Request.QueryString("progressid"))
%>
C# fileUpload.ProgressID = (int)Request.QueryString["progressid"];
VB.NET fileUpload.ProgressID = _
CType(Request.QueryString("progressid"), Integer)

Because progress indication requires the coordination of several scripts, please see the appropriate Programmer's Guide for a complete sample the demonstrates the use of the FileUp ProgressID property.

  • Programmer's Guide for ASP Adding a Server-Side Progress Indicator
  • Programmer's Guide for ASP.NET: Adding a Server-Side Progress Indicator


Progress Object Properties

This section contains the properties implemented by the Progress object.

Items Property

Percentage Property

ProgressID Property

TotalBytes Property

TransferComplete Property

TransferredBytes Property


TotalBytes Property

Object: SoftArtisans.FileUpProgress
Syntax: TotalBytes
Type: Integer
Read/Write: Read Only
Description:

This property returns the total number of bytes to be transferred for this ProgressID.
Examples:
ASP <%
intTotalBytes = progress.TotalBytes
%>
C# | cellTotalBytes.Text = progress.TotalBytes.ToString();
VB.NET | cellTotalBytes.Text = progress.TotalBytes.ToString()

Because progress indication requires the coordination of several scripts, please see the appropriate Programmer's Guide for a complete sample the demonstrates the use of the FileUp ProgressID property.

  • Programmer's Guide for ASP Adding a Server-Side Progress Indicator
  • Programmer's Guide for ASP.NET: Adding a Server-Side Progress Indicator


TransferComplete Property

Object: SoftArtisans.FileUpProgress
Syntax: TransferComplete
Type: Boolean
Read/Write: Read Only
Description:

This property returns True when the transfer of the current ProgressID is complete.
Examples:
ASP <%
If (Progress.TransferComplete = True) Then
Response.Write("File uploaded successfully!")
End If
%>
C# if (Progress.TransferComplete = true)
{
results.Append("File uploaded successfully!");
}
VB.NET If (Progress.TransferComplete = True) Then
results.Append("File uploaded successfully!")
End If

Because progress indication requires the coordination of several scripts, please see the appropriate Programmer's Guide for a complete sample the demonstrates the use of the FileUp ProgressID property.

  • Programmer's Guide for ASP Adding a Server-Side Progress Indicator
  • Programmer's Guide for ASP.NET: Adding a Server-Side Progress Indicator

Example

Because progress indication requires the coordination of several scripts, please see the appropriate Programmer's Guide for a complete sample the demonstrates the use of the FileUp ProgressID property.

  • Programmer's Guide for ASP Adding a Server-Side Progress Indicator
  • Programmer's Guide for ASP.NET: Adding a Server-Side Progress Indicator


TransferredBytes Property

Object: SoftArtisans.FileUpProgress
Syntax: TransferredBytes
Type: Integer
Read/Write: Read Only
Description:

This property returns the number of bytes that have been received by the server.
Examples:
ASP <%
intBytesTransferred = progress.TransferredBytes
%>
C# | cellTransferredBytes.Text = progress.TransferredBytes.ToString();
VB.NET | cellTransferredBytes.Text = progress.TransferredBytes.ToString()

Because progress indication requires the coordination of several scripts, please see the appropriate Programmer's Guide for a complete sample the demonstrates the use of the FileUp ProgressID property.

  • Programmer's Guide for ASP Adding a Server-Side Progress Indicator
  • Programmer's Guide for ASP.NET: Adding a Server-Side Progress Indicator


The SMTP Mailer Object

SMTP Mailer is SMTPmail's principal object.

SMTP Mailer Methods

SMTP Mailer Properties


AddAttachment Method

Object: | SMTP Mailer
Syntax: | <OBJECT>.AddAttachment ([in] <Filename as String>)
Description: | This method adds attachments to current message. Filename indicates the file you are attaching. Filename must be an explicit path.

Example:

<% Set mailer = Server.CreateObject("SoftArtisans.SMTPMail") ... '--- This
        method adds attachments to current message. mailer.AddAttachment "c:\file.ext" ...
        %>


AddBCC Method

Object: | SMTP Mailer
Syntax: | <OBJECT>.AddBCC([in] <Name as String>, <E-mail as String>)
Returns: | True/False
Description: | This method adds a recipient to the Blind Carbon Copy (BCC) list.

Example:

<% Set mailer = Server.CreateObject("SoftArtisans.SMTPMail") ... '--- Add the
        recipient to the BCC: list of the email. '--- You can add as many people as necessary
        mailer.AddBCC "Joe Smith", "joesmith@unknown.com" ... %>


AddCC Method

Object: | SMTP Mailer
Syntax: | <OBJECT>.AddCC ([in] <Name as String>, <E-mail as String>)
Returns: | True/False
Description: | This method adds a new recipient to the CC: list of a message. It returns True if the address is syntactically valid, False if it is not.

Example:

<% Set mailer = Server.CreateObject("SoftArtisans.SMTPMail") ... '--- Add the
        recipient to the CC: list of the email. '--- You can add as many people as necessary
        mailer.AddCC "Joe Smith", "joesmith@unknown.com" ... %>


AddExtraHeader Method

Object: | SMTP Mailer
Syntax: | <OBJECT>.AddExtraHeader ([in] <X-Header as String>)
Returns: | True/False
Description: | This method adds extra X-Headers to the message's mail envelope. The X-Header value is a string that represents a proper SMTP X-Header. This method returns True is the X-Header is added, False if it is not.

Example:

<% Set mailer = Server.CreateObject("SoftArtisans.SMTPMail") ... '--- This
        method adds extra X-Headers to the message's mail envelope mailer.AddExtraHeader
        "x-mycompany: specialinstruction" ... %>


AddRecipient Method

Object: | SMTP Mailer
Syntax: | <OBJECT>.AddRecipient ([in] <Name as String>, <E-mail as String>)
Returns: | True/False
Description: | This method adds another recipient to the To: list of the message. It returns True if the recipient is a valid address, False if it is not.

Example:

<% Set mailer = Server.CreateObject("SoftArtisans.SMTPMail") ... '--- Add the
        recipient who will receive the email. '--- You can add as many people as necessary
        mailer.AddRecipient "Joe Smith", "joesmith@unknown.com" ... %>


BodyText Property

Object: | SMTP Mailer
Syntax: | <OBJECT>.BodyText = <value>
Type: | String
Read/Write: | Read/Write
Description: | This property contains the body text of a message.

Example:

<% Set mailer = Server.CreateObject("SoftArtisans.SMTPMail") ... '--- Set the
        body text of the e-mail message. mailer.BodyText = "Put your message here" &
        vbCRLF ... %>


CharSet Property

Object: | SMTP Mailer
Syntax: | <OBJECT>.CharSet = <value>
Type: | Integer
Read/Write: | Read/Write
Description: | This property indicates the character set. It returns 1 if the character set is US-ASCII (default), or 2 if the character set is ISO-8859-1.

Example:

<% Set mailer = Server.CreateObject("SoftArtisans.SMTPMail") ... '--- This
        property sets the character set. '--- 1 = US-ASCII '--- 2 = ISO-8859-1 mailer.CharSet
        = 2 ... %>


ClearAllRecipients Method

Object: | SMTP Mailer
Syntax: | <OBJECT>.ClearAllRecipients ()
Description: | This method clears all recipients from all lists (To:, CC:, and BCC:).

Example:

<% Set mailer = Server.CreateObject("SoftArtisans.SMTPMail") ... '--- Remove
        all recipients from e-mail '--- includes TO, CC and BCC recipients. mailer.ClearAllRecipients
        ...


ClearAttachments Method

Object: | SMTP Mailer
Syntax: | <OBJECT>.ClearAttachments ()
Description: | This method removes any attachments to the current message.

Example:

<% Set mailer = Server.CreateObject("SoftArtisans.SMTPMail") ... '--- Remove
        all attachments from e-mail mailer.ClearAttachments ... %>


ClearBCCs Method

Object: | SMTP Mailer
Syntax: | <OBJECT>.ClearBCCs ()
Description: | This method removes any recipients from the Blind Carbon Copy (BCC) list.

Example:

<% Set mailer = Server.CreateObject("SoftArtisans.SMTPMail") ... '--- Remove
        all BCC recipients from e-mail mailer.ClearBCCs ... %>


ClearBodyText Method

Object: | SMTP Mailer
Syntax: | <OBJECT>.ClearBodyText ()
Description: | This method removes any body text assigned to the message that may have been set by the BodyText property.

Example:

<% Set mailer = Server.CreateObject("SoftArtisans.SMTPMail") ... '--- Remove
        body text from e-mail mailer.ClearBodyText ... %>


ClearCCs Method

Object: | SMTP Mailer
Syntax: | <OBJECT>.ClearCCs ()
Description: | This method removes any recipients from the message's CC: list.

Example:

<% Set mailer = Server.CreateObject("SoftArtisans.SMTPMail") ... '--- Remove
        all CC recipients from e-mail mailer.ClearCCs ... %>


ClearExtraHeaders Method

Object: | SMTP Mailer
Syntax: | <OBJECT>.ClearExtraHeaders ()
Description: | This method removes any X-Headers that were set by the AddExtraHeader method .

Example:

<% Set mailer = Server.CreateObject("SoftArtisans.SMTPMail") ... '--- Remove
        X-Headers from e-mail mailer.ClearExtraHeaders ... %>


ClearRecipients Method

Object: | SMTP Mailer
Syntax: | <OBJECT>.ClearRecipients ()
Description: | This method removes any recipients currently in a message's To: list.

Example:

<% Set mailer = Server.CreateObject("SoftArtisans.SMTPMail") ... '--- Remove
        all TO recipients from e-mail mailer.ClearRecipients ... %>


CodePage Property

Object: SMTP Mailer
Syntax: <OBJECT>.CodePage [=Language Code as Long]
Type: Long
Read/Write: Read/Write
Description:

Set CodePage if an email's BodyText and/or HTMLText contains Unicode values (such as, non-English characters). The value of Codepage will be use to convert Unicode values to CharSet bytes. Use this property in conjunction with CustomCharSet.

For a complete list of Codepage values, see Microsoft's Character Set Recognition Reference.

* The CodePage property is not available in SMTPMailFree.

Example:
<% Set Mailer = Server.CreateObject("SoftArtisans.SMTPMail") '--- CodePage
            for Arabic (Windows) Mailer.CodePage = 1256 '--- CharSet for Arabic (Windows) Mailer.CustomCharSet
            = windows-1256 ... %>


ConfirmRead Property

Object: | SMTP Mailer
Syntax: | <OBJECT>.ConfirmRead = <value>
Type: | Boolean
Read/Write: | Read/Write
Description: | This property sets a confirmation read flag. It only works if the recipient's e-mail program supports confirmation. If set to True, the recipient's e-mail program sends a notice confirming that the e-mail has been read.

Example:

<% Set mailer = Server.CreateObject("SoftArtisans.SMTPMail") ... '--- This
        property only works if the recipient's e-mail program supports confirmation. mailer.ConfirmRead
        = true ... %>


ContentTransferEncoding Property

Object: SMTP Mailer
Syntax: <OBJECT>.ContentTransferEncoding = <value>
Type: Integer
Read/Write: Read/Write
Description: The ContentTransferEncoding property allows you to set standard contents encoding. The default value for this property is 7-bit.

Many Content-Types which could usefully be transported via email are represented, in their "natural" format, as 8-bit character or binary data. Such data cannot be transmitted over some transport protocols. For example, RFC 821 restricts mail messages to 7-bit US-ASCII data with lines no longer than 1000 characters.

It is necessary, therefore, to define a standard mechanism for re- encoding such data into a 7-bit short-line format. Such encodings are indicated by the "Content-Transfer-Encoding" header field. The Content-Transfer-Encoding field is used to indicate the type of transformation that has been used in order to represent the body in an acceptable manner for transport.

Note: SMTPmail's ContentTransferEncoding property should be set after setting the CharSet property or the CustomCharSet property. By default, CharSet is US-ASCII, ContentTransferEncoding is 7bit. All other settings (of CharSet and CustomCharSet) are quote-printable, so put the ContentTransferEncoding customization after setting these properties.

This feature is based on the "MIME (Multipurpose Internet Mail Extensions) Part One: Mechanisms for Specifying and Describing the Format of Internet Message Bodies" protocol in RFC1521.

Example:

<% Set mailer = Server.CreateObject("SoftArtisans.SMTPMail") ... '--- Set CharSet
        to ISO=9959-1 '------------------------------------ '--- 1 = US ASCII '--- 2 = ISO-9959-1
        '------------------------------------ mailer.charset = 2 '--- '--- Set the CustomCharSet
        to Polish (ISO-8859-2) mailer.CustomCharSet = "ISO-8859-2" '--- '--- Set ContentTransferEncoding
        to 8bit '------------------------------------ '--- 1 = 7bit '--- 2 = quote-printable
        '--- 3 = base64 '--- 4 = 8bit '------------------------------------ mailer.ContentTransferEncoding
        = 4 ... %>


ContentType Property

Object: | SMTP Mailer
Syntax: | <OBJECT>.ContentType = <value>
Type: | String
Read/Write: | Read/Write
Description: | This property lets you set the ContentType header of a message's BodyText. This property is ignored if the message contains file attachments.

Example:

<% Set mailer = Server.CreateObject("SoftArtisans.SMTPMail") ... '--- Set the
        ContentType header of a message's BodyText. mailer.ContentType = "text/html" ...
        %>


CustomCharSet Property

Object: | SMTP Mailer
Syntax: | <OBJECT>.CustomCharSet = <value>
Type: | String
Read/Write: | Read/Write
Description: | This property lets you use a character set other than the types you can set using the CharSet property. For a complete list of CustomCharSet values, see Microsoft's Character Set Recognition Reference . See also, CodePage.

Example:

<% Set mailer = Server.CreateObject("SoftArtisans.SMTPMail") ... '--- Set if
        you use a character set other than US-ASCII or ISO-8859-1. '--- "Big5" is the Chinese
        Traditional character set mailer.CustomCharSet = "big5" ... %>


DateTime Property

Object: | SMTP Mailer
Syntax: | <OBJECT>.DateTime = <value>
Type: | Date/Time String
Read/Write: | Read/Write
Description: | This property lets you override the default date/time header created by SMTPmail. You must provide a valid date/time string.

Example:

<% Set mailer = Server.CreateObject("SoftArtisans.SMTPMail") ... '--- Used
        to override the default date/time header mailer.DateTime = "Wed, 01 August 2001
        10:53:49 -0500" ... %>


EncodeHeader Method

Object: | SMTP Mailer
Syntax: | <OBJECT>.EncodeHeader ([in] <value>)
Returns: | String
Description: | This method encodes a string in RFC1522 format to provide support for 8-bit mail headers. The encoded strValue is returned as a string.

Example:

<% Set mailer = Server.CreateObject("SoftArtisans.SMTPMail") ... '--- The Encodeheader
        method encodes a string in RFC1522 format to provide support for 8-bit mail headers.
        mailer.Subject = mailer.EncodeHeader("££££££££££££") ... %>


Encoding Property

Object: | SMTP Mailer
Syntax: | <OBJECT>.Encoding = <value>
Type: | Integer
Read/Write: | Read/Write
Description: | This property indicates the encoding type for any attachments. Value can be 1 for UUEncoded or 2 for MIME. The default is MIME.

Example:

<% Set mailer = Server.CreateObject("SoftArtisans.SMTPMail") ... '--- Sets
        encoding type for any attachments. '--- Value can be 1 for UUEncoded or 2 for MIME
        (default). mailer.Encoding = 1 ... %>


Expires Property

Object: | SMTP Mailer
Syntax: | <OBJECT>.Expires
Type: | Date
Read/Write: | Read Only
Description: | This property returns the date that an eval version component stops functioning. This property is only valid if the component is an eval version. Since SoftArtisans SMTPmailFREE is a free component, there will never be an expiring date.

Example:

<% Set mailer = Server.CreateObject("SoftArtisans.SMTPMail") ... '--- Get and
        print the internal expiration date of SMTPMail Response.Write "This evaluation of
        SoftArtisans SMTPMail expires on: " & Mailer.Expires ... %>


FromAddress Property

Object: SMTP Mailer
Syntax: SMTPMailer.FromAddress = email address
Type: String
Read/Write: Read/Write
Description:

FromAddress specifies the e-mail address from which the message was generated. FromAddress is a required field.

If you do not set MailFromAddress, the value of FromAddress will be assigned both to the MAIL FROM field and to subsequent headers.

The value of the optional property MailFromAddress will only be used in the MAIL FROM field. The value of FromAddress will always be used in subsequent headers.

Example:

<% Set mailer = Server.CreateObject("SoftArtisans.SMTPMail") ... '--- Set Properties
        for The name of the sender (FromName) and their email address (FromAddress) Mailer.FromName
        = "Joe Smith" Mailer.FromAddress = "JSmith@unknown.com" ... %>


FromName Property

Object: | SMTP Mailer
Syntax: | <OBJECT>.FromName = <value>
Type: | String
Read/Write: | Read/Write
Description: | This property indicates the name of the person who generated the message.

Example:

<% Set mailer = Server.CreateObject("SoftArtisans.SMTPMail") ... '--- Set Properties
        for The name of the sender (FromName) and their email address (FromAddress) Mailer.FromName
        = "Joe Smith" Mailer.FromAddress = "JSmith@unknown.com" ... %>


GetBodyTextFromFile Method

Object: SMTP Mailer
Syntax:
<OBJECT>.GetBodyTextFromFile ([in] Filename as String, [EraseFile as Boolean],
            [ShowWindow as Boolean])
Description:

GetBodyTextFromFile loads a mail message's body text from a file. Optionally, GetBodyTextFromFile can invoke PGP to encryt the file content.

To invoke the PGP executable:

  1. Set the PGPPath property.
  2. Set the PGPParams property.
  3. Assign a value to GetBodyTextFromFile's EraseFile parameter. Set the parameter to True to erase the file after its content is loaded.
  4. Assign a value to GetBodyTextFromFile's ShowWindow parameter. When ShowWindow is set to True, the PGP process window will open. This is useful for debugging. ShowWindow should be set to False in a production environment.
Note: The two optional parameters EraseFile and ShowWindow work only in a PGP context. You cannot use EraseFile to delete a file if you do not invoke the PGP executable. When GetBodyTextFromFile is used without PGP, it is equivalent to GetPlainTextFromFile.

Example:
<% Set mailer = Server.CreateObject("SoftArtisans.SMTPMail") ... '--- Set the
            path of the PGP executable mailer.PGPPath = "E:\Program Files\Network Associates\PGPcmdln\PGP.exe"
            ... '--- Set the parameters PGP will use to encrypt the file. The '--- following
            signs msg.txt with someone@host.com's private key. mailer.PGPParams = "-s -a ""c:\email\msg.txt""
            -u _ ""<someone@host.com>"" -z ""passwordkey""" ... '--- Invoke the PGP executable
            to encrypt the file, load the '--- file into the email's body text, and erase the
            file after '--- its content is loaded. Do not open the PGP executable '--- window.
            mailer.GetBodyTextFromFile "c:\email\msg.asc", True, False ... %>


GetHtmlTextFromFile Method

Object: | SMTP Mailer
Syntax: | <OBJECT>.GetHtmlTextFromFile ([in] <Filename as String>)
Description: | This method loads the message's HTML-formatted body text from a file. GetHtmlTextFromFile takes HTML-formatted text from any type of text file, including (but not limited to) .doc, .htm and .txt. Please refer to the documentation for the CharSetand CustomCharSet properties if the text in the file does not use the standard US English character set.

Example:

<% Set mailer = Server.CreateObject("SoftArtisans.SMTPMail") ... '--- '---
        Load HTML-formatted body text into e-mail from file. mailer.GetHtmlTextFromFile
        "c:\email\bodytext.htm" ... %>


GetPlainTextFromFile Method

Object: | SMTP Mailer
Syntax: | <OBJECT>.GetPlainTextFromFile ([in] <Filename as String>)
Description: | This method loads the message's Plain-formatted body text from a file. GetPlainTextFromFile takes Plain-formatted text from any type of text file, including (but not limited to) .doc, .htm and .txt. Please refer to the documentation for the CharSetand CustomCharSet properties if the text in the file does not use the standard US English character set.

Example:

<% Set mailer = Server.CreateObject("SoftArtisans.SMTPMail") ... '--- '---
        Load Plain-formatted body text into e-mail from file. mailer.GetPlainTextFromFile
        "c:\email\bodytext.txt" ... %>


GetTempPath Method

Object: | SMTP Mailer
Syntax: | <OBJECT>.GetTempPath()
Returns: | String
Description: | This method returns the path for temporary mail files set by the operating system.

Example:

<% Set mailer = Server.CreateObject("SoftArtisans.SMTPMail") ... '--- This
        method returns the path for temporary mail files set by the operating system Response.Write
        "<BR> " & mailer.GetTempPath ... %>


HtmlText Property

Object: | SMTP Mailer
Syntax: | <OBJECT>.HtmlText = <value>
Type: | String
Read/Write: | Read/Write
Description: | The HtmlText property can be used instead of or in addition to the BodyText property to pass HTML-formatted text into the body of an e-mail.

Example:

<% Set mailer = Server.CreateObject("SoftArtisans.SMTPMail") ... '--- '---
        Set the HTML text that will be passed into the body of the e-mail. mailer.HTMLText
        ="Regarding <B> Order Number: </B> <I> 245 </I>" ... %>


IgnoreMalformedAddress Property

Object: | SMTP Mailer
Syntax: | <OBJECT>.IgnoreMalformedAddress = <value>
Type: | Boolean
Read/Write: | Read/Write
Description: | This property indicates whether SMTPmail will check for an @ sign in the email addresses used in the AddRecipient, AddCC, and AddBCC methods. Any errors are returned in the Response property. By default, this property is set to False. When sent to True, SMTPmail does not validate address syntax.

Example:

<% Set mailer = Server.CreateObject("SoftArtisans.SMTPMail") ... '--- Turn
        IgnoreMalformedAddress property ON '--- SMTPmail will not validate address syntax.
        mailer.IgnoreMalformedAddress = True ... %>


IgnoreRecipientErrors Property

Object: | SMTP Mailer
Syntax: | <OBJECT>.IgnoreRecipientErrors = <value>
Type: | Boolean
Read/Write: | Read/Write
Description: | This property indicates whether SoftArtisans SMTPmail will ignore error messages from the SMTP server generated by invalid addresses. Default is True.

Example:

<% Set mailer = Server.CreateObject("SoftArtisans.SMTPMail") ... '--- Turn
        IgnoreRecipientErrors OFF. '--- SMTPmail will return errors generated by invalid
        addresses. mailer.IgnoreRecipientErrors = False ... %>


Live Property

Object: | SMTP Mailer
Syntax: | <OBJECT>.Live = <value>
Type: | Boolean
Read/Write: | Read/Write
Description: | This property lets you test that SoftArtisans SMTPmail works, without actually having an SMTP server. By default, this property is set to True, in which case messages are sent to the recipients. If you set Live to False, only a NET SEND (alert) message will be sent to the specified user. No e-mail will be sent. The message receiver will be determined by the FromName property and the message will only contain the result of the Subject property; the message body will not be sent. This is useful for testing without an SMTP server.

Example:

<% Set mailer = Server.CreateObject("SoftArtisans.SMTPMail") ... '--- This
        property lets you test that SoftArtisans SMTPMail works, without '--- actually having
        an SMTP server. mailer.Live = false ... %>


LoggingLevel Property *

*This property is not available in SMTPMailFree.

Object: SMTP Mailer
Syntax: <OBJECT>.LoggingLevel = <value>
Type: Long
Read/Write: Read/Write
Description: LoggingLevel is available in SMTPMail 2.3 and later versions. LoggingLevel works only on Windows NT and Windows 2000.

Use LoggingLevel in conjunction with the SMTPLogproperty. SMTPLog sets the location of a log file that records information about sent messages. LoggingLevel sets the type of log file that SMTPMail will create.

When LoggingLevel is set to 1 or 2 a new log file is created per day, by default. This log creation interval value is set by the registry key NewLogFileInterval. The value of NewLogFileInterval is a number of days (default value: 1). To change the value of this key:
  1. From the Start menu, select Run.
  2. Enter regedit and click Ok.
  3. Open HKEY_LOCAL_MACHINE\SOFTWARE\Software Artisans\SMTPMail\Parameters.
  4. Right-click NewLogFileInterval and select Modify.
  5. In the Value Data field enter a number of days.

LoggingLevel Values
0

(Default value) 		Backward compatible with the SMTPLog property in versions earlier than 2.3. Level 0 logs detailed debug information. The log file is not cumulative; it records information about a single sent message.
1 Cumulative history of messages sent. For each sent message, level 1 logs:
  • Start_Date_Time
  • Remote_Host
  • From
  • To
  • SMTP_Status
  • Overall_Status
  • End_Date_Time
Note: A cumulative log file may contain both level 1 and level 2 records.
2 Cumulative history of messages sent. Contains complete message data. For each sent message, level 2 logs:
  • Start_Date_Time
  • Remote_Host
  • From
  • To
  • SMTP_Status
  • Message_Data
  • Overall_Status
  • End_Date_Time
Note: A cumulative log file may contain both level 1 and level 2 records.
SMTP_Status:

SMTP_Status codes include:

211 | System status, or system help reply | 500 | Syntax error, command unrecognized (This may include errors such as command line too long)
214 | Help message (Information on how to use the receiver or the meaning of a particular non-standard command) | 501 | Syntax error in parameters or arguments
220 | Service ready | 502 | Command not implemented
221 | Service closing connection | 503 | Bad sequence of commands
250 | Requested mail action okay, completed | 504 | Command parameter not implemented
251 | User not local; will forward to | 550 | Requested action not taken: mailbox unavailable (E.g., mailbox not found, no access)
354 | Start mail input | 551 | User not local; please try
421 | Service not available, closing transmission channel | 552 | Requested mail action aborted: exceeded storage allocation
450 | Requested mail action not taken: mailbox unavailable (E.g., mailbox busy) | 553 | Requested action not taken: mailbox name not allowed (E.g., mailbox syntax incorrect)
451 | Requested action aborted: local error in processing | 554 | Transaction failed
452 | Requested action not taken: insufficient system storage
Message_Data:

The Message_Data field contains the data that SMTP mail servers send and receive, for example:

From: john@yahoo.com To: <anne@hotmail.com> Subject: <Hi>
            Date: Wed, 19 Feb 2003 14:00:49 +0200 Content-Type: text/plain; charset="US-ASCII"
            Content-Transfer-Encoding: 7bit Hi John
Examples:
Set Mailer = Server.CreateObject("SoftArtisans.SMTPMail") Mailer.LoggingLevel
            = 0 '--- When LoggingLevel is set to 0, set SMTPLog '--- to the log file's path
            and include the complete '--- file name. The file is replaced with each '--- request.
            Mailer.SMTPLog = "C:\Mail\Log\Msg1.log"
Set Mailer = Server.CreateObject("SoftArtisans.SMTPMail") Mailer.LoggingLevel
            = 1 '--- When LoggingLevel is set to 1, set SMTPLog '--- to the log file's path
            and file name prefix. '--- The log generated will be cumulative and the '--- log
            file's name will contain the date. The '--- format of the file name generated by
            this '--- example would be "Log_YYYYMMDD.log". Mailer.SMTPLog = "C:\Mail\Log"
Set Mailer = Server.CreateObject("SoftArtisans.SMTPMail") Mailer.LoggingLevel
            = 2 '--- When LoggingLevel is set to 2, set SMTPLog '--- to the log file's path
            and file name prefix. '--- The log generated will be cumulative and the '--- log
            file's name will contain the date. The '--- format of the file name generated by
            this '--- example would be "Log_YYYYMMDD.log". Mailer.SMTPLog = "C:\Mail\Log"


MailFromAddress Property

Object: SMTP Mailer
Syntax: SMTPMailer.MailFromAddress = email address
Type: String
Read/Write: Read/Write
Description:

MailFromAddress specifies the e-mail address from which the message was sent. The value of MailFromAddress will be used in the message's MAIL FROM field. The value of MailFromAddress will not be used in subsequent headers.

MailFromAddress is not a required property. If you do not set MailFromAddress, the value of FromAddress will be assigned both to the MAIL FROM field and to subsequent headers. Note that you must set the FromAddress property.

Example:

<% Set mailer = Server.CreateObject("SoftArtisans.SMTPMail") ... Mailer.FromName
        = "Joe Smith" Mailer.MailFromAddress = "JSmith@unknown.com" Mailer.FromAddress =
        "JohnS@unknown.org" ... %>


MassMail Method

Object: SMTP Mailer
Syntax: <OBJECT>.MassMail ([in] RecordSet Pointer)
Returns: True/False
Description: The MassMail method works like a mail merge to send e-mail messages to a mailing list with only one connection to the mail server.

MassMail replaces the SendMail method. You should not use the SendMail method if you are using the MassMail method.

MassMail sends each e-mail as it replaces the coded template with values from your data source. When creating the template in your code, use "%%" delimiter characters on each side of the column names in order to indicate which columns you would like SMTPMail to pull data from when using the MassMail feature.

For example, if you want to pull an e-mail address out of a column named "EmailAddress", you would refer to it in your code as %%EmailAddress%%. If you want to use the delimiter characters, "%%", in the subject or body of your e-mail without referring to a data source column, you should put the escape character ("\") in front of them, like this: "\%\%".

The MassMail method does not handle bounced messages.

This functionality is compatible with LSMTP.

Note: You can use the MassMail functionality from within an HTML message or when getting the body text of a message from an HTML file, but SMTPMail will read the column name value inside delimiters literally, so you cannot use HTML formatting or any additional characters inside the delimiters. For example, if you use %%<B>E</B>mailAddress%%as the value inside the delimiters, SMTPMail will read the column name as"<B>E</B>mailAddress", will not recognize it as a valid column name and will pass it out to the body text of the e-mail as HTML-formatted text, " %%EmailAddress%% ".

Example:

<% Set mailer = Server.CreateObject("SoftArtisans.SMTPMail") ... '--- '---
        Set the Subject, Recipient and BodyText of the mass e-mail mailer.Subject = "Regarding
        Order Number %%OrderNumber%%" mailer.BodyText = "Dear %%FirstName%% :" & vbCrLf
        ... mailer.AddRecipient "%%FirstName%% %%LastName%%", "%%EmailAddress%%" mailer.AddCC
        "Mail Administrator", "webmaster@website.com" '--- '--- Set remote host name mailer.RemoteHost
        = "servername" '--- '--- Set database connection filePath = Server.MapPath("massmail.mdb")
        strConnect = "DBQ=" & filePath & ";Driver={Microsoft Access Driver (*.mdb)};DriverId=25;FIL=MSAccess;"
        '--- Dim objRec Dim objCommand '--- Set objCommand = Server.CreateObject ("ADODB.Command")
        Set objRec = Server.CreateObject("ADODB.Recordset") '--- objCommand.ActiveConnection
        = strConnect objCommand.CommandType = adcmdText objCommand.CommandText = "SELECT
        LastName, EmailAddress, FirstName, OrderNumber FROM Customers" Set objRec = objCommand.Execute
        '--- '--- Until end of recordset is reached, send e-mail If mailer.MassMail (objRec)
        Then Response.Write "Mail sent..." Else Response.Write "Mail failure." End If '---
        Set objRec = nothing Set mailer = nothing ... %>


MassMailFailed Property

Object: | SMTP Mailer
Syntax: | <OBJECT>.MassMailFailed
Type: | Double
Read/Write: | Read Only
Description: | This property returns the number of e-mails that failed while MassMail was running. The MassMailFailed property is only useful if you are using the MassMail method. If you are not using the MassMail method, this property will return 0. The MassMailFailed property can be used in conjunction with the MassMailTotal property to find the number of successfully sent e-mails in a mass mailing. MassMailTotal Property - MassMailFailed Property = successfully sent e-mails

Example:

<% Set mailer = Server.CreateObject("SoftArtisans.SMTPMail") ... '--- Print
        the number of failed e-mails in the current SMTPMail MassMail Response.Write "The
        number of e-mails that failed during MassMail is: " & Mailer.MassMailFailed
        ... %>


MassMailTotal Property

Object: | SMTP Mailer
Syntax: | <OBJECT>.MassMailTotal
Type: | Double
Read/Write: | Read Only
Description: | This property returns the total number of e-mails that were attempted while MassMail was running. The MassMailTotal property is only useful if you are using the MassMail method. If you are not using the MassMail method, this property will return 0. The MassMailTotal property can be used in conjunction with the MassMailFailed property to find the number of successfully sent e-mails in a mass mailing. MassMailTotal Property - MassMailFailed Property = successfully sent e-mails

Example:

<% Set mailer = Server.CreateObject("SoftArtisans.SMTPMail") ... '--- Print
        the total number of attempted e-mails in the current SMTPMail MassMail Response.Write
        "The number of e-mails that were attempted during MassMail is: " & Mailer.MassMailTotal
        ... %>


SMTP Mailer Methods

AddAttachment
AddBCC
AddCC
AddExtraHeader
AddRecipient
ClearAllRecpients
ClearAttachments
ClearBCCs
ClearBodyText
ClearCC
ClearExtraHeaders
ClearRecipients
EncodeHeader
GetBodyTextFromFile
GetHtmlTextFromFile
GetPlainTextFromFile
GetTempPath
MassMail
SendMail


Organization Property

Object: | SMTP Mailer
Syntax: | <OBJECT>.Organization = <value>
Type: | String
Read/Write: | Read/Write
Description: | This property sets the Organization header in a message.

Example:

<% Set mailer = Server.CreateObject("SoftArtisans.SMTPMail") ... '--- Sets
        the Organization header. mailer.Organization = "SoftArtisans SMTP Org" ... %>


Password Property *

Object: | SMTP Mailer
Syntax: | <OBJECT>.Password = <value>
Type: | String
Read/Write: | Read/Write
Description: | This property allows you to set the password which you can use to authenticate with the mail server. This property can be used to prevent spam from being sent from your mail server. It must be used in conjunction with the UserName property . If you do not set BOTH the UserName and Password properties, your mail will not be authenticated with the server. Only Login Authentication is supported at this time. This feature is based on the "SMTP Service Extension for Authentication" protocol in RFC2554.

Example:

<% Set mailer = Server.CreateObject("SoftArtisans.SMTPMail") ... '--- '---
        Set the UserName and Password with which mail server will authenticate mailer.UserName
        ="User name" mailer.Password ="Password" '--- '--- If mail server authenticates,
        send e-mail mailer.SendMail ... %>
* ONLY available in the Full version of SoftArtisans SMTPmail.


PGPParams Property

Object: | SMTP Mailer
Syntax: | <OBJECT>.PGPParams = <value>
Type: | String
Read/Write: | Read/Write
Description: | This property contains the parameters that PGP uses to process the message. This string contains parameters that are passed to the PGP command line. This property must be used in conjunction with the PGPPath property. For more information on PGP and the different parameters that it requires, visit www.pgp.com. See also, GetBodyTextFromFile.

Example:

<% Set mailer = Server.CreateObject("SoftArtisans.SMTPMail") ... '--- Set the
        path of the PGP executable mailer.PGPPath = "E:\Program Files\Network Associates\PGPcmdln\PGP.exe"
        '--- '--- Set the parameters with which PGP will function '--- These parameters
        are dependant on the executable set in the PGPPath property '--- In this example,
        we want PGP to encrypt a plaintext file with recipient's public key mailer.PGPParams
        = "-s -a ""c:\test1.txt"" -u ""<Anyone@unknown.com>"" -z ""passwordkey"""
        ... %>


PGPPath Property

Object: | SMTP Mailer
Syntax: | <OBJECT>.PGPPath = <value>
Type: | String
Read/Write: | Read/Write
Description: | This property returns the path for the location of the PGP executable. It should be used in conjunction with the PGPParams property to set PGP security on the e-mail. See also, GetBodyTextFromFile.

Example:

<% Set mailer = Server.CreateObject("SoftArtisans.SMTPMail") ... '--- Set the
        path of the PGP executable mailer.PGPPath = "E:\Program Files\Network Associates\PGPcmdln\PGP.exe"
        '--- '--- Set the parameters with which PGP will function '--- These parameters
        are dependant on the executable set in the PGPPath property '--- In this example,
        we want PGP to encrypt a plaintext file with recipient's public key mailer.PGPParams
        = "-s -a ""c:\test1.txt"" -u ""<Anyone@unknown.com>"" -z ""passwordkey"""
        ... %>


Port Property

Object: | SMTP Mailer
Syntax: | <OBJECT>.Port = <value>
Type: | Long
Read/Write: | Read/Write
Description: | Sets or returns the SMTP port number. Port is set to 25 by default.

Example:

<% Set mailer = Server.CreateObject("SoftArtisans.SMTPMail") ... '--- Set the
        port that SMTPmail should use to send e-mail. mailer.Port = 1025 ... %>


Priority Property

Object: SMTP Mailer
Syntax: <OBJECT>.Priority = <value>
Type: Integer
Read/Write: Read/Write
Description: This property sets the priority level for a message. Priority levels are one through five and are reflected in the X-Priority.

Valid values are:

Value | Description
1 | High
3 | Normal
5 | Low

Example:

<% Set mailer = Server.CreateObject("SoftArtisans.SMTPMail") ... '------------------------------------
        '--- Set priority and if message is urgent. Prioritys are 1, 3, 5 and '--- are reflected
        in the X-Priority header '--- 1 = High, 3 = Normal, 5 = Low '------------------------------------
        mailer.Priority = 1 ... %>


prog_ref_smtp_properties

BodyText
CharSet
CodePage
ConfirmRead
ContentTransferEncoding
ContentType
CustomCharSet
DateTime
Encoding
Expires
FromAddress
FromName
HtmlText
IgnoreMalformedAddress
IgnoreRecipientErrors
Live
LoggingLevel
MailFromAddress
MassMailFailed
MassMailTotal
Organization
Password
PGPParams
PGPPath
Priority
RemoteHost
ReplyTo
Response
ReturnPath
ReturnReceipt
SMTPLog
Subject
SuppressMsgBody
TimeOut
Urgent
UseMSMailHeaders
UserName
Version
WordWrap
WordWrapLen


RemoteHost Property

Object: | SMTP Mailer
Syntax: | <OBJECT>.RemoteHost = <value>
Type: | String
Read/Write: | Read/Write
Description: | This property indicates the remote SMTP host through which the message is sent. The value passed to this property can be an IP address or mail server name.

Example:

<% Set mailer = Server.CreateObject("SoftArtisans.SMTPMail") ... '--- Set the
        Remote Host (SMTP) that SMTPMail will use to send mail. '--- You can set a condition
        to verify that Remote Host is correct. strMailHost = "MailServer" If strMailHost
        = "mailhost.xyz.com" Then Response.Write "<h2 align=center>Error: You need
        to change the mailhost to your SMTP server address</h2>" Else mailer.RemoteHost
        = strMailHost End If ... %>


ReplyTo Property

Object: | SMTP Mailer
Syntax: | <OBJECT>.ReplyTo
Type: | String
Read/Write: | Read/Write
Description: | This property lets you specify a different e-mail address to which replies will be sent.


Response Property

Object: SMTP Mailer
Syntax: <OBJECT>.Response
Type: String
Read/Write: Read Only
Description: This property returns any of the following types of error messages:.

  • SMTP error messages, such as SMTP server response error.
  • System error messages, such as temporary file creation failure error.
  • Error messages that help the user to find problems beyond the SMTP returned message, such as MalformedEmailAddress, connection setup, or connection closing.

Example:

<% Set mailer = Server.CreateObject("SoftArtisans.SMTPMail") ... '--- This
        property returns any errors. Response.Write "<BR> " & mailer.Response
        ... %>


ReturnPath Property

Object: SMTP Mailer
Syntax: SMTPMailer.ReturnPath = <email address>
Type: String
Read/Write: Read/Write
Description:

ReturnPath sets a message's return-path header. ReturnPath is not a required property. If you do not set ReturnPath, the value of FromAddresswill be used in the return-path header field.

Note that you must include <> in the ReturnPath value, as follows:

Mailer.ReturnPath = "<info@softartisans.com>"


ReturnReceipt Property

Object: | SMTP Mailer
Syntax: | <OBJECT>.ReturnReceipt = <value>
Type: | Boolean
Read/Write: | Read/Write
Description: | This property sets a ReturnReceipt flag. It only works if the recipient's SMTP server supports confirmation and that capability is enabled on the recipient's server. If set to True, the recipient's SMTP server sends a notice confirming that the e-mail has been delivered.

Example:

<% Set mailer = Server.CreateObject("SoftArtisans.SMTPMail") ... '--- Recipient's
        SMTP server sends a notice confirming that the e-mail has been delivered. '--- This
        property works only if user's server supports notifcation. mailer.ReturnReceipt
        = true ... %>


SendMail Method

Object: | SMTP Mailer
Syntax: | <OBJECT>.SendMail()
Returns: | True/False
Description: | This method attempts to send the e-mail message.

Example:

<% Set mailer = Server.CreateObject("SoftArtisans.SMTPMail") ... '--- Sends
        the message and can be used to verify if there if it has been sent. If mailer.SendMail
        Then Response.Write "<P>Mail sent..." Else Response.Write "<P>Mail failure.
        Check mail host server name and tcp/ip connection..." End If ... %>


SMTPLog Property

Object: SMTP Mailer
Syntax: <OBJECT>.SMTPLog = <value>
Type: String
Read/Write: Read/Write
Description: SMTPLog sets the name and location of a log file that records information about sent messages. SMTPMail will create one of three types of log file, depending on the value of LoggingLevel.

If LoggingLevel = 0

(default value) 		Set SMTPLog to the log file's path and include the complete file name. The file is replaced with each request. For example,
Mailer.SMTPLog = "C:\Mail\Log\Msg1.log"
If LoggingLevel = 1

(Not available in SMTPMailFree) 		Set SMTPLog to the log file's path and file name prefix. The Log generated will be cumulative and the name will contain the date. For example,
Mailer.SMTPLog = "C:\Mail\Log"
The format of the log file generated will be "Log_YYYYMMDD.log".
If LoggingLevel = 2

(Not available in SMTPMailFree) 		Set SMTPLog to the log file's path and file name prefix. The Log generated will be cumulative and the name will contain the date. For example,
Mailer.SMTPLog = "C:\Mail\Log"
The format of the log file generated will be "Log_YYYYMMDD.log".
Examples:
Set Mailer = Server.CreateObject("SoftArtisans.SMTPMail") Mailer.LoggingLevel
            = 0 '--- When LoggingLevel is set to 0, set SMTPLog '--- to the log file's path
            and include the complete '--- file name. The file is replaced with each '--- request.
            Mailer.SMTPLog = "C:\Mail\Log\Msg1.log"
Set Mailer = Server.CreateObject("SoftArtisans.SMTPMail") Mailer.LoggingLevel
            = 1 '--- When LoggingLevel is set to 1, set SMTPLog '--- to the log file's path
            and file name prefix. '--- The log generated will be cumulative and the '--- log
            file's name will contain the date. The '--- format of the file name generated by
            this '--- example would be "Log_YYYYMMDD.log". Mailer.SMTPLog = "C:\Mail\Log"
Set Mailer = Server.CreateObject("SoftArtisans.SMTPMail") Mailer.LoggingLevel
            = 2 '--- When LoggingLevel is set to 2, set SMTPLog '--- to the log file's path
            and file name prefix. '--- The log generated will be cumulative and the '--- log
            file's name will contain the date. The '--- format of the file name generated by
            this '--- example would be "Log_YYYYMMDD.log". Mailer.SMTPLog = "C:\Mail\Log"


Subject Property

Object: | SMTP Mailer
Syntax: | <OBJECT>.Subject = <value>
Type: | String
Read/Write: | Read/Write
Description: | This property contains the Subject line for the message.

Example:

<% Set mailer = Server.CreateObject("SoftArtisans.SMTPMail") ... '--- Sets
        Subject line for the message mailer.Subject = "Put your subject here" ... %>


SuppressMsgBody Property

Object: | SMTP Mailer
Syntax: | <OBJECT>.SuppressMsgBody = <value>
Type: | Boolean
Read/Write: | Read/Write
Description: | This property works in conjunction with the SMTPLog property to indicate whether the log file receives a copy of the message text. When SMTPLog is set to a file and this property is set to True (the default), a copy of the message text is sent to the log file.

Example:

<% Set mailer = Server.CreateObject("SoftArtisans.SMTPMail") ... '--- Used
        for Logging Debugging log mailer.SMTPLog = "c:\mysmtplog.txt" '--- '--- This property
        works in conjunction with the SMTPLog property to '--- indicate whether the log
        file receives a copy of the message text mailer.SuppressMsgBody = false ... %>


TimeOut Property

Object: | SMTP Mailer
Syntax: | <OBJECT>.TimeOut = <value>
Type: | Integer
Read/Write: | Read/Write
Description: | This property indicates the maximum amount of time, in seconds, that SoftArtisans SMTPMailwaits for a response from the remote. The default is 30 seconds.

Example:

<% Set mailer = Server.CreateObject("SoftArtisans.SMTPMail") ... '--- This
        property indicates the maximum amount of time, in seconds, '--- that SoftArtisans
        SmtpMail waits for a response from the remote SMTP server mailer.TimeOut = 120 ...
        %>


Urgent Property

Object: | SMTP Mailer
Syntax: | <OBJECT>.Urgent = <value>
Type: | Boolean
Read/Write: | Read/Write
Description: | This property sets a flag in the outgoing message that indicates the message is urgent. Not all mail readers support this flag.

Example:

<% Set mailer = Server.CreateObject("SoftArtisans.SMTPMail") ... '--- This
        property sets a flag in the outgoing message that indicates '--- the message is
        urgent mailer.Urgent = true ... %>


UseMSMailHeaders Property

Object: | SMTP Mailer
Syntax: | <OBJECT>.UseMSMailHeaders = <value>
Type: | Boolean
Read/Write: | Read/Write
Description: | This property indicates whether MS-Mail priority headers are sent in addition to the standard SMTP priority headers. By default, MS-Mail priority headers are on. You can turn off the MS-Mail headers by setting this property to False.

Example:

<% Set mailer = Server.CreateObject("SoftArtisans.SMTPMail") ... '--- This
        property indicates whether Microsoft mail headers will be turned on or off mailer.UseMSMailHeaders
        = false ... %>


UseMSPickUpDir Method *

Object: SMTP Mailer
Syntax: <OBJECT>.UseMSPickUpDir ([in] Directory as String)
Description: For each configured domain, Microsoft SMTP Service (Service) supports the placement of all incoming messages directly into a Drop folder. This allows the Service to be used as an e-mail receiver for other applications.

In additon to connecting to a TCP port to send messages, applications can also use a Pickup folder. Once a message is placed in the Pickup folder, the Service delivers the message.

The UseMSPickUpDir method allows you to use the Service and to specify the path of the pickup directory.

If the directory specified is the Microsoft Pickup directory, the Service will pick the messages up from the directory. If it is not the Pickup directory, the messages will only be stored in the directory, but will not be picked up by the Service. Check the Microsoft SMTP Service documentation for instructions on configuring this service.

Important: This will only work if Microsoft SMTP Service is configured and running correctly.

The RemoteHost property is NOT needed when using the UseMSPickUpDir method.

Example:

<% Set mailer = Server.CreateObject("SoftArtisans.SMTPMail") ... mailer.UseMSPickUpDir
        ("c:\pickup") ... %>
* ONLY available in the Full version of SoftArtisans SMTPmail.


UserName Property *

Object: | SMTP Mailer
Syntax: | <OBJECT>.UserName = <value>
Type: | String
Read/Write: | Read/Write
Description: | This property allows you to set the username which you can use to authenticate with the mail server. This property can be used to prevent spam from being sent from your mail server. It must be used in conjunction with the Password property . If you do not set BOTH the UserName and Password properties, your mail will not be authenticated with the server. Only Login Authentication is supported at this time. This feature is based on the "SMTP Service Extension for Authentication" protocol in RFC2554.

Example:

<% Set mailer = Server.CreateObject("SoftArtisans.SMTPMail") ... '--- '---
        Set the UserName and Password with which mail server will authenticate mailer.UserName
        ="User name" mailer.Password ="Password" '--- '--- If mail server authenticates,
        send e-mail mailer.SendMail ... %>
* ONLY available in the Full version of SoftArtisans SMTPmail.


Version Property

Object: | SMTP Mailer
Syntax: | <OBJECT>.Version
Type: | String
Read/Write: | Read Only
Description: | This property returns the version number of the internal component.

Example:

<% Set mailer = Server.CreateObject("SoftArtisans.SMTPMail") ... '--- Get and
        print the internal version number of SMTPMail Response.Write "SoftArtisans SMTPMail
        Version: " & Mailer.Version ... %>


WordWrap Property

Object: | SMTP Mailer
Syntax: | <OBJECT>.WordWrap = <value>
Type: | Boolean
Read/Write: | Read/Write
Description: | This property indicates whether the message will word wrap. By default, word wrap is turned off. Set this property to True to turn word wrap on.

Example:

<% Set mailer = Server.CreateObject("SoftArtisans.SMTPMail") ... '--- This
        property indicates whether the message will word wrap. mailer.WordWrap = true ...
        %>


WordWrapLen Property

Object: | SMTP Mailer
Syntax: | <OBJECT>.WordWrapLen = <value>
Type: | Integer
Read/Write: | Read/Write
Description: | This property sets the position at which the message body wraps if the WordWrap property is set.

Example:

<% Set mailer = Server.CreateObject("SoftArtisans.SMTPMail") ... '--- This
        property indicates whether the message will word wrap. mailer.WordWrap = true '---
        '--- This property sets the position at which the message body wraps '--- if the
        WordWrap property is set mailer.WordWrapLen = 50 ... %>


Key Features

  • Sends e-mail from any COM client
  • Similar object model to ServerObjects' AspMail
  • Written for high performance
  • Supports all threading models
  • Pretty Good Privacy (PGP) is supported in Active Server Pages
  • Supports common functions like file attachments, multiple encoding schemes, and many others
  • Login authentication with the server
  • Mass mail

SMTPmail has one object: the SMTP Mailer.


prog_ref_xfhref_linktext

Class: SAXFileLib.XFFile

Property: DateLastModified

Type: Variant

Read Only

Description:

Example:

<% If upl.DateLastModified <> "form-data" Then %>
  Your upload did not succeed, most likely because your browser
  does not support Upload via this mechanism.
<br>


prog_ref_xfhref_url

Class: SAXFileLib.XFHREF

Property: URL

Type: Variant

Read Only

Description: The URL (Universal Resource Locator) of the link contained within the XFHREF object.

Example:

<% If upl.URL < > "form-data" Then %>
    Your upload did not succeed, most likely because your browser
    does not support Upload via this mechanism.
<br />


The XFile Objects

Top Level Objects When to Use Child Objects
The Transfer Engine

XFRequest Object
<OBJECT CLASSID="clsid:C3A57B60-C117-11D2-BD9B-00105A0A7E89"> </OBJECT>
         Use as the top level object for an upload or download without a GUI for the end-user. Use as a child object of the AXFFile or AXFFileDownload objects when a GUI is desired.
Transfer Engine File Collection
(XFFileCollection )
Request/Response Header Collection
(XFHTTPHeaderCollection)
Form Collection
(XFFormCollection)
Resumable Transfer Objects
(xxxxxxxxxxxxxxxxxxxxxx)
Download Error Object
(DownloadError)
The Upload GUI

AXFFile Object
<OBJECT CLASSID="CLSID:230C3D02-DA27-11D2-8612-00A0C93EEA3C"> </OBJECT>
         Use as a top level object when you want the end-user to have a GUI when uploading.
Transfer Engine
(XFRequest) (and all of it's child objects listed above)
The File Collection of the GUI
(AXFileCollection)
The Download GUI

AXFFileDownload Object
<OBJECT CLASSID="CLSID:B82FA17C-F3A9-11D2-B5DD-0050041B7FF6"> </OBJECT>
 Use as a top level object when you want the end-user to have a GUI when downloading.
Transfer Engine
(XFRequest) (and all of it's child objects listed above)
The File Collection of the GUI
(AXFileCollection)
The Progress Indicator

AXFFileProgress Object
<OBJECT CLASSID="CLSID:C3EAF164-E06A-11D2-B5C9-0050041B7FF6"> </OBJECT>
         Use in conjunction with either the XFRequest, AXFFile or AXFFileDownload objects to provide a ready-made progress indicator. no child objects


UseCookie Method

Object: | XFRequest
Syntax: | UseCookie Cookie as String
Description: | Adds a cookie to the request's HTTP header.
Example: | SAXFile.UseCookie "GUID=8E021C1F5D0311D497F5090273F1EE9; ASPSESSIONIDQGGGQQAB=LHDDEDKBPEBAEEJJFKENHOAA"


programmer_ref_archive

SoftArtisans Archive provides programmers with a tool to create and extract archives in both ZIP and Microsoft Cabinet format. Using Archive, you can:

  • Create a new archive.
  • Add, extract, or delete files from an existing archive.
  • Enumerate the contents of an archive.
  • Sign the archive using Microsoft Authenticode (for .CAB or .EXE files only).

Archive has three objects:

  • Archive Object
  • ArchiveItemCollection Object
  • ArchiveItem Object