Welcome

Welcome to FileUp Enterprise Edition, v5.3.1

Last Update: 05/2010
  • Introduction describes the basic features and requirements of FileUpEE.

  • Installation includes automatic and manual install and uninstall instructions, configuration settings, and important security information.

  • Quick Start shows how easy it is to upload and download files with FileUpEE.

  • Features in Depth describes FileUpEE's major features, with code examples.

  • Client-Side Solutions explains how to use XFileEE.

  • Samples includes all ASP and ASP.NET sample applications.

  • Programmer's Reference contains definitions of each object, method, and property.

  • SoftArtisans XFile contains definitions of each object, method, and property of XFileEE.

  • Backwards Compatibility contains information regarding deprecated software from previous editions of FileUpEE.

Copyright © 2010 SoftArtisans, Inc. All rights reserved.


What is SoftArtisans FileUp Enterprise Edition?

Industrial Grade File Upload/Download for
ASP.NET, Classic ASP, and web Services

SoftArtisans FileUpEE is the choice for building industrial grade upload/download applications for either ASP.NET or Classic ASP. FileUpEE enables multi-gigabyte file transfers in a web farm, without compromising security. Thousands of files of any format - images, Word documents, databases - can be sent in a single operation.

FileUpEE allows users with a web browser to transmit files from their local hard disk to a web farm and/or to a separate file server that is networked to the web farm. The web server makes a SOAP request to the file server, which may be located within a firewall-protected LAN. The FileUpEE file server is isolated and secure from public web servers. If the web server is compromised, the file servers will stay safe.


Features and Benefits

Resumable File Transfers
  • Uploads from web server to file server are fully resumable when uploading from a browser.
  • Uploads and downloads are fully resumable between client and web server and between web server and file server when using XFileEE on the client.

Security
  • The FileUpEE file server is isolated and secure from public Web servers. If the web server is compromised, all file transfers will stay safe.
  • SSL is fully supported.
  • Each transferred file's integrity can be confirmed using MD5 hashing.
  • Can be fully integrated with your existing web application's authentication scheme.

Firewall Support
  • Communication between web server and file server across a firewall occurs on a single user-defined TCP port.

Streaming 3-Tier Requests in ASP*
  • Performance gain: No temporary files are written on the web server.
  • Security: The uploaded files are never on the web server in their complete form, either in memory or on disk.

Web Farm Support/Scalability
  • FileUpEE supports simultaneous uploads to multiple web servers accessing a common, secure file store.

High Volume
  • SoftArtisans has tested file transfers of over 100 gigabytes with success. With FileUpEE, entire systems can be backed up in a single step.

Data Integrity
  • FileUpEE allows verification of the integrity of uploaded data.

Progress Indication
  • FileUpEE includes an accurate progress indicator for uploads.

SOAP-based Web Service
  • FileUpEE uses a SOAP-based File Service to transfer files from web Server to File Server.

Client-Side Controls
  • For optimal performance, FileUpEE is bundled with a full license of the client-side control SoftArtisans XFileEE .

*This feature is not available in ASP.NET.


System Requirements

  • FileUpEE Requirements
  • XFileEE Requirements
FileUpEE Requirements
Server Requirements
  • Windows 2000 (Professional, Server, or Advanced Server), XP Professional, 2003 Server, Vista*, or 2008 Server*

  • IIS 5 or higher

  • To use FileUpEE on a 64-bit server in IIS 7.0, the FileUpEE application must run in a 32-bit application pool. 64-bit servers using IIS 6.0 must be in 32-bit compatibility mode.

  • ASP.NET 1.0 or higher or ASP 3.0 or higher

FileUpEE Supported Browsers

FileUpEE supports all browsers that are compliant with the HTTP RFC1867 protocol for browser-based uploads and downloads.. However, in order to use the XFileEE client-side ActiveX control, the client must use Microsoft Internet Explorer 4 and above, as Internet Explorer is the only browser with ActiveX support.

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

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

Server Requirements
  • XFileEE sends data to the HTTP server using the upload standard documented in RFC 1867 [image] . The HTTP server should provide RFC 1867 compliant upload software such as FileUpEE.

Complete XFileEE documentation can be found at FileUpEE/XFile/XFile.chm or on the SoftArtisans support site.

*FileUpEE applications must be set to Classic .NET pipeline mode in IIS

Top


New Features

New in v5.3.1

  • Added full support to XFileEE for 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 XFileEE ASP.NET samples using custom HTML client-side progress indicator

New in v5.3.0

  • Created a .NET utility class named Encryption in FileUpEE
  • Added a new method named AddEncryptedRequestHttpHeader to XFile's XFRequest object to be used with FileUpEE's new Encryption class (See KB article Session loss in ASP.NET 2.0 using XFileEE with FileUpEE)

New in v5.2.0

  • New FileUpEE constructor allows greater control of cleanup of temp files during resumable transfers.
  • Updated installer with support for Vista and Windows 2008
  • Extensive new collection of .NET samples demonstrating all enterprise features of FileUpEE, including:
    • Resumable and non-resumable 2-tier upload and download samples
    • Resumable and non-resumable 3-tier upload and download samples
    • Sophisticated custom HTML client-side progress indicator
    • All samples can handle file transfers of unlimited size
    • All 3-tier download samples use streaming functionality so no files are cached on the webserver
    • Fileserver code now in separate application which can easily be moved to another server for testing 3-tier transfers
  • Updated documentation
    • More .NET code examples
    • Improved accuracy in descriptions of many methods and properties
    • Complete documentation of the new HttpModule (released in version 5.1.0) which is configured in web.config rather than the registry
    • XFileEE documentation now bundled with the main FileUpEE documentation

New in v5.1.1

  • New HttpModule takes parameters out of the registry and into the web.config file, allowing HttModule settings to be adjusted on the application level, rather than on the machine level.

  • Improved performance over previous versions of FileUpEE due to more efficient algorithms for parsing the request.

New in v5.0

  • Resumable uploads from client to web server with SoftArtisans XFileEE.

  • Streaming 3-tier file transfers improve performance and security. (Streaming uploads only available in ASP. Streaming download functionality available in both ASP/ASP.NET).

  • IIS 6 support:
    • Chunked transfer-encoding allows requests of unlimited size to IIS 6.
    • FileUpEE's HttpModule allows accurate progress indication and overcomes ASP.NET's inefficient memory utilization in IIS 6 and above.

  • New in SoftArtisans XFileEE:
    • Unlimited upload and download size.
    • Resumable uploading and downloading.


Related Products from SoftArtisans

Industry-Standard File Transfer Technology

As the leader in HTTP-based file transfer technology, SoftArtisans has spent over six years providing world-class products and services 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, 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.


Installation

Installing FileUpEE for ASP.NET

Installing FileUpEE for ASP

Installing XFileEE

Dependencies

FileUpEE Registry Keys

Security Considerations

Notes for Server Administrators

Removing FileUpEE


Installing FileUpEE for ASP.NET

  • Upgrading to a New Version of FileUpEE
  • Automatic Installation
  • Manual Installation
  • Adding FileUpEE to an ASP.NET Application
  • The HttpModule
  • Installing FileUpEE Globally
Upgrading to a New Version of FileUpEE

If you are upgrading to a new version of FileUpEE, remove the old version before installing the new version.

Automatic Installation
To create 3-tier upload and 3-tier download applications, you must install FileUpEE on both the web server and the file server.

To run the automatic installer, double-click FileUpEE.exe, and follow the InstallShield instructions.

During installation you will be asked if the machine on which you are installing is a web server or a file server. If you are installing on a development machine that functions as both a web server and a file server, select "Web server."

Top

Manual Installation

To install FileUpEE the first time, run the automatic installer. Once InstallShield has unpacked the dll files that contain FileUpEE, you can re-install FileUpEE manually (if, for example, you are moving FileUpEE to a different server). Even when working in .NET, the COM .dlls must be registered.

  1. Make sure that you have MSXML 4.0 SP2 installed. If it is not not installed already, download the msxml.msi from Microsoft's MSXML 4.0 Service Pack 2 web page and install it on your server.

  2. Open a command prompt window and move to the directory FileUpEE\COM.
    For example, enter cd Program Files\SoftArtisans\FileUpEE\COM.

  3. Enter regsvr32 FileUpEE.dll. A dialog box will inform you that FileUpEE.dll registered successfully; click Ok.

  4. Enter regsvr32 MimeClient.dll. A dialog box will inform you that MimeClient.dll registered successfully; click Ok.

  5. Enter regsvr32 FileUpEEProgress.dll. A dialog box will inform you that MimeClient.dll registered successfully; click Ok.

  6. Enter iisreset to reset IIS.

Top

Adding FileUpEE to an ASP.NET application

To add the FileUpEE assemblies to your application:

  1. Within your application, include a top level direcory called bin that contains the FileUpEE.dll, MimeClient.dll, FileUpEEModule.dll, and FileUpEEProgress.dll files from the directory FileUpEE\dotnet.

    The files you include in the bin directory must have the same version numbers as the files you registered to your server, either manually or using the automatic installer. Please note that FileUpEEModule.dll does not need to be registered, but must simply be added to the application's bin directory.

  2. Create a text file containing the contents of the example web.config file and save it as web.config. Make sure that the version number for the FileUpEeModule in the web.config file matches the version number of the FileUpEeModule.dll that you add to your application. Save web.config at the top level of your application.

    The FileUpEEModule can be configured using the Application Keys in the application's web.config file. An explanation of the functions of each FileUpEEModule Application key can be found on this page: FileUpEEModule Application Settings

The <httpRuntime> node is not necessary in the web.config for the FileUpEEModule to work. In order to allow large uploads, however, the executionTimeout and maxRequestLength settings must be set appropriately. This will override the default settings from the machine.config file.

Top

The HttpModule

SoftArtisans strongly recommends using the HttpModule with all uploads in ASP.NET. The HttpModule is an interceptor that resolves memory utilization and disk caching performance issues in ASP.NET uploads. Though uploads can be performed without the HttpModule, there is a severe performance penalty with any large upload that does not use the HttpModule. Other benefits include server-side progress indication, increased speed due to reduced buffer size, and three-tier upload capability.

To install the FileUpEE HttpModule to your ASP.NET application, follow the instructions on the HttpModule installation page.

Installing FileUpEE Globally

The FileUpEE assemblies - FileUpEE.dll, MimeClient.dll, FileUpEEModule.dll and FileUpEEProgress.dll - can be made accessible either globally or at the application level. If you would like the same .NET assemblies to be available to all applications, install the dll files in the Global Assembly Cache (GAC):

SoftArtisans recommends registering FielUpEE on the application level.
  1. Open a command prompt window and move to the directory FileUpEE\DotNet.
    For example, enter cd Program Files\SoftArtisans\FileUpEE\DotNet.

    The files you add to the GAC must have the same version numbers as the files registered to your server either manually or through the automatic installer.

  2. Enter gacutil /i FileUpEE.dll.

  3. Enter gacutil /i MimeClient.dll.

  4. Enter gacutil /i FileUpEEProgress.dll.

  5. Enter gacutil /i FileUpEEModule.dll.

  6. Open the file machine.config (in [Windows directory]\Microsoft.NET\Framework\[.NET version directory]\CONFIG).

  7. Add the following lines to the assemblies node of machine.config:

    <add assembly="FileUpEE, Version=x.x.x.x, Culture=neutral, PublicKeyToken=f593502af6ee46ae"/>
<add assembly="MimeClient, Version=x.x.x.x, Culture=neutral, PublicKeyToken=f593502af6ee46ae"/>
<add assembly="FileUpEEProgress, Version=x.x.x.x, Culture=neutral, PublicKeyToken=f593502af6ee46ae"/>
<add assembly="FileUpEEModule, Version=x.x.x.x, Culture=neutral, PublicKeyToken=f593502af6ee46ae"/>

    The version attribute of the add assembly node must correspond exactly to the version of the assembly (dll file) added to the GAC. If you add a new version of FileUpEE to the GAC using the gacutil command, update the dll version attributes in machine.config. To get the exact version of the dll file, right-click the dll and select the Properties tab.

The FileUpEE assemblies that you add to your ASP.NET application must be the same DLL files that you registered to the GAC.

Top

Top


Installing the HttpModule

FileUpEE's HttpModule is an interceptor that is used under ASP.NET to overcome inefficient memory utilization and disk caching performance in ASP.NET uploads. Additionally, it enables accurate server-side progress indication. The HttpModule intercepts an upload request, reads all the data, and writes it to a temp file chunk by chunk before sending it to ASP.NET. With the HttpModule and chunked transfer encoding, upload size in ASP.NET is unlimited.

It should be noted, however, that all major internet browsers have upload limits of 2 GB. Larger uploads must be generated by a client-side control that can handle very large transfers. FileUpEE includes SoftArtisans XFileEE, a client-side file transfer control that can submit uploads of any size.

For performance reasons, the HttpModule can be configured not to intercept all ASP.NET requests. SoftArtisans suggests that only requests for files with the extension .uplx be handled by the HttpModule, allowing requests with the extension .aspx to be sent directly to ASP.NET. This prevents burdening the server with unnecessary use of the HttpModule.

Note: You can use any file extension as the FileUpEE Module file extension, provided that it is 7 or fewer characters in length and is not already in use. In order to use a file extension other than .uplx, replace .uplx with your own custom extension in the instructions listed below.
  1. Install the HttpModule
    The HttpModule can be installed in the Global Assembly Cache (GAC) or on the application level. SoftArtisans recommends installing on the application level.

    To install HttpModule on the application level (recommended):

    Under <system.web>, add the following node, which adds the FileUpEE HttpModule to the project:

    <httpModules>
    <add name="FileUpEeModule" type="SoftArtisans.Net.FileUpEeFilter.Module.FileUpEeModule,
        FileUpEeModule, version=x.x.x.x, Culture=neutral, PublicKeyToken=f593502af6ee46ae"/>
</httpModule>

    Directly under the previous node, add the following node, which allows the .uplx extension to be processed by .NET:

    <httpHandlers>
    <add verb="*" path="*.uplx" type="System.Web.UI.PageHandlerFactory"/>
</httpHandlers>

    If you are running FileUpEE on version 2.x of the .NET framework, add the following under the <compiliation> node:

    <compilation>
    <buildProviders>
        <add extension=".uplx" type="System.Web.Compilation.PageBuildProvider"/>
    </buildProviders>
</compilation>
  2. Add a reference to the HttpModule assembly in Visual Studio.
    1. Open your project in Visual Studio

    2. Right click on your solution and select "Add Reference"

    3. Select the "Browse" tab and navigate to SoftArtisans\FileUpEE\dotnet

    4. Select FileUpEEModule.dll

  3. Add the configuration settings to the web.config file
    Past versions of the FileUpEE HttpModule have used the registry key to store important configuration information. The current version of the HttpModule stores these values on the application level in the <appSettings> node of the web.config file. A table detailing the use of these settings can be found on the HttpModule Application Keys page.

    The following is a list of settings to be added to the <appSettings> node in your application's web.config file. These are sample values and should be changed to suit the needs of your application.
    <appSettings>
    <add key="Resumable" value="true" />
    <add key="AllowClientOverride" value="true"/>
    <add key="FileUpEeTempDir" value="C:\Temp\FileUpEe\Cache" />
    <add key="TransferStage" value="1" />
    <add key="UseHttpModuleWithAspDotNet" value="true"/>
    <add key="FilterAspDotNetFlagExtension" value=".uplx" />
    <add key="FilterAspDotNetAtNKiloBytes"value="0"/>
    <add key="MaxKBytes" value="0" />
    <add key="MaxKBytesToCancel" value="0"/>
    <add key="ProgressIndicator" value="true" />
    <add key="ProgressIndicatorParam" value="progressid" />
    <add key="DynamicAdjustScriptTimeout" value="true" />
    <add key="ErrorLogDestination" value="0" />
    <add key="ErrorLogFile" value="C:\Temp\logs\FileUpEeModuleError.log"/>
    <add key="TraceLogFile" value="C:\Temp\logs\FileUpEeModuleTrace.log" />
    <add key="FilterReadBufferNKiloBytes" value="32" />
    <add key="MaxReadMemoryKiloBytes" value="16000" />
    <add key="FileWriteBufferNKiloBytes" value="32" />
</appSettings>
    A sample web.config file for the HttpModule installed on the application level can be found on our Sample web.config page, complete with explanations of each value.

  4. Allow ASP.NET to Process Files with the .uplx Extension
    Though the FilterAspDotNetFlagExtension application setting key can be used to intercept files with any file extension, including .aspx, using FileUpEE's HttpModule, SoftArtisans recommends using extension .uplx to keep from filtering .aspx files that do not use FileUpEE. After a request is handled by the HttpModule, the request is forwarded to ASP.NET. To allow ASP.NET to process files with the extension .uplx, you must add a script map to IIS (for security reasons, FileUpEE's automatic installation does not add the script map automatically).

    In the Windows XP IIS console, the Web Sites and Default web Site nodes have identical properties dialogs. The script maps can be installed in the web Sites properties, but they will be ignored by IIS. The script maps must be installed from the node containing your FileUpEE application.

    • Add .uplx to the Default web Site's App Mappings
      1. Open IIS, right-click the Default web Site, and select Properties.
      2. Select the Home Directory tab.
      3. Click Configuration.
      4. Select the App Mappings tab.
      5. Click Add.
      6. Browse to aspnet_isapi.dll (typically in [Windows directory]\Microsoft.NET\Framework\[.NET version directory]\).
      7. In the Extension field, enter uplx.
      8. Select All Verbs.
      9. Check Script Engine, and click Ok.

      OR

    • Add .uplx to the Application's App Mappings
      1. Open IIS, right-click your application's virtual directory, and select Properties.
      2. Select the Virtual Directory tab.
      3. Click Configuration.
      4. Select the App Mappings tab.
      5. Click Add.
      6. Browse to aspnet_isapi.dll (typically in [Windows directory]\Microsoft.NET\Framework\[.NET version directory]\).
      7. In the Extension field, enter uplx.
      8. Select All Verbs.
      9. Check Script Engine, and click Ok.

    Under ASP.NET, FileUpEE's progress indicator is handled by the HttpModule. So, to display accurate progress indication, upload to a page with the .uplx extension.

Installing the FileUpEE HttpModule in the GAC

To install HttpModule in the GAC:

  1. Open a command prompt window and move to the directory FileUpEE\DotNet.

  2. Enter gacutil /i FileUpEeModule.dll.

  3. Open the file machine.config (in [Windows directory]\Microsoft.NET\Framework\[.NET version directory]\CONFIG).

  4. Add the following to the <httpHandlers> node of machine.config:
    <add verb="GET,HEAD,POST" path="*.uplx" type="System.Web.UI.PageHandlerFactory" />
    Add the line above to machine.config before these entries:
    <add verb="GET,HEAD" path="*" type="System.Web.StaticFileHandler" />
<add verb="*" path="*" type="System.Web.HttpMethodNotAllowedHandler" />

    Add the following to the httpModules node of machine.config:
    <add name="FileUpEeModule" type="SoftArtisans.Net.FileUpEeModule, FileUpEeModule,
    Version=x.x.x.x, Culture=neutral, PublicKeyToken=f593502af6ee46ae"/>

    Add the following to the assembly node of machine.config:
    <add assembly="FileUpEEModule, Version=x.x.x.x, Culture=neutral,
    PublicKeyToken=f593502af6ee46ae"/>

    If you are running FileUpEE on version 2.x of the .NET framework, add the following under the <compiliation> node:

    <compilation>
    <buildProviders>
        <add extension=".uplx" type="System.Web.Compilation.PageBuildProvider"/>
    </buildProviders>
</compilation>

To add the FileUpEE assemblies to your application after having installed it in the GAC, follow the same instructions as you would for adding the assembly on the application level, making sure that the FileUpEE dlls that you add to your application are the ones that have been registered in the GAC.

The version attribute must correspond exactly to the version of FileUpEeModule.dll that you added to the GAC. If you add a new version of FileUpEeModule.dll to the GAC, update the version attribute in machine.config. To get the exact version of FileUpEeModule.dll, right-click the file and select the Properties tab.

Top


HttpModule Application Keys

HttpModule configuration is performed by adjusting a number of application keys located in the web.config file of the FileUpEE application:

  1. Open your FileUpEE application

  2. Open the web.config file for your application.

  3. In the web.config file, navigate to the <appSettings> node.

A sample web.config can be found on this page: Example web.config file for FileUpEE application with HttpModule

HTTPModule Application Keys

These application keys change settings on the FileUpEE HttpModule

HTTPModule Application Keys
AllowClientOverride If this key is set to true, the X-SaWsMaxKBytesToCancel header can be used to set the maximum Kilobytes permitted to be sent through FileUpEE. If this value is false, the MaxKBytesToCancel setting from the web.config file will instead be used, and the X-SaWsMaxKBytesToCancel header setting will be ignored.

This setting should only be used while testing resumability and should always be turned off in production.

DynamicAdjustScriptTimeout If this key is set to 1, the script's tiemout value will be increased until an upload is complete. Use DynamicAdjustScriptTimeout to ensure that large uploads will not be timed out. To disable DynamicAdjustScriptTimeout, set it to 0.
ErrorLogDestination ErrorLogDestination sets the type of error logging that FileUpEE will use. To enable error logging, set ErrorLogDestination to one of the following values:
SALogDestination Values
0 | Errors will not be logged.
1 | Errors will be logged in the file set by ErrorLogFile.
If ErrorLogDestination is set to 1, set ErrorLogFile.
ErrorLogFile | ErrorLogFile sets the physical path and file name of the FileUpEE HttpModule error log file. In order for the error log file to be successfully created, you must give read and write permissions on the parent folder to the ASP.NET Machine Account user on the server. The HttpModule will log errors in a file if ErrorLogDestination is set to 1.
FileUpEETempDir FileUpEE's interceptor - the HttpModule - caches request data before it is processed by ASP.NET. Set a different temp directory by setting the value of FileUpEETempDir.

The temp directory must be the physical path to a directory that is writable by the account under which the application is running. If you wish to cache to a network share, the account must have network privileges.
FilterAspDotNetAtNKiloBytes This key specifies the smallest ASP.NET upload size - in kilobytes - for which FileUpEE will use the HttpModule. If the size of an ASP.NET upload equals or is greater than the value of FilterAspDotNetAtNKiloBytes, FileUpEE's HttpModule will be used to process the upload.

Remember: In ASP.NET, the HttpModule only intercepts requests for files with the extension set at FilterAspDotNetFlagExtension, regardless of the value of FilterAspDotNetAtNKiloBytes. If, for example, is set to 4000000 and the server-side upload processing page is WebServer.aspx, the filter will not intercept uploads that are equal to or greater than 4000000 KB (4 GB).
FilterAspDotNetFlagExtension For performance reasons, FileUpEE's HttpModule does not intercept all ASP.NET requests. The FileUpEE samples have the HttpModule 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 servers with unnecessary use of the filters.

FilterAspDotNetFlagExtension allows you to change the file extension used to signal the filters in ASP.NET (.uplx) to a different extension of up to seven characters. By using a file extension other than .uplx you can hide your web server implementation (Windows/IIS) from potential hackers.

If you change the value of this application setting, you must add an extension mapping for the new extension to IIS. Additionally, you will need to add the new extension to the web.config file under the HttpHandlers and BuildProviders nodes.
FilterReadBufferNKiloBytes | FilterReadBufferNKiloBytes allows you to change the buffer size for the input stream. The default value for this setting is 8 Kilobytes.
FilterWriteBufferNKiloBytes | FilterWriteBufferNKiloBytes allows you to change the buffer size for the output stream to the temporary file. The maximum value is 32 Kilobytes, while the minimum value is 4 Kilobytes. The default value for this setting is 4 Kilobytes.
MaxKBytes MaxKBytes sets the size limit for an upload. MaxKBytes is a per-file limit, not a limit for the whole upload in a multiple-file upload. The HttpModule will stop writing the file to disk when its size reaches the value of MaxKBytes. Note that incomplete files will be saved and no error is thrown when the MaxKBytes limit is exceeded.

When MaxKBytes is set to zero, there is no size limit for uploaded files.

MaxKBytesToCancel The HttpModule will abort an 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.

Setting MaxKBytesToCancel may reduce the threat of a Denial of Service (DoS) attack on the file server. When an upload size hits MaxKBytesToCancel, the connection to the server will be terminated, the ASP.NET page will finish executing, and the ASP.NET thread will be freed.

When MaxKBytesToCancel is set to zero, there is no size limit for uploads.
MaxReadMemoryKiloBytes MaxReadMemoryKiloBytes allows you to set the maximum limit on the size of the total input buffer memory space. This value should be a multiple of FilterReadBufferNKiloBytes. This setting can be used to balance the rate of input to the HttpModule to the rate of output. Once the max value is reached, the module will wait before reading in more data. This can be useful when the output rate is slower than the input rate. If the output rate is slower than the input rate, the bottleneck of backed up bytes can overwhelm the memory available and cause an Out of Memory exception.
A value of 0 disables this setting.
ProgressIndicator | Set ProgressIndicator to 1 or true to enable FileUpEE's progress indicator.
ProgressIndicatorParam | The ProgressIndicatorParam sets the expected progress indicator query string parameter to be passed from the client to the server in an upload with progress indication.
Resumable | When Resumable is set to true on both the web server and the client (through XFileEE), FileUpEE will be able to resume an upload from client to web server that was suspended because of a network connection failure.
TraceLevelSwitch The TraceLevelSwitch is not strictly an application key, but is a switch set in the <switches> element of the <system.diagnostics> node. Turn tracing on or off. Tracing is used to create a debug log for the httpModule, and is for use during testing or debugging. It should probably be left off in production.
TraceLevelSwitch Values
0 | Off - The Trace Log is disabled.
1 | Errors - Only errors are logged by the HttpModule.
2 | Warnings - Warnings and errors will be logged by the HttpModule.
3 | Info - The entire contents of the intercepted requests are logged by the HttpModule. Additionally, the method calls of the HttpModule are logged
4 | Verbose - The entire contents of the intercepted requests are logged by the HttpModule. Additionally, the method calls of the HttpModule are logged in greater detail.
TraceLogFile | TraceLogFile sets the tracing log file location, which must be a pre-existing physical path that is writable by the account under which the application is running. It can be enabled or disabled by the TraceLevelSwitch set in the <system.diagnostics> section of the web.config file. If trace logging is turned on but no TraceLogFile is specified, debug output will be sent to the debug listener, and can be examined with a program such as DebugView.
TransferStage | TransferStage specifies the stage of an upload, which may be either web server or file server. On a web server, set TransferStage to 1. On a file server, set TransferStage to 2.
UseHttpModuleWithAspDotNet | FileUpEE's HttpModule intercepts an upload request, reads all the data, and writes it to a temp file chunk by chunk before sending it to ASP.NET. UseHttpModuleWithAspDotNet turns the installed filter on or off for ASP.NET uploads. To turn the installed filter off, set UseHttpModuleWithAspDotNet to 0. To turn the filter on, set UseHttpModuleWithAspDotNet to 1.


Example web.config file for FileUpEE application with HttpModule

<?xml version="1.0" ?>
    <configuration>
        <system.web>

            <!--This loads the FileUpEE HttpModule for this application. Version numbers
                      must match the FileUpEeModule.dll exactly. -->
            <httpModules>
                <add name="FileUpEeModule"
                    type="SoftArtisans.Net.FileUpEeFilter.Module.FileUpEeModule, FileUpEeModule,
                        version=x.x.x.x,
                        Culture=neutral,
                        PublicKeyToken=f593502af6ee46ae"/>
            </httpModules>

            <!--Allows pages with this file extension to be processed by ASP.NET. This value
                     must match the value assigned to the FilterASPDotNetFlagExtension
                     application key. -->
            <httpHandlers>
                <add verb="*" path="*.uplx" type="System.Web.UI.PageHandlerFactory"/>
            </httpHandlers>

            <customErrors mode="Off" />

            <!-- Two of these settings are important in relation to large file uploads:
                       executionTimeout: Sets the maximum time in seconds that the page can run.
                       Make sure to leave enough time to finish any uploads.
                       maxRequestLength: Sets the maximum size in kilobytes of the entire
                       request. The maximum allowed value for this is 2097151. This setting
                       is applied only to the first chunk doing chunked uploads and is therefore
                       less important. -->
            <httpRuntime
                    executionTimeout="1200"
                    maxRequestLength="102400" />

            <!-- Uncomment this section for .NET 2.0 applications -->
            <!-- <compilation>
                <buildProviders>
                    <add extension=".uplx" type="System.Web.Compilation.PageBuildProvider" />
                </buildProviders>
            </compilation> -->

        </system.web>
        <appSettings>

            <!-- All the following App Settings are required by the HttpModule and will
                        result in an error if removed -->

            <!-- Enable resumable uploads. -->
            <add key="Resumable" value="true" />

            <!-- Allow client to override the MaxKBytes settings for resumability testing by
                        sending "X-SaWsMaxKBytesToCancel" HTTP header. This should always be
                        turned off in production. -->
            <add key="AllowClientOverride" value="false" />

            <!-- Temp Directory is the cache directory that the httpModule will save
                        files to. This directory must be accessible by your ASPNET or
                        NETWORK_SERVICE user account with modify permissions. If impersonation
                        or another account is used, that account must have permissions. -->
            <add key="FileUpEeTempDir" value="C:\Temp\FileUpEe\Cache\" />

            <!-- Transfer stage 1= WebServer, 2= FileServer -->
            <add key="TransferStage" value="1" />

            <!-- Enable ASP.NET filtering - this should always be set to true if you want to
                        use the HttpModule. -->
            <add key="UseHttpModuleWithAspDotNet" value="true" />

            <!-- Extension to filter on. NOTE: this can only be a single extension; you
                        cannot have multiple filter extensions. If you want to use the
                        .uplx extension you will also need to change it here. -->
            <add key="FilterAspDotNetFlagExtension" value=".uplx" />

            <!-- Start filtering ASP.NET at N Kbytes. If you set this to 10 then only
                        files over 10K will get processed by the HttpModule. -->
            <add key="FilterAspDotNetAtNKiloBytes" value="0" />

            <!-- Stop caching upload if total request exceeds KBytes. After MaxKBytes is
                        reached then the HttpModule will still pass the first MaxKBytes of
                        the file to the ASP.NET page for processing. -->
            <add key="MaxKBytes" value="0" />

            <!-- Cancel upload if is exeeds KBytes. After MaxKBytesToCancel is reached
                        then the connection with the client will be dropped and the
                        HttpModule will not pass anything on to the ASP.NET page
                        for processing. -->
            <add key="MaxKBytesToCancel" value="0" />

            <!-- Enable server side Progress Indicator. -->
            <add key="ProgressIndicator" value="true" />

            <!-- Expected progress indicator querystring parameter for client to server progid. -->
            <add key="ProgressIndicatorParam" value="progressid" />

            <!-- Dynamically adjust the script timeout higher while data is being transferred. -->
            <add key="DynamicAdjustScriptTimeout" value="true" />

            <!-- Error Log Destination: set to 0 to disable, 1 to enable. -->
            <add key="ErrorLogDestination" value="0" />

            <!-- Error Log File sets the location of the log file. This directory needs to
                        exist and must be accessible by your ASPNET or NETWORK_SERVICE user
                        account with modify permissions. If impersonation or another account
                        is used, that account must have permissions. -->
            <add key="ErrorLogFile" value="C:\Temp\logs\FileUpEeModuleError.log" />

            <!-- Tracing log file location. Enabled/Disabled by the TraceLevelSwitch set
                        in the system.diagnostics section of the web.config. If trace logging
                        is turned on but no TraceLogFile is specified, debug output will be
                        sent to the debug listener, and can be examined with a program such
                        as DebugView. -->
            <add key="TraceLogFile" value="C:\Temp\logs\FileUpEeModuleTrace.log" />

            <!-- Buffer Size for the input stream - tune for best performance. -->
            <add key="FilterReadBufferNKiloBytes" value="32" />

            <!-- Maximum Read Buffer Memory in Kilobytes Value should be multiples
                        of MaxReadBufferNKilobytes -->
            <add key="MaxReadMemoryKiloBytes" value="16000"/>

            <!-- Temp File Stream buffer - tune for best performance. Maximum is 32K,
                        Minimum is 4K -->
            <add key="FileWriteBufferNKiloBytes" value="32" />
        </appSettings>
        <system.diagnostics>
            <switches>
                <!-- Turn tracing on or off. Tracing is used to create a debug log for the
                           httpModule, and is for use during testing or debugging. It should probably
                           be left off in production. Trace Log Level 0= Off, 1= Errors, 2= Warnings,
                           3= Info, 4= Verbose -->
                <add name="TraceLevelSwitch" value="0" />
            </switches>
        </system.diagnostics>
    </configuration>

Top


Installing FileUpEE for ASP

  • Upgrading to a New Version of FileUpEE
  • Automatic Installation
  • Manual Installation
  • The Resumable Upload Status Databases

Upgrading to a New Version of FileUpEE

If you are upgrading to a new version of FileUpEE, before installing the new version, remove the old version.

Automatic Installation

To create 3-tier upload and 3-tier download applications, you must install FileUpEE on both the web server and the file server.

To run the automatic installation, double-click FileUpEE.exe, and follow the InstallShield instructions.

During installation you will be asked if the machine on which you are installing is a web server or a file server. If you are installing on a development machine that functions as both a web server and a file server, select "Web server."

Manual Installation

To create 3-tier upload and 3-tier download applications, you must install FileUpEE on both the web server and the file server.

FileUpEE includes two sets of dll files in the folders COM and DotNet. The dlls in COM work only with ASP. The dlls in DotNet work with both ASP and ASP.NET, and cannot be installed on a server that does not have the ASP.NET Framework. If you are installing FileUpEE for ASP only and do not have the ASP.NET Framework, register the dlls in the COM folder. For instructions on installing the ASP/ASP.NET version of FileUpEE, see Installing FileUpEE for ASP.NET.

To install FileUpEE the first time, run the automatic installation. Once InstallShield has unpacked the dll files that contain FileUpEE, you can re-install FileUpEE manually (if, for example, you are moving FileUpEE to a different server):

  1. Make sure that you have MSXML 4.0 SP2 installed. If it is not not installed already, download the msxml.msi from Microsoft's MSXML 4.0 Service Pack 2 web page and install it on your server.
    In addition, you should make sure that there is no conflict on your machine with FileUpEE dependencies.

  2. Open a command prompt window and move to the directory FileUpEE\COM.
    For example, enter cd Program Files\SoftArtisans\FileUpEE\COM.

  3. Enter regsvr32 FileUpEE.dll. A dialog box will inform you that FileUpEE.dll registered successfully; click Ok.

  4. Enter regsvr32 MimeClient.dll. A dialog box will inform you that MimeClient.dll registered successfully; click Ok.

  5. Enter regsvr32 FileUpEEProgress.dll. A dialog box will inform you that MimeClient.dll registered successfully; click Ok.

  6. Enter iisreset to reset IIS.

Top

The Resumable Upload Status Databases

In a resumable upload, FileUpEE saves information about the upload in two upload status databases, one on the web server and one on the file server. If the upload from web server to file server is suspended, and the Resume method is called, FileUpEE will get the status of the upload - the number of bytes uploaded to the file server - from the file server database. FileUpEE will then resume the upload from the point at which it stopped.

There are two ways to set the connection string for an upload status database:

  • Set the ResumeConnectionString property for the specified upload database (Web server or file server).

    OR

  • Set the web server and file server connection strings in two udl files. On the web server, in WINDOWS\system32\fileupee.udl, save the web server's status database connection string. On the file server, in WINDOWS\system32\fileupee.udl, save the file server's status database connection string.

    To store a database connection string in a udl file:

    1. Go to C:\WINDOWS\system32.
    2. Right click within the system32 directory and select New -> Text Document.
    3. Name the file fileupee.udl.
    4. Double-click fileupee.udl to open it.
    5. Select the Provider tab.
    6. Select Microsoft Jet 4.0 OLE DB Provider, and click Next.
    7. Browse to FileUpEEWS.mdb if you are at the web server, or FileUpEEFS.mdb if you are at the file server.
    8. Click Test Connection.
The Internet user account must have Read, Write, and Modify access the directories containing the status databases. For the FileUpEE samples, that directory is FileUpEE\samples\BrowserBasedSamples\UploadSamples\Intermediate\Resume\ASP. For resumable uploads in ASP, make sure that the IUSR_MACHINENAME account has Read, Write, and Modify access to this directory. For security reasons the FileUpEE install package does not grant this access.

Top


install_xfileee

Installation Instructions

Unpacking SoftArtisans XFileEE

Client-side Installation and Instantiation

Upgrading SoftArtisans XFileEE

Removing SoftArtisans XFileEE

Signing XFileEE


Unpacking SoftArtisans XFileEE

  • Unpacking Using Automatic Installer
  • Unpacking XFileEE Manually

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

Automatic installation

Double-click FileUpEE-Installer-v5.1.1-Full.exe and follow the InstallShield instructions to unpack XFileEE as part of your FileUpEE install.

By default, the automatic installer copies two sets of dlls to the following directory: C:\Program Files\SoftArtisans\FileUpEE\XFile. One set is wrapped in the cabinet file, SAXFileEE.cab, that is signed by SoftArtisans and the other set is found as a collection of individual dlls in the directory. The following table lists the files installed with XFileEE:

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

Note: SAXFShExEE.dll (shell extension) is not included in the SoftArtisans signed CAB file.

XFileEE 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 XFileEE client side/HTML code samples, the dlls must be available in a downloadable CAB file or distributed and installed by some other client-side method. 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.

  2. 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.

  3. 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, you will need to install XFileEE. See Client-Side Installation for more information.

Unpacking XFileEE Manually

To unpack SoftArtisans XFileEE the first time, run the automatic installer. Once InstallShield has unpacked the files that contain XFileEE, you can move XFileEE manually (if, for example, you are moving the component to a different server). By default, the automatic installer unpacks 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 following table lists the files unpacked with each edition:

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


Client-Side Installation & Instantiation

Client-side Installation and Instantiation

CAB Installation in Non-Admin mode

As of version 2.5.1, XFileEE�s CAB installation fully supports non-administrative ActiveX installation in Internet Explorer 8on platforms running Windows Vista and later. In prior versions of XFileEE, regardless of the version of Internet Explorer or Windows OS, the user needed to have administrative privileges to be able to install through Internet Explorer. Now with version 2.5.1, on Windows Vista and later, a standard user can install XFileEE 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 XFileEE on the client is handled by the browser when it encounters a request to instantiate and XFileEE object. If the browser cannot locate the needed dlls, it will make a request to the server for the XFileEE cab, and install these dlls. All of this depends on proper use of the HTML <OBJECT> tag, which is used to instantiate XFileEE in the browser.

The <OBJECT> tag

To create client-side instances of XFileEE'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 XFileEE's visual upload control, use,

<OBJECT classid="CLSID:7B7929AB-E06A-4508-BE68-1CC7A6997808" id="AXFFile"
      codebase="[path]/saXFileEE.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 XFileEE'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 SAXFileEE.cab (see the table 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, SAAXFileEE.dll file) is 2.4.1.20454. Add "version=2,4,1,20454" to the codebase attribute:

<OBJECT classid="CLSID:7B7929AB-E06A-4508-BE68-1CC7A6997808" id="AXFFile"
      codebase="saxfile.cab#version=2,4,1,20454">

This will assure that your end users are running at least this version of the control. Please see Upgrading XFileEE 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 XFileEE 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.

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


Removing SoftArtisans XFileEE

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

Removing XFileEE from the Server

Automatic Removal

If you installed XFileEE by running the SoftArtisans FileUpEE installer package on the server, you can run the uninstaller to remove the Program Folder contents (samples, dlls, documentation). Note that if FileUpEE is uninstalled using the uninstaller, XFileEE is also uninstalled.

  • Open the Control Panel and select Add/Remove programs
  • Select "SoftArtisans FileUpEE"
  • Click Change/Remove
  • In the SoftArtisans FileUpEE InstallShield Wizard, make sure that the "Modify" radio button is checked and click Next
  • Uncheck the checkbox beside "XFileEE" and click Next to automatically remove XFileEE from the server
Manual Removal of XFileEE

    As XFileEE is a client-side component and is not registered on the server, simply delete the XFileEE dlls: XFileEE.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 XFileEE from the Client", below.

Removing SoftArtisans XFileEE from the Client

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

  1. Close all instances of Internet Explorer to remove XFileEE 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 XFileEE controls that have been installed.

If these controls do not appear in the Internet Explorer Temporary Internet Files Folder after using XFileEE in a Web page on the client, then it is possible that the XFileEE dlls were registered directly with regsvr32, and must be removed using the regsvr32 unregister command. From the command line, perform the command "regsvr32 /u dll name" for each of the XFileEE dlls, then reset IIS using the "iisreset" command.

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 XFileEE

Upgrading XFileEE

Upgrading the Server Installation of XFileEE

If the SoftArtisans XFileEE installer package was run on the server, it is best to run the uninstaller before attempting to upgrade your server installation of XFileEE. 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 XFileEE from the client, as well.

Upgrading XFileEE on the client

To upgrade XFileEE on the client, you must first locate your XFileEE 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 XFileEE 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 XFileEE objects, including FileManager and Archive.

  1. Extract the appropriate file from the SAXFileEE.cab (see the table 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 (AXFFileEE object, SAAXFileEE.dll file) is 2.4.1.20454. Add "version=2,4,1,20454" to the codebase attribute:

<OBJECT classid="CLSID:7B7929AB-E06A-4508-BE68-1CC7A6997808" id="AXFFile"
      codebase="saXFileEE.cab#version=2,4,1,20454">

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

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 | SAAXFileEE.dll | 53B29E97-9753-44B4-AE57-D51322B2BD49
SoftArtisans Archive | SAArch.dll | D3400FEE-041F-11D3-B1C5-00A0C9B4587A
SoftArtisans FileManager | SAFilMgr.dll | E7B62F4E-82F4-11D2-BD41-00105A0A7E89


Signing XFileEE

Signing SAXFileEE

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 XFileEE 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 XFileEE dlls and sign the cab file yourself.

XFileEE's automatic installation installs two sets of dlls. One set is wrapped in a cabinet file, SAXFileEE, that is signed by SoftArtisans and the other set is a collection of individual dlls. XFileEE 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 XFileEE 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.

  2. 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.

  3. 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 XFileEE, SAXFileEE.cab, 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), XFileEE will display a dialog asking the user to accept or refuse the upload or download.

Only the CAB version of SoftArtisans XFileEE will display the file-transfer confirmation dialog. If If the non-CAB version of XFileEE (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. To customize Shell Extension uploads, include SAXFShExEE.dll in your CAB file.

The following table lists the files installed with XFileEE:

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

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

SoftArtisans XFileEE Module | XFileEE.dll, SAAXFileEE.dll, [SAXFShExEE.dll], XFileEE.inf Inclusion of 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, XFileEE.inf
SoftArtisans FileManager Module | SAFilMgr.dll, XFileEE.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 XFileEE.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 XFileEE.inf.
  2. Remove from XFileEE.inf all references to XFileEE.dll, SAAXFileEE.dll, SAFilMgr.dll, and SAFmgPws.dll.

When creating a CAB for SoftArtisans Archive or SoftArtisans FileManager, remove from XFileEE.inf all references to SAXFShExEE.dll, as well as references to XFileEE.dll and SAAXFileEE.dll.

If you are creating a CAB including SoftArtisans XFileEE (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 SAXFileEE.cab to the new directory.
  2. Find xfileee.dll and saaxfileee.dll in XFileEE's installation directory (usually, C:\Program Files\SoftArtisans\FileUpEE\XFile).
  3. Copy the installation directory's XFileEE.dll and saaxfileee.dll over the extracted xfileee.dll and saaxfileee.dll.
  4. Create a new CAB from the files in the extracted CAB directory.

To sign XFileEE 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. XFileEE's Unsigned Dlls Files
    These are the individual dlls in XFileEE's installation directory (the same directory that contains XFileEE.cab). The installation directory is usually C:\Program Files\SoftArtisans\FileUpEE\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 XFileEE's unsigned dll files. These are the individual dlls in XFileEE's installation directory (the same directory that contains XFileEE.cab). The installation directory is usually C:\Program Files\SoftArtisans\FileUpEE\XFile.

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


Dependencies

In addition to the Requirements listed in the Introduction, FileUpEE is dependent on the Microsoft XML parser(MSXML) and Windows HTTP Services(WinHTTP).

MSXML is distributed with various Microsoft products. If you do not have the following dlls on your web and file servers, please go to the Microsoft knowledgebase article "List of Microsoft XML Parser (MSXML) versions" for information on how to obtain the MSXML libraries:

msxml.dll
msxml2.dll
msxml2r.dll
msxml3.dll
msxml3a.dll
msxml3r.dll
msxml4.dll
msxml4r.dll
msxmlr.dll

The system DLL WinHTTP(winhttp.dll) must also be installed on your web and file servers in order for FileUpEE to work.

All of these files are typically found in "C:\WINDOWS\System32" as part of other Microsoft product distributions.

Top


FileUpEE Registry Keys

FileUpEE includes several registry keys that allow you to fine-tune upload performance. To change a registry key value:

  1. Open the Start menu and select Run...

  2. Enter regedit and click Ok.

  3. Open the folder HKEY_LOCAL_MACHINE\SOFTWARE\SoftArtisans\FileUpEE\Parameters.

  4. Double click the key you want to update. An Edit DWORD Value dialog will open.

  5. In the Value Data field, enter a new value for the key.

  • Actively Supported Registry Keys
  • Deprecated HttpModule Registry Keys
  • Deprecated ISAPI Filter Registry Keys

Actively Supported Registry Keys

These registry keys change settings for the FileUpEE COM object. Please note that the FileUpEE COM object is referenced by the .NET assemblies of FileUpEE, meaning that these registry keys must be considered in ASP.NET projects as well.

FileUpEE Registry Keys
AuditLogDatabase

When AuditLogDestination is set to 2, FileUpEE will save log records in a database. AuditLogDatabase sets the connection string for FileUpEE's audit log database.

Use the database FileUpEEWS.mdb for audit logging on the web server, and FileUpEEFS.mdb for audit logging on the file server. You will find these databases in doc-samples\Samples\UploadSamples\Intermediate\Resume\ASP. You can generate a new audit log database with FileUpEE.CreateDatabase. To see the audit log, open the table FileUpEE. The State column contains an SAUploadState value.

SAUploadState Values
saTransferComplete | 0
saTransferConnecting | 1
saTransferTransferring | 2
saTransferSuspended | 3
saTransferError | 4
saTransferCancelled | 5
saTransferIncomplete | 6
saTransferNotStarted | 7

The sample databases included with FileUpEE and the databases generated by FileUpEE.CreateDatabase are Access databases. To generate a set of tables for an Oracle or SQL Server database, run the script FileUpEE.sql. The script is included in the folder SoftArtisans\FileUpEE.

Note

When audit logging is on, FileUpEE will create an audit log record for each file transfer. On a busy system, this can make the destination very large. If you enable logging, remember to delete old items in the log destination.

AuditLogDestination

AuditLogDestination sets the type of audit logging that FileUpEE will use. By default, FileUpEE will not create an audit log. To enable audit logging, set AuditLogDestination to one of the following values:

1 | The audit log will be a file set by AuditLogFile.
2 | FileUpEE will save log records in a database set by AuditLogDatabase.
4 | File transfers will be logged in the Windows EventLog. To view the log go to Start/Control Panel/Administrative Tools/Event Viewer.
8 | File transfers will be logged in the system debugger. You can view the records with tools such as Sysinternals DebugView [image] .

If AuditLogDestination is set to 1, set AuditLogFile. If AuditLogDestination is set to 2, set AuditLogDatabase. By default AuditLogDestination is set to 0 and audit logging is disabled.
AuditLogFile

AuditLogFile sets the path and file name of FileUpEE's audit log file. When audit logging is enabled, FileUpEE will create an audit log for each file transfer. FileUpEE will save the audit log to a file if AuditLogDestination is set to 1.
DebugLevel

DebugLevel can be used in conjunction with DebugLogFile to enable debugging. The debug level can be set according to the level of detail you wish the log files to contain.

Values | Level of Detail
0 | No debug output.
1 | Outputs trace log that includes which methods are used.
2 | More detailed debugging.
3 | Verbose debugging. Includes dumps of headers and the SOAP envelope. It is not recommended to use this level of debugging in a production environment as it will slow the application.
It is also possible to override the registry and control logging in your code. DebugLevel and DebugLogFile have been added as properties to the FileUpEe object.

objFileUpEe.DebugLevel = [Log Level as Integer] oFUEE.DebugLogFile = [Debug
                Log Path as String]

The ability to turn the logging on and off in code means that specific sections of the code can now be targeted for debugging. If debug logging isn't used in the registry but is turned on in code, the logging will be unable to start until the FileUpEe object has fully initialized. This means that any errors thrown during the initialization process will not be caught.
DebugLogFile

DebugLogFile sets the path and file name of FileUpEE's debug log file. Debug logging must be enabled using the DebugLevel registry key.
DynamicAdjustScriptTimeout (ASP only) If this key is set to 1, IIS's ScriptTimeout value will be increased until an upload or download is complete. Use DynamicAdjustScriptTimeout to ensure that large uploads and downloads will not be timed out. DynamicAdjustScriptTimeout is set to 1 by default. To disable DynamicAdjustScriptTimeout, set it to 0.
ErrorLogDatabase

ErrorLogDatabase sets the connection string for FileUpEE's error database. FileUpEE will log errors in a database if ErrorLogDestination is set to 2.

Use the database FileUpEEWS.mdb for error logging on the web server, and FileUpEEFS.mdb for error logging on the file server. You will find these databases in doc-samples\Samples\UploadSamples\Intermediate\Resume\ASP. You can generate a new audit log database with FileUpEE.CreateDatabase. To see the error log, open the Errors table.

The sample databases included with FileUpEE and the databases generated by FileUpEE.CreateDatabase are Access databases. To generate a set of tables for an Oracle or SQL Server database, run the script FileUpEE.sql. The script is included in the folder SoftArtisans\FileUpEE.
IgnoreUnknownCA 3-tier SSL uploads can fail if the webserver does not have an up-to-date root certificate for the Certifying Authority for the SSL certificate on the fileserver. Because webservers do not usually make HTTP requests to other servers, this situation may not be noticed until someone tries to use FileUpEe in a 3-tier file transfer application. If during development, you experience problems with 3-tier SSL uploads, this key can be enabled (set to "1") to have FileUpEe instruct WinHttp to ignore the problem and go ahead and send the request. This key should not be used in a production environment as the transfer will not be secure. It is meant as a work-around during development until a valid certificate can be obtained.
UseMemory (ASP Only)

If UseMemory is set to 1, FileUpEE will store uploaded data in memory until the data is saved. If UseMemory is set to 0, uploaded data will be cached in a temporary directory until it is saved. UseMemory is set to 0 by default.

The benefits of caching in memory may be:

  • Security
    No files are written to disk until the upload is saved.

  • Performance
    Caching files in memory can increase the speed of uploads. However, before setting UseMemory to True you should consider other factors affecting the upload, such as, available memory on the file server, how active the server is, and the size of the upload. If an upload is larger than 1-5 MB (depending on the system load), caching in memory will probably not improve performance.

Do not set UseMemory to 1 if you expect very large uploads (100 MB or more).

Note

This setting has no effect during ASP.NET uploads because the HttpModule caches the entire upload to disk.

Deprecated ISAPI Filter Registry Keys

These registry keys change settings for the ISAPI filter, which is deprecated in this edition of FileUpEE. Though these registry keys are created by the automatic installer, they are not used by default in FileUpEE.

Deprecated HTTPModule Registry Keys

These registry keys change settings on older versions of the FileUpEE HttpModule which have been deprecated for releases 5.1 and up. These registry keys are created by the automatic installer, but are not used by FileUpEE or the HttpModule. To change settings on the currently-supported HTTPModule, edit the web.config file for your web application.

Deprecated HTTPModule Registry Keys
ErrorLogDestination

ErrorLogDestination sets the type of error logging that FileUpEE will use. By default, FileUpEE will not create an error log. To enable error logging, set ErrorLogDestination to one of the following values:

SALogDestination Values
1 | Errors will be logged in the file set by ErrorLogFile.
2 | Errors will be logged in a database set by ErrorLogDatabase.
4 | Errors will be logged in the Windows EventLog. To view the errors go to Start/Control Panel/Administrative Tools/Event Viewer.
8 | Errors will be logged in the system debugger. You can view the errors with tools such as Sysinternals DebugView [image] . If ErrorLogDestination is set to 1, set ErrorLogFile. If ErrorLogDestination is set to 2, set ErrorLogDatabase.
ErrorLogFile

ErrorLogFile sets the path and file name of FileUpEE's error log file. FileUpEE will log errors in a file if ErrorLogDestination is set to 1.
FileUpEETempDir Note: If both IsapiTempDir and FileUpEETempDir are set FileUpEE will use the value of FileUpEETempDir. The IsapiTempDir registry key is deprecated in FileUpEE 5. Use FileUpEETempDir instead.

FileUpEE's interceptors - the ISAPI filter and the HttpModule - cache request data before it is processed by ASP or ASP.NET. By default, the cache location is the system's default directory for cached files, which is determined by the system environment variable TEMP. To set a different temp directory for either interceptor, change the value of FileUpEETempDir.

The temp directory must be on a local drive, not on a network shared drive, because the interceptors write to the server hard drive as the local SYSTEM account and this account does not have access to network drives.
FilterAspDotNetAtNKiloBytes This key specifies the smallest ASP.NET upload size - in kilobytes - for which FileUpEE will use the ISAPI filter (IIS 5) or the HttpModule (IIS 6). If the size of an ASP.NET upload equals or is greater than the value of FilterAspDotNetAtNKiloBytes, and UseIsapiFilterWithAspDotNet is set to 1, FileUpEE's ISAPI filter or HttpModule will be used to process the upload. The default value of FilterAspDotNetAtNKiloBytes is 0, meaning that the filter will intercept all uploads to files with the extension .uplx.

FilterAspDotNetAtNKiloBytes will have no effect if the registry key UseIsapiFilterWithAspDotNet is set to 0 (disabled).

Remember: In ASP.NET, the ISAPI filter and HttpModule only intercept requests for files with the extension .uplx, regardless of the values of FilterAspDotNetAtNKiloBytes and UseIsapiFilterWithAspDotNet. If, for example, UseIsapiFilterWithAspDotNet is set to 1 (enabled), and FilterAspDotNetAtNKiloBytes is set to 4000000, and the server-side upload processing page is WebServer.aspx, the filter will not intercept uploads that are equal to or greater than 4000000 KB (4 GB).
FilterAspDotNetFlagExtension For performance reasons, FileUpEE's ISAPI filter (IIS 5) and HttpModule (IIS 6) do not intercept all ASP.NET requests. By default, the filters 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 servers with unnecessary use of the filters.

FilterAspDotNetFlagExtension allows you to change the file extension used to signal the filters in ASP.NET (.uplx) to a different extension of up to seven characters. By using a file extension other than .uplx you can hide your web server implementation (Windows/IIS) from potential hackers.
MaxKBytes

MaxKBytes sets a file size limit for an upload. MaxKBytes is a per-file limit, not a limit for a whole multiple-file upload. For each file in an upload, FileUpEE will stop writing the file to disk at the value of MaxKBytes. Note that incomplete files will be saved.

When MaxKBytes is set to zero, there is no size limit for uploaded files. MaxKBytes is set to zero by default.

MaxKBytesToCancel

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.

Setting MaxKBytesToCancel may reduce the threat of a Denial of Service (DoS) attack on the file server. When an upload size hits MaxKBytesToCancel, the connection to the server will be terminated, the ASP.NET page will finish executing, and the ASP.NET thread will be freed.

When MaxKBytesToCancel is set to zero, there is no size limit for uploaded files. MaxKBytesToCancel is set to zero by default.

ProgressIndicator | Set ProgressIndicator to 1 to enable FileUpEE's progress indicator. ProgressIndicator is set to 0 by default.
ProgressIndicatorParam | When a request is intercepted by the ISAPI filter or the HttpModule, it is the interceptor that updates the progress indicator. For performance reasons, you can disable the progress indicator functionality of the interceptors. There is a slight performance increase when the functionality is turned off. To turn off progress indicator updating by the interceptors, set ProgressIndicatorParam to 0. To turn this feature on, set ProgressIndicatorParam to 1.
Resumable

When Resumable is set to 1 on both the web server and the file server, FileUpEE will be able to resume an upload from web server to file server that was suspended because of a network connection failure. Resumable is set to 0 (disabled) by default.
TransferStage

TransferStage specifies the stage of an upload, which may be either web server or file server. On a web server, set TransferStage to 1. On a file server, set TransferStage to 2.
UseHttpModuleWithAspDotNet

FileUpEE's HttpModule (IIS 6) intercepts an upload request, reads all the data, and writes it to a temp file chunk by chunk, before sending it to ASP.NET. UseHttpModuleWithAspDotNet turns the HttpModule on or off for ASP.NET uploads. To turn the installed filter off, set UseHttpModuleWithAspDotNet to 0. To turn the filter on, set UseHttpModuleWithAspDotNet to 1.

Deprecated ISAPI Filter Registry Keys
FilterAspAtNKiloBytes | This key specifies the smallest ASP upload size - in kilobytes - for which FileUpEE will use the ISAPI filter. If the size of an ASP upload equals or is greater than the value of FilterAspAtNKiloBytes and UseIsapiFilterWithAsp is set to 1, FileUpEE's ISAPI filter will be used to process the upload. The default value of FilterAspAtNKiloBytes is 4000000 (4-GB). By default the filter is not enabled for ASP. FilterAspAtNKiloBytes will have no effect unless the registry key UseIsapiFilterWithAsp is set to 1. Remember: In ASP, the ISAPI filter only intercepts requests for files with the extension .upl, regardless of the values of FilterAspAtNKiloBytes and UseIsapiFilterWithAsp. If, for example, UseIsapiFilterWithAsp is set to 1 (enabled), and FilterAspAtNKiloBytes is set to 4000000, and the server-side upload processing page is WebServer.asp, the ISAPI filter will not intercept uploads that are equal to or greater than 4000000 KB (4 GB).
FilterAspFlagExtension | For performance reasons, FileUpEE's ISAPI filter in IIS 5 does not intercept all ASP requests. By default, the ISAPI filter intercepts ASP requests for files with the extension .upl. Files with the extension .asp will not be processed by the filter and will be sent directly to ASP. This prevents burdening servers with unnecessary use of the ISAPI filter. FilterAspFlagExtension allows you to change the file extension used to signal the filters in ASP (.upl) to a different extension of up to seven characters. By using a file extension other than .upl you can hide your web server implementation (Windows/IIS) from potential hackers.
IsapiBufferSize | FileUpEE's ISAPI filter intercepts an upload request, reads all the data, and writes it to a temp file chunk by chunk, before sending it to ASP or ASP.NET. IsapiBufferSize specifies the size of these data chunks. Note that in FileUpEE Version 4, changing the value of this key will have no effect.
IsapiTempDir | Note: The IsapiTempDir registry key is deprecated in FileUpEE 5. Use FileUpEETempDir instead. If both keys are set, FileUpEE will use the value of FileUpEETempDir. FileUpEE's interceptors - the ISAPI filter and the HttpModule - cache request data before it is processed by ASP or ASP.NET. By default, the cache location is the system's default directory for cached files, which is determined by the system environment variable TEMP. To set a different temp directory for the ISAPI Filter, you can change the value of IsapiTempDir. The ISAPI temp directory must be on a local drive, not on a network shared drive, because the ISAPI filter writes to the server hard drive as the local SYSTEM account and this account does not have access to network drives.
LockedFileRetryTime | If a file is uploaded to a virtual directory, and then requested via HTTP, IIS or another process may lock the requested file. For example, if a user uploads an image file, and immediately opens the uploaded image in the browser, IIS may lock the file for up to 30 seconds after it was requested via HTTP. So, if the same user tries to upload a replacement of the image file immediately after viewing it, the upload will fail. IIS may continue locking the file for as long as there are outstanding requests to the file. A heavily requested file may stay locked for minutes or hours at a time. In addition to IIS, web server processes such as content indexing, backup utilities, or virus scanners, may lock files. By default, FileUpEE will try overwriting the locked file once per second for up to 45 seconds. To change this value, edit LockedFileRetryTime.
UseIsapiFilterWithAsp | FileUpEE's ISAPI filter intercepts an upload request, reads all the data, and writes it to a temp file chunk by chunk, before sending it to ASP or ASP.NET. UseIsapiFilterWithAsp turns the ISAPI filter on or off for ASP uploads. To turn the filter off, set UseIsapiFilterWithAsp to 0. To turn the filter on, set UseIsapiFilterWithAsp to 1. UseIsapiFilterWithAsp is set to 0 by default.
UseIsapiFilterWithAspDotNet | FileUpEE's ISAPI filter intercepts an upload request, reads all the data, and writes it to a temp file chunk by chunk, before sending it to ASP.NET. UseIsapiFilterWithAspDotNet turns the ISAPI filter on IIS 5 for ASP.NET uploads. To turn the ISAPI filter off, set UseIsapiFilterWithAspDotNet to 0. To turn the filter on, set UseIsapiFilterWithAspDotNet to 1.


Security Considerations

  • ASP.NET Security Settings
  • ASP Security Settings
  • General Guidelines
ASP.NET Security Settings

FileUpEE's interceptor - the HttpModule - caches request data before it is processed by ASP.NET.

The HttpModule writes to the hard drive as the same account as the application under which it is running, and can write to any directory on the server. The HttpModule can cache to a network share, but only if the account has network privileges.

The location of the temporary directory can be configured in the web.config file. To set the HttpModule temp directory:

  1. Open the web.config file for the web site.

  2. Navigate to the FileUpEETempDir application key under the <appSettings> node.

  3. In Value attribute, enter the path and folder name.

In ASP.NET, if impersonation is disabled - as it is by default - FileUpEE executes in the context of the NETWORK_SERVICE account (in IIS 6) or the ASPNET account (in IIS 5.1). To allow uploads, the NETWORK_SERVICE account or ASPNET account must have Read, Write, and Modify permissions for FileUpEE's temporary and destination folders. An upload's destination folder is set in code by DestinationDirectory, DestinationPath, or SaveAs.

In a 3 tier upload (client -> web server -> file server) FileUpEE will use two temporary folders, one on the Web server and one on the file server. Both temporary folders require Read, Write, and Modify permissions for the ASPNET or authenticated user account under which the application is running on that machine.

Under ASP.NET impersonation is controlled in the .NET configuration file for your web application - web.config or machine.config (For information about these files, see Installing FileUpEE for ASP.NET). If no userName or password is set, the application will run in the user set in IIS just as it would for an ASP application. To enable impersonation, set impersonate to true in the <identity> node in the <system.web> section of web.config or machine.config:

<identity impersonate="true" userName="" password=""/>

Top

ASP Security Settings

In ASP, FileUpEE executes in a specific user context:

  • IUSR_MACHINENAME (The default anonymous user account)

    OR

  • An authenticated user account

To allow uploads, the IUSR_MACHINENAME or authenticated user must have Read, Write, and Modify NTFS permissions for FileUpEE's temporary and destination folders. An upload's destination folder is set in code by DestinationDirectory, DestinationPath, or SaveAs. The temporary directory for an upload can be set in code by the property TempStorageLocation. If you do not assign a value to TempStorageLocation, uploads will be cached in the system's default directory for cached files, which is determined by the system environment variable TEMP.

To change the system's default directory for cached files, reset the TEMP environment variable, as follows:

  1. Open the Control Panel.

  2. Select System.

  3. Select the Advanced tab.

  4. Click Environment variables...

  5. Select TEMP from the System Variables list.

  6. Click Edit.

  7. Enter a new Variable Value, and click Ok.

In a 3 tier upload (client -> web server -> file server) FileUpEE will use two temporary folders -- one on the Web server and one on the file server. Both temporary folders require Read, Write, and Modify permissions for the anonymous or authenticated user.

If UseMemory is set to True, FileUpEE will not write temporary files and it is not necessary to set permissions for a temporary directory.

Top

General Guidelines
  • Don't allow write access to critical directories such as "C:\", "C:\WINNT", and "C:\WINNT\System32".

  • Do audit scripts to ensure that ASP developers are writing to correct locations.

  • Do audit scripts to ensure that an instance of FileUpEE is not created as an Application variable.

  • Do use the TempStorageLocation property to set an appropriate temporary directory. FileUpEE needs a file cache to function. If the TempStorageLocation property is not set, FileUpEE will use the default temporary directory of the system.

  • Don't prevent the IUSR_MACHINENAME account for ASP from reading the system registry, especially the HKEY_CLASSES_ROOT hive.

  • Don't prevent the IUSR_MACHINENAME account (for ASP) or the ASPNET or NETWORK_SERVICES accounts (for ASP.NET) from reading FileUpEE.DLL or MimeClient.dll.

  • Don't leave the default Everyone-Everything permission on a publicly available web server.

Top


Notes for ISPs

Licensing and Sharing SoftArtisans FileUpEE

SoftArtisans FileUpEE is licensed on a per-CPU basis. There are no per-server, per-user, per-processor, or per-concurrent upload license costs. If the ISP is hosting multiple sites or clients on a single server, every site or client on that server can create an instance of FileUpEE and perform uploads.

If a single customer purchases FileUpEE and the ISP installs it on their server, FileUpEE will automatically be available to all customers on that server. You can limit usage of the FileUpEE components (FileUpEE.dll, MimeClient.dll, and FileUpEEProgress.dll) to a single customer.

An ISP customer cannot install FileUpEE without the assistance of the ISP. Even if your customer transfers the DLL files to your server, administrator access is required to register the DLLs in the system registry.

When a customer is interested in FileUpEE, some ISPs elect to purchase the tool because:

  • The ISP is directly supported by SoftArtisans rather than passing through the intermediary of their customer.
  • The upload and secure download features of FileUpEE are additional features that can be offered by the ISP to prospective customers.
Disallowing Sharing of SoftArtisans FileUpEE

By default, FileUpEE will be available to all customers hosted on your web site. To restrict usage of FileUpEE to particular virtual servers or sites:

  • Create a specific NT account with "log on locally" rights.
  • Within the IIS Microsoft Management Console, set the Anonymous user for the chosen site to be the newly created account.
  • Ensure that the NTFS permissions on FileUpEE.DLL allow access by the newly created account only, and not IUSR_MachineName . This will prevent other users from creating an instance of FileUpEE.

You cannot limit the use of FileUpEE's deprecated ISAPI filter to a single customer. The filter will be available to all web sites hosted on the server where the filter is installed. However, the filter will only intercept requests for files with the extension .upl.

Auditing Your web Sites

For maximum security, it would be prudent to occasionally audit your customer's code. In particular, you should verify:

  • That the destinations of the uploads are in appropriate directories.
  • That an instance of FileUpEE is not created as an application variable. Creating an instance of FileUpEE as an application variable is a security risk.


Removing FileUpEE for ASP.NET

Unregistering using the Automatic Uninstaller

If FileUpEE was installed with the automatic installer, use Add/Remove Programsto unregister and remove FileUpEE and all of its associated documentation and samples:

  1. From the Start menu, select Settings -> Control Panel.

  2. Double-click Add/Remove Programs.

  3. Select SoftArtisans FileUp Enterprise Edition.

  4. Click the Change/Remove button to remove the old copy of FileUpEE.

Unregistering manually

If FileUpEE.dll, MimeClient.dll, and FileUpEEProgress.dll were manually registered with regsvr32, you must manually unregister the dlls and delete them. These uninstall instructions will also be effective if you installed with the automatic installer.

To manually remove FileUpEE:

  1. Unregister the dll Files
    1. Open a DOS prompt window.

    2. Go to FileUpEE's COM directory.

    3. Enter regsvr32 FileUpEE.dll /u and click Ok.

    4. Enter regsvr32 MimeClient.dll /u and click Ok.

    5. Enter regsvr32 FileUpEEProgress.dll /u and click Ok.

    6. To reset IIS, enter iisreset.

  2. Delete these files from both FileUpEE/DotNet and FileUpEE/COM:
    • FileUpEE.dll
    • MimeClient.dll
    • FileUpEEProgress.dll
    • FileUpEeIsapi.dll (from COM folder)
    • FileUpEeModule.dll (from DotNet folder)
    • FileUpEeErrorMsgs.dll

Delete FileUpEE DLLs from bin directories

If you used FileUpEE in ASP.NET, you may have copies of FileUpEE.dll, MimeClient.dll, FileUpEeModule.dll and FileUpEEProgress.dll in several bin directories. Delete all copies.

Delete FileUpEE DLLs from temp directories

If you used FileUpEE in ASP.NET, you may have copies of FileUpEE.dll, MimeClient.dll, FileUpEeModule.dll and FileUpEEProgress.dll in several temporary directories. Navigate to C:\WINDOWS\Microsoft.NET\Framework\vx.x.xxxx\Temporary ASP.NET files\ and search for your FileUpEE projects. Delete all copies from each temporary directory.

Remove the ASP.NET Assemblies from the Global Assembly Cache

If you have added the ASP.NET FileUpEE Assemblies to the cache, you must remove them in order for your uninstall to be complete.

  1. Open a DOS prompt window.

  2. Go to FileUpEE's DotNet directory.

  3. Enter gacutil.exe /u FileUpEE and click Ok.

  4. Enter gacutil.exe /u MimeClient and click Ok.

  5. Enter gacutil.exe /u FileUpEEProgress and click Ok.

  6. Enter gacutil.exe /u FileUpEEModule and click Ok.

  7. Delete the following lines from machine.config:
    <add assembly="FileUpEE, Version=x.x.x.x, Culture=neutral, PublicKeyToken=f593502af6ee46ae"/>
<add assembly="MimeClient, Version=x.x.x.x, Culture=neutral, PublicKeyToken=f593502af6ee46ae"/>
<add assembly="FileUpEEProgress, Version=x.x.x.x, Culture=neutral, PublicKeyToken=f593502af6ee46ae"/>
<add assembly="FileUpEEModule, Version=x.x.x.x, Culture=neutral, PublicKeyToken=f593502af6ee46ae"/>


Removing FileUpEE for ASP

Automatic Removal

If FileUpEE was installed with the automatic installer, use Add/Remove Programsto unregister and remove FileUpEE and all of its associated documentation and samples:

  1. From the Start menu, select Settings -> Control Panel.

  2. Double-click Add/Remove Programs.

  3. Select SoftArtisans FileUp Enterprise Edition.

  4. Click the Change/Remove button to remove the old copy of FileUpEE.

Manual Removal

If FileUpEE.dll, MimeClient.dll, and FileUpEEProgress.dll were manually registered with regsvr32, you must manually unregister the dlls and delete them. These uninstall instructions will also be effective if you installed with the automatic installer.

To manually remove FileUpEE:

  1. Unregister the dll Files
    1. Open a DOS prompt window.

    2. Go to FileUpEE's COM directory.

    3. Enter regsvr32 FileUpEE.dll /u and click Ok.

    4. Enter regsvr32 MimeClient.dll /u and click Ok.

    5. Enter regsvr32 FileUpEEProgress.dll /u and click Ok.

    6. To reset IIS, enter iisreset.

  2. Delete these files from both FileUpEE/DotNet and FileUpEE/COM:
    • FileUpEE.dll
    • MimeClient.dll
    • FileUpEEProgress.dll
    • FileUpEeIsapi.dll
    • FileUpEeErrorMsgs.dll
    • FileUpEeModule.dll


Quick Start

A Simple Upload in ASP

A Simple Upload in ASP.NET

A 3-tier Upload

Download a File


A Simple Upload in ASP

The following tutorial explains how to make an application that uploads a file from a client to a web server by using an HTML form to submit the upload from the client. SoftArtisans FileUpEE receives and processes the upload on the web server.

To allow file uploads, NTFS permissions must be set appropriately for FileUpEE's temporary and destination directories. This example saves the upload to the folder FileUpEE\doc-samples\samples\temp. The IUSR_MACHINENAME or authenticated user account must have Read, Write, and Modify access to this folder. For more information, see Security Considerations.

The example uses an HTML form to upload the file from the client. The HTML form submitting the file must contain:

  • A <form> ACTION attribute that calls the upload processing script on the server.

  • The <form> tag attribute ENCTYPE="multipart/form-data".

  • An <input type="file"> tag, including a name attribute.

On the web server, FileUpEE receives and saves the uploaded file. In the FileUpEE code, the following lines process the upload request, and save the uploaded file:

  • Set oFileUpEE = Server.CreateObject("SoftArtisans.FileUpEE")
    Creates an instance of the FileUpEE object.

  • oFileUpEE.TransferStage = saWebServer
    This property tells FileUpEE the stage of the file transfer, that is, the server on which the current code should run. The transfer stage can be set to saWebServer or saFileServer. The TransferStage property is required. Set this property immediately after creating an instance of FileUpEE.

  • oFileUpEE.ProcessRequest Request, False, False
    The ProcessRequest method passes the Request object to FileUpEE. The collection of transferred files is not available until after ProcessRequest is called. In addition to the ASP Request object, ProcessRequest takes two boolean parameters:

    SoapRequest
    The SoapRequest parameter tells FileUpEE whether the file transfer is a SOAP request or not. Since the web server in this tutorial receives a form-based request and not a SOAP request, SoapRequest is set to false.
    AutoProcess
    If the AutoProcess parameter is set to true, FileUpEE will process the Request according to the SOAP payload (the XML document tranferred with a SOAP request), and it is not required to "manually" save the files by calling FileEe.Save in the script that passes true as the AutoProcess parameter of ProcessRequest. AutoProcess can only be true if the script is processing a SOAP request. This tutorial's web server is processing a form-based file upload, not a SOAP request, so AutoProcess must be false.

  • oFileUpEE.DestinationDirectory = Server.MapPath("/FileUpEE/samples/temp")
    Sets the destination directory for the uploaded file.

  • oFileUpEE.Files("myFile").Save
    Saves the file.
Avoid Errors by Using Typelibs

In ASP, Typelibs provide quick and convenient access to constants associated with a particular object. The server script in this example includes FileUpEE's TypeLib because the script uses constants (e.g, saAllProcessed). The UUID attribute specifies FileUpEE's unique identifier.

<!--METADATA TYPE="TypeLib" UUID="{6B16F98B-015D-417C-9753-74C0404EBC37}" -->


A Simple Upload in ASP.NET (VB.NET)

The following tutorial shows how to create an ASP.NET application that uploads a file from a client to a web server using a web form to submit the upload from the client. SoftArtisans FileUpEE receives and processes the upload on the web server.

To allow file uploads, NTFS permissions must be set appropriately for FileUpEE's temporary and destination directories. For more information, see Security Considerations.

The tutorial uses a web form to upload a file from the client. The web form submitting the file must contain:

  • A <form> ACTION attribute that calls the upload processing script on the server.

  • The <form> tag attribute ENCTYPE="multipart/form-data".

  • An <input type="file"> tag, including a name attribute.

On the web server, FileUpEE receives and saves the uploaded file. The FileUpEE objects are in the SoftArtisans.Net namespace. The objects can be referenced as fully qualified names, such as SoftArtisans.Net.FileUpEe. To minimize typing and errors, use an Import directive to import the namespace to the ASP.NET page. This allows you to reference objects by name alone, without the namespace prefix. If you are coding directly in the .aspx page, following the Page directive in the aspx page, include:

<%@Import namespace="SoftArtisans.Net"%>

If you are coding in the "code behind" page, include an Imports statement at the top of the "code behind" page in VB.NET or an using in C#:

[VB.NET]
Imports SoftArtisans.Net

[C#]
using SoftArtisans.Net;

In the FileUpEE code, the following lines process the upload request, and save the uploaded file:

  • [VB.NET] Dim oFileUpEE As New FileUpEe()

    [C#] FileUpEE oFileUpEE = new FileUpEe();

    Creates an instance of FileUpEE.

  • [VB.NET] oFileUpEE.TransferStage = saTransferStage.saWebServer

    [C#] oFileUpEE.TransferStage = saTransferStage.saWebServer;

    This property tells FileUpEE the stage of the file transfer, that is, the server on which the current code should run. The transfer stage can be client, web server, or file server. The transfer stage can be set to saWebServer or saFileServer. The TransferStage property is required. Set this property immediately after creating an instance of FileUpEE.

  • [VB.NET] oFileUpEE.ProcessRequest(Page.Request, False, False)

    [C#] oFileUpEE.ProcessRequest(Page.Request, False, False);

    The ProcessRequest method passes the Request object to FileUpEE. The collection of transferred files is not available until after ProcessRequest is called. In addition to the Request object, ProcessRequest takes two boolean parameters:

    SoapRequest
    The SoapRequest parameter tells FileUpEE whether the file transfer is a SOAP request or not. Since the tutorial's web server code receives a form-based request, and not a SOAP request, SoapRequest is set to false.
    AutoProcess
    If the AutoProcess parameter is set to true, FileUpEE will process the Request according to the SOAP payload (the XML document tranferred with a SOAP request), and it is not required to "manually" save the files by calling FileEe.Save in the script that passes true as the AutoProcess parameter of ProcessRequest. AutoProcess can only be true if the script is processing a SOAP request. The tutorial's web server is processing a form-based file upload, not a SOAP request, so AutoProcess must be false.

  • [VB.NET] oFileUpEE.DestinationDirectory = Page.MapPath("/FileUpEE/Samples/temp")

    [C#] oFileUpEE.DestinationDirectory = Page.MapPath("/FileUpEE/Samples/temp");

    Sets the destination directory for the uploaded file.

  • [VB.NET] oFile.DestinationFileName = oFile.ClientFileName

    [C#] oFile.DestinationFileName = oFile.ClientFileName;

    Sets the destination file name to the file's original name.

  • [VB.NET] oFile.Save()

    [C#] oFile.Save();

    Saves the file.

When you are finished using an instance of FileUpEE under .NET, always call FileUpEE.Dispose(). This ensures thorough cleanup of temporary files.

[VB.NET]
Finally
    If Not (oFileUpEE Is Nothing) Then
        oFileUpEE.Dispose()
    End If
    oFileUpEE = Nothing
End Try

[C#]
finally
{
    if (oFileUpEE != null)
        oFileUpEE.Dispose();
}

Top


3-Tier Upload in ASP

FileUpEE can perform a browser-to-server-to-server (3-tier) upload, allowing you to maintain a secure file server that is isolated from your public web server.

The client-to-server part of the file transfer is a form-based file upload [image]. This type of upload submits form data (the file and/or other form elements) as name/value pairs. FileUpEE processes the upload on the web server.

FileUpEE submits the server-to-server part of the file transfer as a SOAP message with an attachment [image]. SOAP (Simple Object Access Protocol) is an Internet protocol that uses HTTP as its transport and XML as its data format. A SOAP request is submitted in an XML document (the XML payload) via HTTP. Unlike a form-based upload request - which can only include name/value pairs - the XML payload can contain a much richer, hierarchical set of data.

When scripting a 3-tier upload, you can include all upload processing instructions on the Web server, as you would in a client-to-server upload. If the request from web server to file server includes all processing instructions, these can be executed automatically on the file server. Alternatively, you can put the processing instructions on the file server, to protect important paths and database information.

To allow file uploads, NTFS permissions must be set appropriately for FileUpEE's temporary and destination directories. For more information, see Security Considerations.
Uploading a File from Client to web Server to File Server

The following ASP tutorial demonstrates 3-tier uploading with FileUpEE. The tutorial's application uploads a file from a web form. The file is first sent to a Web server, and then to a file server, where it is saved. All upload processing directions (such as the destination directory) are in the web server page. These directions are executed by FileUpEE on the file server if automatic file processing is selected (as it is in the following tutorial).

The Client-Side Code

The client-side page defines a web form that is used to upload the file from the client to the web server. The web form submitting the file must contain:

  • A <form> ACTION attribute that calls the upload processing script on the server.

  • The <form> tag attribute ENCTYPE="multipart/form-data".

  • An <input type="file"> tag, including a name attribute.
The web Server Code

The web server page includes all upload processing directions: the save method (FileUpEE can save to either a directory or a database), save location, and other properties. FileUpEE sends the upload request from the web server to the file server page specified by the TargetUrl property. The upload request from web server to file server is a SOAP message with an attachment. The SOAP request (an XML file) contains all the processing directions specified on the web server. These directions are executed by FileUpEE on the file server if automatic file processing is selected (as it is in the following tutorial).

The following VBScript lines receive the upload on the web server, set instructions to be executed on the file server (the upload's final destination), and send the upload (as a SOAP request) to the file server:

  • Set oFileUpEE = Server.CreateObject("SoftArtisans.FileUpEe")
    Creates an instance of FileUpEE.

  • oFileUpEE.TransferStage = saWebServer
    The TransferStage property specifies the stage of the file upload, that is, the server on which the current code should run. The transfer stage can be set to saWebServer or saFileServer. The TransferStage property is required. Set this property immediately after creating an instance of FileUpEE.

  • oFileUpEE.ProcessRequest Request, False, False
    The ProcessRequest method passes the Request object to FileUpEE. The collection of transferred files is not available until after ProcessRequest is called. In addition to the ASP Request object, ProcessRequest takes two boolean parameters:

    SoapRequest
    The SoapRequest parameter tells FileUpEE whether the file transfer is a SOAP request or not. Since the web server receives a form-based request and not a SOAP request, SoapRequest is set to false.
    AutoProcess
    If the AutoProcess parameter is set to true, FileUpEE will process the Request according to the SOAP payload (the XML document transferred with a SOAP request), and it is not required to "manually" save the files by calling FileEe.Save in the script that passes true as the AutoProcess parameter of ProcessRequest. AutoProcess can only be true if the script is processing a SOAP request. The web server is processing a form-based file upload, not a SOAP request, so AutoProcess must be false.

  • oFileUpEE.DestinationDirectory = Server.MapPath("/FileUpEE/Samples/temp")
    Sets the directory on the file server in which the uploaded file will be saved.

  • Set oFile = oFileUpEE.Files("myFile")
    Sets a FileEE object which represents the uploaded file. "myFile" is the name of the file input field in the form that submitted the upload.

  • oFileUpEE.TargetUrl = "http://localhost/FileUpEE/Samples/UploadSamples/Basic/Simple3Tier/ASP/fileserver.asp"
    When sending a request from server to server you must set TargetUrl. This property specifies the url of the page on the file server to which FileUpEE will submit the request.

  • oFile.DestinationFileName = oFile.ClientFileName
    The DestinationFileName property sets the name with which to save the uploaded file. In this case, the name is set to the file's original name on the client.

  • intSAResult = oFileUpEE.SendRequest()
    Sends the upload request to the file server's FileUpEE application.

The File Server Code

The file server code does not include upload processing instructions, because it automatically executes the instructions that were set on the web server and sent to the file server as a SOAP request.

  • Set oFileUpEe = Server.CreateObject("SoftArtisans.FileUpEe")
    Creates an instance of FileUpEE.

  • oFileUpEE.TransferStage = saFileServer
    The TransferStage property specifies the stage of the file upload, that is, the server on which the current code should run. The transfer stage can be client, web server, or file server. The transfer stage can be set to saWebServer or saFileServer. The TransferStage property is required. Set this property immediately after creating an instance of FileUpEE.

  • oFileUpEe.ProcessRequest Request, True, True
    The ProcessRequest method passes the Request object to FileUpEE. The collection of transferred files is not available until after ProcessRequest is called. In addition to the ASP Request object, ProcessRequest takes two boolean parameters:
    SoapRequest
    The SoapRequest parameter tells FileUpEE whether the file transfer is a SOAP request or not. Since the file server receives a SOAP request from the web Server, SoapRequest is set to true. Note that in almost all cases, server-to-server FileUpEE file transfers are SOAP requests.
    AutoProcess
    If the AutoProcess parameter is set to true, FileUpEE will process the Request according to the SOAP payload (the XML document tranferred with a SOAP request), and it is not required to "manually" save the files by calling FileEe.Save in the script that passes true as the AutoProcess parameter of ProcessRequest. AutoProcess can only be true if the script is processing a SOAP request. Since all upload processing instructions for the file server were included in the web server code, in the file server page AutoProcess is set to true.

  • oFileUpEe.SendResponse Response
    Takes the ASP Response object and sends it to the FileUpEE application on the web server. Note that the response to the client was set in the web server code.

Avoid Errors by Using Typelibs

In ASP, Typelibs provide quick and convenient access to constants associated with a particular object. The web server script in this example includes FileUpEE's TypeLib because the script uses constants (e.g, saWebServer). The UUID attribute specifies FileUpEE's unique identifier.

<!--METADATA TYPE="TypeLib" UUID="{6B16F98B-015D-417C-9753-74C0404EBC37}"-->

Top


A Simple Download

The advantages of FileUpEE downloading include:

  • The files to download do not have to be in a browsable location on the server.

  • The path to the file only exists in the server-side code, which helps protect sensitive information from end-users.

  • FileUpEE can download from file server to web server to client (a 3-tier download).

  • FileUpEE can download from a directory or a database.

  • FileUpEE allows you to limit the bandwidth used for downloads per connection and per server.
Important!
The behavior of a download is extremely browser-dependent. To ensure that your application works as desired, test it on different browser platforms. Alternatively, use a client-side control such SoftArtisans XFileEE to handle your downloads.

The following ASP and ASP.NET samples demonstrate downloading a single file from web server to client. Note that the download scripts do not contain HTML or Response.Write statements. In a download, the response should include only the downloaded file and its response headers. HTML and Response.Write lines will corrupt the downloaded file.

FileUpEE provides two techniques for downloading files from web server to client: AddDownloadFile/WriteToResponse and TransferFile. The samples above use the AddDownloadFile/WriteToResponse to download the file sample.doc from FileUpEE's doc-samples\samples directory.

Downloading with AddDownloadFile and WriteToResponse

The following VBScript lines download a file using the FileUpEE method AddDownloadFile and the FileEE method WriteToResponse:

  • Set oFileUpEE = Server.CreateObject("SoftArtisans.FileUpEE")
    Creates an instance of FileUpEE.

  • strPathToDownloadFile = Server.MapPath("/FileUpEE/Samples/sample.doc")
    Set oDownFile = oFileUpEE.AddDownloadFile(strPathToDownloadFile, "docdownload.doc", "myDownFile", True)
    Adds a file to the collection of files to download. The AddDownloadFile method returns a FileEE object that represents the file to download. AddDownloadFile takes four parameters:
    DownloadPath
    The path and name of the file to download.
    ClientPath
    The destination name of the downloaded file. This file name will appear in the "Open or Save" dialog on the client.
    Name
    The value of Name may be used to reference the file in script, for example:
    objFileUpEE("myDownFile").ContentType = "text/plain"
    WebServerDownload
    To script a download from a file server to a web server to a client, set WebServerDownload to False. To script a download from a web server to a client, set WebServerDownload to True.
  • oDownFile.WriteToResponse Response
    Downloads the file to the client.

To ensure that the download is not corrupted by extraneous characters in the response:

  1. Do not include Response.Write statements in the download script.

  2. Do not include HTML in the download script.

  3. Before calling WriteToResponse, call Response.Clear to erase any buffered HTML output.

  4. In ASP, after calling WriteToResponse, call Response.End. In ASP.NET, after calling WriteToResponse, call Response.Close.

The AddDownloadFile method sets content-type and content-disposition response headers for the file to download. When using the AddDownloadFile/WriteToResponse download method, do not set these response headers in script.

Top

Downloading with TransferFile

To download a file using the FileUpEE method TransferFile:

  1. The TransferFile method does not set response headers for the download. To let the browser know how to handle a download, set the content-type and content-disposition response headers:

    Response.ContentType = "application/msword"
    Response.AddHeader "content-disposition", "attachment;filename=""docdownload.doc"""

  2. Call TransferFile to download the file from the web server to the client:

    strPathToDownloadFile = Server.MapPath("/FileUpEE/Samples/sample.doc")
    oFileUpEE.TransferFile Request, Response, strPathToDownloadFile

To ensure that the download is not corrupted by extraneous characters in the response:

  1. Do not include Response.Write statements in the download script.

  2. Do not include HTML in the download script.

  3. Before setting the response headers, call Response.Clear to erase any buffered HTML output.

  4. In ASP, after calling TransferFile, call Response.End. In ASP.NET, after calling TransferFile, call Response.Close.
Avoid Errors by Using Typelibs

In ASP, Typelibs provide quick and convenient access to constants associated with a particular object. The script in this example includes FileUpEE's TypeLib because the script uses constants (e.g, saWebServer). The UUID attribute specifies FileUpEE's unique identifier.

<!--METADATA TYPE="TypeLib" UUID="{6B16F98B-015D-417C-9753-74C0404EBC37}" -->

Top


Features In Depth

A 3-Tier Download

Uploading to a Database

Downloading from a Database

Resumable Uploading

The Progress Indicator

Large Uploads in ASP

Large Uploads in ASP.NET

Large Uploads in IIS 6

Using the HttpModule in Visual Studio .NET

Streaming Requests

FileUpSE Support

Glossary


A 3-Tier Download

The following 3-tier ASP and ASP.NET tutorial shows how to download a file from file server to web server to browser. On the web server, FileUpEE.AddDownloadFile sets the file to download from the file server and FileUpEE.SendRequest sends the download request to the file server. On the file server, FileUpEE.SendResponse sends the download to the web server. After the file arrives on the web server, the FileEE.WriteToResponse downloads it to the browser.

The web Server Script

On the web server, FileUpEE requests a file from the file server, receives the file, and sends it to the browser. The following VBScript lines are for the web server code in an ASP three tier download:

  • oFileUpEE.TargetUrl = _ "http://localhost/FileUpEE/Samples/DownloadSamples/Basic/3TierDownload/ASP/fileserver.asp"
    Sets the page on the file server to which FileUpEE will submit the request.

  • strPathToDownloadFile = Server.MapPath("/FileUpEE/Samples/sample.doc")
    Set oDownFile = oFileUpEE.AddDownloadFile(strPathToDownloadFile, "docdownload.doc", _ "myDownFile", False)
    Sets the file to get from the file server. The AddDownloadFile method returns a FileEE object that represents the file to download. AddDownloadFile takes four parameters:
    DownloadPath
    The path and name of the file to download.
    ClientPath
    The destination name of the downloaded file. This file name will appear in the "Open or Save" dialog on the client.
    Name
    The value of Name may be used to reference the file in script, for example:
    objFileUpEE("myDownFile").ContentType = "text/plain"
    WebServerDownload
    To script a download from a file server to a web server to a client, set WebServerDownload to False. To script a download from a web server to a client, set WebServerDownload to True.

  • intSAResult = oFileUpEE.SendRequest()
    Sends the download request to the file server. SendRequest returns an SAResult value that allows you to check the status of the response from the file server.

  • If oDownFile.Processed = saDownloaded Then
    oDownFile.WriteToResponse Response
    This occurs after the web server receives the response from the file server. If the file arrives, WriteToResponse sends the file from the Web server to the browser.

  • Response.End
    Ends the response to ensure that the download is not corrupted by extraneous characters.
The File Server Script

On the file server, FileUpEE receives the download request from the web server and returns the requested file. The following VBScript lines are from the file server code in an ASP three tier download:

  • oFileUpEE.ProcessRequest Request, True, True
    Passes the request from the web server to FileUpEE. Since AutoProcess (the third argument) is set to True, FileUpEE will process the request automatically - that is, execute the instructions set on the web server.

  • oFileUpEE.SendResponse Response
    Sends the response (in this case, downloads the file) to the web server.

Top


Uploading to a Database in ASP

FileUpEE allows you to upload to a directory or a database. The SaveMethod property specifies whether to save an uploaded file to a directory or a database column. By default, SaveMethod is set to saDiskFile, meaning that uploaded files will be saved as files in a directory. Set SaveMethod to saDatabase to save an uploaded file as a database BLOB.

The following tutorial shows how to upload a file from client to web server to file server and save the file in the database upload.mdb.

The Upload Form

The upload form page contains the upload form which includes an <input> of type "file" and a comment field. Both the file and the comment will be saved in a database record.

The Web Server script

The web server code does not contain the database connection string or table name. In this tutorial, these values are set on the file server. By setting database properties on the file server, rather than your public web server, you can protect sensitive information.

SaveMethod tells FileUpEE to save the uploaded file as a database BLOB:

oFileUpEE.SaveMethod = saDatabase

DbSchema - a property of the FileEE object - is a collection of name-value pairs representing the column names and values of a database row. Use DbSchema.Add to add or update a database field value. DbSchema.Add takes two parameters - column name and column value. In the web server code, DbSchema.Add is used to insert values in the FileName, ContentType, ByteSize, and Comment columns in the uploaded file's database record:

'--- These values come from properties of the uploaded file
oFile.DbSchema.Add "FileName", oFile.ClientFileName
oFile.DbSchema.Add "ContentType", oFile.ContentType
oFile.DbSchema.Add "ByteSize", oFile.Size

'--- This value comes directly from a text form element
oFile.DbSchema.Add "Comment", oFileUpEE.Form("fileComment")
The File Server Script

The file server script is executed on the file server. In this tutorial, to protect database information, the database connection string and table name are set on the file server, not on the public web server. In addition to database information, the file server code contains a Save statement. Since the file server code includes these upload processing instructions and does not automatically execute instructions sent from the web server, AutoProcess - the third parameter of ProcessRequest - is set to false:

objFileUpEE.ProcessRequest Request, True, False

When uploading to a database, always set:

  1. the database connection string,
  2. the name of the table in which to save the file, and
  3. the name of the file column within the table.

The connection string and table name may be set for the whole upload, or for an individual file within the upload. The file column name is set for each file. In the file server code, the database connection string is set by the per-upload property FileUpEE.DbConnection:

oFileUpEE.DbConnection = "Driver={Microsoft Access Driver (*.mdb)};Dbq=" & _
    Server.MapPath("/FileUpEE/samples/upload.mdb")

The table in which to save the upload is set by the per-upload property FileUpEE.DbTableName:

oFileUpEE.DbTableName = "UploadTable"

The column in which to save the uploaded file must be set for each file in an upload:

oFileUpEE.Files("myFile").DbFileColumnName = "FileBinary"
This example adds a new row to the database for the uploaded file. When updating a row, you must set the properties DbPrimaryKey and DbPrimaryKeyValue. Do not set these values to add a row.

Top

See Also

Per-upload database properties: FileUpEE.DbConnection, FileUpEE.DbPrimaryKey, FileUpEE.DbPrimaryKeyValue, FileUpEE.DbSqlCommand, FileUpEE.DbTableName and FileUpEE.SaveMethod.

Per-file database methods and properties: FileEE.DbConnection, FileEE.DbFileColumnName, FileEE.DbIdentityColumnName, FileEE.DbPrimaryKey, FileEE.DbPrimaryKeyValue, FileEE.DbSqlCommand, FileEE.DbTableName, FileEE.SaveAsBlob, FileEE.SaveMethod, and FileEE.DbSchema.

Top


Downloading from a Database in ASP

With FileUpEE, you can download a file from a directory or a database. To download a file, use the FileUpEE method TransferFile, or - as in the following example - the FileEE method WriteToResponse.

This tutorial shows how to create an application that downloads a file from the database upload.mdb on the file server. The file is downloaded to the web server and then to the client.

The Client Script

The form page displays a table of all files in the database upload.mdb and a Download link for each file. A SQL query is used to get the information about the files in the database. The query gets the values of the UploadTable columns ID, FileName, ByteSize, ContentType, and Comment:

Set oConn = Server.CreateObject("ADODB.Connection")
oConn.Open "Driver={Microsoft Access Driver (*.mdb)};Dbq=" & _
    Server.MapPath("/FileUpEE/samples/upload.mdb")

'--- The RecordSet object oRS contains ID, FileName,
'--- ByteSize, ContentType, and Comment - all the UploadTable
'--- fields except for the actual file.
Set oRS = oConn.Execute("SELECT ID, FileName, ByteSize, ContentType,_
    Comment FROM UploadTable ORDER BY ID")

'--- If there are no files in the database, this
'--- message will be displayed.
If oRS.EOF And oRS.BOF Then
    Response.Write("There are no files currently in the database.")
    Response.End
End If

An HTML table displays the information about the files and a Download link for each file. Clicking a file's Download link sends a request to the download page with two values in the query string - the file name, and the file id:

Response.Write("<TD>[<A HREF=""download.asp?name=" &_
    oRS.Fields("FileName").Value & "&id=" & oRS.Fields("ID").Value &_
    """>Download</A>]</TD>")
The web Server Script

The database upload.mdb is on the file server. The requested file will be downloaded from the file server to the web server and then to the client. The download page is on the Web server and contains all download instructions. These will be executed automatically in the file server code.

The AddDbDownloadFile method adds a file from a database to the collection of files to download. AddDbDownloadFile takes the download destination file name and returns a FileEE object. The forms page got the file's name from the database and sent the name in the query string. In the download page, this name is passed to AddDbDownloadFile:

strFileNameForSaveAs = Request.QueryString("name")
...
Set oDownFile = oFileUpEE.AddDbDownloadFile(strFileNameForSaveAs, "myDownFile", False)

The file name you pass to AddDbDownloadFile does not have to be the file name in the database, as it is in this sample. The file name passed to AddDbDownloadFile is the name that will be displayed to the user when the file is downloaded.

You can set the database connection string for the upload - using FileUpEE.DbConnection - or for the file - using FileEE.DbConnection. In the download page, the connection string is set by the FileEE object's DbConnection property:

oDownFile.DbConnection = "Driver={Microsoft Access Driver (*.mdb)};Dbq=" & _
    Server.MapPath("/FileUpEE/samples/upload.mdb")

When downloading a file from a database, to tell FileUpEE where to find the file, you must set:

  1. the file's table name,
  2. primary key column,
  3. primary key value, and
  4. file column name.

oDownFile.DbTableName = "UploadTable"
oDownFile.DbPrimaryKey = "ID"
oDownFile.DbPrimaryKeyValue = intFileID
oDownFile.DbFileColumnName = "FileBinary"

After calling AddDbDownloadFile and providing the necessary information about the file to download, the download request is sent to the file server:

intSAResult = oFileUpEE.SendRequest()

If the SendRequest method returns saAllProcessed, the file was successfully downloaded from the file server to the web server. The WriteToResponse method then takes the response from the file server and downloads the file to the client:

If intSAResult = saDownloaded Then
    oDownFile.WriteToResponse Response
Else
The File Server Script

The file server code is executed on the file server. The file server does not include upload processing instructions, instead automatically executing the instructions that were set in the download page and sent from the web server as a SOAP message. FileUpEE automatically processes the request according to the SOAP message because AutoProcess - the third parameter of ProcessRequest - is set to True:

objFileUpEE.ProcessRequest Request, True, True
Do not set AutoProcess to True unless the web server script contains all necessary processing instructions.

Top

See Also

The example uses the method WriteToResponse to download a file. Alternatively, use the method TransferFile.

Per-upload database properties: FileUpEE.DbConnection, FileUpEE.DbPrimaryKey, FileUpEE.DbPrimaryKeyValue, FileUpEE.DbSqlCommand, FileUpEE.DbTableName and FileUpEE.SaveMethod.

Per-file database properties: FileEE.DbConnection, FileEE.DbFileColumnName, FileEE.DbIdentityColumnName, FileEE.DbPrimaryKey, FileEE.DbPrimaryKeyValue, FileEE.DbSqlCommand, FileEE.DbTableName, and FileEE.DbSchema.

Top


SoftArtisans XFileEE
XFileEE Documentation
You will find the complete XFileEE documentation at FileUpEE/XFile/XFile.chm, or on the SoftArtisans support site.

For optimal performance, FileUpEE is bundled with a full license of the client-side control SoftArtisans XFileEE. This tool will enhance your applications and help overcome browser limitations. You will find the complete XFileEE documentation at FileUpEE\Documentation\XFile.chm, or on the SoftArtisans support site.

SoftArtisans XFileEE is a powerful ActiveX product with a non-visual COM file transfer engine. SoftArtisans XFileEE is a complete HTTP client that may be used from ASP, ASP.NET, Visual Basic, Windows Scripting Host, Microsoft Office, or Windows Explorer. XFileEE's many features include:

XFileEE's ActiveX Upload Control
  • Visual (ActiveX) control
    • Can be used from Internet Explorer, Visual Basic
    • Supports drag-and-drop
    • List of files to transfer can be preset
    • Accurate progress indicator
    • Shows estimated size and transfer time

  • Non-visual COM Component file transfer engine:
    • Allows multiple HTTP GET, POST, PUT in a single operation
    • Generates events for capture by Internet Explorer or Visual Basic
    • Supports SSL, Proxies, Multiple authentication mechanisms
    • Can be used from Internet Explorer (optional silent operation), Visual Basic or ASP

  • Resumable File Transfer Requests
    • Resumable uploads
    • Resumable downloads

  • Client-side progress indicator

  • Two bonus tools:
    • SoftArtisans FileManager - an easy-to-use solution that meets all your file management needs.
    • SoftArtisans Archive - a programmer's tool for the creation and extraction of ZIP and CAB archives.

  • Downloads multiple files to preset locations

  • Downloads to a string or to a file

  • XFileEE is Unicode compliant - safely uploads non-English file names and form elements


A Resumable Upload

  • Resumable Uploading
  • The Upload Status Databases
  • Example: A Resumable Upload
Resumable Uploading

FileUpEE can resume failed client-to-server and server-to-server uploads. Since browsers do not support resumable uploading, you must use XFileEE on the client to create a client-to-server resumable upload application. This section explains how to create a server-to-server upload application in ASP. See XFileEE Resumable Upload to learn how to create a resumable client-to-server upload with XFileEE and 2-tier Resumable Upload in .NET to learn how to create a resumable two-tier upload in ASP.NET.

An upload may fail because of a network connection failure, or because the upload size was greater than MaxKBytesToCancel. To resume a server-to-server upload, call the Resume method on the web server. Behind the scenes, FileUpEE will send a query to the file server asking for the number of bytes received. The resume request will begin at the point where the file server stopped receiving data.

The Upload Status Databases

When a resumable upload fails, FileUpEE saves information about the upload on both the web server and the file server. When the Resume method is called, FileUpEE will get the status of the upload - the number of bytes uploaded to the file server - from the file server database. FileUpEE will then resume the upload from the point at which it stopped.

There are two ways to set the connection string for an upload status database:

  • Set the ResumeConnectionString property for the specified upload database (Web server or file server).

    OR

  • Set the web server and file server connection strings in two udl files. On the web server, in WINDOWS\system32\fileupee.udl, save the web server's status database connection string. On the file server, in WINDOWS\system32\fileupee.udl, save the file server's status database connection string.

    To store a database connection string in a udl file:

    1. Go to C:\WINDOWS\system32.
    2. Right click within the system32 directory and select New -> Text Document.
    3. Name the file fileupee.udl.
    4. Double-click fileupee.udl to open it.
    5. Select the Provider tab.
    6. Select the appropriate Provider, and click Next. (If you are using the Microsoft Access files included with FileUpEE, select Microsoft Jet 4.0 OLE DB Provider).
    7. Configure the database provider. (If you are using the Microsoft Access files included with FileUpEE, browse to FileUpEEWS.mdb if you are at the web server, or FileUpEEFS.mdb if you are at the file server.)
    8. Click Test Connection.
The internet user account must have write access the directory where the databases are held. Make sure that the IUSR_MACHINENAME account has Read, Write, and Delete access to this directory. For security reasons the FileUpEE install package does not grant this access.
The sample databases included with FileUpEE and the databases generated by FileUpEE.CreateDatabase are Access databases. To generate a set of tables for an Oracle or SQL Server database, run the script FileUpEE.sql. The script is included in the folder SoftArtisans\FileUpEE.

Top

Resumable Uploading with XFileEE
Using FileUpEE alone, you can create server-to-server resumable transfer applications. To create a client-to-server resumable upload, use XFileEE. See XFileEE Resumable Upload to learn how to create a resumable client-to-server upload with XFileEE and 2-tier Resumable Upload in .NET to learn how to create a resumable two-tier upload in ASP.NET..
The Client Script

The forms page contains the upload form. The form includes a file <input> field, and a radio <input> field that allows the user to force an upload failure. If you select Yes, the MaxKBytesToCancel(saFileServer) property will be set to 1 KB (on the wev server page) and uploads that are larger than 1 KB will fail.

The web Server Script

The web server script runs on the web server. It includes all upload processing information: the save method (directory or database), save location, etc. The web server sends the upload request to the file server script set by the TargetURL property. The request to the file server is a SOAP message (an XML file).

When Resumable(saWebServer) is set to True, FileUpEE will be able to resume a Web-server-to-file-server upload that was suspended because of a network connection failure, or because the upload size was greater than MaxKBytesToCancel. Resumable is set to False by default. Resumable takes the parameter SATransferStage which specifies the stage of the upload: client-to-Web-server or Web-server-to-file server. In the web server script, before calling ProcessRequest, to enable resumable Web-server-to-file-server uploads, you must set:

oFileUpEE.Resumable(saWebServer) = True

Set oFileUpEE.Resumable(saFileServer) to true on either the web server or the file server, at any point before calling ProcessRequest on the file server. In the sample, Resumable(saFileServer) is set in the web server script:

oFileUpEE.Resumable(saFileServer) = True

A resumable upload application uses two status databases, one on the web server and one on the file server. In the web server code, ResumeConnectionString(saWebServer) sets the connection string for the upload status database on the web server. Set ResumeConnectionString before calling ProcessRequest:

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

For a FileUpEE request to be resumable, information about the file transfer must be persisted on all stages of that request. For this reason the FileUpEe.ResumeConnectionString and FileUpEe.Resumable properties must be set for all stages of the upload. Therefore, for a web server to file server request to be resumable, Resumable(saWebServer) and Resumable(saFileServer) must both be set to true. Also, FileUpEe must know that the transfer is resumable before reading the HTTP request, so make sure that these properties are set for a stage of the upload before that stage's ProcessRequest method.

FileUpEE will abort a file upload when the size of the transfer reaches the value of MaxKBytesToCancel. In the web server code MaxKBytesToCancel(saFileServer) is set to 1:

If oFileUpEE.Form("ForceFailure") = "yes" Then
    oFileUpEE.MaxKBytesToCancel(saFileServer) = 1
End If

Upload a file that is larger than 1 KB to run a resumable upload. To allow the upload to be resumed, MaxKBytesToCancel(saFileServer) will be reset to a higher value in the resume page code.

FileUpEE generally reads data in chunks greater than 56 KB. To see a true resumable request, set MaxKBytesToCancel to 60 and upload a file greater than 60 KB.

If the upload from web server to file server is suspended, and the user clicks the Resume link, the resume-upload script will be called. When the Resume method is called, a request will be made to the status server script. The response will tell FileUpEE the point at which the upload was suspended. StatusUrl specifies the URL of the status server script. You can set StatusUrl in the web server script, before calling SendRequest, or in the resume-upload script, before calling Resume. In this sample, StatusUrl is set in WebServer.asp:

oFileUpEE.StatusURL = "http://localhost/fileupee/samples/" & _
    "uploadsamples/intermediate/resume/asp/status.asp"

If the upload stops before it is complete, a listing script is called is called which displays all suspended uploads and a Resume link for each.

If eSAResult <> saAllProcessed Then
    Response.Write("<P ALIGN=center><B>Error!</B>Your upload has failed.")
    Response.Write("Click <a href=""listresumable.asp"">here</a> to see if the _
        transfer is resumable.</P>")
End If
The Response to a Suspended Upload

If the upload stops, the listing script displays a table of all suspended uploads, with a Resume link for each upload. Clicking Resume submits a request to the resume script with the specified upload's JobId in the query string.

The Resume Script

Before resuming the upload, MaxKBytesToCancel(saFileServer) is reset to a value that will allow the upload to complete:

oFileUpEE.MaxKBytesToCancel(saFileServer) = 999

The Resume method takes an upload's JobId and uses it to get the suspended upload's status from the database. Resume requests the status from Status.asp (the status URL). The ReturnStatus method in Status.asp returns the upload's status to the Resume method, and Resume then continues the upload from the point at which it stopped.

intSAResult = oFileUpEE.Resume(guidJobID)
The Status Script

When a file transfer is resumed, FileUpEE needs to communicate with a status page on the file server to determine the status of the transfer. The URL of this page is set on the web server through the StatusUrl property. If a suspended upload is resumed, the status page will get the upload status from the status database on the file server:

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

To resume the upload, the status script calls FileUpEE's ReturnStatus method:

oFileUpEE.ReturnStatus Request, Response
The status page can be a dedicated web page or the same file server page as you post to during a typical file upload. This page will look up the status of the file transfer in the database, so be sure that FileUpEe's ResumeConnectionString property is set.
The File Server Script

A resumable upload application uses two status databases, one on the web server and one on the file server. In the file server script, ResumeConnectionString(saFileServer) sets the connection string for the upload status database on the web server. Set ResumeConnectionString before calling ProcessRequest:

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

Since AutoProcess (the third parameter of ProcessRequest is set to True, the file server script will automatically execute the upload instructions set in the web server script.

oFileUpEE.ProcessRequest Request, True, True

Top


A 2-Tier Resumable Upload in ASP.NET

  • Resumable Uploading
  • Client-side configuration and code
  • HttpModule settings
  • Server-side Processing Page
Resumable Uploading

FileUpEE can resume failed uploads. This tutorial will demonstrate resumability between the client and webserver in ASP.NET. The code examples on this page are a simplified version of the ASP.NET two-tiered resumable upload in the FileUpEE samples.

Since browsers do not support resumable uploading, XFileEE must be used on the client to create a client-to-server resumable upload application.

In ASP.NET, resumability between the client and the server is accomplished through the HttpModule. Hence, it is necessary to use the HttpModule for every FileUpEE resumable upload using ASP.NET.

An upload may fail because of a number of reasons, including a network connection failure, or because the upload size was greater than MaxKBytesToCancel.

Client-side Configuration and Code
Client configuration

XFileEE must be used as the client for any resumable upload. Because of this, the XFileEE cab must be downloadable from your web directory.

XFileEE has resumability-specific functionality that must be added to your XFileEE upload code:

When making a resumable request:

  • XFRequest.ResumeInfo.Resumable property should be set to true .
  • XFRequest.ResumeInfo.CacheRequest property should be set to true or false depending on whether or not you want a complete copy of the file cached on the client. In a resumable upload, XFileEE stores upload data in a temporary directory on the client, before starting the upload. XFileEE's ResumeInfo.CacheRequest property 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. This may be useful if you suspect that the file to be uploaded could be edited between the time the upload fails and the time at which it is resumed. Setting CacheRequest to true will ensure that the file is resumed in its original state, as it will be resumed from the cache instead of from its original location on the file system. Please note, however, that there is a significant performance penalty for caching requests that include large files.
  • XFRequest.ResumeInfo.TopFolder property should be set to the location where XFile should store resumability information on the client.

When resuming a request:

  • XFRequest.Resume([XFRequest.ResumeInfo.JobID])should be used to specify which upload request should be resumed.
The client code:

<html>
<head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>Two-Tier Resumable Upload via XFile Non-Visual Control</title>

    <script type="text/javascript">

    /****************************************************************************
    **** Do Upload (XFile Non-Visual) *******************************************
    *****************************************************************************/

    function send()
    {
        //--- Add the selected files for upload to the XFRequest object's Files
        //--- collection
        XFile.AddFile(document.getElementById("File1").value, "File1");
        XFile.AddFile(document.getElementById("File2").value, "File2");

        // -------------------- Resumability ------------------------------------
        // ----------------------------------------------------------------------
        //--- Set Resumable to True to tell XFileEE that the upload is resumable
        XFile.ResumeInfo.Resumable = true;

        //--- If CacheRequest is set to True, XFile will make copies of the files
        //--- before uploading. This is to guarantee data integrity in case the
        //--- user modifies a file between upload attempts.
        //--- If CacheRequest is set to false, XFile will not pre-cache the files.
        //--- This speeds up the upload process significantly but carries a risk
        //--- of file corruption if an upload is resumed after the user modifies
        //--- the file.
        XFile.ResumeInfo.CacheRequest = false;

        //--- Set TopFolder property to tell XFileEE where to store information
        //--- that will allow a failed upload to be resumed.
        //--- If CacheRequest is set to true, copies of the files will be stored
        //--- in this folder until the upload is complete.
        //--- If CacheRequest is set to false, only information about the request
        //--- will be stored.
        //--- Note: If TopFolder is not set, XFile will store request data in the
        //--- user's temp directory.
        XFile.ResumeInfo.TopFolder = "C:\\Temp\\XFileResumeInfo\\";

        // -------------------- Process Upload ----------------------------------
        // ----------------------------------------------------------------------

        //--- Set the URL where you will upload the files to
        XFile.CurrentUrl =
            "http://localhost/TwoTierResumableWebServer_Docs/
                ResumableUpload/TwoTRUploadWS.uplx";

        try
        {
            //--- Begin the transfer
            XFile.Start();
        }
        catch(errorObject)
        {
            alert("Error: " + errorObject.message +
                    "An error has occurred during the upload. You may resume the
                        transfer by clicking the \"Resume\" button.");
        }
    }

    /****************************************************************************
    **** Do Resume (XFile Non-Visual) *******************************************
    *****************************************************************************/

    function resume()
    {
        try
        {
            //--- Resume the transfer by passing the JobID
            XFile.Resume(XFile.ResumeInfo.JobId);
        }
        catch(errorObject)
        {
            alert("Error: " + errorObject.message +
                    "An error has occurred during the resume. You may re-resume
                        the transfer by clicking the \"Resume\" button.");
        }
    }

    </script>

</head>
<body>
    <h2 style="text-align: center">
        Two-Tier Resumable Upload via XFile Non-Visual Control</h2>
    <!-- This OBJECT tag declares and loads the XFRequest object (the non-visual
        control of XFile) into the page.  Change the CODEBASE attribute if you
        choose to deploy the SAXFileEE.cab from another location -->
    <object id="XFile" codebase="/cab/SAXFileEE.cab"
        classid="clsid:8B3512EF-4FF5-4aa4-9CDE-56BB03E04B9F">
    </object>
    <br />
    <table align="center" width="600">
        <tr>
            <td>
                Description:  This sample demonstrates how to perform a
                resumable two-tier upload to the webserver using XFile's Non-Visual
                ActiveX Control.  After the user selects files from the HTML
                file input controls, the files are passed to XFile programmatically
                by calling the AddFile method.
            </td>
        </tr>
    </table>
    <form>
        <table align="center" border="0">
            <tr>
                <td align="left" valign="top">
                    <b>Enter Filename:</b></td>
                <td>
                    <input type="file" id="File1"><br />
                    <i>Click "Browse" to select a file to upload.</i>
                </td>
            </tr>
            <tr>
                <td align="left" valign="top">
                    <b>Enter Filename:</b></td>
                <td>
                    <input type="file" id="File2"><br />
                    <i>Click "Browse" to select a file to upload.</i>
                </td>
            </tr>
         </table>
    </form>
    <p align="center">
        <input id="btnUpload" onclick="send()" type="button" value="Upload"
            name="btnUpload" style="width: 70px" />
        <input disabled id="btnResume" onclick="resume()" type="button"
            value="Resume" name="btnResume" style="width: 70px" />
    </p>
</body>
</html>
HttpModule Settings

The FileUpEE HttpModule sits on the server and intercepts client requests that are sent to pages using the .uplx extension. In ASP.NET, it is used to enable resumable uploads. The server side code page in ASP.NET resumable uploads must have a .uplx extension for this reason.

The HttpModule is configured using appSettings within the web.config file of the application. The following keys must be changed to enable resumable file transfers in ASP.NET.

  • UseHttpModuleWithAspDotNet should be set to "1" to enable the FileUpEE HttpModule.

  • Resumable should be set to "1" to enable resumability.

  • FileUpEeTempDir should be set to a location with adequate NTFS permissions for your web application's identity. This is where the module will temporarily cache the upload request. In addition, the module will temporarily store files that provide information regarding the resumability status of the request. These files will be cleaned out of the directory if the upload is sucessful.

Server-Side Processing Page

FileUpEE

No special considerations must be made in the FileUpEE code for resumable uploads. The same server side code can be used for both resumable and non-resumable uploads. However, greater user control is provided when the FileUpEE(Boolean EnablePreserveResumeInfoBehavior) constructor is used.

Passing in true to FileUpEE will prevent FileUpEE from disposing of resume information until the upload transfer is confirmed to be successful. The default preserve behavior is for FileUpEE to not delete resume information until the saSaveResult for each uploaded file returns saSaved or saExists.

This behavior can be overridden by the script writer through a new property PreserveResumeInfo that has been added to the FileUpEe object. This property can be set to saPreserveBehavior.saPreserve or saPreserveBehavior.saDelete to preserve or delete the resume information when the FileUpEe object is destructed. The default setting is saPreserveBehavior.saDefault.

The webserver code:

using System;
using System.Collections;
using System.ComponentModel;
using System.Data;
using System.Drawing;
using System.Web;
using System.Web.SessionState;
using System.Web.UI;
using System.Web.UI.WebControls;
using System.Web.UI.HtmlControls;
using SoftArtisans.Net;

namespace SoftArtisans.FileUpEESamples
{
    public class TwoTRUploadWS : System.Web.UI.Page
    {
        private void Page_Load(object sender, EventArgs e)
        {
            //--- When the page loads, process the upload
            ProcessUpload();
        }

        private void ProcessUpload()
        {
            //--- Declare the FileUpEe instance variable
            FileUpEe oFileUpEE = null;

            try
            {
                //--- Instantiate the FileUpEE object

                //--- Note: For resumable uploads in ASP.NET, a new constructor which
                //--- receives  a boolean "EnablePreserveResumeInfoBehavior" parameter
                //--- has been added to FileUpEE. Passing in "true" will prevent
                //--- FileUpEE from disposing of resume information until the upload
                //--- transfer is confirmed to be successful. The default preserve
                //--- behavior is that FileUpEE will not delete resume information
                //--- until the "saSaveResult" for each uploaded file returns "saSaved"
                //--- or "saExists".  This behavior can be overridden by the script
                //--- writer through a new property "PreserveResumeInfo" that has been
                //--- added to the FileUpEe object. This  property can be set to
                //--- "saPreserveBehavior.saPreserve" or "saPreserveBehavior.saDelete"
                //--- to preserve or delete the resume information when the FileUpEe
                //--- object is destructed.  The default setting is
                //--- "saPreserveBehavior.saDefault".
                oFileUpEE = new FileUpEe(true);

                //--- Let FileUpEE know what stage we're working on
                //--- Note: Be sure to set this immediately after instantiating the object
                oFileUpEE.TransferStage = saTransferStage.saWebServer;

                //--- Set the directory on the webserver where you want to save the files
                oFileUpEE.DestinationDirectory =
                    @"C:\Program Files\SoftArtisans\FileUpEE\temp\DestinationDir";

                //--- Call ProcessRequest to read the request from the form
                //--- Parameters for ProcessRequest:
                //---	1) Page.Request - HttpRequest instance
                //---	2) SOAP Request? - false, the web server is not being sent SOAP
                //---      from the form
                //---	3) Auto Process? - false, do not auto process on the web server
                //---	Note: false, false is typically what you will use in a web server
                //---   script
                oFileUpEE.ProcessRequest(Request, false, false);

                //--- Loop through all of the files in the Files collection
                foreach (FileEe oFile in oFileUpEE.Files)
                {
                    //--- If a file was submitted, show the results
                    //--- FileEe.Size will be 0 if no file was submitted
                    if (oFile.Size != 0)
                    {
                        //--- Save the file to the webserver disk
                        oFile.Save();

                    }
                }
            }
            catch (SaProcessRequestException ex)
            {
                //--- In your error handling code you can override the preserve behavior
                //--- if you choose to preserve or delete resume information
                //oFileUpEE.PreserveResumeInfo = saPreserveBehavior.saPreserve;
                //oFileUpEE.PreserveResumeInfo = saPreserveBehavior.saDelete;

                Response.StatusCode = 500;
                Page.Response.Write("<B>WebServer ProcessRequest exception:</B>  "
                    + ex.Message);
            }
            catch (Exception ex)
            {
                //--- In your error handling code you can override the preserve behavior
                //--- if you choose to preserve or delete resume information
                //oFileUpEE.PreserveResumeInfo = saPreserveBehavior.saPreserve;
                //oFileUpEE.PreserveResumeInfo = saPreserveBehavior.saDelete;

                Response.StatusCode = 500;
                Page.Response.Write("<B>WebServer exception:</B>  " + ex.Message);
            }
            finally
            {
                //--- Always call FileUpEE.Dispose in finally block
                if (oFileUpEE != null)
                    oFileUpEE.Dispose();
                oFileUpEE = null;
            }
        }
    }
}

Top


XFileEE Resumable Download
XFileEE Documentation
You will find the complete XFileEE documentation at FileUpEE/XFile/XFile.chm, or on the SoftArtisans support site.

XFile Enterprise Edition (XFileEE) supports resumable downloading from web server to client. 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.

<% Show3TierExample "DownloadSamples/Client/XFileResumeDownload/XFileResumeDownload.asp",_ "DownloadSamples/Client/XFileResumeDownload/webserver.asp",_ "DownloadSamples/Client/XFileResumeDownload/fileserver.asp",_ "Resumable Download with XFileEE" %>

To enable resumable downloading with XFileEE:

  1. Set a ResumeInfo object, for example:
    Set XFileResumeInfo = XFileEE.ResumeInfo
  2. Set the ResumeInfo object'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 XFileEE.ResponseStatus <> "200 OK" Then
    MsgBox "The download has failed. Press the Resume button to attempt to & _
        redownload the file." & vbCrLf & "The response status from the web & _
        server was: " & vbCrLf & XFileEE.ResponseStatus
    document.all("ResumeFileButton").Disabled = False
Else
    MsgBox "The file has been successfully downloaded."
End If
  4. If the user chooses to resume the download, call the XFRequest object's Resume method, for example:

Dim resumejobid
resumejobid = XFileEE.ResumeInfo.JobID
...
XFileEE.Resume resumejobid
    In a resumable file transfer request, XFileEE 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.

To demonstrate resumable downloading, the example above forces a download failure by setting XFileEE'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.


Preserving Form Elements While Using XFileEE
XFileEE Documentation
You will find the complete XFileEE documentation at FileUpEE/XFile/XFile.chm, or on the SoftArtisans support site.
Preserving form values in an XFileEE file transfer

In a FileUpEE file transfer application using the XFileEE client, non-file form elements are not automatically preserved when the request is posted to the server page. In order to pass the form elements to the server-side code, it is necessary to explicitly add each element using the XFRequest.AddFormElement method. In the server-side code, the FileUpEE.Form element returns a collection of the non-file form elements of the request.

The following code snippet shows how to loop through each of the HTML form elements on the page and add the non-file elements manually to the XFileEE request:

Client-side processing

//--- Cycle through the elements in your form
for(i = 0; i < document.getElementById("form1").length; i++)
{
    //--- If it is a file element, we want to add it using the XFRequest.AddFile()
    //--- method.
    if (document.getElementById("form1").elements[i].type == "file")
    {
        //--- We only want to add the file is a file is selected
        if (!isEmpty(document.getElementById("form1").elements[i]))
        {
            //--- Add the file to the XFRequest object
            XFile.AddFile(document.getElementById("form1").elements[i].value, document.getElementById("form1").elements[i].id);
        }
    } else {
        //--- Add all non-file elements of the form as form elements using the
        //--- XFRequest.AddFormElement() method.
        XFile.AddFormElement(document.getElementById("form1").elements[i].name, document.getElementById("form1").elements[i].value);
    }
}

//--- Set the URL where you will upload the file to
XFile.CurrentUrl = serverURL;

try
{
    //--- Begin the transfer
    XFile.Start();

    //--- Write the server response to the div
    document.getElementById('divServerResponse').style.display = "block";
    ServerResponse.innerHTML = "<b>Server Response:</b>  " + XFile.Response;

}
catch(errorObject)
{
    alert("Error: " + errorObject.message +
        "An error has occurred during the upload.");

    //--- Write the server response to the div
    document.getElementById('divServerResponse').style.display = "block";
    ServerResponse.innerHTML = "<b>Server Response:</b>  " + XFile.Response;
}

//--- Clear files from the XFRequest object's Files collection
XFile.Files.RemoveAll();

//--- Enable the Reset button
document.getElementById("btnReset").disabled = false;

Server-side processing:

FileUpEe oFileUpEE = null;

try
{
    oFileUpEE = new FileUpEe();

    //--- Let FileUpEE know what stage we're working on
    oFileUpEE.TransferStage = saTransferStage.saWebServer;

    //--- Set the directory on the webserver where you want to save the files
    oFileUpEE.DestinationDirectory = Application["destinationdir"].ToString();

    oFileUpEE.ProcessRequest(Request, false, false);

    //-----------------------------------------------------------------
    //--- Here we're building a confirmation message about the upload
    //-----------------------------------------------------------------
    System.Text.StringBuilder sbConfirm = new System.Text.StringBuilder();

    sbConfirm.Append("<H2 ALIGN=\"center\">Upload results</H2>");
    sbConfirm.Append("<H3><u>Non-File Form elements:</u></H3>");

    //--- Use a foreach loop to iterate through all of the items in the Form collection
    //--- Each item in the Form collection has a Name and Value property
    foreach (SaDictionary oFormItem in oFileUpEE.Form)
    {
        sbConfirm.Append("<DL>");
        //--- Print the name of the form field
        sbConfirm.Append("<DT><B>" + oFormItem.Name + "</B></DT>");

        //--- If the Value property is a VariantMap, then it's a subcollection--
        //--- a form element with multiple values like checkboxes or multi-selects.
        //--- In this case the Value property itself is a collection and you need to loop
        //--- again
        if (oFormItem.Value is VariantMap)
        {
            //--- If it's a subcollection,
            //--- loop through the subitems in the Value property
            foreach (SaDictionary oSubItem in (VariantMap)oFormItem.Value)
                sbConfirm.Append("<DD>" + oSubItem.Value + "</DD>");
        }
        else
        {
            //--- If it's not a subcollection, print the value string
            sbConfirm.Append("<DD>" + oFormItem.Value + "</DD>");
        }

        sbConfirm.Append("</DL>");
    }

    //--- Loop through all of the files in the Files collection
    foreach (FileEe oFile in oFileUpEE.Files)
    {
        {
            try
            {
                //--- Save the file to the webserver disk
                oFile.Save();
            }
            catch (Exception ex)
            {
            }

        }
    }

    //--- Display the results in the webform
    Response.Write(sbConfirm.ToString());
}
catch (SaProcessRequestException ex)
{
    Response.StatusCode = 500;
    Page.Response.Write("<B>WebServer ProcessRequest exception:</B>  " + ex.Message);
}
catch (Exception ex)
{
    Response.StatusCode = 500;
    Page.Response.Write("<B>WebServer exception:</B>  " + ex.Message);
}
finally
{
    //--- Always call FileUpEE.Dispose in finally block
    if (oFileUpEE != null)
        oFileUpEE.Dispose();
    oFileUpEE = null;
}
Problems with Viewstate on XFileEE pages

SoftArtisans recommends separating the client-side XFileEE page and the server-side FileUpEE processing page. This is because XFileEE, as an ActiveX client-side object, would lose its state on postback. For this reason ASP.NET server-side controls should have their AutoPostBack property set to false if they are included in the same page as the XFileEE ActiveX object. As the upload is being posted from XFileEE, not from the browser, XFileEE cas easily be hosted in a separate page with the XFRequest.CurrentURL property set to the URL of the FileUpEE processing .uplx (for uploads) or .aspx (for downloads) page.

It should also be noted that among the elements that are not preserved during an XFileEE file transfer is the hidden _VIEWSTATE element that allows the application to preserve the viewstate of the application. The _VIEWSTATE element can be preserved just as any other form element by using the XFRequest.AddFormElement method, though the viewstate will not be valid if the request is posted to a separate processing page.


The Progress Indicator

  • Example: Pop-up Progress Indicator
  • Progress Indicator Methods and Properties

FileUpEE includes a server-side progress indicator that allows you to log and display the progress of an upload. Note that the progress indicator monitors the whole upload, and cannot watch the progress of an individual file within an upload.

FileUpEE's progress indicator can monitor uploads from client to web server, and from web server to file server. The progress from client to web server is measured as the number of bytes received on the web server. Progress from web server to file server is measured as the number of bytes sent from the web server; note that this is not proof of arrival on the file server.
To allow file uploads, NTFS permissions must be set appropriately for FileUpEE's temporary and destination directories. For more information, see Security Considerations.
Due to HTTP protocol and MIME-encoding parts of the upload request, the size of the request will be slightly larger than the size of the uploaded files.

XFileEE includes a client-side progress indicator that can monitor the upload of individual files from client to web server. To learn how to use XFileEE's progress indicator, see the XFileEE documentation at FileUpEE/XFile/XFile.chm.

Example: 3-Tier Upload with A Pop-up Progress Indicator

In this 3-tier upload example, the progress indicator is displayed in a pop-up browser window.

The progress indicator example includes four scripts:

  • Form.asp
    The upload form.

  • Progress.asp
    The pop-up progress indicator.

  • WebServer.asp
    The web server script. Webserver.asp includes all server-side upload processing instructions.

  • FileServer.asp
    The file server script. FileServer.asp executes the instructions that were set in WebServer.asp.

Form.asp

Form.asp contains the upload form. Form.asp creates two instances of the progress indicator for the two stages of the upload - client to web server and web server to file server:

Set oFileUpEEProgressWS = Server.CreateObject("SoftArtisans.FileUpEEProgress")
Set oFileUpEEProgressClient = Server.CreateObject("SoftArtisans.FileUpEEProgress")

The Watch property specifies the stage of the upload to monitor. In Form.asp, one progress indicator is set to monitor the upload from client to Web server (transfer stage saClient), and the other is set monitor the upload from web server to file server (transfer stage saWebServer):

'--- Watch the upload from client to web server. That is,
'--- monitor the upload as it is RECEIVED on the web server.
oFileUpEEProgressClient.Watch = saClient

'--- Watch the upload from web server to file server. That
'--- is, monitor the upload as it is SENT FROM the web server.
oFileUpEEProgressClient.Watch = saWebServer

The NextProgressID method generates progress ids for both stages of the upload - client to web server and web server to file server:

'--- Get a new progress ID for the client > web server layer
clProgID = oFileUpEEProgressClient.NextProgressID
'--- Get a new progress ID for the web server > file server layer
wsProgID = oFileUpEEProgressWS.NextProgressID

The two ProgressIds generated for the two stages of the upload will be identical. The ProgressIds will be passed to WebServer.asp and to Progress.asp through the startUpload() function. Clicking Upload File will call startupload(). The function submits the upload request with the progress ids to WebServer.asp, and opens the progress indicator window (Progress.asp), passing it the two progress ids:

function startUpload()
    {
        winstyle=
            "height=150,
            width=560,
            status=no,
            scrollbars=no,
            toolbar=no,
            menubar=no,
            location=no";
        window.open("progress.asp?
            wprogressid=<%=wsProgID%>
            &cprogressid=<%=clProgID%>",
            null,
            winstyle);
        document.theForm.action=
            "webserver.asp?
            wprogressid=<%=wsProgID%>
            &cprogressid=<%=clProgID%>";
    }
Progress.asp

Progress.asp is the pop-up progress indicator. The upload progress is displayed within an HTML table. For each stage of the upload, the table dispays: the progress id, a visual progress indicator, the number of bytes transferred so far, the percentage of bytes transferred so far, and total bytes to transfer.

The progress indicator monitors the whole upload. It does not watch the progress of an individual file within an upload.

As in Form.asp, two FileUpEEProgress objects are created for the two stages of the upload - client to web server and web server to file server. For each instance of the FileUpEEProgress object, the Watch property is set to the appropriate transfer stage (saClient or saWebServer).

Set oFileUpProgressClient = Server.CreateObject("Softartisans.FileUpEEProgress")
Set oFileUpProgressWS = Server.CreateObject("Softartisans.FileUpEEProgress")
oFileUpProgressClient.Watch = saClient
oFileUpProgressWS.Watch = saWebServer

The client and web server progress ids that were submitted in the query string are passed to the appropriate FileUpEEProgress objects:

oFileUpProgressClient.ProgressID = CInt(request.querystring("cprogressid"))
oFileUpProgressWS.ProgressID = CInt(request.querystring("wprogressid"))
The progress from client to web server is measured as the number of bytes received on the web server. Progress from web server to file server is measured as the number of bytes sent from the web server, which is not proof of arrival on the file server.
WebServer.asp

WebServer.asp runs on the web server. It includes all upload processing information. WebServer.asp sends the upload request to the file server script set by the TargetURL property. The request to the file server is a SOAP message (an XML file).

To enable progress indication, the FileUpEE object's ProgressIndicator property must be set to true for both upload stages:

oFileUpEE.ProgressIndicator(saClient) = True
oFileUpEE.ProgressIndicator(saWebServer) = True

The progress ids that were submitted in the query string must be passed to the FileUpEE object's ProgressID(saClient) and ProgressID(saWebServer) properties:

oFileUpEE.ProgressID(saClient) = CInt(request.querystring("cprogressid"))
oFileUpEE.ProgressID(saWebServer) = CInt(request.querystring("wprogressid"))
FileServer.asp

FileServer.asp is executed on the file server. FileServer.asp does not include upload processing instructions; it automatically executes the instructions that were set in WebServer.asp and sent from the web server as a SOAP message. FileUpEE automatically processes the request according to the SOAP message because AutoProcess - the third parameter of ProcessRequest - is set to True.

Top

Progress Indicator Methods and Properties
NextProgressID | The NextProgressId method returns the next unused ProgressId.
Percentage The Percentage property returns the percentage of the upload that was:
  • Received on the web server (if the upload is from client to Web server)

    OR

  • Sent to the file server (if the upload is from web server to file server)
ProgressId | The ProgressId property sets or returns a progress id number for an upload.
TotalBytes | The TotalBytes property returns the total number of bytes to be uploaded.
TransferredBytes The TransferredBytes property returns the number of bytes that were:
  • Received on the web server (if the upload is from client to Web server)

    OR

  • Sent to the file server (if the upload is from web server to file server)
Watch | The Watch property specifies the transfer stage that the progress indicator should watch: saClient or saWebServer.

Top


Large Uploads in ASP

  • XFileEE
  • FileUpEE Registry Keys
  • ScriptTimeout
  • Connection Timeout
  • Session State Considerations
XFileEE

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 XFileEE. Because XFileEE is an ActiveX component, it can only be used with the Microsoft Internet Explorer browser.

Top

FileUpEE Registry Keys

FileUpEE includes several registry keys that allow you to optimize the performance of large uploads. For more information see, FileUpEE Registry Keys.

Top

ScriptTimeout

ASP's ScriptTimeout property sets the length of time in seconds that ASP pages will allow for a script to execute. The default value of this property in IIS is 90 seconds. In a file upload, the ASP page must execute for the duration of the upload. If your user is transferring information over a slow line or is transferring a large quantity of information, it is easy to exceed this limit.

To increase the ASP ScriptTimeout in IIS:

  1. Right-click the application that will perform uploads, and select Properties.
  2. Select the Virtual Directory tab and click Configuration.
  3. Select App Options.
  4. In ASP Script Timeout, enter a value in seconds.

To increase the ASP ScriptTimeout in script, set the property Server.ScriptTimeout. For example:

<% Server.ScriptTimeout = 300 %>

The FileUpEE registry key DynamicAdjustScriptTimeout allows you to ensure that large uploads and downloads will not be timed out. If this key is set to True, IIS's ScriptTimeout value will be increased until an upload or download is complete.

To enable DynamicAdjustScriptTimeout:

  1. Open the Start menu and select Run...

  2. Enter regedit and click Ok.

  3. Open the folder HKEY_LOCAL_MACHINE\SOFTWARE\SoftArtisans\FileUpEE\Parameters.

  4. Double click DynamicAdjustScriptTimeout. An Edit DWORD Value dialog will open.

  5. In the Value Data field, enter 1.

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

Session State Considerations

When Session State is turned on, the page is serialized and the page is locked while the process finishes. During a large file transfer, this means that the user cannot take any other action on the page until the transfer is complete. If the page requires user action to be possible during a large transfer, the session state can be turned off by adding the statement <% EnableSessionState=False %> to the top of the page.

Top


Large Uploads in ASP.NET

  • XFileEE
  • FileUpEE's HttpModule
  • FileUpEE Registry Keys
  • Connection Timeout
  • .NET Settings
  • Session State Considerations
XFileEE

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 XFileEE. Because XFileEE is an ActiveX component, it can only be used with the Microsoft Internet Explorer browser.

Top

The HttpModule

FileUpEE'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.

With the web.config application key FilterAspDotNetFlagExtension, you can change the file extension used to signal the HttpModule in ASP.NET (.uplx) to a different extension of up to seven characters. By using a file extension other than .uplx you can hide your web server implementation (Windows/IIS) from potential hackers.

If you install the ASP.NET version of FileUpEE, the automatic installation package will install the HttpModule for FileUpEE'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.

The HttpModule and Progress Indication
Under ASP.NET, FileUpEE's progress indicator is handled by the HttpModule. To display accurate progress indication, upload to a file with the .uplx extension, and ensure that the ProgressIndicatorapplication key is set to 1.

Top

FileUpEE Registry Keys

FileUpEE includes several registry keys that allow you to optimize the performance of large uploads. For more information see, FileUpEE Registry Keys.

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

Session State Considerations

When Session State is turned on, the page is serialized and the page is locked while the process finishes. During a large file transfer, this means that the user cannot take any other action on the page until the transfer is complete. If the page requires user action to be possible during a large transfer, the session state can be turned to Read-Only by adding the statement <%Page EnableSessionState=ReadOnly %> to the top of the page.

Top


Large Uploads in IIS 6 and 7

  • The HttpModule
  • Chunked Transfer Encoding
  • AspMaxRequestEntityAllowed Metabase Property (IIS 6)
  • MaxRequestEntityAllowed IIS 7 Settings Schema Property
  • Session State Considerations

IIS 6 and 7 present two obstacles to very large file transfers: inefficient memory utilization and a 4-GB request size limit. To overcome these problems in IIS 6 and 7, FileUpEE provides the HttpModule and supports chunked transfer-encoding.

The HttpModule

FileUpEE'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 sending it 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.

With the FileUpEE registry key FilterAspDotNetFlagExtension, you can change the file extension used to signal the HttpModule in ASP.NET (.uplx) to a different extension of up to seven characters. By using a file extension other than .aspx you can hide your web server implementation (Windows/IIS) from potential hackers.

If you install the ASP.NET version of FileUpEE, the automatic installation package will install the HttpModule for FileUpEE'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.

Unlimited Upload Size on the Client
While FileUpEE can process uploads of any size, 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 XFileEE.
The HttpModule and Progress Indication
Under ASP.NET, FileUpEE's progress indicator is handled by the HttpModule. So, to display accurate progress indication, upload to a file with the .uplx extension.
Chunked Transfer-Encoding

IIS 6 and 7 get the size of a request from the request's content-length header, and do not accept requests larger than 4-GB. By default, IIS 6 and 7 accept requests of no more than 1-MB. You can increase this value by resetting the IIS 6 or 7 property MaxRequestEntityAllowed [image] , but the maximum value is 4-GB.

To overcome the request size limits imposed by IIS 6 and 7, FileUpEE supports chunked transfer-encoding. 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. Since IIS 6 and 7 reject a request because of the size of the request's content-length header, they find no reason to reject a request without a content-length header. With chunked-transfer encoding, no matter how large the upload, it will not be rejected by IIS 6 or 7.

To prevent misuse of chunked uploading, FileUpEE allows you to control the maximum allowable file transfer through the MaxKBytes and MaxKBytesToCancel properties.

Browsers do not support chunked transfer-encoding. To send a chunked upload from client to web server you must use SoftArtisans XFileEE. Chunked transfer-encoding is not supported by Microsoft ISA Server and Microsoft Proxy Server. If your requests must go through ISA Server or Proxy Server, you cannot use chunked-transfer encoding.

To enable uploads of more than 4-GB to IIS 6 (running in native IIS 6 mode) and 7, you must use chunked-transfer encoding.

To send a chunked upload from the client-side browser to the web server, set XFRequest.TransferEncoding to 1 in your client-side XFileEE code. Set TransferEncoding before calling Start.

<script type="text/javascript">
...
XFileEE.TransferEncoding = 1;
try
{
    XFileEE.Start;
    ...
}
...
</script>
<body>
    <!-- This OBJECT tag declares and loads the XFRequest object (the non-visual control of XFile) into the page.
    Change the CODEBASE attribute if you choose to deploy the SAXFileEE.cab from another location -->
    <object id="XFile" codebase="SAXFileEE.cab"
        classid="clsid:8B3512EF-4FF5-4aa4-9CDE-56BB03E04B9F">
</body>

To send a chunked upload from web server to file server, on the web server set FileUpEE.TransferEncoding to saChunked. Set TransferEncoding after setting TransferStage, and before ProcessRequest.

Set oFileUpEE = Server.CreateObject("SoftArtisans.FileUpEE")
oFileUpEE.TransferStage = saWebServer
oFileUpEE.TransferEncoding(saWebServer) = saChunked
...
oFileUpEE.ProcessRequest Request, False, False
AspMaxRequestEntityAllowed Metabase Property

In IIS 6.0, Microsoft introduced a new metabase property setting, AspMaxRequestEntityAllowed, to help users secure their web servers more easily. AspMaxRequestEntityAllowed lets users specify the maximum number of bytes allowed in the entity body of an ASP request. Unfortunately, this setting interferes with large FileUpEE uploads with ASP. If this setting is too low, you can observe the temp files being created but never saved, or IIS could return a 403 error response.

Additionally, multiple file uploads may return no error, but instead any file sent after the AspMaxRequestEntityAllowed value is exceeded will not be saved. The temp files will be created in the Path directory for all files in the transfer, but they will not be saved in the destination directory.

Hence, if you are performing large FileUpEE uploads in ASP on a server running IIS 6, you will need to edit the Metabase.xml file for your IIS installation. You can find your Metabase.xml file at C:\Windows\System32\Inetsrv. Find the AspMaxRequestEntityAllowed node and change the setting to a value just large enough for your largest uploads in bytes. For instance, if you expect no uploads greater than 1 GB, you can set the value to 1073741824.

For more information on the AspMaxRequestEntityAllowed metabase property, please read this article at the Microsoft Windows Server 2003 TechCenter: AspMaxRequestLengthEntityAllowed Metabase Property (IIS 6.0)

Session State Considerations

When Session State is turned on, the page is serialized and the page is locked while the process finishes. During a large file transfer, this means that the user cannot take any other action on the page until the transfer is complete. If the page requires user action to be possible during a large transfer, the session state can be turned off in ASP by adding the statement <% EnableSessionState=False %> or turned to Read-Only in ASP.NET by adding the statement <%Page EnableSessionState=ReadOnly %> to the top of the page.

Top


Using the HttpModule in Visual Studio .NET

Posting to files with a .uplx extension invokes FileUpEE's HttpModule. The HttpModule is necessary to provide accurate progress indication and adequate memory management when uploading with ASP.NET. In a production environment, any page receiving an upload should be named with a .uplx extension to take advantage of the HttpModule. Although .uplx pages are just ASP.NET web forms with a different file extension, you may find that Visual Studio .NET does not handle .uplx files in the same way that it does .aspx files. Visual Studio .NET may not allow you to edit .uplx web forms in the web form designer, or recognize the code-behind relationship between the web form and the class file. This section explains how to use the .uplx extension when developing a FileUpEE application in Visual Studio .NET.

Why use the .uplx file extension?
  • To utilize FileUpEE's accurate server-side progress indication for uploads.
  • To bypass ASP.NET's poor memory management during processing of upload requests.
Why use the .aspx extension for development?
  • To use Visual Studio .NET's advanced developer features like colorized code, IntelliSense, and drag-and-drop controls.
  • To use Visual Studio .NET's web form and code-behind pairing
Do I need to change the file extensions to get my samples to run?
No. The pages will run in Visual Studio .NET whether they are .uplx or .aspx, as long as the file extension is mapped to aspnet_isapi.dll. What you lose when opening .uplx pages in Visual Studio .NET are the advanced editing features.

To configure FileUpEE sample code to integrate with Visual Studio .NET:

  1. Change the sample application's file extensions from .uplx to .aspx. For example:

    Simple2Tier.uplx -> Simple2Tier.aspx
    Simple2Tier.uplx.cs -> Simple2Tier.aspx.cs

  2. Import Sample Files:

    1. Open Visual Studio .NET to create a new project.
    2. Specify either VB.NET or C# and name the web project.
    3. Right-click the project name in the Visual Studio .NET Solution Explorer.
    4. Choose Add, then Add Existing Item.
    5. Browse to and add the FileUpEE sample web form and code-behind pages that you renamed with the .aspx extension.

  3. At the top of the web form page, rename the Src directive to CodeBehind. For example, change:
    <%@ Page Language="c#" Inherits="FileUpEESamples.Simple2Tier" Debug="True"
         Src="Simple2Tier.uplx.cs" AutoEventWireup="false" %>

    To:

    <%@ Page Language="c#" Inherits="FileUpEESamples.Simple2Tier" Debug="True"
         CodeBehind="Simple2Tier.aspx.cs" AutoEventWireup="false" %>
  4. Add Object References:

    1. Right-click References in the Visual Studio .NET Solution Explorer.
    2. Choose Add References.
    3. Click Browse, go to the folder SoftArtisans\FileUpEE\DotNet, and select FileUpEE.dll, MimeClient.dll, FileUpEeProgress.dll, and - for use when the extension is .uplx - FileUpEeModule.dll. Finally, click Ok. Note: If you registered the dll files manually with regsvr32, and have more than one copy of each file, make sure you select the files you registered; for more information, see Installing FileUpEE for ASP.NET.

  5. Open the application's web.config file and add the following node:
    <httpModules>
    <add name="FileUpEeModule"
            type="SoftArtisans.Net.FileUpEeModule, FileUpEeModule,
                Version=x.x.x.x,
                Culture=neutral,
                PublicKeyToken=f593502af6ee46ae">
</httpModules>
    Note: The version attribute in web.config must match the FileUpEeModule.dll version exactly. To determine the dll version, locate FileUpEeModule.dll in Windows Explorer, right-click the file, choose Properties, select the Version tab. The file version is listed at the top.

To revert FileUpEE files for production:

  1. For the web form that posts to the code-behind page, change the file extension from .aspx to .uplx. For example:

    Simple2Tier.aspx -> Simple2Tier.uplx
  2. Add FileUpEeModule.dll to the application's bin directory.

  3. Add the HttpModule node to the application's web.config file, referencing the version of FileUpEeModule.dll in that application's bin directory.

Which files should I convert from .aspx to .uplx?
For production, rename the web form with a .uplx extension. You do not have to rename the code-behind page that the web form posts to. The progress indicator page should have a .aspx extension; while it is involved in an upload, it does not actually process the upload.

Top


Limiting Upload Size

  • The MaxKBytes Property
  • The MaxKBytesToCancel Property
  • XFile Client-Side Controls
  • Sending an Error Message to the User and Deleting the File

Limiting the size of uploads can be useful for file transfer applications for a number of different reasons, among them performance considerations, security against denial of service (DoS) attacks, and limited storage capacity.

There are two main levels where the upload size can be limited when performing an upload with FileUpEE: the client-side with XFileEE and on the server side with FileUpEE. Because FileUpEE resides on the server and the upload is initiated on the client machine, FileUpEE cannot access properties of a file until it is temporarily cached on the server. Hence, FileUpEE cannot limit file size before the upload begins. For this reason, XFileEE has the properties MaxFiles, MaxFileSize, and MaxTransferSize to control the side of uploads from the client side. FileUpEE's server-side upload size controls include the MaxKBytes and MaxKBytesToCancel properties, which can be set in the HttpModule application keys or directly through the FileUpEE object.

MaxKBytes: Limiting by Individual Files

The MaxKBytes property specifies the maximum number of kilobytes per file that the HttpModule will write to disk before passing on the request for further processing. This means that files will be truncated at the size specified in the MaxKBytes setting. No errors will be raised by FileUpEE when this occurs. Setting this key to 0, the default value, disables MaxKBytes. When using ASP, use the MaxKBytes property of the FileUpEE object. When using ASP.NET, you must use the HttpModule MaxKBytes application key instead, since the HttpModule processes the request before the ASP.NET script is executed.

FileUpEE will not return an error if the MaxKBytes value is exceeded. If you wish to return an error message to the user and/or to delete the file, you must add your own error handling.

MaxKBytesToCancel: Limiting by Total Request Size.

The MaxKBytesToCancel property specifies the maximum size in kilobytes of the entire Request before FileUpEE aborts the Request. Setting this key to 0, the default value, disables MaxKBytesToCancel. When using ASP, use the MaxKBytesToCancel property of the FileUpEE object. When using ASP.NET, you must use the HttpModule MaxKBytesToCancel application key, since the HttpModule processes the request before the ASP.NET script is executed.

FileUpEE does not catch an error when the MaxKBytesToCancel value is exceeded, but simply redirects the user to a 404 "Page Not Found" error page. This is because the connection is broken as soon as the MaxKBytesToCancel value is exceeded.

XFileEE Client-Side Controls

If your upload application uses XFileEE as its upload client, you can limit the size of the request, the size of the files being uploaded, and the number of files being uploaded using the MaxTransferSize, MaxFileSize, and MaxFiles properties of the XFRequest object. Exceeding the limits placed with any of these properties will cause a client-side error message to pop up. To use any of these properties, set it before calling XFRequest.AddFile() or the property will have no effect.

Please note that while these settings are useful in preventing files that are too large from being uploaded from your client side code, they are not foolproof in preventing attacks through your FileUpEE server code, as client-side security can be bypasses by skilled attackers. The highest level of security in FileUpEE code uses server-side limits whether or not client-side limits are set.

  • MaxTransferSize
    The MaxTransferSize property allows you to set the maximum size for the entire request in bytes. The browser will throw a pop-up error when you attempt to start a transfer and you will need to choose your files again before attempting to proceed.
  • MaxFileSize
    The MaxFileSize property allows you to set the maximum size for each file in the request. If one of your files exceeds the MaxFileSize setting, the browser will pop up an error and the transfer will not proceed.
  • MaxFiles
    The MaxFiles property allows you to set the maximum number of files that can be transferred in a single request. The browser will throw a pop-up error when you attempt to start a transfer, and you will not be able to start the transfer until the number of files chosen does not exceed the value of this property.
Sending an Error Message to the User and Deleting the File

Both of these settings are stop-gap measures that can be employed to protect your webserver from certain types of attacks; however, used alone, they are not ideal for providing a user-friendly experience to legitimate users. Whether or not you use MaxBytes, you will need to add your own error handling to avoid saving a large file and return a friendly error message to the user.

In your error handling, if you do not call a Save method, such as Save, SaveAs, or SaveAsBlob, when a file is above a certain size, the file will not be moved to the final destination and the temporary cache file will be automatically deleted.

  1. Using Size with MaxKBytes
    Since the MaxKBytes setting may result in truncated files, you will need to devise a system for distiguishing between files that are exactly the size of the MaxKBytes setting and those files that have been truncated. One possibility is to set MaxKBytes to 1 kilobyte higher than your actual cut-off point. The Size property of the FileEE object can be used to test for any files that are the same size as your MaxKBytes property. A message can be sent to the user that the file has been truncated, or the file can be deleted from the webserver with the .NET File object's delete method.

[C#]

//--- Get a reference to the uploaded file field
FileEE oFile = (FileEE)fileUpEE.Files["myFile"];

if(oFile != null)
{
    if(!oFile.IsEmpty)
    {
        // --- The MaxKBytes application key has been set to 1025
        // --- even though the actual desired cut-off is 1024
        // --- This will help us avoid confusion between properly
        // --- sized files and those that have been truncated
        // --- because of the MaxKBytes setting.
        long total;

        // --- Convert the file size from bytes to kilobytes
        total = oFile.Size/1000;

        if(total > 1024)
        {
            // --- Delete the file from the webserver, because it's
            // --- too large and most likely was truncated by the
            // --- MaxBytes setting anyway.
            File.Delete(oFile.ServerFileName);
        }
        else
        {
            try
            {
                oFile.Save();
            }
            catch (Exception ex)
            {
                // --- Write your error handling code here
            }
        }
    }
}

[VB.NET]

'--- Get a reference to the uploaded file field
Dim oFile As FileEE = CType(oFileUpEE.Form("myFile"), FileEE)

If Not (oFile Is Nothing) Then
    If Not (oFile.IsEmpty) Then

        '--- The MaxBytes application key has been set to 1025
        '--- even though the actual desired cut-off is 1024
        '--- This will help us avoid confusion between properly
        '--- sized files and those that have been truncated
        '--- because of the MaxBytes setting.

        Dim number as Long

        '--- Convert file size from bytes to kilobytes
        number = oFile.Size / 1000

        If (number > 1024) then
            '--- Delete the file from the webserver, because it's
            '--- too large and most likely was truncated by the
            '--- MaxBytes setting anyway.
            file.Delete(oFile.ServerFileName)
        Else
            Try
                oFile.Save()
            Catch ex As Exception
                '--- Write your error handling code here
            End Try
        End If
    End If
End If

Top


Streaming Requests in ASP

By default, when uploading files from client to web server to file server (a 3-tier upload), FileUpEE writes the upload to temporary files on the web server before sending the upload to the file server. FileUpEE begins writing the temporary files when ProcessRequest is called on the web server. FileUpEE's StreamRequest property enables streamed 3-tier uploading in ASP only. When this property is set to true on the web server, FileUpEE will stream the files submitted from the client directly to the file server, without writing temporary files on the web server. The advantages of a streamed upload are:

  • Improved performance: No temporary files are written on the web server.

  • Enhanced Security: The uploaded files are never on the web server in their complete form, either in memory or on disk.

3-tier streaming uploads are not available in ASP.NET. In a streamed request, no temp files are written to the webserver. However, in the .NET environment our httpModule must intercept the request and temporarily cache it to disk to avoid .NET's memory utilization issues. Therefore, streaming requests are only available in ASP.

To stream an upload request to the file server, set TargetUrl and set StreamRequest to true on the web server before calling ProcessRequest:

[VBScript]
Set oFileUpEE = Server.CreateObject("SoftArtisans.FileUpEE")
oFileUpEE.TransferStage = saWebServer
oFileUpEE.StreamRequest = True
...
oFileUpEE.ProcessRequest Request, False, False

The ProcessRequest method passes the request to FileUpEE. By default, FileUpEE does not stream uploads to the file server and will start writing the upload to temporary files when you call ProcessRequest on the web server. Therefore, setting StreamRequest to true after calling ProcessRequest has no effect. You must tell FileUpEE to stream the request before FileUpEE processes the request.

In a standard 3-tier upload (where StreamRequest is not enabled), FileUpEE begins uploading from web server to file server when SendRequest is called on the web server. If StreamRequest is set to true, FileUpEE will start streaming the upload to the file server when ProcessRequest is called on the web server. Therefore, before calling ProcessRequest, you must set properties that determine how the files will be uploaded from web server to file server. For example, FileUpEE must know where the upload request is going before streaming the request, so set TargetURL before calling ProcessRequest. When StreamRequest is true, the properties that must be set before ProcessRequest are those that take effect between SendRequest on the web server and ProcessRequest on the file server. For example, TargetURL, MaxKBytes(saFileServer), and TempStorageLocation(saFileServer) .

When you script a 3-tier streaming upload, order FileUpEE methods and properties on the web server as follows:

  1. Set TransferStage to saWebServer.
  2. Set StreamRequest to true.
  3. Set properties that take effect between SendRequest on the web server and ProcessRequest on the file server.
  4. Call ProcessRequest.
Limitations

Streamed 3-tier uploading offers significant performance and security advantages. However, this feature will not work in all 3-tier upload scenarios. It will not work if you want to get information submitted from the client, before setting any of the properties that must be set before ProcessRequest on the web server, because to access form values in the client upload request, you must first call ProcessRequest. For example, if you want to check the content-type of the uploaded file before setting the upload's TargetURL, you will have to set TargetURL after ProcessRequest, making a streamed upload impossible.

Note that in a streamed upload, you can set properties that determine how a file will be handled on the file server after calling ProcessRequest. For example, if you want to set an upload's destination directory based on its content-type, you can set DestinationDirectory on the web server, after ProcessRequest, but before SendRequest .

FileUpEE's streamed upload does not comply with the specification for SOAP Messages with Attachments [image], so it will not interoperate with the Java implementation of SOAP with Attachments in JAXM.


FileUpSE Support in ASP

If you have created upload applications using FileUp Standard Edition [image] (FileUpSE), you can use FileUpEE to create 3-tier uploads (client to web Server to file server) without rewriting your existing FileUpSE scripts. FileUpEE's FileUpCompat property allows you to use FileUpEE with FileUpSE.
The FileUpCompat property and FileUpSE support are available only in ASP, not in ASP.NET
FileUpSE can handle uploads of up to 4-GB. If you expect uploads greater than 4-GB, use FileUpEE on both the Web server and the file server.

A FileUpSE upload application includes a client-side file submission script and a server-side script that uses FileUp to process the upload:

In a 3-tier FileUpEE upload, if FileUpCompat is set to true on the web server, you can use a FileUpSE script on the file server:

In a FileUpCompat upload, FileUpEE must be installed on the web server, and FileUpSE on the file server.

When you use an existing FileUpSE script on the file server, in your FileUpEE web server script:

  1. Create an instance of FileUpEE:
    Set oFileUpEE = Server.CreateObject("SoftArtisans.FileUpEe")
  2. Set FileUpCompat to true:
    oFileUpEE.FileUpCompat = True
  3. Call ProcessRequest.
    oFileUpEE.ProcessRequest Request, False, False
  4. Set TargetUrl to the URL of the FileUpSE script on the file server:
    oFileUpEE.TargetUrl = "http://locahost/fileserver/FileUpResp.asp"
  5. Call SendRequest:
    intSAResult = oFileUpEE.SendRequest()
Limitations

FileUpEE's FileUpCompat property allows you to use FileUpEE without rewriting existing FileUpSE code. However, the following FileUpEE features are not available in a FileUpCompat application:

  • Resumable file transfers.
  • Auditing on the file server.
  • Unlimited upload size (FileUpSE can handle uploads of up to 4-GB).
Top


Glossary

2-Tier Download | A FileUpEE 2-tier download is a download from a Web server to a client.
3-Tier Download | A FileUpEE 3-tier download is a download from a file server to a Web server to a client.
2-Tier Upload | A FileUpEE 2-tier upload is an upload from client to Web server. FileUpEE handles 2-tier uploads according to the protocol for form-based file uploads defined in RFC 1867.
3-Tier Upload A FileUpEE 3-tier upload is an upload from client to Web server to file server. 3-tier uploading allows you to maintain a secure file server that is isolated from the Internet.

FileUpEE handles the browser to server part of the upload according to the protocol for form-based file uploads defined in RFC 1867. FileUpEE can handle the server to server part of the upload as either an RFC 1867 request or as a SOAP request with an attachment.
FileUp Enterprise Developer Edition

FileUpEE Developer offers the same functionality as FileUpEE, but processes only one upload or one download at a time, which is the typical development environment. Other restrictions may apply.

Licensing of FileUpEE Developer is per development server (not per developer). A developer license is required for every development server where FileUpEE Developer is installed. The developer license does not allow redistribution of FileUpEE Developer or SoftArtisans XFileEE.
FileUp Standard Edition FileUp Standard Edition [image] (FileUpSE) is a server-side file transfer tool. Like FileUpEE, FileUpSE can perform 2-tier form-based file uploads (RFC 1867) and secure downloads. Unlike FileUpEE, FileUpSE cannot perform 3-tier file transfers or process SOAP requests. FileUp can upload up to 4-GB.

If you have created upload applications using FileUpSE, you can use FileUpEE to create 3-tier uploads (client -> web Server -> file server) without rewriting your existing FileUpSE scripts. FileUpEE's FileUpCompat property allows you to use FileUpEE with FileUpSE. For more information on using the two products together, see FileUpSE Support.

Important: FileUpSE and FileUpEE have different object models. To run a FileUpSE script, you must install FileUpSE.
HttpModule FileUpEE's HttpModule is an interceptor that is used under ASP.NET to overcome inefficient memory utilization in ASP.NET and in IIS 6, to allow accurate progress indication, and to allow uploads of greater than 4-GB. The HttpModule intercepts an upload request, reads all the data, and writes it to a temp file chunk by chunk, before sending it to ASP.NET. With the HttpModule and chunked transfer-encoding, upload size in IIS 6 is unlimited.

Note that 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. FileUpEE includes SoftArtisans XFileEE, a client-side file transfer control that can submit uploads of any size.

For performance reasons, the HttpModule will not intercept all ASP.NET requests. Only requests for files with the extension .uplx will be handled by the HttpModule. Requests for files with the extension .aspx will not be processed by the HttpModule; they will be sent directly to ASP.NET. This prevents burdening the server with unnecessary use of the HttpModule.
Progress Indicator FileUpEE includes a server-side progress indicator that allows you to log and display the progress of an upload. The progress indicator monitors the whole upload; it does not watch the progress of an individual file within an upload.

FileUpEE's progress indicator can monitor uploads from client to web server, and from web server to file server. The progress from client to web server is measured as the number of bytes received on the web server. Progress from web server to file server is measured as the number of bytes sent from the web server; note that this is not proof of arrival on the file server.

For more information on using the progress indicator, see The Progress Indicator.
Resumable Upload | FileUpEE can resume client-to-server and server-to-server uploads that were suspended because of a network connection failure. In a resumable upload, if the upload is suspended, and the user clicks a Resume link or button, FileUpEE gets the status of the upload from a database and resumes the upload from the point at which it stopped. For more information, see A Resumable Upload.
RFC 1867 | RFC 1867 [image] defines a protocol for form-based file uploads. This type of upload submits form data (the file and/or other form elements) as name/value pairs. FileUpEE handles all uploads from browser to web server according to RFC 1867. FileUpEE usually handles uploads from web server to file server as SOAP messages with attachments, but can process server to server uploads according to RFC 1867 as in the example 3 Tier Upload with Standard FileUp.
SOAP Message with an Attachment In most cases, FileUpEE submits the server-to-server part of a file transfer as a SOAP message with an attachment [image]. SOAP (Simple Object Access Protocol) is an Internet protocol that uses HTTP as its transport and XML as its data format. A SOAP request is submitted in an XML document (the XML payload) via HTTP. Unlike a form-based upload request (RFC 1867), the XML payload can contain structured, hierarchical data.

A server-to-server file transfer SOAP request contains the the SOAP message in XML format and one or more files as attachments. The MIME content-type of a SOAP message with an attachment is "multipart/related." The various parts of the request - the SOAP message and the file or files to upload - are separated by MIME boundaries. Each MIME part includes a Content-Type header that describes the embedded data (the SOAP message or a file to upload), and other header information. All the MIME parts - the SOAP message and the attached files - form the request's HTTP body.

With FileUpEE, the server-to-server part of an upload or download is a SOAP request in all but two cases:

  • A 3-tier download (file server -> web server -> browser) that uses the method TransferFile on both the file server and the web server.
  • A 3-tier upload (browser -> web server -> file server) with Standard FileUp on the file server. See Standard FileUp Support.


Samples

FileUpEE includes numerous ASP.NET and ASP sample applications to help you learn how to use FileUpEE. The ASP.NET samples are available in C# and VB.NET versions, while the ASP samples are written in VBScript. The XFileEE ASP.NET Samples are written in C#, with client-side code written in JavaScript.

The FileUpEE automatic installer gives options for where to install the FileUpEESamples. During the install process, you can choose which existing website you wish to contain the FileUpEESamples or create a new website for the samples. On machines running IIS 5, you should install the samples in your active existing website, as only one website can be active at a time. On machines running IIS 6, you may choose from among the existing web sites or create a new one, whichever is preferred. On machines running IIS 7, you may have no other choice than to create a new website for the FileUpEESamples.

The automatic installation creates the virtual directory FileUpEESamples in IIS if you chose to install the samples in an existing web site. If you chose to install the samples in a new web site, the samples are instead installed directly into the new site. Three new virtual directories are also created under the FileUpEESamples main virtual directory or web site: BrowserBasedSamples, XFileEEASPSamples, and XFileEEDotNetSamples. Additionally, five new virtual directories are created under the XFileEEDotNetSamples virtual directory: FileServer, TwoTierNonResumableWebServer, TwoTierResumableWebServer, ThreeTierNonResumableWebServer, and ThreeTierResumableWebServer. Having discrete file server and three-tier web server virtual directories allows you to copy the file server and web server components onto different machines for testing with only a minor amount of editing.

To run the samples and view the code, open a browser window and enter the URL http://localhost/FileupEESamples if you chose to install the samples to an existing web site (if you are browsing the samples from a remote machine, replace "localhost" with your server name). If you chose to install the samples into a new web site, you can reach the samples default page by navigating to http://localhost:TCP port number/. The source code can be found in samples subdirectory of the FileUpEE program folder.

The Browser-based samples are accessible from the default page of the samples virtual directory or web site, an index page which includes links to the Browser-based upload and Browser-based download samples under the ASP.NET and ASP sections. These samples, available in ASP.NET (C# or VB.NET) and ASP (VBScript), show how to create FileUpEE applications that do not use the XFileEE client-side component.

The XFileEE ASP.NET Samples are accessible from the default page of the samples virtual directory or web site, an index page which includes links to the XFileEE ASP.NET Samples in the ASP.NET section. These new samples, in C# with JavaScript client-side code, demonstrate all of the advanced features available through FileUpEE with XFileEE integration, including 3-tier uploads and downloads, resumability, unlimited file transfer size, and a sophisticated HTML-based XFileEE progress indicator. Additionally, these samples show how to use the new FileUpEE constructor for ASP.NET resumable uploads.

The XFileEE ASP Samples are accessible from the default page of the samples virtual directory or web site, an index page which includes links to XFileEE ASP Samples in the ASP section. These samples, primarily in vbscript, show how to create ASP-based FileUpEE applications using the client-side XFileEE object to select files, perform progress indication, or enable resumability.

When using the automated installer on Windows 2008 and Vista, due to InstallShield limitations the only option for installing the samples application will be to create a new website. If you do not wish to have the installer create a new website, simply select the "do not install" checkbox. The samples may be installed into an existing website at a later time using the Samples Installer utility in the FileUpEE program folder under "\utilities\SASamplesInstaller".


Programmer's Reference

Object Model

FileUpEE Object

FileCollection Object

FileEE Object

Encryption Object

Progress Object

Windows System Error Codes

HTTP Status Codes


Object Model

FileUpEE Object Model

FileUpEE
Object Properties Methods
FileUpEE AuditLogDatabase, AuditLogDestination, AuditLogFile, CodePage, ConnectTimeout, ContentDisposition, ContentType, CopyFiles, DbConnection, DbPrimaryKey, DbPrimaryKeyValue, DbSqlCommand, DbTableName, Description, DestinationDirectory, DynamicAdjustScriptTimeout, Error, ErrorLogDatabase, ErrorLogDestination, ErrorLogFile, Files, FileUpCompat, FilterOn, Form, HostPort, HttpResponse, Item, JobId, MaxKBytes, MaxKBytesToCancel, OverwriteFiles, PerConnectionBandwidthLimit, PerServerBandwidthLimit, PreserveMacBinary, PreserveResumeInfo, ProgressId, ProgressIndicator, ReceiveTimeout, RequestTimeout, ResolveTimeout, Resumable, ResumeConnectionString, SaveMethod, SendTimeout, StatusUrl, StreamRequest, TargetUrl, TempStorageLocation, TransferEncoding, TransferStage, UseChecksum, UseMemory Add, AddDbDownloadFile, AddDownloadFile, AddFile, CreateDatabase, Dispose, NextProgressId, ProcessRequest, ResetAllProgressIds, ResetProgressId, Resume, ReturnStatus, SendRequest, SendResponse, TransferFile, TransferBlob, ValidateChecksums
FileCollection Count, Item Add, AddDbDownloadFile, AddDownloadFile, AddFile, AddFileEE, Remove, RemoveAll
FileEE Body, Checksum, ChunkSize, ClientFileName, ClientPath, ContentDisposition, ContentId, ContentType, CreateUniqueFileName, DbConnection, DbFileColumnName, DbIdentityColumnName, DbPrimaryKey, DbPrimaryKeyValue, DbSchema, DbSqlCommand, DbTableName, Description, DestinationFileExists, DestinationFileName, DestinationPath, DownloadedFileName, DownloadedPath, Error, ErrorCode, FileMethod, FormName, Name, OverwriteFile, Params, PreserveMacBinary, PreviousChecksum, Processed, RelativeName, SaveMethod, ServerFileName, Size, TempFile, UseChecksum Download, Save, SaveAs, SaveAsBlob, ValidateChecksum, WriteToResponse
Encryption (ASP.NET only) Encrypt


The FileUpEe Object

The FileUpEe object is a file-transfer control which processes both form-based file uploads and server-to-server SOAP transfers, enabling uploads from browser to web server to file server and downloads from file server to web server to browser.

FileUpEe in ASP.NET

The FileUpEE objects for ASP.NET are in the SoftArtisans.Net namespace. The objects can be referenced as fully qualified names, such as SoftArtisans.Net.FileUpEe. To minimize typing and errors, use an using (in C#) or Import (in VB.NET) directive to import the namespace to the ASP.NET page. This allows you to reference objects by name alone, without the namespace prefix. Add a reference to FileUpEE in ASP.NET by including this statement at the top of your code behind page:

In C#:      using SoftArtisans.Net;
In VB.NET:  Imports SoftArtisans.Net

To create an instance of FileUpEe in an ASP.NET page, use:

In C#:      FileUpEe oFileUpEe = new FileUpEe();
In VB.NET:  Dim oFileUpEe As New FileUpEe()

A new constructor which receives a boolean PreserveResumeInformation parameter has been added to FileUpEE for use with resumable uploads in ASP.NET. Passing in true will force FileUpEE to preserve resume information until the upload transfer is deemed successful. The default preserve behavior is to preserve resume information until the saSaveResult for each uploaded file returns saSaved or saExists. A new FileUpEE property, PreserveResumeInfo, can override this behavior.

In C#:      FileUpEe oFileUpEe = new FileUpEe(true);
In VB.NET:  Dim oFileUpEe as New FileUpEe(true)
FileUpEe in ASP

To create an instance of FileUpEe in an ASP page, use:

[VBScript]
Set objFileUpEe = Server.CreateObject("SoftArtisans.FileUpEe")
See Also
Form-based File Upload in HTML [image] and SOAP Messages with Attachments [image].
FileUpEe Properties |  |  | FileUpEe Methods
AuditLogDatabase | ErrorLogFile | ReceiveTimeout | Add
AuditLogDestination | Files | RequestTimeout | AddDbDownloadFile
AuditLogFile | FileUpCompat | ResolveTimeout | AddDownloadFile
CodePage | FilterOn | Resumable | AddFile
ConnectTimeout | Form | ResumeConnectionString | CreateDatabase
ContentDisposition | HostPort | SaveMethod | Dispose
ContentType | HttpResponse | SendTimeout | NextProgressId
CopyFiles | Item | StatusUrl | ProcessRequest
DbConnection | JobId | StreamRequest | ResetAllProgressIds
DbPrimaryKey | MaxKBytes | TargetUrl | ResetProgressId
DbPrimaryKeyValue | MaxKBytesToCancel | TempStorageLocation | Resume
DbSqlCommand | OverwriteFiles | TransferEncoding | ReturnStatus
DbTableName | PerConnectionBandwidthLimit | TransferStage | SendRequest
Description | PerServerBandwidthLimit | UseChecksum | SendResponse
DestinationDirectory | ProgressId | UseMemory | TransferBlob
DynamicAdjustScriptTimeout | ProgressIndicator |  | TransferFile
Error | PreserveMacBinary |  | ValidateChecksums
ErrorLogDatabase | PreserveResumeInfo |  |
ErrorLogDestination |  |  |
FileUpEe Properties
AuditLogDatabase
Syntax
objFileUpEE.AuditLogDatabase(SATransferStage) [= Database Connection String]
Description

AuditLogDatabase sets the connection string for FileUpEE's audit log database. FileUpEE will save audit logs in a database if AuditLogDestination is set to saLogDatabase.

AuditLogDatabase is a Read/Write property.

You can use the database FileUpEEWs.mdb for audit logging on the web server, and FileUpEEFs.mdb for audit logging on the file server. Both databases are located in the samples at doc-samples\Samples\UploadSamples\Intermediate\Resume\ASP. You can generate a new audit log database in ASP with the FileUpEE.CreateDatabase method. To see the audit log, open the table FileUpEE. The State column contains an SAUploadState value.

SAUploadState Values
saTransferComplete | 0
saTransferConnecting | 1
saTransferTransferring | 2
saTransferSuspended | 3
saTransferError | 4
saTransferCancelled | 5
saTransferIncomplete | 6
saTransferNotStarted | 7

The sample databases included with FileUpEE and the databases generated by FileUpEE.CreateDatabase are Access databases. To generate a set of tables for an Oracle or SQL Server database, run the script FileUpEE.sql. The script is included in the folder SoftArtisans\FileUpEE\samples.

Parameter

AuditLogDatabase takes the parameter SATransferStage which specifies the stage of the upload: client to web server or web server to file server.

SATransferStage Values
saWebServer | 1
saFileServer | 2
Note

When audit logging is on, FileUpEE will create an audit log record for each file transfer. On a busy system, this can make the audit log database very large. If you enable logging, remember to delete old items in the audit log database.

AuditLogDatabase must be set before calling the ProcessRequest method.

See Also
AuditLogDestination, AuditLogFile, ErrorLogDatabase, ErrorLogDestination, and ErrorLogFile.
Example
In ASP.NET:
[C#]
oFileUpEE.set_AuditLogDestination(saTransferStage.saWebServer, saLogDestination.saLogDatabase);
oFileUpEE.set_AuditLogDatabase(saTransferStage.saWebServer, "Provider=Microsoft.Jet.OLEDB.4.0;" +
    "Data Source=C:\FileUpEE\FileUpEEWS.mdb;" +
    "Persist Security Info=False");

[VB.NET]
oFileUpEE.AuditLogDestination(saTransferStage.saWebServer) = saLogDestination.saLogDatabase
oFileUpEE.AuditLogDatabase(saTransferStage.saWebServer) = "Provider=Microsoft.Jet.OLEDB.4.0;" & _
    "Data Source=C:\FileUpEE\FileUpEEWS.mdb;" & _
    "Persist Security Info=False"
In ASP:
[VBScript]
oFileUpEE.AuditLogDestination(saWebServer) = saLogDatabase
oFileUpEE.AuditLogDatabase(saWebServer) = "Provider=Microsoft.Jet.OLEDB.4.0;" & _
    "Data Source=C:\FileUpEE\FileUpEEWS.mdb;" & _
    "Persist Security Info=False"
Top
AuditLogDestination
Syntax
objFileUpEE.AuditLogDestination(SATransferStage) [= Audit Log Type as SALogDestination]
Description

AuditLogDestination sets the type of audit logging that FileUpEE will use. By default, FileUpEE will not create an audit log. To enable audit logging, set AuditLogDestination to an SALogDestination. When audit logging is enabled, FileUpEE will create an audit log for each file transfer. FileUpEE will record:

  • When the request from the previous stage (client, web server, or file server) began.
  • When the request from the previous stage completed.
  • When the upload to the next stage began.
  • When the upload to the next stage completed.
  • When the response from the next stage was received.
  • When the response to the previous stage began.
  • When the response to the previous stage completed.

AuditLogDestination is a Read/Write property.

Set AuditLogDestination to an SALogDestination:

SALogDestination Values
saNoLog | 0 (Default value) | FileUpEE will not create an Audit log.
saLogFile | 1 | The audit log will be a file set by the property AuditLogFile.
saLogDatabase | 2 | FileUpEE will save log records in a database set by the property AuditLogDatabase.
saEventLog | 4 | File transfers will be logged in the Windows EventLog. To view the log go to Start/Control Panel/Administrative Tools/Event Viewer.
saDebugString | 8 | File transfers will be logged in the system debugger. You can view the records with tools such as Sysinternals DebugView [image] .

If AuditLogDestination is set to saLogFile, set AuditLogFile. If AuditLogDestination is set to saLogDatabase, set AuditLogDatabase.

Parameter

AuditLogDestination takes the parameter SATransferStage which specifies the stage of the upload: client to web server or web server to file server.

SATransferStage Values
saWebServer | 1
saFileServer | 2
Note

When audit logging is on, FileUpEE will create an audit log for each file transfer. On a busy system, this can make the destination very large. If you enable logging, remember to delete old items in the log destination. This is particularly important when logging to a database or to Windows EventLog.

AuditLogDestination must be set before calling the ProcessRequest method.

See Also
AuditLogDatabase, AuditLogFile, ErrorLogDatabase, ErrorLogDestination, and ErrorLogFile.
Example
In ASP.NET:
[C#]
oFileUpEE.set_AuditLogDestination(saTransferStage.saWebServer, saLogDestination.saLogFile);
oFileUpEE.set_AuditLogFile(saTransferStage.saWebServer, "D:\FileUpEE\auditlog.txt");

[VB.NET]
oFileUpEE.AuditLogDestination(saTransferStage.saWebServer) = saLogDestination.saLogFile
oFileUpEE.AuditLogFile(saTransferStage.saWebServer) = "D:\FileUpEE\auditlog.txt"
In ASP:
[VBScript]
oFileUpEE.AuditLogDestination(saWebServer) = saLogFile
oFileUpEE.AuditLogFile(saWebServer) = "D:\FileUpEE\auditlog.txt"
Top
AuditLogFile
Syntax
objFileUpEE.AuditLogFile(SATransferStage) [= Audit Log Path as String]
Description

AuditLogFile sets the path and file name of FileUpEE's audit log file. When audit logging is enabled, FileUpEE will create an audit log for each file transfer. FileUpEE will save the audit log to a file if AuditLogDestination is set to saLogFile.

AuditLogFile is a Read/Write property.

Parameter

AuditLogFile takes the parameter SATransferStage which specifies the stage of the upload: client to web server or web server to file server.

SATransferStage Values
saWebServer | 1
saFileServer | 2
See Also
AuditLogDatabase, AuditLogDestination, ErrorLogDatabase, ErrorLogDestination, and ErrorLogFile.
Note

When audit logging is on, FileUpEE will create an audit log for each file transfer. On a busy system, this can make the destination very large. If you enable logging, remember to delete old items in the log destination. This is particularly important when logging to a database or to Windows EventLog.

AuditLogFile must be set before calling the ProcessRequest method.

Example
In ASP.NET:
[C#]
oFileUpEE.set_AuditLogDestination(saTransferStage.saWebServer, saLogDestination.saLogFile);
oFileUpEE.set_AuditLogFile(saTransferStage.saWebServer, "D:\FileUpEE\auditlog.txt");

[VB.NET]
oFileUpEE.AuditLogDestination(saTransferStage.saWebServer) = saLogDestination.saLogFile
oFileUpEE.AuditLogFile(saTransferStage.saWebServer) = "D:\FileUpEE\auditlog.txt"
In ASP:
[VBScript]
oFileUpEE.AuditLogDestination(saWebServer) = saLogFile
oFileUpEE.AuditLogFile(saWebServer) = "D:\FileUpEE\auditlog.txt"
Top
CodePage
Syntax
objFileUpEE.CodePage [= Language Code as Long]
Description

Sets or returns the language of the file(s) or folder(s) being transferred. SoftArtisans FileUpEE is Unicode compliant, enabling the transfer of data between systems regardless of language without the risk of data corruption. By setting FileUpEE's Codepage property you will be able to preserve file names in their original language.

FileUpEE's Codepage property specifies a Unicode language code for correctly storing the file name internally.

ASP.NET has end-to-end unicode support. To display the filename correctly in ASP, set the HTML <META> tag's Charset attribute as well as the Codepage property of the page directive.

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
In ASP.NET:
[C#]
objFileUpEE.CodePage = 65001;

[VB.NET]
objFileUpEE.CodePage = 65001
In ASP:
<%@ Language=VBScript codepage=65001 %>
<% Option Explicit %>
<HTML>
    <HEAD>
        <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
    </HEAD>
    ...
    <%
    objFileUpEE.CodePage=65001
    ...
    %>
</HTML>

Note on the use of XFileEE as the client:
When using XFileEE as the client, you must also remember to set the CodePage property of the XFRequest object.

Top
ConnectTimeout (3-tier transfers only)
Syntax
objFileUpEE.ConnectTimeout [= Timeout in Seconds as Long]
Description

ConnectTimeout sets a timeout value in seconds for web server connection requests to the file server. If a connection request takes longer than this value, the request will be cancelled. The default value of ConnectTimeout is 40 seconds.

ConnectTimeout is a Read/Write property.

Example
In ASP.NET:
[C#]
objFileUpEE.ConnectTimeout = 60;

[VB.NET]
objFileUpEE.ConnectTimeout = 60
In ASP:
[vbscript]
objFileUpEE.ConnectTimeout = 60
Top
ContentDisposition
Syntax
objFileUpEE.ContentDisposition [= MIME Content-Disposition as String]
Description

ContentDisposition specifies the upload's MIME content-disposition. For example, when uploading a file from a web form, the content-disposition value is form-data.

ContentDisposition is a Read/Write property.

Top
ContentType
Syntax
objFileUpEE.ContentType [= MIME Content-Type as String]
Description

ContentType specifies the transferred data's MIME content type (e.g., text/plain, application/msword, image/jpeg, application/pdf).

ContentType is a Read/Write property.

Example
In ASP.NET:
[C#]
oFileUpEE.ContentType = "text/plain";

[VB.NET]
oFileUpEE.ContentType = "text/plain"
In ASP:
[vbscript]
oFileUpEE.ContentType = "text/plain"
Top
CopyFiles
Syntax
objFileUpEE.CopyFiles(SATransferStage) [= Boolean]
Description

CopyFiles enables caching of the files to upload before sending a resumable upload request. When CopyFiles is set to true, FileUpEE will save a copy of the file to upload before sending the upload request. In a resumable upload, enabling CopyFiles guarantees that the upload will be resumable. If CopyFiles is set to false, FileUpEE will not pre-cache the files; if they are removed after a failed upload attempt, the request will not be resumable. CopyFiles is set to false by default.

When CopyFiles is enabled, uploads will be slower and will require more disk space.

CopyFiles is a Read/Write property.

Example
In ASP.NET:
[C#]
FileUpEE oFileUpEE = new FileUpEE();
oFileUpEE.TransferStage = saTransferStage.saWebServer;
oFileUpEE.set_CopyFiles(saTransferStage.saWebServer, true);
...

[VB.NET]
Dim oFileUpEE As New FileUpEE()
oFileUpEE.TransferStage = saTransferStage.saWebServer
oFileUpEE.CopyFiles(saTransferStage.saWebServer) = True
...
In ASP:
[VBScript]
Set oFileUpEE = Server.CreateObject("SoftArtisans.FileUpEE")
oFileUpEE.TransferStage = saWebServer
oFileUpEE.CopyFiles(saWebServer) = True
oFileUpEE.Resumable(saWebServer) = True
...
Top
DbConnection
Syntax
objFileUpEE.DbConnection [= Connection String]
Description

Use DbConnection to set the database connection string when uploading files to a database or downloading files from a database.

DbConnection is a Read/Write property.

See Also

Per-upload database properties: FileUpEE.DbPrimaryKey, FileUpEE.DbPrimaryKeyValue, FileUpEE.DbSqlCommand, FileUpEE.DbTableName and FileUpEE.SaveMethod.

Per-file database properties: FileEE.DbConnection, FileEE.DbFileColumnName, FileEE.DbPrimaryKey, FileEE.DbPrimaryKeyValue, FileEE.DbSqlCommand, FileEE.DbTableName, FileEE.SaveAsBlob, FileEE.SaveMethod, and FileEE.DbSchema.

Example
In ASP.NET:
[C#]
objFileUpEE.DbConnection = "Provider=Microsoft.Jet.OLEDB.4.0;" +
    @"Data Source=C:\Uploads\Images.mdb;" +
    "Persist Security Info=False";

[VB.NET]
objFileUpEE.DbConnection = "Provider=Microsoft.Jet.OLEDB.4.0;" & _
    "Data Source=C:\Uploads\Images.mdb;" & _
    "Persist Security Info=False"
In ASP:

[VBScript]
objFileUpEE.DbConnection = "Provider=Microsoft.Jet.OLEDB.4.0;" & _
    "Data Source=C:\Uploads\Images.mdb;" & _
    "Persist Security Info=False"
Top
DbPrimaryKey
Syntax
objFileUpEE.DbPrimaryKey [= Primary Key Column Name]
Description

DbPrimaryKey sets or returns a database table's primary key column name.

When uploading files to a database, to update a row, you must set DbPrimaryKey and DbPrimaryKeyValue. Do not set these values to add a row.

DbPrimaryKey is a Read/Write property.

See Also

Per-upload database properties: FileUpEE.DbConnection, FileUpEE.DbPrimaryKeyValue, FileUpEE.DbSqlCommand, FileUpEE.DbTableName, and FileUpEE.SaveMethod .

Per-file database properties: FileEE.DbConnection, FileEE.DbFileColumnName, FileEE.DbPrimaryKey, FileEE.DbPrimaryKeyValue, FileEE.DbSqlCommand, FileEE.DbTableName, FileEE.SaveAsBlob, FileEE.SaveMethod, and FileEE.DbSchema.

Example
In ASP.NET:
[C#]
...
objFileUpEE.DbTableName = "Files";
objFileUpEE.DbSqlCommand = "Select * from Files where FileId = 184";
objFileUpEE.DbPrimaryKey = "FileId";
objFileUpEE.DbPrimaryKeyValue = "6325";
...

[VB.NET]
...
objFileUpEE.DbTableName = "Files"
objFileUpEE.DbSqlCommand = "Select * from Files where FileId = 184"
objFileUpEE.DbPrimaryKey = "FileId"
objFileUpEE.DbPrimaryKeyValue = "6325"
...
In ASP:
[VBScript]
...
objFileUpEE.DbTableName = "Files"
objFileUpEE.DbSqlCommand = "Select * from Files where FileId = 184"
objFileUpEE.DbPrimaryKey = "FileId"
objFileUpEE.DbPrimaryKeyValue = "6325"
...
Top
DbPrimaryKeyValue
Syntax
objFileUpEE.DbPrimaryKeyValue [= Primary Key Value]
Description

DbPrimaryKeyValue sets or returns a database record's primary key value.

When uploading a file to a database, to update a row, you must set DbPrimaryKeyValue and DbPrimaryKey. Do not set these values to add a row.

When downloading a file from database, you must set DbPrimaryKeyValue for the record containing the file.

DbPrimaryKeyValue is a Read/Write property.

See Also

Per-upload database properties: FileUpEE.DbConnection, FileUpEE.DbPrimaryKey, FileUpEE.DbSqlCommand, FileUpEE.DbTableName, and FileUpEE.SaveMethod .

Per-file database properties: FileEE.DbConnection, FileEE.DbFileColumnName, FileEE.DbPrimaryKey, FileEE.DbPrimaryKeyValue, FileEE.DbSqlCommand, FileEE.DbTableName, FileEE.SaveAsBlob, FileEE.SaveMethod, and FileEE.DbSchema.

Example
In ASP.NET:
[C#]
...
objFileUpEE.DbTableName = "Files";
objFileUpEE.DbSqlCommand = "Select * from Files where FileId = 184";
objFileUpEE.DbPrimaryKey = "FileId";
objFileUpEE.DbPrimaryKeyValue = "6235";
...

[VB.NET]
...
objFileUpEE.DbTableName = "Files"
objFileUpEE.DbSqlCommand = "Select * from Files where FileId = 184"
objFileUpEE.DbPrimaryKey = "FileId"
objFileUpEE.DbPrimaryKeyValue = "6235"
...
In ASP:
[VBScript]
...
objFileUpEE.DbTableName = "Files"
objFileUpEE.DbSqlCommand = "Select * from Files where FileId = 184"
objFileUpEE.DbPrimaryKey = "FileId"
objFileUpEE.DbPrimaryKeyValue = "6235"
...
Top
DbSqlCommand
Syntax
objFileUpEE.DbSqlCommand [= SQL Query]
Description

Use DbSqlCommand to set a SQL query when transferring files to or from a database. DbSqlCommand is a Read/Write property.

See Also

Per-upload database properties: FileUpEE.DbConnection, FileUpEE.DbPrimaryKey, FileUpEE.DbPrimaryKeyValue, FileUpEE.DbTableName, and FileUpEE.SaveMethod.

Per-file database properties: FileEE.DbConnection, FileEE.DbPrimaryKey, FileEE.DbPrimaryKeyValue, FileEE.DbSqlCommand, FileEE.DbTableName, FileEE.SaveAsBlob, FileEE.SaveMethod, and FileEE.DbSchema.

Example
In ASP.NET:
[C#]
...
objFileUpEE.DbTableName = "Files";
objFileUpEE.DbSqlCommand = "Select * from Files where FileId = 184";
objFileUpEE.DbPrimaryKey = "FileId";
objFileUpEE.DbPrimaryKeyValue = "6325";
...

[VB.NET]
...
objFileUpEE.DbTableName = "Files"
objFileUpEE.DbSqlCommand = "Select * from Files where FileId = 184"
objFileUpEE.DbPrimaryKey = "FileId"
objFileUpEE.DbPrimaryKeyValue = "6325"
...
In ASP:
[VBScript]
...
objFileUpEE.DbTableName = "Files"
objFileUpEE.DbSqlCommand = "Select * from Files where FileId = 184"
objFileUpEE.DbPrimaryKey = "FileId"
objFileUpEE.DbPrimaryKeyValue = "6325"
...
Top
DbTableName
Syntax
objFileUpEE.DbTableName [= Database Table Name]
Description

When uploading files to a database, set DbTableName to the destination table for your upload.

When downloading files from a database, set DbTableName to the table containing the files to download.

To set the destination table for an individual file in an upload, use FileEE.DbTableName.

DbTableName is a Read/Write property.

See Also

Per-upload database properties: FileUpEE.DbConnection, FileUpEE.DbPrimaryKey, FileUpEE.DbPrimaryKeyValue, FileUpEE.SaveMethod, and FileUpEE.DbSqlCommand .

Per-file database properties: FileEE.DbConnection, FileEE.DbPrimaryKey, FileEE.DbPrimaryKeyValue, FileEE.DbSqlCommand, FileEE.DbTableName, FileEE.SaveAsBlob, FileEE.SaveMethod, and FileEE.DbSchema.

Example
In ASP.NET:
[C#]
...
objFileUpEE.SaveMethod = saSaveMethod.saDatabase;
objFileUpEE.DbConnection = "Provider=Microsoft.Jet.OLEDB.4.0;" +
    @"Data Source=C:\Uploads\files.mdb;" +
    "Persist Security Info=False";

//--- DbTableName specifies the upload's destination table in the database
objFileUpEE.DbTableName = "Images";
dbFileName = objFileUpEE[0].ClientFileName;
objFileUpEE[0].DbSchema.Add("File Name", dbFileName);
objFileUpEE[0].DbSchema.Add("ContentId", fileUp[0].ContentId);
...

[VB.NET]
...
objFileUpEE.SaveMethod = saSaveMethod.saDatabase
objFileUpEE.DbConnection = "Provider=Microsoft.Jet.OLEDB.4.0;" & _
    "Data Source=C:\Uploads\files.mdb;" & _
    "Persist Security Info=False"

'--- DbTableName specifies the upload's destination table in the database
objFileUpEE.DbTableName = "Images"
dbFileName = objFileUpEE(0).ClientFileName
objFileUpEE(0).DbSchema.Add("File Name", dbFileName)
objFileUpEE(0).DbSchema.Add("ContentId", fileUp(0).ContentId)
...
In ASP:

[VBScript]
...
objFileUpEE.SaveMethod = saDatabase
objFileUpEE.DbConnection = "Provider=Microsoft.Jet.OLEDB.4.0;" & _
    "Data Source=C:\Uploads\files.mdb;" & _
    "Persist Security Info=False"

'--- DbTableName specifies the upload's destination table in the database
objFileUpEE.DbTableName = "Images"
dbFileName = objFileUpEE(1).ClientFileName
objFileUpEE(1).DbSchema.Add "File Name", dbFileName
objFileUpEE(1).DbSchema.Add "ContentId", fileUp(1).ContentId
...
Top
Description
Syntax
objFileUpEE.Description [= String]
Description

Use Description to send metadata with the file transfer request. Description is a Read/Write property.

Example
In ASP.NET:
[C#]
FileUpEE oFileUpEE = new FileUpEE();
oFileUpEE.TransferStage = saTransferStage.saWebServer;
oFileUpEE.Description = "2-tier upload";
oFileUpEE.DestinationDirectory = Server.MapPath(@"/FileUpEE/samples/temp");
FileEE oFileEE = oFileUpEE.Files("myFile");
oFileEE.Save();
...

[VB.NET]
Dim oFileUpEE As New FileUpEE()
oFileUpEE.TransferStage = saTransferStage.saWebServer
oFileUpEE.Description = "2-tier upload"
oFileUpEE.DestinationDirectory = Server.MapPath("/FileUpEE/samples/temp")
Dim oFile As FileEE = oFileUpEE.Files("myFile")
oFile.Save()
...
In ASP:
[VBScript]
Set oFileUpEE = Server.CreateObject("SoftArtisans.FileUpEE")
oFileUpEE.TransferStage = saWebServer
oFileUpEE.Description = "2-tier upload"
oFileUpEE.DestinationDirectory = Server.MapPath("/FileUpEE/samples/temp")
Set oFile = oFileUpEE.Files("myFile")
oFile.Save
...
Top
DestinationDirectory
Syntax
objFileUpEE.DestinationDirectory [= Directory Path]
Description

To save all files in a file transfer to one directory, set DestinationDirectory to the destination directory path.

If you set DestinationDirectory, set each file's DestinationFileName. Alternatively, use DestinationPath to set both the directory and file name of an individual file.

You may include or omit the destination path's ending backslash; both of the following assignments will work:

objFileUpEE.DestinationDirectory = "C:\Uploads\"
objFileUpEE.DestinationDirectory = "C:\Uploads"

DestinationDirectory is a Read/Write property.

Example
In ASP.NET:
[C#]
objFileUpEE.DestinationDirectory = @"C:\Uploads\Images\";
objFileUpEE[0].DestinationFileName = "image1.jpg";
objFileUpEE[1].DestinationFileName = "image2.jpg";
objFileUpEE[2].DestinationFileName = "image3.jpg";

[VB.NET]
objFileUpEE.DestinationDirectory = "C:\Uploads\Images\"
objFileUpEE(0).DestinationFileName = "image1.jpg"
objFileUpEE(1).DestinationFileName = "image2.jpg"
objFileUpEE(2).DestinationFileName = "image3.jpg"
In ASP:
[VBScript]
objFileUpEE.DestinationDirectory = "C:\Uploads\Images\"
objFileUpEE(1).DestinationFileName = "image1.jpg"
objFileUpEE(2).DestinationFileName = "image2.jpg"
objFileUpEE(3).DestinationFileName = "image3.jpg"
Top
DynamicAdjustScriptTimeout (ASP only)
Syntax
objFileUpEE.DynamicAdjustScriptTimeout(SATransferStage) [= Boolean]
Description

The default ScriptTimeout value in IIS is 90 seconds. In a file upload, the ASP page must execute for the duration of the upload. If your user is transferring information over a slow line or is transferring a large quantity of information, it is easy to exceed this limit. If DynamicAdjustScriptTimeout is set to true, the IIS ScriptTimeout value will increase automatically as long as new data is coming from the browser.

DynamicAdjustScriptTimeout is a Read/Write property.

Note

In ASP.NET, you can only enable DynamicAdjustScriptTimeout in the application's web.config file. In ASP, however, you can either enable DynamicAdjustScriptTimeout in code or in the or Windows Registry Editor. To change the DynamicAdjustScriptTimeout registry key value:

  • From the Start menu, select Run....
  • Enter regedit and click Ok.
  • Open HKEY_LOCAL_MACHINE\SOFTWARE\SoftArtisans\FileUpEe\Parameters.
  • Right-click DynamicAdjustScriptTimeout, and select Modify.
  • In the Value data field, enter 1.
Example
[VBScript]
objFileUpEE.DynamicAdjustScriptTimeout(saWebServer)
Top
Error
Syntax
objFileUpEE.Error [= Error Message as String]
Description

Error sets or returns a FileUpEE error message.

Error is a Read/Write property.

Example
In ASP.NET:
[C#]
Response.Write(objFileUpEE.Error);

[VB.NET]
Response.Write(objFileUpEE.Error)
In ASP:
[VBScript]
Response.Write objFileUpEE.Error
Top
ErrorLogDatabase
Syntax
objFileUpEE.ErrorLogDatabase(SATransferStage) [= Error Database Connection String]
Description

ErrorLogDatabase sets the connection string for FileUpEE's error database. FileUpEE will log errors in a database if ErrorLogDestination is set to saLogDatabase.

You can use the database FileUpEEWs.mdb for error logging on the web server and FileUpEEFs.mdb for error logging on the file server. Both databases are in FileUpEE\samples\UploadSamples\Intermediate\Resume\ASP. You can generate a new error log database in ASP with FileUpEE.CreateDatabase. To see the audit log, open the Errors table.

The sample databases included with FileUpEE and the databases generated by FileUpEE.CreateDatabase are Access databases. To generate a set of tables for an Oracle or SQL Server database, run the script FileUpEE.sql. The script is included in the folder SoftArtisans\FileUpEE.

ErrorLogDatabase is a Read/Write property.

Parameter

ErrorLogDatabase takes the parameter SATransferStage which specifies the stage of the upload: client -> web server or web server -> file server.

SATransferStage Values
saWebServer | 1
saFileServer | 2
See Also
AuditLogDatabase, AuditLogDestination, AuditLogFile, ErrorLogDestination, and ErrorLogFile.
Note

ErrorLogDatabase must be set before calling the ProcessRequest method.

Example
In ASP.NET:
[C#]
objFileUpEE.set_ErrorLogDestination(saTransferStage.saWebServer, saLogDestination.saLogDatabase);
objFileUpEE.set_ErrorLogDatabase(saTransferStage.saWebServer, "Provider=Microsoft.Jet.OLEDB.4.0;" +
    "Data Source=C:\FileUpEE\FileUpEEWS.mdb;" +
    "Persist Security Info=False");

[VB.NET]
objFileUpEE.ErrorLogDestination(saTransferStage.saWebServer) = saLogDestination.saLogDatabase
objFileUpEE.ErrorLogDatabase(saTransferStage.saWebServer) = "Provider=Microsoft.Jet.OLEDB.4.0;" & _
    @"Data Source=C:\FileUpEE\FileUpEEWS.mdb;" & _
    "Persist Security Info=False"
In ASP:
[VBScript]
objFileUpEE.ErrorLogDestination(saWebServer) = saLogDatabase
objFileUpEE.ErrorLogDatabase(saWebServer) = "Provider=Microsoft.Jet.OLEDB.4.0;" & _
    "Data Source=C:\FileUpEE\FileUpEEWS.mdb;" & _
    "Persist Security Info=False"
Top
ErrorLogDestination
Syntax
objFileUpEE.ErrorLogDestination(SATransferStage) [= Error Log Type as SALogDestination]
Description

ErrorLogDestination sets the type of error logging that FileUpEE will use. By default, FileUpEE will not create an error log. To enable error logging, set ErrorLogDestination to an SALogDestination.

If ErrorLogDestination is set to saLogFile, set ErrorLogFile. If ErrorLogDestination is set to saLogDatabase, set ErrorLogDatabase.

ErrorLogDestination is a Read/Write property.

Set ErrorLogDestination to an SALogDestination:

SALogDestination Values
saNoLog | 0 (Default value) | FileUpEE will not create an Error log.
saLogFile | 1 | Errors will be logged in the file set by the property ErrorLogFile.
saLogDatabase | 2 | Errors will be logged in a database set by the property ErrorLogDatabase.
saEventLog | 4 | Errors will be logged in the Windows EventLog. To view the errors go to Start/Control Panel/Administrative Tools/Event Viewer.
saDebugString | 8 | Errors will be logged in the system debugger. You can view the errors with tools such as Sysinternals DebugView [image] .
Parameter

ErrorLogDestination takes the parameter SATransferStage which specifies the stage of the upload: client to web server or web server to file server.

SATransferStage Values
saWebServer | 1
saFileServer | 2
See Also
AuditLogDatabase, AuditLogDestination, AuditLogFile, ErrorLogDatabase, and ErrorLogFile.
Note

ErrorLogDestination must be set before calling the ProcessRequest method.

Example
In ASP.NET:
[C#]
objFileUpEE.set_ErrorLogDestination(saTransferStage.saWebServer, saLogDestination.saLogDatabase);
objFileUpEE.set_ErrorLogDatabase(saTransferStage.saWebServer, "Provider=Microsoft.Jet.OLEDB.4.0;" +
    @"Data Source=C:\FileUpEE\FileUpEEWS.mdb;" +
    "Persist Security Info=False");

[VB.NET]
objFileUpEE.ErrorLogDestination(saTransferStage.saWebServer) = saLogDestination.saLogDatabase
objFileUpEE.ErrorLogDatabase(saTransferStage.saWebServer) = "Provider=Microsoft.Jet.OLEDB.4.0;" & _
    "Data Source=C:\FileUpEE\FileUpEEWS.mdb;" & _
    "Persist Security Info=False"
In ASP:

[VBScript]
objFileUpEE.ErrorLogDestination(saWebServer) = saLogDatabase
objFileUpEE.ErrorLogDatabase(saWebServer) = "Provider=Microsoft.Jet.OLEDB.4.0;" & _
    "Data Source=C:\FileUpEE\FileUpEEWS.mdb;" & _
    "Persist Security Info=False"

Top
ErrorLogFile
Syntax
objFileUpEE.ErrorLogFile(SATransferStage) [= Error Log Path as String]
Description

ErrorLogFile sets the path and file name of FileUpEE's error log file. FileUpEE will log errors in a file if ErrorLogDestination is set to saLogFile.

ErrorLogFile is a Read/Write property.

Parameter

ErrorLogFile takes the parameter SATransferStage which specifies the stage of the upload: client to web server or web server to file server.

SATransferStage Values
saWebServer | 1
saFileServer | 2
See Also
AuditLogDatabase, AuditLogDestination, AuditLogFile, ErrorLogDatabase, and ErrorLogDestination.

ErrorLogFile must be set before calling the ProcessRequest method.

Example
In ASP.NET:
[C#]
objFileUpEE.set_ErrorLogDestination(saTransferStage.saWebServer, saLogDestination.saLogFile);
objFileUpEE.set_ErrorLogFile(saTransferStage.saWebServer, "C:\FileUpEE\ErrorLog.txt");

[VB.NET]
objFileUpEE.ErrorLogDestination(saTransferStage.saWebServer) = saLogDestination.saLogFile
objFileUpEE.ErrorLogFile(saTransferStage.saWebServer) = @"C:\FileUpEE\ErrorLog.txt"
In ASP:
[VBScript]
objFileUpEE.ErrorLogDestination(saWebServer) = saLogFile
objFileUpEE.ErrorLogFile(saWebServer) = "C:\FileUpEE\ErrorLog.txt"
Top
Files
Syntax
objFileUpEE.Files
Description

Files returns the collection of files in an upload.

Files is a Read Only property.

Example
In ASP.NET:
[C#]
FileUpEE objFileUpEE = new FileUpEE();
FileEE FirstFile = objFileUpEE.Files[0];
FirstFile.OverwriteFile = false;
FirstFile.DestinationPath = @"C:\Uploads\Images\file.gif";
...

[VB.NET]
Dim objFileUpEE As New FileUpEE()
Dim FirstFile As FileEE = objFileUpEE.Files(0)
FirstFile.OverwriteFile = False
FirstFile.DestinationPath = "C:\Uploads\Images\file.gif"
...
In ASP:

[VBScript]
Set objFileUpEE = Server.CreateObject("SoftArtisans.FileUpEE")
Set FirstFile = objFileUpEE.Files(0)
FirstFile.OverwriteFile = False
FirstFile.DestinationPath = "C:\Uploads\Images\file.gif"
...
Top
FileUpCompat (ASP Only)
Syntax
objFileUpEE.FileUpCompat [= Boolean]
Description

FileUpCompat allows you to use FileUpEE with FileUp Standard Edition [image]. You can use FileUpEE to create a 3-tier upload (client to web Server to file server) without rewriting your existing FileUpSE script.

A FileUpSE upload application includes a client-side file submission script and a server-side script that uses FileUpSE to process the upload:

In a 3-tier FileUpEE upload, if FileUpCompat is set to true on the web server, you can use a FileUpSE script on the file server:

When you use an existing FileUpSE script on the file server, in your web server script:

  1. Set FileUpCompat to true.
  2. Call ProcessRequest.
  3. Set TargetUrl.
  4. Call SendRequest.

FileUpCompat is a Read/Write property.

Example

The following is from a web server script in a 3-tier upload that uses FileUpSE on the file server:

[VBScript]
Set oFileUpEE = Server.CreateObject("SoftArtisans.FileUpEe"))
oFileUpEE.FileUpCompat = True
oFileUpEE.ProcessRequest Request, False, False
objFileUpEE.TargetUrl = "http://localhost/fileupeescripts/fs.asp"
objFileUpEE.SendRequest(Response)
Top
FilterOn
Syntax
objFileUpEE.FilterOn(SATransferStage) [= Boolean]
Description

The value of FilterOn tells you whether or not an upload was intercepted by the HttpModule. FilterOn returns true if the request was intercepted by the HttpModule, and false if it was not. The FilterOn property can be useful for testing and troubleshooting.

FilterOn is a Read Only property.

Example
In ASP.NET:
[C#]
FileUpEE oFileUpEE = new FileUpEE();
oFileUpEE.TransferStage = saTransferStage.saWebServer;
oFileUpEE.DestinationDirectory = Server.MapPath(@"/FileUpEE/samples/temp");
FileEE oFile = oFileUpEE.Files["myFile"];
oFile.Save();
if (oFile.Processed == saSaveResult.saSaved)
{
    Response.Write(@"<h3>Upload Successful</h3>");
    Response.Write("DestinationPath: " + oFile.DestinationPath);
    Response.Write("<br>");
    Response.Write("FilterOn: " + oFileUpEE.get_FilterOn(saTransferStage.saWebServer));
...

[VB.NET]
Dim oFileUpEE As New FileUpEE()
oFileUpEE.TransferStage = saTransferStage.saWebServer
oFileUpEE.DestinationDirectory = Server.MapPath("/FileUpEE/samples/temp")
Dim oFile as FileEE = oFileUpEE.Files("myFile")
oFile.Save()
If oFile.Processed = saSaveResult.saSaved Then
    Response.Write("<h3>Upload Successful</h3>")
    Response.Write("DestinationPath:" & oFile.DestinationPath)
    Response.Write("<br>")
    Response.Write("FilterOn:" & oFileUpEE.FilterOn(saTransferStage.saWebServer))
...
In ASP:
[VBScript]
Set oFileUpEE = Server.CreateObject("SoftArtisans.FileUpEE")
oFileUpEE.TransferStage = saWebServer
oFileUpEE.DestinationDirectory = Server.MapPath("/FileUpEE/samples/temp")
Set oFile = oFileUpEE.Files("myFile")
oFile.Save
If oFile.Processed = saSaved Then
    Response.Write "<h3>Upload Successful</h3>"
    Response.Write "DestinationPath:" & oFile.DestinationPath
    Response.Write "<br>"
    Response.Write "FilterOn:" & oFileUpEE.FilterOn(saWebServer)
...
Top
Form
Syntax
objFileUpEE.Form
Description

Form returns the collection of elements (name/value pairs) uploaded from an HTML form, excluding files.

Form is a Read Only property.

The Form collection has three properties:

Form Properties
Count | Returns the number of form elements (excluding files) in an uploaded HTML form.
Exists | Returns true if a specified form element exists, false if it does not.
Item | Represents a single form element in a Form collection. Item is the default property of Form, therefore, Form(2) is equivalent to Form.Item(2). Item takes a key and returns a form element. The key is the form element's name (the value of its HTML NAME attribute), or number (Item numbers are 0-based).
Is the form element a string or a collection?

Use the following methods to determine whether a member of the Form collection is a string (e.g., a radio button value) or a collection (e.g., a set of check box values).

  • Checking in ASP.NET

    In ASP.NET check if a form element's value is String to determine wheter the element is a single element or a collection. Example:

    [C#]
foreach(SaDictionary objElem in fileUp.Form)
{
    if(objElem.Value is String)
    {
        Response.Write("Name:");
        Response.Write(objElem.Name);
        Response.Write("Value:");
        Response.Write(objElem.Value);
    }
    else
    {
        Response.Write("Name:");
        Response.Write(strName);
        Response.Write("Value:");
        Response.Write("<br>");
        Response.Write("Sub Array:");

        foreach(SaDictionary objSubElem in (IEnumerable  )objElem.Value)
        {
            Response.Write("Name:");
            Response.Write(objSubElem.Name);
            Response.Write("Value:");
            Response.Write(objSubElem.Value);
            Response.Write("<br>");
        }
    }
    Response.Write("<br>");
}

[VB.NET]
For Each objElem As SaDictionary In fileUp.Form
    If objElem.Value Is String
        Response.Write("Name:")
        Response.Write(objElem.Name)
        Response.Write("Value:")
        Response.Write(objElem.Value)
    Else
        Response.Write("Name:")
        Response.Write(strName)
        Response.Write("Value:")
        Response.Write("<br>")
        Response.Write("Sub Array:")

        For Each objSubElem As SaDictionary In DirectCast(objElem.Value, IEnumerable  )
            Response.Write("Name:")
            Response.Write(objSubElem.Name)
            Response.Write("Value:")
            Response.Write(objSubElem.Value)
            Response.Write("<br>")
        Next
    End If
    Response.Write("<br>");
Next
  • Checking in ASP

    In ASP, a collection of elements is an object. Therefore, to determine whether a form element is a string or a collection, use IsObject to check if the form element's value is an object. For example:

    [VBScript]
For each item in objFileUpEE.Form
    Response.Write "Name: " & item.Name
    Response.Write "<br>"
    Response.Write "Value: "
        If IsObject(item.Value) then
            For each subitem in item.Value
                Response.Write "<br>"
                Response.Write "&nbsp;&nbsp;Name: " & subitem.Name
                Response.Write "<br>"
                Response.Write "&nbsp;&nbsp;Value: " & subitem.Value
            Next
         Else
            Response.Write item.Value
         End if
     Response.Write "<br>"
Next
Top
HostPort
Syntax
objFileUpEE.HostPort [=Port Number]
Description

Specifies the port that the web server will use to connect to the file server. The default value of HostPort is 80. This property has no effect on what port the web server will use for client requests.

HostPort is a Read/Write property.

Top
HttpResponse
Syntax
objFileUpEE.HttpResponse
Description

HttpResponse returns an instance of HttpParams that represents the HTTP/SOAP response from the previous stage of a file transfer. For example, in a 3-tier upload from client to web server to file server, HttpResponse on the web server represents the response from the file server to the web server.

HttpParams Properties
BodyText If the response from the next stage is not a SOAP response, you can use BodyText to get the HTTP response. Example:
oFileUpEE.HttpResponse.BodyText
Header Returns the value of a specified HTTP header. Example:
oFileUpEE.HttpResponse.Header("content-type")
Headers Returns all HTTP response headers. Example:
oFileUpEE.HttpResponse.Headers
Status Returns an HTTP status code. Example:
oFileUpEE.HttpResponse.Status

HttpResponse is a Read Only property.

Top
Item
Syntax
objFileUpEE[.Item](Key)
Description

Item represents a single file in a file transfer. Item is the default property of FileUpEE, so objFileUpEE(2) is equivalent to objFileUpEE.Item(2).

Item numbers are 0 based.

Item takes a key and returns a FileEE object.

Example
In ASP.NET:
[C#]
//--- Save the first file in an upload to a directory
objFileUpEE[0].SaveMethod = saSaveMethod.saDiskFile;
objFileUpEE[0].DestinationFileName = @"C:\Uploads\Images\image.jpg";
objFileUpEE[0].OverwriteFile = true;

[VB.NET]
'--- Save the first file in an upload to a directory
objFileUpEE(0).SaveMethod = saSaveMethod.saDiskFile
objFileUpEE(0).DestinationFileName = "C:\Uploads\Images\image.jpg"
objFileUpEE(0).OverwriteFile = True
In ASP:
[VBScript]
'--- Save the first file in an upload to a directory
objFileUpEE(0).SaveMethod = saDiskFile
objFileUpEE(0).DestinationFileName = "C:\Uploads\Images\image.jpg"
objFileUpEE(0).OverwriteFile = True
Top
JobId
Syntax
objFileUpEE.JobId [= JobId as String]
Description

In a resumable upload, FileUpEE generates a unique JobId for each upload (not for each file). If the upload is suspended, the upload's JobId and information about the incomplete upload will be stored by the HttpModule in ASP.NET or in an upload status database in ASP. You can then call Resume to resume the upload.

The Resume method takes an upload's JobId and uses it to get the suspended upload's status from the HttpModule or the database. Resume then continues the upload from the point at which it stopped.

JobId is a Read/Write property.

Example

In a standard 3-tier upload (client to web server to file server), there are three scripts: the client-side file submission script, the web server script, and the file server script. A resumable upload has two additional scripts: a resume-upload script and a status server script.

If the upload from web server to file server is suspended, and the user clicks a Resume link/button, the resume-upload script will be called. When the Resume method (within the resume-upload script) is called, a request will be made to the status server script. The response will tell FileUpEE the point at which the upload was suspended.

The following lines from the web server script create a link to the resume-upload script. The query string includes the JobId which the Resume method will need to get the status of the suspended upload.

In ASP.NET:
[C#]
...
saResult numRetVal = objFileUpEE.SendRequest();

//--- If the upload from web server to file server
//--- is suspended because of a network error, display
//--- a "Resume upload" link to send.aspx.
if (err.number != 0)
{
    Response.Write(@"<h2>Upload Failed</h2><br>");
    Response.Write(objFileUpEE.Error);
    Response.Write("<br><a href=send.aspx?JobId=" + objFileUpEE.JobId +
        @">Resume upload</a>");
    Response.End();
}
...

[VB.NET]
...
On Error Resume Next
Dim numRetVal As saResult = objFileUpEE.SendRequest()

'--- If the upload from web server to file server
'--- is suspended because of a network error, display
'--- a "Resume upload" link to send.aspx.
If err.number <> 0 Then
    Response.Write("<h2>Upload Failed</h2><br>")
    Response.Write(objFileUpEE.Error)
    Response.Write("<br><a href=send.aspx?JobId=" & objFileUpEE.JobId & _
        ">Resume upload</a>")
    Response.End()
End If
...
In ASP:
[VBScript]
...
On error resume next
numRetVal = objFileUpEE.SendRequest()

'--- If the upload from web server to file server
'--- is suspended because of a network error, display
'--- a "Resume upload" link to send.asp.
If err.number <> 0 then
    Response.Write "<h2>Upload Failed</h2><br>"
    Response.Write objFileUpEE.Error
    Response.Write "<br><a href=send.asp?JobId=" & objFileUpEE.JobId & _
        ">Resume upload</a>"
    Response.End
End if
...

In the resume-upload script (send.asp or send.aspx), Resume takes the upload's JobId and makes a request to the status server which returns the number of bytes received on the file server. Resume then continues the upload from the point at which it stopped.

In ASP.NET:
[C#]
...
//--- The Resume method takes the JobId sent from ws.aspx
//--- and resumes the upload from the point at which it
//--- stopped.
objFileUpEE.Resume(Request.QueryString("JobID"));
...

[VB.NET]
...
'--- The Resume method takes the JobId sent from ws.aspx
'--- and resumes the upload from the point at which it
'--- stopped.
objFileUpEE.Resume(Request.QueryString("JobID"))
...
In ASP:
[VBScript]
...
'--- The Resume method takes the JobId sent from ws.asp
'--- and resumes the upload from the point at which it
'--- stopped.
objFileUpEE.Resume(Request.QueryString("JobID"))
...
Top
MaxKBytes (ASP Only)
Syntax
objFileUpEE.MaxKBytes(SATransferStage) [= Upload size limit in Kilobytes as Double]
Description

Note: To set MaxKBytes in ASP.NET uploads, change the settings for the MaxKBytes application key in the web.config file.

MaxKBytes sets a file size limit for an upload. MaxKBytes is a per-file limit, not a limit for a whole multiple-file upload. For each file in an upload, FileUpEE will stop writing the file to disk at the value of MaxKBytes. Note that incomplete files will be saved and no error will be thrown if the MaxKBytes limit is exceeded.

In a client to web server to file server upload, you can set two upload size limits: a limit for the web server and a limit for the file server. The parameter SATransferStage specifies whether the size limit is for the web server or file server.

When MaxKBytes is set to zero, there is no size limit for uploaded files. MaxKBytes is set to zero by default.

To take effect, MaxKBytes(saWebServer) must be set before ProcessRequest is called on the web server. MaxKBytes(saFileServer) must be set before ProcessRequest is called on the file server.

MaxKBytes is a Read/Write property.

Parameter

MaxKBytes takes the parameter SATransferStage which specifies the stage of the upload: client to web server or web server to file server.

SATransferStage Values
saWebServer | 1
saFileServer | 2
Example

The following is from the web server script in an upload from browser to web server to file server:

[VBScript]
Set objFileUpEE = Server.CreateObject("SoftArtisans.FileUpEE")
objFileUpEE.MaxKBytes(saWebServer) = 500000
objFileUpEE.ProcessRequest Request, True, True
...
Top
MaxKBytesToCancel (ASP Only)
Syntax
objFileUpEE.MaxKBytesToCancel(SATransferStage) [= File size limit in Kilobytes as Double]
Description

Note: To set MaxKBytesToCancel in ASP.NET uploads, change the settings for the MaxKBytesToCancel application key in the web.config file.

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.

Setting MaxKBytesToCancel may reduce the threat of a Denial of Service (DoS) attack on the file server. When an upload size hits MaxKBytesToCancel, the connection to the server will be terminated, the ASP page will finish executing, and the ASP thread will be freed.

In a client to web server to file server upload, you can set one of two upload size limits: a limit for the web server or a limit for the file server. The parameter SATransferStage specifies whether the size limit is for the web server or file server.

To take effect, MaxKBytesToCancel(saWebServer) must be set before ProcessRequest is called on the web server. MaxKBytesToCancel(saFileServer) must be set before ProcessRequest is called on the file server.

MaxKBytesToCancel is a Read/Write property.

Parameter

MaxKBytesToCancel takes the parameter SATransferStage which specifies the stage of the upload: client to web server or web server to file server.

SATransferStage Values
saWebServer | 1
saFileServer | 2
Example

The following is from the file server script in an upload from browser to web server to file server:

[VBScript]
Set objFileUpEE = Server.CreateObject("SoftArtisans.FileUpEE")

'--- Set MaxKBytesToCancel before calling ProcessRequest.
objFileUpEE.MaxKBytesToCancel(saFileServer) = 500000
objFileUpEE.ProcessRequest Request, True, True
...
Top
OverwriteFiles
Syntax
objFileUpEE.OverwriteFiles [= Boolean]
Description

When OverwriteFiles set to true, an uploaded file will overwrite an existing file with the same name. When OverwriteFiles is set to false, an uploaded file will not be saved if a file with the same name exists.

OverwriteFiles is a Read/Write property, and is set to true by default.

See Also

To set this property for individual files, rather than the whole upload, use FileEE.OverwriteFile.

Top
PerConnectionBandwidthLimit

Syntax
objFileUpEE.PerConnectionBandwidthLimit(SATransferStage) [= Bandwidth Limit in Kilobytes per Second as Long]
Description

PerConnectionBandwidthLimit limits each download connection to a specific bandwidth in kilobytes per second. If this property is set, each download will not exceed the designated speed.

Example
In ASP.NET:
[C#]
FileUpEE oFileUpEE = new FileUpEE();

//--- Set bandwidth limit to 10-KB per second
oFileUpEE.PerConnectionBandwidthLimit = 10;

//--- Start the download
oFileUpEE.TransferFile(Page.Context, @"C:\Images\image.gif");

[VB.NET]
Dim oFileUpEE As New FileUpEE()

'--- Set bandwidth limit to 10-KB per second
oFileUpEE.PerConnectionBandwidthLimit = 10

'--- Start the download
oFileUpEE.TransferFile(Page.Context, "C:\Images\image.gif")
In ASP:
[VBScript]
Set oFileUpEE = Server.CreateObject("SoftArtisans.FileUpEE")

'--- Set bandwidth limit to 10-KB per second
oFileUpEE.PerConnectionBandwidthLimit = 10

'--- Start the download
oFileUpEE.TransferFile Request, Response, "C:\Images\image.gif"
Top
PerServerBandwidthLimit

Syntax
objFileUpEE.PerServerBandwidthLimit(SATransferStage) [= Bandwidth Limit in Kilobytes per Second as Long]
Description

When used in a download, PerServerBandwidthLimit will limit the total server output to a specific bandwidth in kilobytes per second. If PerServerBandwidthLimit is set, the total speed of the server's output for all connections combined will not exceed the designated limit. Each connection will get a proportion of bandwidth based on the total bandwidth available, divided by the number of current connections.

Example
In ASP.NET:
[C#]
FileUpEE oFileUpEE = new FileUpEE();

//--- Set the server output bandwidth limit to 1000 KB per
//--- second for all connections combined
oFileUpEE.PerServerBandwidthLimit = 1000;

//--- Start the download
oFileUpEE.TransferFile(Page.Context, @"C:\Images\image.gif");

[VB.NET]
Dim oFileUpEE As New FileUpEE()

'--- Set the server output bandwidth limit to 1000 KB per
'--- second for all connections combined
oFileUpEE.PerServerBandwidthLimit = 1000

'--- Start the download
oFileUpEE.TransferFile(Page.Context, "C:\Images\image.gif")
In ASP:
[VBScript]
Set oFileUpEE = Server.CreateObject("SoftArtisans.FileUpEE")

'--- Set the server output bandwidth limit to 1000 KB per
'--- second for all connections combined
oFileUpEE.PerServerBandwidthLimit = 1000

'--- Start the download
oFileUpEE.TransferFile Request, Response, "C:\Images\image.gif"
Top
PreserveMacBinary (ASP Only)
Syntax
objFileUpEE.PreserveMacBinary [= Boolean]
Description

If PreserveMacBinary is set to true, files uploaded from a Macintosh will be saved in MacBinary format. If this property is set to false, the data fork will be extracted and saved as the uploaded file. PreserveMacBinary is set to false by default.

PreserveMacBinary is a Read/Write property.

Note: When using the HttpModule, this property will have no effect.
Example
[VBScript]
objFileUpEE.PreserveMacBinary = True
Top
PreserveResumeInfo (ASP.NET only)
Syntax
objFileUpEE.PreserveResumeInfo [= Resume Preserve Info as saPreserveBehavior]
Description

PreserveResumeInfo gives control over the deletion of resume information in FileUpEE during a resumable upload transfer in ASP.NET. To use this property, the FileUpEe object must be instantiated with the PreserveResumeInformation parameter set to true.

PreserveResumeInfo is a Read/Write property.

Passing true to the FileUpEE constructor automatically enables the default resume behavior of FileUpEE, which is to preserve resume information until the upload transfer is deemed successful. By default, FileUpEE assumes an upload has succeeded if the saSaveResult for each uploaded file in the Files collection returns saSaved or saExists.

Setting the PreserveResumeInfo property to saPreserveBehavior.saPreserve or saPreserveBehavior.saDelete overrides FileUpEE's default resume behavior, preserving or deleting the resume information when the FileUpEe object is destructed.

saPreserveBehavior Values
saDefault | If the PreserveResumeInformation parameter was set to true in the constructor, FileUpEE will exhibit its default resume behavior - that is, FileUpEE will not delete the temporary resume and request files until it deems that the upload has succeeded. FileUpEE assumes an upload to be successful if the saSaveResult for each uploaded file in the Files collection returns saSaved or saExists.
saPreserve | FileUpEE will not delete the temporary resume and request files. They will remain in the FileUpEeModule's cache location along with the tmp files - that is, the actual uploaded files that were cached - until the the upload is deemed successful and the PreserveResumeInfo is set to saDefault. If this property is not explicitly reset to saDefault at some point in the upload processing, the uploaded files will never be moved to the final save location.
saDelete | FileUpEE will delete the temporary resume and request files whether the upload transfer succeeds or not.
Note
Example
[C#]
//--- You must pass the boolean value true into the FileUpEE
//--- constructor in order to enable PreserveResumeInformation
FileUpEE oFileUpEE = new FileUpEE(true);
...
if (oFile.Size != 0)
{
    try
    {
        //--- Save the file to the webserver disk
        oFile.Save();
    }
    catch(Exception ex)
    {
        //--- If there is a general exception, delete the temporary files
        oFileUpEE.PreserveResumeInfo = saPreserveBehavior.saDelete;
        saveExceptionInfo.Append("<b>WebServer exception: </b>An +
            error occurred when saving the file <i>" + oFile.ClientFileName +
            "</i><br/><b>Exception: </b>" + ex.Message + "<br/><br/>");
    }
}

[VB.NET]
'--- You must pass the boolean value true into the FileUpEE
'--- constructor in order to enable PreserveResumeInformation
Dim oFileUpEE As New FileUpEE(true)
...
If oFile.Size <> 0 Then
    Try
        '--- Save the file to the webserver disk
        oFile.Save()
    Catch ex As Exception
        '--- If there is a general exception, delete the temporary files
        oFileUpEE.PreserveResumeInfo = saPreserveBehavior.saDelete
        saveExceptionInfo.Append("<b>WebServer exception: </b>An " & _
            error occurred when saving the file <i>" & oFile.ClientFileName & _
            "</i><br/><b>Exception: </b>" & ex.Message & "<br/><br/>")
End If
Top
ProgressId
Syntax
objFileUpEE.ProgressId(SATransferStage) [= Long]
Description

ProgressId sets or returns an ID number for an upload that is being monitored by FileUpEE's progress indicator.

ProgressId is a Read/Write property.

Parameter

FileUpEE's progress indicator can monitor uploads from client to web server, and from web server to file server. The progress from client to web server is measured as the number of bytes received on the web server. Progress from web server to file server is measured as the number of bytes sent from the web server (note that this is not proof of arrival on the file server).

ProgressId takes the parameter SATransferStage which specifies the stage of the upload: client to web server or web server to file server.

SATransferStage Values for ProgressId
saClient | 0 | Upload to web server
saWebServer | 1 | Upload from web server
Example

The following is from the web server script in a 3-tier upload (client to web server to file server) application with a progress indicator.

In ASP.NET:
[C#]
FileUpEE objFileUpEE = new FileUpEe();
objFileUpEE.TransferStage = saTransferStage.saWebServer;

//--- Enable the progress indicator for both stages of the upload.
objFileUpEE.set_ProgressIndicator(saTransferStage.saClient, true);
objFileUpEE.set_ProgressIndicator(saTransferStage.saWebServer, true);

//--- Set the ProgressIds for each stage to the ProgressId values
//--- sent in the QueryString.
objFileUpEE.set_ProgressId(saTransferStage.saClient, Convert.ToInt32(Request.QueryString["progressid"]));
objFileUpEE.set_ProgressId(saTransferStage.saWebServer, Convert.ToInt32(Request.QueryString["WSprogressid"]));
...

[VB.NET]
Dim objFileUpEE As New FileUpEe()
objFileUpEE.TransferStage = saWebServer

'--- Enable the progress indicator for both stages of the upload.
objFileUpEE.ProgressIndicator(saTransferStage.saClient) = True
objFileUpEE.ProgressIndicator(saTransferStage.saWebServer) = True

'--- Set the ProgressIds for each stage to the ProgressId values
'--- sent in the QueryString.
objFileUpEE.ProgressId(saTransferStage.saClient) = Convert.ToInt32(Request.QueryString("progressid"))
objFileUpEE.ProgressId(saTransferStage.saWebServer) = Convert.ToInt32(Request.QueryString("WSprogressid"))
...
In ASP:
[VBScript]
Dim objFileUpEE
Set objFileUpEE = Server.CreateObject("SoftArtisans.FileUpEe")
objFileUpEE.TransferStage = saWebServer

'--- Enable the progress indicator for both stages of the upload.
objFileUpEE.ProgressIndicator(saClient) = True
objFileUpEE.ProgressIndicator(saWebServer) = True

'--- Set the ProgressIds for each stage to the ProgressId values
'--- sent in the QueryString.
objFileUpEE.ProgressId(saClient) = cint(Request.QueryString("progressid"))
objFileUpEE.ProgressId(saWebServer) = cint(Request.QueryString("WSprogressid"))
...
Top
ProgressIndicator
Syntax
objFileUpEE.ProgressIndicator(SATransferStage) [= Boolean]
Description

Set ProgressIndicator to true to turn on progress logging for the specified upload transfer stage. ProgressIndicator is set to false by default.

ProgressIndicator is a Read/Write property.

Example

The following is from the web server script in a 3-tier upload (client to web server to file server) application with a progress indicator.

In ASP.NET:
[C#]
FileUpEE objFileUpEE = new FileUpEe();
objFileUpEE.TransferStage = saTransferStage.saWebServer;

//--- Enable the progress indicator for both stages of the upload.
objFileUpEE.set_ProgressIndicator(saTransferStage.saClient, true);
objFileUpEE.set_ProgressIndicator(saTransferStage.saWebServer, true);

//--- Set the ProgressIds for each stage to the ProgressId values
//--- sent in the QueryString.
objFileUpEE.set_ProgressId(saTransferStage.saClient, Convert.ToInt32(Page.Request.QueryString("progressid")));
objFileUpEE.set_ProgressId(saTransferStage.saWebServer, Convert.ToInt32(Page.Request.QueryString("WSprogressid")));
...

[VB.NET]
Dim objFileUpEE As New FileUpEe()
objFileUpEE.TransferStage = saTransferStage.saWebServer

'--- Enable the progress indicator for both stages of the upload.
objFileUpEE.ProgressIndicator(saTransferStage.saClient) = True
objFileUpEE.ProgressIndicator(saTransferStage.saWebServer) = True

'--- Set the ProgressIds for each stage to the ProgressId values
'--- sent in the QueryString.
objFileUpEE.ProgressId(saTransferStage.saClient) = CInt(Page.Request.QueryString("progressid"))
objFileUpEE.ProgressId(saTransferStage.saWebServer) = CInt(Page.Request.QueryString("WSprogressid"))
...
In ASP:
[VBScript]
Dim objFileUpEE
Set objFileUpEE = Server.CreateObject("SoftArtisans.FileUpEe")
objFileUpEE.TransferStage = saWebServer

'--- Enable the progress indicator for both stages of the upload.
objFileUpEE.ProgressIndicator(saClient) = True
objFileUpEE.ProgressIndicator(saWebServer) = True

'--- Set the ProgressIds for each stage to the ProgressId values
'--- sent in the QueryString.
objFileUpEE.ProgressId(saClient) = cint(Request.QueryString("progressid"))
objFileUpEE.ProgressId(saWebServer) = cint(Request.QueryString("WSprogressid"))
...
Top
ReceiveTimeout
Syntax
objFileUpEE.ReceiveTimeout [= Timeout in Seconds as Long]
Description

ReceiveTimeout sets a time-out value, in seconds, for receiving a response to a request. If a response takes longer than this value, the request will be cancelled. The default value of ReceiveTimeout is 40 seconds.

ReceiveTimeout is a Read/Write property.

Example
In ASP.NET:
[C#]
objFileUpEE.ReceiveTimeout = 60;

[VB.NET]
objFileUpEE.ReceiveTimeout = 60
In ASP:
[VBScript]
objFileUpEE.ReceiveTimeout = 60

Top
RequestTimeout
Syntax
objFileUpEE.RequestTimeout(SATransferStage) [= Timeout in Seconds as Long]
Description

RequestTimeout sets a time, in seconds, at which a file transfer request will be killed, whether it is finished or not. The default value of RequestTimeout is 40 seconds.

RequestTimeout is a Read/Write property.

Parameter

RequestTimeout takes the parameter SATransferStage which specifies the stage of the upload: client to web server or web server to file server.

SATransferStage Values
saWebServer | 1
saFileServer | 2
Example
In ASP.NET:
[C#]
objFileUpEE.set_RequestTimeout(saTransferStage.saWebServer, 60);

[VB.NET]
objFileUpEE.RequestTimeout(saTransferStage.saWebServer) = 60
In ASP:
[VBScript]
objFileUpEE.RequestTimeout(saWebServer) = 60

Top
ResolveTimeout
Syntax
objFileUpEE.ResolveTimeout [= Timeout in Seconds as Long]
Description

ResolveTimeout sets a time-out value, in seconds, to use for name resolution. Name resolution is the process of obtaining a TCP/IP address from a host name (such as softartisans.com). If resolution takes longer than the value of ResolveTimeout, the action is cancelled. The default value of ResolveTimeout is 40 seconds.

ResolveTimeout is a Read/Write property.

Example
In ASP.NET:
[C#]
objFileUpEE.ResolveTimeout = 60;

[VB.NET]
objFileUpEE.ResolveTimeout = 60
In ASP:
[VBScript]
objFileUpEE.ResolveTimeout = 60
Top
Resumable (ASP Only)
Syntax
objFileUpEE.Resumable(SATransferStage) [= Boolean]
Description

Note: In ASP.NET, set resumability to true using the Resumable application key in the web.config file of the application's web server and/or file server.

When Resumable is set to true, FileUpEE will be able to resume an upload in ASP that was suspended because of a network connection failure or because the upload size was greater than MaxKBytesToCancel. Resumable is set to false by default.

Resumable takes the parameter SATransferStage which specifies the stage of the upload: client to web server or web server to file server. In a 3-tier upload from an HTML form (browser to web server to file server), FileUpEE can resume the upload if it was suspended between web server and file server. If you use XFile to upload from the client, FileUpEE can also resume the upload if it was suspended between client to web server. In a 3-tier upload, you must set Resumable to true for both the web server and the file server.

Set Resumable before calling ProcessRequest.

Resumable is a Read/Write property.

Parameter

Resumable takes the parameter SATransferStage which specifies the stage of the upload: client to web server or web server to file server.

SATransferStage Values
saWebServer | 1
saFileServer | 2
Example

The following lines are from the web server script in a resumable 3-tier upload (client -> web server -> file server) application.

[VBScript]
Dim objFileUpEE
Set objFileUpEE = Server.CreateObject("SoftArtisans.FileUpEE")

'--- Set the upload's transfer stage to saWebServer.
objFileUpEE.TransferStage = saWebServer

'--- Enable resumable upload on the web server.
objFileUpEE.Resumable(saWebServer) = True

'--- Enable resumable upload on the file server.
objFileUpEE.Resumable(saFileServer) = True

'--- Set the connection string for the web server's
'--- upload status database.
objFileUpEE.ResumeConnectionString(saWebServer) = "Provider=" & _
    "Microsoft.Jet.OLEDB.4.0;Data Source=" & _
    Server.MapPath(Application("vroot") & "FileUpEEWS.mdb") & _
    ";Persist Security Info=False"

'--- Set the connection string for the file server's
'--- upload status database.
objFileUpEE.ResumeConnectionString(saFileServer) = "Provider="& _
    "Microsoft.Jet.OLEDB.4.0;Data Source=" & _
    Server.MapPath(Application("vroot") & "FileUpEEFS.mdb") & _
    ";Persist Security Info=False"

'--- Pass the Request object to FileUpEE.
objFileUpEE.ProcessRequest Request
...
Top
ResumeConnectionString (ASP Only)
Syntax
objFileUpEE.ResumeConnectionString(SATransferStage) [= Connection String]
Description

Note: In ASP.NET, resume information is handled by the HttpModule and there is no upload status database.

In a resumable upload in ASP, if the upload is suspended because of a network connection failure or because the upload size was greater than MaxKBytesToCancel, FileUpEE will save information about the incomplete upload in an upload status database. ResumeConnectionString sets the connection string for the upload status database.

A resumable 3-tier upload in ASP (client to web server to file server) application uses two status databases, one on the web server and one on the file server. In the web server script, set ResumeConnectionString for both web server and file server. In the file server script set ResumeConnectionString for the file server. Set ResumeConnectionString before calling ProcessRequest.

ResumeConnectionString is a Read/Write property.

Parameter

ResumeConnectionString takes the parameter SATransferStage which specifies the stage of the upload: client to web server or web server to file server.

SATransferStage Values
saWebServer | 1
saFileServer | 2
Example

The following lines are from the file server script in a resumable 3-tier upload (client -> web server -> file server) application.

[VBScript]
Dim objFileUpEE
Set objFileUpEE = Server.CreateObject("SoftArtisans.FileUpEE")

'--- Set the upload's transfer stage to saFileServer.
objFileUpEE.TransferStage = saFileServer

'--- Enable resumable upload on the file server.
objFileUpEE.Resumable(saFileServer) = True

'--- Set the connection string for the file server's
'--- upload status database. If the upload to the file
'--- server stops before all the data is transferred,
'--- FileUpEE will enter upload status information in
'--- this database. To resume  the upload, FileUpEE
'--- reads the status of the suspended upload from this
'--- database.
objFileUpEE.ResumeConnectionString(saFileServer) = "Provider=" & _
    "Microsoft.Jet.OLEDB.4.0;Data Source=" & _
    Server.MapPath(Application("vroot") & "FileUpEEFS.mdb") & _
    ";Persist Security Info=False"

'--- Pass the request from the web server to FileUpEe.
objFileUpEe.ProcessRequest Request, True, True

'--- Send the file server response to the web server.
objFileUpEE.SendResponse Response
Top
SaveMethod
Syntax
objFileUpEE.SaveMethod [= saSaveMethod]
Description

SaveMethod specifies whether uploaded files will be saved to a file directory or in a database. SaveMethod is a Read/Write property.

Set SaveMethod to an saSaveMethod by name or number:

saSaveMethod Values
saDatabase | 0
saDiskFile | 1 (Default value)
See Also

FileEE.SaveMethod

Example
In ASP.NET:
[C#]
...
objFileUpEE.SaveMethod = saSaveMethod.saDatabase;
objFileUpEE.DbConnection = "Provider=Microsoft.Jet.OLEDB.4.0;" +
    @"Data Source=C:\Uploads\files.mdb;" +
    "Persist Security Info=False";
objFileUpEE.DbTableName = "Images";
String dbFileName = objFileUpEE.ClientFileName;
objFileUpEE[0].DbSchema.Add("File Name", dbFileName);
...

[VB.NET]
...
objFileUpEE.SaveMethod = saSaveMethod.saDatabase
objFileUpEE.DbConnection = "Provider=Microsoft.Jet.OLEDB.4.0;" & _
    "Data Source=C:\Uploads\files.mdb;" & _
    "Persist Security Info=False"
objFileUpEE.DbTableName = "Images"
Dim dbFileName As String = objFileUpEE.ClientFileName
objFileUpEE(0).DbSchema.Add("File Name", dbFileName)
...
In ASP:
[VBScript]
...
objFileUpEE.SaveMethod = saDatabase
objFileUpEE.DbConnection = "Provider=Microsoft.Jet.OLEDB.4.0;" & _
    "Data Source=C:\Uploads\files.mdb;" & _
    "Persist Security Info=False"
objFileUpEE.DbTableName = "Images"
dbFileName = objFileUpEE.ClientFileName
objFileUpEE(1).DbSchema.Add "File Name", dbFileName
...
Top
SendTimeout
Syntax
objFileUpEE.SendTimeout[= Timeout in Seconds as Long]
Description

SendTimeout sets a time-out value, in seconds, to use for sending requests. If sending a request takes longer than this value, the send will be cancelled. The default value of SendTimeout is 40 seconds.

Example
In ASP.NET:
[C#]
objFileUpEE.SendTimeout = 60;

[VB.NET]
objFileUpEE.SendTimeout = 60
In ASP:
[VBScript]
objFileUpEE.SendTimeout = 60
Top
StatusUrl (3-tier resumable transfers only)
Syntax
objFileUpEE.StatusUrl [=URL]
Description

In a standard 3-tier resumable upload (client to web server to file server), there are three scripts: the client-side file submission script, the web server script, and the file server script. A resumable upload has two additional scripts: a resume-upload script (on the web server) and a status server script (on the file server).

If the upload from web server to file server is suspended, and the user clicks a Resume link/button, the resume-upload script will be called. When the Resume method is called (within the resume-upload script), a request will be made to the status server script. The response will tell FileUpEE the point at which the upload was suspended.

StatusUrl specifies the URL of the status server script. You can set StatusUrl in the web server script, before calling SendRequest, or in the resume-upload script, before calling Resume.

Example

The status database and the status script are on the file server. You can set StatusUrl in the web server script, before calling SendRequest, or in the resume-upload script, before calling Resume.

In ASP.NET:
[C#]
//--- Set the status URL on the file server. If the
//--- upload is suspended, and the user click's "Resume,"
//--- status.aspx will return the status of the suspended
//--- upload. The Resume method will restart the upload
//--- from the point at which it stopped.
objFileUpEE.StatusUrl = @"http://localhost/fileupee/status.aspx";

[VB.NET]
'--- Set the status URL on the file server. If the
'--- upload is suspended, and the user click's "Resume,"
'--- status.aspx will return the status of the suspended
'--- upload. The Resume method will restart the upload
'--- from the point at which it stopped.
objFileUpEE.StatusUrl = "http://localhost/fileupee/status.aspx";
In ASP:
[VBScript]
'--- Set the status URL on the file server. If the
'--- upload is suspended, and the user click's "Resume,"
'--- status.asp will return the status of the suspended
'--- upload. The Resume method will restart the upload
'--- from the point at which it stopped.
objFileUpEE.StatusUrl = "http://localhost/fileupee/status.asp"
Top
StreamRequest (ASP only)
Syntax
objFileUpEE.StreamRequest [= Boolean]
Description

Important Note: Streaming Uploads are only available in ASP, due to limitations in the .NET framework. Therefore, this property is only effective in an ASP environment.

In an ASP-based 3-tier upload (client to web server to file server), FileUpEE can stream the files submitted from the client directly to the file server without writing temporary files on the web server. The advantages of a streamed upload are:

  • Improved performance: No temporary files are written on the web server.
  • Security: The uploaded files are never on the web server in their complete form, either in memory or on disk.

To stream an upload request to the file server:

  1. On the web server, set StreamRequest to true before calling ProcessRequest.

    The ProcessRequest method passes the request to FileUpEE. By default, FileUpEE does not stream uploads to the file server and will start writing the upload to temporary files when you call ProcessRequest on the web server. Therefore, setting StreamRequest to true after calling ProcessRequest has no effect. You must tell FileUpEE to stream the request before FileUpEE processes the request.

  2. On the web server, set properties that affect how the files will be uploaded from web server to file server before calling ProcessRequest. For example, set TargetURL, MaxKBytes(saFileServer), and TempStorageLocation(saFileServer) before calling ProcessRequest.

    If StreamRequest is set to true, FileUpEE will start streaming the upload to the file server when ProcessRequest is called. Therefore, before calling ProcessRequest, you must set properties that determine how the files will be uploaded from web server to file server. For example, FileUpEE must know where the upload request is going before streaming the request, so set TargetURL before calling ProcessRequest.

To access form values in the client upload request, you must first call ProcessRequest. Therefore, if you want to get information submitted from the client before setting TargetURL on the web server, you cannot stream the request to the file server. For example, if you want to check the content-type of the uploaded file before setting the upload's TargetURL, you will have to set TargetURL after ProcessRequest, making a streamed upload impossible.

StreamRequest is a Read/Write property.

Note

FileUpEE's streamed upload does not comply with the specification for SOAP Messages with Attachments [image], so it will not interoperate with the Java implementation of SOAP with Attachments in JAXM.

Example
[VBScript]
Set oFileUpEE = Server.CreateObject("SoftArtisans.FileUpEE")
oFileUpEE.TransferStage = saWebServer

'--- Set StreamRequest to True before calling ProcessRequest on
'--- the web server and before setting properties that take effect
'--- between SendRequest on the web server
'--- and ProcessRequest on the file server.
oFileUpEE.StreamRequest = True
oFileUpEE.TargetUrl = "http://localhost/FileUpEE/StreamUpload/fileserver.asp"
oFileUpEE.ProcessRequest Request, False, False
...
Top
TargetUrl
Syntax
objFileUpEE.TargetUrl [= URL]
Description

Set TargetUrl to the page to which FileUpEE will submit a server-to-server request. TargetUrl is a Read/Write property.

Example

When submitting an upload from a web form to a web server to a file server, set TargetUrl to the destination page on the file server. So, if the web form submits to webserver.asp, and the processing page on the file server is fileserver.asp, set TargetUrl on webserver.asp to the URL of fileserver.asp.

In ASP.NET:
[C#]
objFileUpEE.TargetUrl = "http://www.fileserver.com/fileserver.aspx";

[VB.NET]
objFileUpEE.TargetUrl = "http://www.fileserver.com/fileserver.aspx"
In ASP:
[VBScript]
objFileUpEE.TargetUrl = "http://www.fileserver.com/fileserver.asp"
Top
TempStorageLocation (ASP Only)
Syntax
objFileUpEE.TempStorageLocation(SATransferStage) [= Temp Directory]
Description

Note: In ASP.NET uploads, the temporary storage location is set using the HttpModule's FileUpEETempDir application key.

When an upload reaches the web server or the file server, the upload is cached. TempStorageLocation sets the cache directory on the specified server. If you do not assign a value to TempStorageLocation, uploads will be cached in the system's default directory for cached files, which is determined by the system environment variable TEMP.

To take effect, TempStorageLocation(saWebServer) must be set before ProcessRequest is called on the web server. TempStorageLocation(saFileServer) must be set before ProcessRequest is called on the file server.

You may include or omit the temp path's ending backslash; both of the following assignments will work:

[VBScript]
objFileUpEE.TempStorageLocation(saWebServer) = "C:\Temp\"
objFileUpEE.TempStorageLocation(saWebServer) = "C:\Temp"

TempStorageLocation is a Read/Write property.

Parameter

TempStorageLocation takes the parameter SATransferStage which specifies whether to set the directory on the web server or file server. Note that FileUpEE will cache files on both the web server and the file server.

SATransferStage Values
saWebServer | 1
saFileServer | 2
Note

To change the system's default directory for cached files, reset the TEMP environment variable, as follows:

  • Open the Control Panel.
  • Select System .
  • Select the Advanced tab.
  • Click Environment variables...
  • Select TEMP from the System Variables list.
  • Click Edit .
  • Enter a new Variable Value, and click Ok .
Example

[VBScript]
Set objFileUpEE = Server.CreateObject("SoftArtisans.FileUpEE")

'--- Set TempStorageLocation before calling
'--- ProcessRequest.
objFileUpEE.TempStorageLocation(saWebServer) = "c:\upload\temp"
objFileUpEE.ProcessRequest Request

Top
TransferEncoding
Syntax
objFileUpEE.TransferEncoding(SATransferStage) [= SATransferEncoding]
Description

To overcome inefficient memory utilization in IIS 6 on Windows 2003, FileUpEE allows you to send a chunked upload. To send a chunked upload, set TransferEncoding to saChunked. In this case, the HTTP request will not include a content-length header for the whole request. Instead, each chunk is preceded by a header that indicates the chunk size.

When uploading in ASP.NET to IIS 6, set TransferEncoding to saChunked and use FileUpEE's HttpModule to intercept the upload request.

Browsers do not support chunked transfer-encoding. To send a chunked upload from client to web server you must use XFileEE, a client-side control included with FileUpEE.

TransferEncoding is a Read/Write property. Set the value of SATransferEncoding by name or number:

SATransferEncoding Values
saNone (default value) | 0
saChunked | 1
Example
In ASP.NET:
[C#]
FileUpEE oFileUpEE = new FileUpEE();
oFileUpEE.TransferStage = saTransferStage.saWebServer;
oFileUpEE.set_TransferEncoding(saTransferStage.saWebServer, saTransferEncoding.saChunked);
...

[VB.NET]
Dim oFileUpEE As New FileUpEE()
oFileUpEE.TransferStage = saTransferStage.saWebServer
oFileUpEE.TransferEncoding(saTransferStage.saWebServer) = saTransferEncoding.saChunked
...
In ASP:
[VBScript]
Set oFileUpEE = Server.CreateObject("SoftArtisans.FileUpEE")
oFileUpEE.TransferStage = saWebServer
oFileUpEE.TransferEncoding(saWebServer) = saChunked
...

Top
TransferStage
Syntax
objFileUpEE.TransferStage [= SATransferStage]
Description

TransferStage specifies the stage of an upload, which may be either web server or file server. Set TransferStage by name or number:

SATransferStage Values
saWebServer | 1
saFileServer | 2

TransferStage is a Read/Write property.

Example

Set a script's TransferStage before calling ProcessRequest:

In ASP.NET:
[C#]
FileUpEE objFileUpEE = new FileUpEE();

//--- Set the upload's transfer stage to saWebServer.
objFileUpEE.TransferStage = saTransferStage.saWebServer;
objFileUpEE.ProcessRequest(Page.Request, false, false);

[VB.NET]
Dim objFileUpEE As New FileUpEE()

'--- Set the upload's transfer stage to saWebServer.
objFileUpEE.TransferStage = saTransferStage.saWebServer
objFileUpEE.ProcessRequest(Page.Request, False, False)
In ASP:
[VBScript]
Set objFileUpEE = Server.CreateObject("SoftArtisans.FileUpEE")

'--- Set the upload's transfer stage to saWebServer.
objFileUpEE.TransferStage = saWebServer
objFileUpEE.ProcessRequest Request

Top
UseChecksum
Syntax
objFileUpEE.UseChecksum [= Boolean]
Description

UseChecksum allows you to verify the integrity of data uploaded from web server to file server. If UseChecksum is set to true on the web server, FileUpEE will generate a file content checksum for the upload and send the checksum with the upload to the file server. On the file server, use ValidateChecksums to verify that the data was not corrupted during transfer.

In very large uploads, generating a checksum for each file can take so long that the upload may fail. Enabling UseChecksum is not recommended for very large uploads.

UseChecksum is a Read/Write property.

See Also

You can generate and validate a content checksum for a single file or for the whole upload. For information on using per-file checksums, see FileEE.Checksum, FileEE.PreviousChecksum, FileEE.UseChecksum, and FileEE.ValidateChecksum.

Top
UseMemory (ASP Only)
Syntax
objFileUpEE.UseMemory(SATransferStage) [= Boolean]
Description

If UseMemory is set to true, FileUpEE will store data uploaded to the specified server in memory until the data is saved. If UseMemory is set to false, data uploaded to the specified server will be cached in a temporary directory until it is saved. UseMemory is set to false by default.

The benefits of caching in memory may be:

  • Security
    No files are written to disk until the upload is saved.

  • Performance
    Caching files in memory can increase the speed of uploads. However, before setting UseMemory to true you should consider other factors affecting the upload, such as available memory on the file server, how active the server is, and the size of the upload. If an upload is larger than 1-5 MB (depending on the system load), caching in memory will probably not improve performance.

Do not set UseMemory to True if you expect very large uploads (100 MB or more).

To take effect, UseMemory(saWebServer) must be set before ProcessRequest is called on the web server. UseMemory(saFileServer) must be set before ProcessRequest is called on the file server.

UseMemory is a Read/Write property.

Parameter

UseMemory takes the parameter SATransferStage which specifies whether to cache in memory on the web server or file server. Note that FileUpEE will cache files on both the web server and the file server.

SATransferStage Values
saWebServer | 1
saFileServer | 2
Note on UseMemory and the HttpModule Filters

FileUpEE's UseMemory property allows you to keep uploaded data in memory until it is saved. FileUpEE's HttpModule reads the whole upload request and writes it to temporary files before the request is processed by the ASP.NET page on the server. If you set UseMemory in the ASP.NET page, the property will have no effect because the page is processed after the filter writes the temp files.

Example
In ASP:
[VBScript]
objFileUpEE.UseMemory(saWebServer) = True
Top

FileUpEe Methods
Add
Syntax
objFileUpEE.Add(FileBuffer, [Name], [ContentId])
Description

Adds a file to the FileCollection. The source of this file is a byte array.

You can use Add to upload a file from server to server.

Top
AddDbDownloadFile
Syntax
objFileEE = objFileUpEE.AddDbDownloadFile(ClientFileName, [Name],[WebServerDownload as Boolean])
Description

AddDbDownloadFile adds a file from a database to the collection of files to download. AddDbDownloadFile takes the download destination file name and returns a FileEE object.

To download a file from a database, you must set the file's table name, primary key column, primary key value, file column name, and the database connection string.

Parameters
ClientFileName | A destination name of the downloaded file. This file name will appear in the "Open or Save" dialog on the client. |
Name | Optional. The value of name may be used to reference the file in script, for example: objFileUpEE("file1").ContentType = "text/plain" | Default value: ""
WebServerDownload | Optional. To script a download from a file server to a web server to a client, set WebServerDownload to false. To script a download from a web server to a client, set WebServerDownload to true. | Default value: false
See Also

FileUpEE.DbTableName, FileUpEE.DbPrimaryKey, FileUpEE.DbPrimaryKeyValue, FileUpEE.DbConnection, FileEE.DbTableName, FileEE.DbPrimaryKey, FileEE.DbPrimaryKeyValue, FileEE.DbFileColumnName, and FileEE.DbConnection.

Example

The following web server script gets the download destination directory from the form field "Client."

In ASP.NET:
[C#]
FileUpEE objFileUpEE = new FileUpEE();
objFileUpEE.ProcessRequest(Page.Request, false, false);
objFileUpEE.AddDbDownloadFile(fileUp.Form("Client"), "file1", false);
objFileUpEE[0].DbTableName = "Files";
objFileUpEE[0].DbPrimaryKey = "FileId";
objFileUpEE[0].DbPrimaryKeyValue = "260";
objFileUpEE[0].DbFileColumnName = "File";
objFileUpEE[0].DbConnection = @"Provider=Microsoft.Jet.OLEDB.4.0;
    Data Source=C:\FilesDB\files.mdb; Persist Security Info=False";
objFileUpEE.TargetUrl = @"http://localhost/fileupee/dbdownload/fsDownDb.aspx";
objFileUpEE.SendRequest(Page.Response);

[VB.NET]
Dim objFileUpEE As New FileUpEE()
objFileUpEE.ProcessRequest(Page.Request, False, False)
objFileUpEE.AddDbDownloadFile(fileUp.Form("Client"), "file1", False)
objFileUpEE(0).DbTableName = "Files"
objFileUpEE(0).DbPrimaryKey = "FileId"
objFileUpEE(0).DbPrimaryKeyValue = "260"
objFileUpEE(0).DbFileColumnName = "File"
objFileUpEE(0).DbConnection = "Provider=Microsoft.Jet.OLEDB.4.0; _
    Data Source=C:\FilesDB\files.mdb; Persist Security Info=False"
objFileUpEE.TargetUrl = "http://localhost/fileupee/dbdownload/fsDownDb.aspx"
objFileUpEE.SendRequest(Page.Response)
In ASP:
[VBScript]
Dim objFileUpEE
Set objFileUpEE = Server.CreateObject("SoftArtisans.FileUpEE")
objFileUpEE.ProcessRequest Request
objFileUpEE.AddDbDownloadFile fileUp.Form("Client")
objFileUpEE(0).DbTableName = "Files"
objFileUpEE(0).DbPrimaryKey = "FileId"
objFileUpEE(0).DbPrimaryKeyValue = "260"
objFileUpEE(0).DbFileColumnName = "File"
objFileUpEE(0).DbConnection = "Provider=Microsoft.Jet.OLEDB.4.0; _
    Data Source=C:\FilesDB\files.mdb; Persist Security Info=False"
objFileUpEE.TargetUrl = "http://localhost/fileupee/dbdownload/fsDownDb.asp"
objFileUpEE.SendRequest(Response)
Top
AddDownloadFile
Syntax
objFileEE = objFileUpEE.AddDownloadFile(DownloadPath, ClientPath, [Name], [WebServerDownload as Boolean])
Description

AddDownloadFile adds a file to the collection of files to download.

Parameters
DownloadPath | The path and name of the file to download. |
ClientPath | A destination name for the downloaded file. This file name will appear in the "Open or Save" dialog on the client. |
Name | Optional. The value of name may be used to reference the file in script, for example: objFileUpEE("file1").ContentType = "text/plain" | Default value: ""
WebServerDownload | Optional. To script a download from a file server to a web server to a client, set WebServerDownload to false. To script a download from a web server to a client, set WebServerDownload to true. | Default value: false
Note

In a 3-tier download from file server to web server to client, files cannot be added to the FileUpEE.Files collection on the file server. If you want to set the source path of the file to download on the file server, the file should be added on the web server using AddDownloadFile with an empty string for the download source path, for example:

Set oFile = oFileUpEE.AddDownloadFile("","","file1")

On the file server, set the download source an destination paths, for example:

In ASP.NET:
[C#]
oFileUpEE[0].DownloadedPath = @"C:\images\image.jpg";
oFileUpEE[0].ClientFileName = oFileUpEE.Form("Client");

[VB.NET]
oFileUpEE(0).DownloadedPath = "C:\images\image.jpg"
oFileUpEE(0).ClientFileName = oFileUpEE.Form("Client")
In ASP:
[VBScript]
oFileUpEE(0).DownloadedPath = "C:\images\image.jpg"
oFileUpEE(0).ClientFileName = oFileUpEE.Form("Client")
Example

The following web server script gets the download's source and destination directories from the form fields "Download" and "Client."

In ASP.NET:
[C#]
FileUpEE objFileUpEE = new FileUpEE();
objFileUpEE.ProcessRequest(Page.Request, false, false);
objFileUpEE.AddDownloadFile(objFileUpEE.Form("Download"), objFileUpEE.Form("Client"), "file1");
objFileUpEE.TargetUrl = @"http://localhost/fileupee/download/fsDown.aspx";
saResult enumRetVal = objFileUpEE.SendRequest(Response);

[VB.NET]
Dim objFileUpEE As New FileUpEE()
objFileUpEE.ProcessRequest(Page.Request, False, False)
objFileUpEE.AddDownloadFile(objFileUpEE.Form("Download"), objFileUpEE.Form("Client"), "file1")
objFileUpEE.TargetUrl = "http://localhost/fileupee/download/fsDown.aspx"
Dim enumRetVal As String = objFileUpEE.SendRequest(Response)
In ASP:
[VBScript]
Set objFileUpEE = Server.CreateObject("SoftArtisans.FileUpEE")
objFileUpEE.ProcessRequest Request
objFileUpEE.AddDownloadFile objFileUpEE.Form("Download"), _
    objFileUpEE.Form("Client")
objFileUpEE.TargetUrl = "http://localhost/fileupee/download/fsDown.asp"
enumRetVal = objFileUpEE.SendRequest(Response)
Top
AddFile
Syntax
objFileUpEE.AddFile(FileName, [Name], [ContentId])
Description

Use AddFile to add a file from the file system to the collection of files to upload.

You can use AddFile to upload a file from server to server.

Parameters
FileName File path and name
Name Optional. Equivalent to FileEE.Name. The name assigned can be used as the file's key. For example,
In ASP.NET:
[C#]
objFileUpEE.AddFile(@"C:\first.xls", "AddedFile", 1234);
objFileUpEE["AddedFile"].OverwriteFile = false;
objFileUpEE["AddedFile"].DestinationPath = @"C:\Images\file.gif";
...

[VB.NET]
objFileUpEE.AddFile("C:\first.xls", "AddedFile", 1234)
objFileUpEE("AddedFile").OverwriteFile = False
objFileUpEE("AddedFile").DestinationPath = "C:\Images\file.gif"
...
In ASP:
[VBScript]
objFileUpEE.AddFile "C:\first.xls", "AddedFile", 1234
objFileUpEE("AddedFile").OverwriteFile = False
objFileUpEE("AddedFile").DestinationPath = "C:\Images\file.gif"
...
ContentId Optional. Equivalent to FileEE.ContentId. FileUpEE will automatically generate a unique content-ID for each file uploaded, unless a content-ID is assigned in script, as in the following example:
objFileUpEE.AddFile "C:\first.xls","AddedFile","1234"
 Default value: "" (In this case FileUpEE will generate a content-ID.)
Example
In ASP.NET:
[C#]
FileUpEE objFileUpEE = new FileUpEE();
objFileUpEE.ProcessRequest(Page.Request, false, false);
objFileUpEE.AddFile("C:\first.xls", "AddedFile", 1234);
objFileUpEE["AddedFile"].OverwriteFile = false;
objFileUpEE["AddedFile"].DestinationPath = "C:\Images\file.gif";
...

[VB.NET]
Dim objFileUpEE As New FileUpEE
objFileUpEE.ProcessRequest(Page.Request, False, False)
objFileUpEE.AddFile("C:\first.xls", "AddedFile", 1234)
objFileUpEE("AddedFile").OverwriteFile = False
objFileUpEE("AddedFile").DestinationPath = "C:\Images\file.gif"
...
In ASP:
[VBScript]
Set objFileUpEE = Server.CreateObject("SoftArtisans.FileUpEE")
objFileUpEE.ProcessRequest Request
objFileUpEE.AddFile "C:\first.xls","AddedFile",1234
objFileUpEE("AddedFile").OverwriteFile = False
objFileUpEE("AddedFile").DestinationPath = "C:\Images\file.gif"
...
Top
CreateDatabase (ASP only)
Syntax
objFileUpEE.CreateDatabase(DatabasePath as String)
Description

CreateDatabase creates a FileUpEE database at the location specified by DatabasePath. This method is only available in ASP. It is not available in ASP.NET.

The generated FileUpEE database can be used as:

  • An upload status database for resumable uploads.
  • An audit log database.
  • An error log database.

CreateDatabase generates a Microsoft Access database (a .mdb file); the file name specified in DatabasePath should have the extension .mdb. MS Access does not have to be installed for FileUpEE to generate or use the database.

Example
The following lines create a FileUpEE database, and use it as an upload status database for resumable uploading.
[VBScript]
Set oFileUpEE = Server.CreateObject("SoftArtisans.FileUpEE")
oFileUpEE.TransferStage = saWebServer
oFileUpEE.CreateDatabase("D:\FileUpEE\UploadStatus\uploads.mdb")
objFileUpEE.Resumable(saWebServer) = True
objFileUpEE.ResumeConnectionString(saFileServer) = "Provider=" & _
    "Microsoft.Jet.OLEDB.4.0;Data Source=" & _
    "D:\FileUpEE\UploadStatus\uploads.mdb" & _
    ";Persist Security Info=False"
...
Top
Dispose
Syntax
objFileUpEE.Dispose()
Description

When you are finished using an instance of FileUpEE under .NET, always call Dispose to ensure thorough cleanup of temporary files and unmanaged objects.

Example
[C#]
finally
{
    if (oFileUpEE != null)
    {
        oFileUpEE.Dispose();
    }
    oFileUpEE = null;
}

[VB.NET]
Finally
    If Not (oFileUpEE Is Nothing) Then
        oFileUpEE.Dispose()
    End If
    oFileUpEE = Nothing
End Try
Top
NextProgressId
Syntax
objFileUpEE.NextProgressId(SATransferStage)
Description

FileUpEE includes a server-side progress indicator that allows you to log and display the progress of an upload. The progress indicator automatically generates a unique progress ID number for each upload. NextProgressId returns the next unused progress ID.

Parameter

NextProgressId an SATransferStage, which specifies the stage of the upload: client-to-Web-server or Web-server-to-file-server.

SATransferStage Values
saClient | 0
saWebServer | 1
Example
In ASP.NET:
[C#]
FileUpEE oFileUpEE = new FileUpEE();
oFileUpEE.TransferStage = saTransferStage.saWebServer;

//--- Enable progress indication for client-to-Web-server
//--- and Web-server-to-file-server.
oFileUpEE.set_ProgressIndicator(saTransferStage.saClient, true);
oFileUpEE.set_ProgressIndicator(saTransferStage.saWebServer, true);

//--- Set the progress IDs for both upload stages to
//--- each stage's next unused progress ID.
oFileUpEE.set_ProgressID(saTransferStage.saClient, oFileUpEE.NextProgressID(saTransferStage.saClient));
oFileUpEE.set_ProgressID(saTransferStage.saWebServer, oFileUpEE.NextProgressID(saTransferStage.saWebServer));
...

[VB.NET]
Dim oFileUpEE As New FileUpEE()
oFileUpEE.TransferStage = saTransferStage.saWebServer

'--- Enable progress indication for client-to-Web-server
'--- and Web-server-to-file-server.
oFileUpEE.ProgressIndicator(saTransferStage.saClient) = True
oFileUpEE.ProgressIndicator(saTransferStage.saWebServer) = True

'--- Set the progress IDs for both upload stages to
'--- each stage's next unused progress ID.
oFileUpEE.ProgressID(saTransferStage.saClient) = oFileUpEE.NextProgressID(saTransferStage.saClient)
oFileUpEE.ProgressID(saTransferStage.saWebServer) = oFileUpEE.NextProgressID(saTransferStage.saWebServer)
...
In ASP:
[VBScript]
Set oFileUpEE = Server.CreateObject("SoftArtisans.FileUpEE")
oFileUpEE.TransferStage = saWebServer

'--- Enable progress indication for client-to-Web-server
'--- and Web-server-to-file-server.
oFileUpEE.ProgressIndicator(saClient) = True
oFileUpEE.ProgressIndicator(saWebServer) = True

'--- Set the progress IDs for both upload stages to
'--- each stage's next unused progress ID.
oFileUpEE.ProgressID(saClient) = oFileUpEE.NextProgressID
oFileUpEE.ProgressID(saWebServer) = oFileUpEE.NextProgressID
...
Top
ProcessRequest
Syntax
saResult = objFileUpEE.ProcessRequest(Request, [SoapRequest], [AutoProcess])
Description

ProcessRequest passes the Request object (as an IStream) to FileUpEE. The collection of transferred files is not available until after ProcessRequest is called.

Parameters
Request The Request object.
SoapRequest

When set to true, FileUpEE will process the file transfer as a SOAP transfer. Set SoapRequest to true on the file server of a 3-tier transfer.

When set to false, FileUpEE will process the file transfer as a form-based file upload. Set SoapRequest to false on the web server of any transfer.

 Default value: false
AutoProcess

If AutoProcess is set to true, FileUpEE will process the request according to the SOAP payload (the XML document tranferred with a SOAP request), and processing instructions (such as a Save statement) are not required in the script that contains the ProcessRequest statement.

When AutoProcess is set to true, the SOAP payload must contain all necessary information to process the Request. For example, when uploading from a web server to a file server, if AutoProcess is set to true in the file server script, the web server script must contain all file server instructions. The instructions will be executed automatically on the file server.

If AutoProcess is set to false, FileUpEE will process the request according to your script. In this case, include all processing instructions (such as database information) in your script. AutoProcess should always be set to false on the web server of any transfer.

 Default value: false
Return Value

ProcessRequest returns an saResult:

saResult Values
saAllProcessed 0 All files were processed without error.
Note
saResult values specify whether or not files were processed correctly, not whether they were saved. If, for example, an uploaded file is not saved because FileEE.OverwriteFile is disabled, the file was processed without error.
saUnknownError | 1 | An unknown error occurred.
saAccessDenied | 2 | Access was denied.
saMaxUpload | 3 | The upload size was greater than MaxKBytesToCancel. The upload stopped at that value.
saDiskFull | 4 | There disk is full.
saFileNotFound | 5 | The file could not be found.
saNetworkError | 6 | A network error stopped the upload before it was complete.
saSendError | 7 | Generic server error.
saDatabaseError | 8 | A database error occurred.
saFileError | 9 | Returned when the file containing resumability information cannot be opened.
saSomeProcessed | 10 | Errors occurred when processing one or more files. Some files were processed without error.
saNoneProcessed | 11 | Errors occurred when processing all files.
saResponseError | 12 | The error occured returning the response.
saNonSoapRequest | 13 | The request was not a SOAP request.
Examples

To process an upload from an HTML form, use:

In ASP.NET:
[C#]
objFileUpEE.ProcessRequest(Page.Request, false, false);

[VB.NET]
objFileUpEE.ProcessRequest(Page.Request, False, False)
In ASP:
[VBScript]
objFileUpEE.ProcessRequest Request, False, False

To process a SOAP file transfer from a web server to a file server according to the SOAP payload, use:

In ASP.NET:
[C#]
objFileUpEE.ProcessRequest(Page.Request, true, true);

[VB.NET]
objFileUpEE.ProcessRequest(Page.Request, True, True)
In ASP:
[VBScript]
objFileUpEE.ProcessRequest Request, True, True
Top
ResetAllProgressIds
Syntax
objFileUpEE.ResetAllProgressIds(SATransferStage)
Description

FileUpEE's server-side progress indicator allows you to log and display the progress of an upload. For each upload that it monitors, the progress indicator generates a unique progress ID number. ResetAllProgressIds resets all FileUpEE progress IDs, clearing the progress indicator of data from all previous and current uploads.

Parameter

ResetAllProgressIds takes an SATransferStage, which specifies the stage of the upload: client to web server or web server to file server.

SATransferStage Values
saClient | 0
saWebServer | 1
Example
In ASP.NET:
[C#]
FileUpEE oFileUpEE = new FileUpEE();
oFileUpEE.TransferStage = saTransferStage.saWebServer;

//--- Enable progress indication for client-to-Web-server
//--- and Web-server-to-file-server.
oFileUpEE.set_ProgressIndicator(saTransferStage.saClient, true);
oFileUpEE.set_ProgressIndicator(saTransferStage.saWebServer, true);

//--- Reset all progress IDs for both upload stages.
oFileUpEE.ResetAllProgressID(saTransferStage.saClient);
oFileUpEE.ResetAllProgressID(saTransferStage.saWebServer);

//--- Set the progress IDs for both upload stages.
oFileUpEE.set_ProgressID(saTransferStage.saClient, oFileUpEE.NextProgressID());
oFileUpEE.set_ProgressID(saTransferStage.saWebServer, oFileUpEE.NextProgressID());
...

[VB.NET]
Dim oFileUpEE As New FileUpEE()
oFileUpEE.TransferStage = saTransferStage.saWebServer

'--- Enable progress indication for client-to-Web-server
'--- and Web-server-to-file-server.
oFileUpEE.ProgressIndicator(saTransferStage.saClient) = True
oFileUpEE.ProgressIndicator(saTransferStage.saWebServer) = True

'--- Reset all progress IDs for both upload stages.
oFileUpEE.ResetAllProgressID(saTransferStage.saClient)
oFileUpEE.ResetAllProgressID(saTransferStage.saWebServer)

'--- Set the progress IDs for both upload stages.
oFileUpEE.ProgressID(saTransferStage.saClient) = oFileUpEE.NextProgressID()
oFileUpEE.ProgressID(saTransferStage.saWebServer) = oFileUpEE.NextProgressID()
...
In ASP:
[VBScript]
Set oFileUpEE = Server.CreateObject("SoftArtisans.FileUpEE")
oFileUpEE.TransferStage = saWebServer

'--- Enable progress indication for client-to-Web-server
'--- and Web-server-to-file-server.
oFileUpEE.ProgressIndicator(saClient) = True
oFileUpEE.ProgressIndicator(saWebServer) = True

'--- Reset all progress IDs for both upload stages.
oFileUpEE.ResetAllProgressID(saClient)
oFileUpEE.ResetAllProgressID(saWebServer)

'--- Set the progress IDs for both upload stages.
oFileUpEE.ProgressID(saClient) = oFileUpEE.NextProgressID
oFileUpEE.ProgressID(saWebServer) = oFileUpEE.NextProgressID
...
Top
ResetProgressId
Syntax
objFileUpEE.ResetProgressId(SATransferStage) ProgressId as Long
Description

FileUpEE's server-side progress indicator allows you to log and display the progress of an upload. For each upload that it monitors, the progress indicator generates a unique progress ID number. ResetProgressId resets a specified progress ID, and ensures that the progress indicator will not store data from previous complete or interrupted uploads.

Parameter

ResetProgressId takes two parameters: SATransferStage, and ProgressId. SATransferStage specifies the stage of the upload: client -> web server or web server -> file server.

SATransferStage Values
saClient | 0
saWebServer | 1
Example
In ASP.NET:
[C#]
FileUpEE oFileUpEE = new FileUpEE();
oFileUpEE.TransferStage = saTransferStage.saWebServer;

//--- Enable progress indication for client-to-Web-server
//--- and Web-server-to-file-server.
oFileUpEE.set_ProgressIndicator(saTransferStage.saClient, true);
oFileUpEE.set_ProgressIndicator(saTransferStage.saWebServer, true);

//--- Set the progress IDs for both upload stages.
oFileUpEE.ProgressID(saTransferStage.saClient) = oFileUpEE.NextProgressID();
oFileUpEE.ProgressID(saTransferStage.saWebServer) = oFileUpEE.NextProgressID();

//--- Reset the progress IDs for both upload stages.
oFileUpEE.ResetProgressID(saTransferStage.saClient, oFileUpEE.ProgressID);
oFileUpEE.ResetProgressID(saTransferStage.saWebServer, oFileUpEE.ProgressID);
...

[VB.NET]
Dim oFileUpEE As New FileUpEE()
oFileUpEE.TransferStage = saTransferStage.saWebServer

'--- Enable progress indication for client-to-Web-server
'--- and Web-server-to-file-server.
oFileUpEE.ProgressIndicator(saTransferStage.saClient) = True
oFileUpEE.ProgressIndicator(saTransferStage.saWebServer) = True

'--- Set the progress IDs for both upload stages.
oFileUpEE.ProgressID(saTransferStage.saClient) = oFileUpEE.NextProgressID
oFileUpEE.ProgressID(saTransferStage.saWebServer) = oFileUpEE.NextProgressID

'--- Reset the progress IDs for both upload stages.
oFileUpEE.ResetProgressID(saTransferStage.saClient, oFileUpEE.ProgressID)
oFileUpEE.ResetProgressID(saTransferStage.saWebServer, oFileUpEE.ProgressID);
...
In ASP:
[VBScript]
Set oFileUpEE = Server.CreateObject("SoftArtisans.FileUpEE")
oFileUpEE.TransferStage = saWebServer

'--- Enable progress indication for client-to-Web-server
'--- and Web-server-to-file-server.
oFileUpEE.ProgressIndicator(saClient) = True
oFileUpEE.ProgressIndicator(saWebServer) = True

'--- Set the progress IDs for both upload stages.
oFileUpEE.ProgressID(saClient) = oFileUpEE.NextProgressID
oFileUpEE.ProgressID(saWebServer) = oFileUpEE.NextProgressID

'--- Reset the progress IDs for both upload stages.
oFileUpEE.ResetProgressID(saClient, oFileUpEE.ProgressID)
oFileUpEE.ResetProgressID(saWebServer, oFileUpEE.ProgressID)
...
Top
Resume
Syntax
objFileUpEE.Resume(JobId)
Description

Resumes a server-to-server upload that was suspended because of a network connection failure or because the upload size was greater than MaxKBytesToCancel. Resume works at the request level, not the file level; if there are several files in an upload, you cannot call Resume for a specific file.

Parameter

Resume takes an upload's JobId and uses it to get the suspended upload's status from an upload status database. Resume then continues the upload from the point at which it stopped.

Set StatusUrl before calling Resume.

Return Value

Resume returns an saResult:

saResult Values
saAllProcessed 0 All files were processed without error.
Note
saResult values specify whether or not files were processed correctly, not whether they were saved. If, for example, an uploaded file is not saved because FileEE.OverwriteFile is disabled, the file was processed without error.
saSomeProcessed | 1 | Errors occurred when processing one or more files. Some files were processed without error.
saNoneProcessed | 2 | Errors occurred when processing all files.
saNetworkError | 3 | A network error stopped the upload before it was complete.
saMaxUpload | 4 | The upload size was greater than MaxKBytesToCancel. The upload stopped at that value.
saFileNotFound | 5
saSendError | 6 | Generic server error.
saGeneralError | 7
Example

In a standard 3-tier upload (client to web server to file server), there are three scripts: the client-side file submission script, the web server script, and the file server script. A resumable upload has two additional scripts: a resume-upload script and a status server script.

If the upload from web server to file server is suspended, and the user clicks a Resume link/button, the resume-upload script will be called. When the Resume method (within the resume-upload script) is called, a request will be made to the status server script. The response will tell FileUpEE the point at which the upload was suspended.

The following lines from the web server script create a link to the resume-upload script (send.asp or send.aspx). The query string includes the JobId which the Resume method will need to get the status of the suspended upload.

In ASP.NET:
[C#]
...
saResult numRetVal = objFileUpEE.SendRequest();

//--- If the upload from web server to file server
//--- is suspended because of a network error, display
//--- a "Resume upload" link to send.asp.
if (err.number != 0)
{
    Response.Write(@"<h2>Upload Failed</h2><br>");
    Response.Write(objFileUpEE.Error);
    Response.Write("<br><a href=send.aspx?JobId=" + objFileUpEE.JobId +
        @">Resume upload</a>");
    Response.End();
}
...

[VB.NET]
...
On Error Resume Next
Dim numRetVal As saResult = objFileUpEE.SendRequest()

'--- If the upload from web server to file server
'--- is suspended because of a network error, display
'--- a "Resume upload" link to send.asp.
If err.number <> 0 Then
    Response.Write("<h2>Upload Failed</h2><br>")
    Response.Write(objFileUpEE.Error)
    Response.Write("<br><a href=send.aspx?JobId=" & objFileUpEE.JobId & _
        ">Resume upload</a>")
    Response.End()
End If
...
In ASP:
[VBScript]
...
On error resume next
numRetVal = objFileUpEE.SendRequest()

'--- If the upload from web server to file server
'--- is suspended because of a network error, display
'--- a "Resume upload" link to send.asp.
If err.number <> 0 then
    Response.Write "<h2>Upload Failed</h2><br>"
    Response.Write objFileUpEE.Error
    Response.Write "<br><a href=send.asp?JobId=" & objFileUpEE.JobId & _
        ">Resume upload</a>"
    Response.End
End if
...

In the resume-upload script (send.asp or send.aspx), Resume takes the upload's JobId and makes a request to the status server which returns the number of bytes received on the file server. Resume then continues the upload from the point at which it stopped.

In ASP.NET:
[C#]
...
//--- The Resume method takes the JobId sent from ws.asp
//--- and resumes the upload from the point at which it
//--- stopped.
objFileUpEE.Resume(Request.QueryString["JobID"]);
...

[VB.NET]
...
'--- The Resume method takes the JobId sent from ws.asp
'--- and resumes the upload from the point at which it
'--- stopped.
objFileUpEE.Resume(Request.QueryString("JobID"))
...
In ASP:
[VBScript]
...
'--- The Resume method takes the JobId sent from ws.asp
'--- and resumes the upload from the point at which it
'--- stopped.
objFileUpEE.Resume(Request.QueryString("JobID"))
...
Top
ReturnStatus (ASP Only)
Syntax
objFileUpEE.ReturnStatus(Request, Response)
Description

In a resumable upload, FileUpEE generates a unique JobId for each upload (not for each file). If the upload is suspended, the upload's JobId and information about the incomplete upload will be stored in an upload status database. You can then call Resume to resume the upload.

When Resume is called, FileUpEE makes a request to the StatusUrl to get status of the suspended upload. In the StatusUrl page, after getting the data from the upload status database, call ReturnStatus which will send a response to the Resume method. The response will tell FileUpEE the point at which the upload was suspended.

Example

In a standard 3-tier upload (client to web server to file server), there are three scripts: the client-side file submission script, the web server script, and the file server script. A resumable upload has two additional scripts: a resume-upload script and a status server script.

If the upload from web server to file server is suspended, and the user clicks a Resume link/button, the resume-upload script will be called. When the Resume method (within the resume-upload script) is called, a request will be made to the StatusUrl page. The response will tell FileUpEE the point at which the upload was suspended.

The following lines are from the StatusUrl page of a resumable upload application.

[VBScript]
'--- Set the connection string for the file server's
'--- upload status database. If the upload to the file
'--- server stops before all the data is transferred,
'--- FileUpEE will enter upload status information in
'--- this database. To resume the upload, FileUpEE
'--- reads the status of the suspended upload from this
'--- database.
objFileUpEE.ResumeConnectionString = "Provider=Microsoft.Jet.OLEDB.4.0;" & _
    "Data Source=" & Server.MapPath(Application("vroot") & _
    "FileUpEEFS.mdb") & ";Persist Security Info=False"

'--- Return the suspended upload's status to the Resume call.
objFileUpEE.ReturnStatus Request, Response
Top
SendRequest
Syntax
objFileUpEE.SendRequest([Response])
Description

SendRequest sends the HTTP file transfer request from the web server to the file server and returns an saResult:

saResult Values
saAllProcessed 0 All files were processed without error.
Note
saResult values specify whether or not files were processed correctly, not whether they were saved. If, for example, an uploaded file is not saved because FileEE.OverwriteFile is disabled, the file was processed without error.
saSomeProcessed | 1 | Errors occurred when processing one or more files. Some files were processed without error.
saNoneProcessed | 2 | Errors occurred when processing all files.
saNetworkError | 3 | A network error stopped the upload before it was complete.
saMaxUpload | 4 | The upload size was greater than MaxKBytesToCancel. The upload stopped at that value.
saSendError | 5 | Generic server error.
Parameter
Response Optional. When downloading files from a file server to a web server to a browser, pass the file server Response to SendRequest. That is, send the file server Response from the web server to the client.

Passing in this optional parameter will result in data being streamed from the file server to the client through the web server without being cached entirely on the web server.

Upload Example
In ASP.NET:
[C#]
FileUpEE objFileUpEE = new FileUpEE();
objFileUpEE.ProcessRequest(Page.Request, false, false);
...
objFileUpEE(0).DestinationPath = @"C:\temp\" + objFileUpEE[0].ClientFileName;
...
objFileUpEE.TargetUrl = @"http://localhost/fileupeescripts/fs.aspx"
...
objFileUpEE.SendRequest();

[VB.NET]
Dim objFileUpEE As New FileUpEE()
objFileUpEE.ProcessRequest(Page.Request, False, False)
...
objFileUpEE(0).DestinationPath = "C:\temp\" & objFileUpEE(0).ClientFileName
...
objFileUpEE.TargetUrl = "http://localhost/fileupeescripts/fs.aspx"
...
objFileUpEE.SendRequest()
In ASP:
[VBScript]
Set objFileUpEE = Server.CreateObject("SoftArtisans.FileUpEE")
objFileUpEE.ProcessRequest Request
...
objFileUpEE(0).DestinationPath = "C:\temp\" & objFileUpEE(0).ClientFileName
...
objFileUpEE.TargetUrl = "http://localhost/fileupeescripts/fs.asp"
...
objFileUpEE.SendRequest()
Download Example
In ASP.NET:
[C#]
FileUpEE objFileUpEE = new FileUpEE();
...
objFileUpEE.AddDownloadFile(@"c:\reports\april.xls", @"c:\downloads\april.xls");
objFileUpEE.TargetUrl = @"http://localhost/fileupeedownload/fsDown.aspx";
objFileUpEE.SendRequest(Page.Response);
...

[VB.NET]
Dim objFileUpEE As New FileUpEE()
...
objFileUpEE.AddDownloadFile("c:\reports\april.xls", "c:\downloads\april.xls")
objFileUpEE.TargetUrl = "http://localhost/fileupeedownload/fsDown.aspx"
objFileUpEE.SendRequest(Page.Response)
...
In ASP:
[VBScript]
Set objFileUpEE = Server.CreateObject("SoftArtisans.FileUpEE")
...
objFileUpEE.AddDownloadFile "c:\reports\april.xls", "c:\downloads\april.xls"
objFileUpEE.TargetUrl = "http://localhost/fileupeedownload/fsDown.asp"
objFileUpEE.SendRequest(Response)
...
Top
SendResponse
Syntax
objFileUpEE.SendResponse Response
Description

SendResponse takes the Response object (as an IStream) and sends the response from the file server to the web server.

Example
In ASP.NET:
[C#]
//--- The following is a file server script for an upload from browser to
//--- web server to file server. Note that AutoProcess is set to
//--- True, so FileUpEE will process the Request according to the SOAP
//--- payload, and processing instructions (such as a Save statement) are not
//--- required in script.
FileUpEE objFileUpEE = new FileUpEE();
objFileUpEE.ProcessRequest(Page.Request, true, true);
objFileUpEE.SendResponse(Page.Response);
Response.End();

[VB.NET]
'--- The following is a file server script for an upload from browser to
'--- web server to file server. Note that AutoProcess is set to
'--- True, so FileUpEE will process the Request according to the SOAP
'--- payload, and processing instructions (such as a Save statement) are not
'--- required in script.
Dim objFileUpEE As New FileUpEE()
objFileUpEE.ProcessRequest(Page.Request, True, True)
objFileUpEE.SendResponse(Page.Response)
Response.End()
In ASP:
[VBScript]
'--- The following is a file server script for an upload from browser to
'--- web server to file server. Note that AutoProcess is set to
'--- True, so FileUpEE will process the Request according to the SOAP
'--- payload, and processing instructions (such as a Save statement) are not
'--- required in script.
Set objFileUpEE = Server.CreateObject("SoftArtisans.FileUpEE")
objFileUpEE.ProcessRequest Request, True, True
objFileUpEE.SendResponse Response
Response.End
Top
TransferBlob (ASP.NET only)
Syntax
objFileUpEE.TransferBlob(Object pObject,long nBlobColumn,long nBlogOffset,long nBufferSize, System.Web.HttpContext pContext)
Description

TransferBlob directly writes from a database BLOB column to the HTTP Response in a download.

This method is only available in ASP.NET.

Parameters
pObject | The Object to be downloaded. The derived type of this object must be either a byte array or an IDataReader. Any other type will result in an invalid data type exception.
nBlobColumn | When passing in an IDataReader, the long integer nBlobColumn is used to specify the column number of the BLOB column.
nBlobOffset | Long integer used to indicate the offset from the beginning of the BLOB column at which to start transferring data to the Response. When resuming a download, this offset is specified in the Range header of the request.
nBufferSize | Long integer used to dictate the buffer size to be used when transferring the data from the BLOB column to the Response in KiloBytes. The default buffer size is 250KB.
pContext | System.Web.HttpContext which contains the HTTP Request and HTTP Response objects. The TransferBlob method uses the Context to obtain the Response object to which it will transfer the BLOB column.
Example:
[C#]
//--- Create database connection string
String connectString = "Server=SQLServer;uid=userid;pwd=password;database=Files";

//--- Create FileUpEE object, set the TransferStage to Web Server
//--- and enable resumability.  Then, process the request
FileUpEe oFileUpEE = new FileUpEe();
oFileUpEE.TransferStage = saTransferStage.saWebServer;
oFileUpEE.set_Resumable(saTransferStage.saWebServer,true);
oFileUpEE.ProcessRequest(Request, false, false);

//--- Connect to the database and return an IDataReader object
SqlConnection conn = new SqlConnection(connectString);
SqlCommand sqlcmd = new SqlCommand("SELECT Filename, FileData" +
    " FROM FileSave WHERE FileID = '8'", conn);
conn.Open();
SqlDataReader dr = sqlcmd.ExecuteReader(CommandBehavior.SequentialAccess);

//--- Peform TransferBlob with IDataReader dr.
try
{
    oFileUpEE.TransferBlob(dr, 1, oFUEE.RequestRange, 0, Context);
    Response.SuppressContent = true;
    Response.Flush();
}
catch (Exception ex)
{
    Response.Write("Error Transferring Binary Large Object: " + ex.Message);
}

[VB.NET]
'--- Create database connection string
Dim connectString As String = "Server=SQLServer;uid=userid;pwd=password;database=Files"

'--- Create FileUpEE object, set the TransferStage to Web Server
'--- and enable resumability.  Then, process the request
Dim oFileUpEE As New FileUpEe()
oFileUpEE.TransferStage = saTransferStage.saWebServer
oFileUpEE.Resumable(saTransferStage.saWebServer) = True
oFileUpEE.ProcessRequest(Request, False, False)

'--- Connect to the database and return an IDataReader object
Dim conn As New SqlConnection(connectString)
Dim sqlcmd As New SqlCommand("SELECT Filename, FileData" & _
    " FROM FileSave WHERE FileID = '8'", conn)
conn.Open()
Dim dr As SqlDataReader = sqlcmd.ExecuteReader(CommandBehavior.SequentialAccess)

'--- Peform TransferBlob with IDataReader dr.
Try
    oFileUpEE.TransferBlob(dr, 1, oFUEE.RequestRange, 0, Context)
    Response.SuppressContent = True
    Response.Flush()
Catch ex As Exception
    Response.Write("Error Transferring Binary Large Object: " + ex.Message)
End Try
Top
TransferFile
Syntax
[ASP]
objFileUpEE.TransferFile(Request,Response,[FileName],[URL])

[ASP.NET]
objFileUpEE.TransferFile(HttpContext Context, string [FileName], string [URL], Boolean [Overwrite])
Description

TransferFile downloads a file from file server to web server to client, or from web server to client.

In a two-tier download, do not set the URL parameter.

In a three-tier download, set the URL parameter to the address of the file server page that will transfer the file from file server to web server. The FileName parameter must be set to the location of the file on the file server. The resulting download is a streaming download that is not cached into temporary directories on the file server or the web server.

Parameters
Request (ASP) | The Request object.
Response (ASP) | The Response object.
Context (ASP.NET) | The HttpContext object. In a three tier download, this is the only parameter that should be passed into the FileUpEE.TransferFile() method in the file server code.
[FileName] | Optional. The path and name of the file to download. This parameter must be set on the web server. In a 3-tier download, the value of FileName should be the location of the file on the file server. Use this parameter in the web server code of a 3-tier download, but not in the file server code.
[URL] | Optional. In a 3-tier download, set the URL parameter to the address of the file server page that will transfer the file from file server to web server. Use this parameter in the web server code of a 3-tier download, but not in the file server code.
Examples:

When performing a 3-tier download, call TransferFile on the web server and file server. The optional FileName parameter should specify the location of the file on the file server. The optional URL parameter should specify the URL of the file server page that will transfer the file from the file server to the web server.

In ASP.NET:
[C#]
//--- From the web server page in a 3-tier download.
objFileUpEE.TransferStage = saTransferStage.saWebServer;
objFileUpEE.TransferFile(Context, @"C:\Images\image.gif",
     @"http://FileServer/download.aspx");
...

//--- From the file server page in a 3-tier download.
objFileUpEE.TransferStage = saTransferStage.saFileServer;

objFileUpEE.TransferFile(Context);

[VB.NET]
'--- From the web server page in a 3-tier download.
objFileUpEE.TransferStage = saTransferStage.saWebServer
objFileUpEE.TransferFile(Context, "C:\Images\image.gif", _
     "http://FileServer/download.aspx")
...

'--- From the file server page in a 3-tier download.
objFileUpEE.TransferStage = saTransferStage.saFileServer

objFileUpEE.TransferFile(Context)
In ASP:
[VBScript]
'--- From the web server page in a 3-tier download.
objFileUpEE.TransferStage = saWebServer
objFileUpEE.TransferFile Request, Response, _
    "C:\Images\image.gif", "http://FileServer/download.asp"
...

'--- From the file server page in a 3-tier download.
objFileUpEE.TransferStage = saFileServer
objFileUpEE.TransferFile Request, Response

When performing a 2-tier download, do not pass the URL parameter:

In ASP.NET:
[C#]
oFileUpEE.TransferStage = saTransferStage.saWebServer;
string strPathToDownloadFile = Server.MapPath(@"/FileUpEE/Samples/sample.doc");
oFileUpEE.TransferFile(Context, strPathToDownloadFile);

[VB.NET]
oFileUpEE.TransferStage = saTransferStage.saWebServer
Dim strPathToDownloadFile As String = Server.MapPath("/FileUpEE/Samples/sample.doc")
oFileUpEE.TransferFile(Context, strPathToDownloadFile)
In ASP:

[VBScript]
strPathToDownloadFile = Server.MapPath("/FileUpEE/Samples/sample.doc")
oFileUpEE.TransferFile Request, Response, strPathToDownloadFile
...
Top
ValidateChecksums
Syntax

objFileUpEE.ValidateChecksums

Description

Use ValidateChecksums to verify the integrity of data transferred from web server to file server. If UseChecksum is set to true on the web server, FileUpEE will generate a file content checksum for the upload and send the checksum with the upload. On the file server, use ValidateChecksums to verify that the data was not corrupted during transfer.

If the upload content checksum received from the web server and the checksum generated on the file server are identical, ValidateChecksums returns true. If the checksums are not identical, the upload was corrupted during transfer, and ValidateChecksums returns false.

Example

The following is from the file server script in a client to web server to file server upload.

In ASP.NET:
[C#]
Boolean bRetVal = objFileUpEE.ValidateChecksums();
if (!bRetVal)
{
    objFileUpEE.Error = "Checksum validation failed";
}

[VB.NET]
Dim bRetVal As Boolean = objFileUpEE.ValidateChecksums()
If bRetVal = False Then
    objFileUpEE.Error = "Checksum validation failed"
End If
In ASP:
[VBScript]
bRetVal = objFileUpEE.ValidateChecksums()
If bRetVal = False then
    objFileUpEE.Error = "Checksum validation failed"
End if
See Also

You can generate and validate a content checksum for a single file or for the whole upload. For information on using per-file checksums, see FileEE.Checksum, FileEE.PreviousChecksum, FileEE.UseChecksum, and FileEE.ValidateChecksum.

Top


The FileCollection Object

The FileCollection object represents the set of files in a file transfer. To set a FileCollection object, use:

In ASP.NET (C#):

FileUpEE objFileUpEE = new FileUpEE();
FileCollection objFileCollection = objFileUpEE.Files;

In ASP:

Set objFileUpEE = Server.CreateObject("SoftArtisans.FileUpEE")
Set objFileCollection = objFileUpEE.Files
FileCollection Properties | FileCollection Methods
Count | Add
Item | AddDbDownloadFile
 | AddDownloadFile
 | AddFile
 | AddFileEE
 | Remove
 | RemoveAll
FileCollection Properties
Count
Syntax
objFileCollection.Count
Description

Returns the number of files in a FileCollection .

Count is a Read Only property.

Top
Item
Syntax
objFileCollection[.Item](Key)
Desription

Item represents a single FileEE object in a FileCollection. Item is the default property of FileCollection , therefore, FileCollection(2) is equivalent to FileCollection.Item(2) . Item numbers are 0-based.

Item is a Read Only property.

Top

FileCollection Methods
Add
Syntax
objFileCollection.Add(FileBuffer, [Name], [ContentId], Overwrite as Boolean)
Description

Use Add to add a byte array to an upload. For example, Add can be used to add a database BLOB to an upload as a file.

Top
AddDbDownloadFile
Syntax
objFileEE = objFileCollection.AddDbDownloadFile(ClientPath, [Name],[WebServerDownload as Boolean])
Description

AddDbDownloadFile adds a file from a database to the collection of files to download. AddDbDownloadFile takes the download destination directory and returns a FileEE object.

To download a file from a database, you must set the file's table name, primary key column, primary key value, file column name, and the database connection string. See the FileEE object's database properties.

Parameters
ClientPath | The destination path and name of the downloaded file. |
Name | Optional. The value of name may be used to reference the file in script, for example: objFileCollection("file1").ContentType = "text/plain" | Default value: ""
WebServerDownload | Optional. To script a download from a file server to a web server to a client, set WebServerDownload to false. To script a download from a web server to a client, set WebServerDownload to true. | Default value: False

Top
AddDownloadFile
Syntax
objFileEE = objFileCollection.AddDownloadFile(DownloadPath, ClientPath, [Name], [WebServerDownload as Boolean])
Description

AddDownloadFile adds a file to the collection of files to download.

Parameters
DownloadPath | The path and name of the file to download. |
ClientPath | The destination path and name of the downloaded file. |
Name | Optional. The value of name may be used to reference the file in script, for example: objFileCollection("file1").ContentType = "text/plain" | Default value: ""
WebServerDownload | Optional. To script a download from a file server to a web server to a client, set WebServerDownload to false. To script a download from a web server to a client, set WebServerDownload to true. | Default value: False

Top
AddFile
Syntax
objFileCollection.AddFile(FileName, [Name], [ContentId], [Overwrite as boolean])
Description

Use AddFile to add a file from the file system to the collection of files to upload.

Parameters
FileName | File path and name
Name | Optional. Equivalent to FileEE.Name. The name assigned can be used as the file's key.
ContentId Optional. Equivalent to FileEE.ContentId. FileUpEE will automatically generate a unique content-id for each file uploaded, unless a content-id is assigned in script, as in the following example:
objFileCollection.AddFile "C:\first.xls","AddedFile",1234
Default value: ""
Overwrite | Optional. If set to true, the uploaded file will overwrite an existing file with the same name. If set to false, the uploaded file will not be saved if a file with the same name exists in the destination directory. | Default value: True

Top
AddFileEE
Syntax
objFileCollection.AddFileEE (FileEE Instance, [ReadFile as Boolean], [DownloadFile as Boolean])
Description

AddFileEE adds an instance of the FileEE object to the file collection.

Top
Remove
Syntax
objFileCollection.Remove(File Key)
Description

Removes a file from the file collection. Remove takes one parameter: the file's key. The key may be either the file's Name property, or Item number.

Top
RemoveAll
Syntax
objFileCollection.RemoveAll()
Description

Removes all files from the file collection.

Top


The FileEe Object

The FileEe object represents a single file in a file transfer.

FileEe in ASP.NET

To set a FileEe object in ASP.NET:

[C#]
...
saResult eSAResult = oFileUpEE.SendRequest();
FileEe oFileEe = oFileUpEE.Files[0];

[VB.NET]
...
Dim eSAResult As saResult = oFileUpEE.SendRequest()
Dim oFileEe As FileEe = oFileUpEE.Files(0)
FileEe in ASP

To set a FileEe object in ASP:

[VBScript]
...
eSAResult = oFileUpEE.SendRequest
Set oFileEe = oFileUpEE.Files(1)

FileEe Properties |  |  | FileEe Methods
Body | DbPrimaryKeyValue | FormName | Download
Checksum | DbSchema | Name | Save
ChunkSize | DbSqlCommand | OverwriteFile | SaveAs
ClientFileName | DbTableName | Params | SaveAsBlob
ClientPath | Description | PreserveMacBinary | ValidateChecksum
ContentDisposition | DestinationFileExists | PreviousChecksum | WriteToResponse
ContentId | DestinationFileName | Processed |
ContentType | DestinationPath | RelativeName |
CreateUniqueFileName | DownloadedFileName | SaveMethod |
DbConnection | DownloadedPath | ServerFileName |
DbFileColumnName | Error | Size |
DbIdentityColumnName | ErrorCode | TempFile |
DbPrimaryKey | FileMethod | UseChecksum |
FileEe Properties
Body
Syntax
objFileEe.Body
Description

Body contains the contents of the file represented by the specified instance of FileEe.

Body is a Read Only property.

Example
In ASP.NET:
[C#]
Response.Write(objFileUpEE[1].Body);

[VB.NET]
Response.Write(objFileUpEE(1).Body)
In ASP:
[VBScript]
Response.Write objFileUpEE(1).Body

Top
Checksum
Syntax
objFileEe.Checksum
Description

FileUpEE allows you to verify the integrity of data uploaded from web server to file server. If FileEe.UseChecksum is enabled on the web server, FileUpEE will generate a file content checksum for the specified file and send the file's checksum with the upload to the file server. On the file server, use FileEe.ValidateChecksum to verify that the data was not corrupted during transfer.

Checksum contains the file content checksum that was generated on the file server, after the upload was received. Checksum is a Read Only property.

See Also

You can generate and validate a content checksum for a single file or for the whole upload. For information on using per-upload checksums, see FileUpEE.UseChecksum and FileUpEE.ValidateChecksums.

For more information on using per-file checksums, see FileEe.PreviousChecksum, FileEe.UseChecksum, and FileEe.ValidateChecksum.

Top
ChunkSize
Syntax
objFileEe.ChunkSize [= Size in KiloBytes]
Description

When transferring a file to or from a database, FileUpEE does not transfer the whole file at once; a file is uploaded to or downloaded from a database in data chunks. ChunkSize sets the size in kilobytes of a data chunk. Setting ChunkSize allows you to fine tune performance based on your network and database.

ChunkSize is a Read/Write property.

Top
ClientFileName
Syntax
objFileEe.ClientFileName [= File Name]
Description

ClientFileName returns the original name of the uploaded file, without a path.

ClientFileName is a Read Only property.

Example
In ASP.NET:
[C#]
...
objFileUpEE[1].SaveMethod = saSaveMethod.saDatabase;
...
String dbFileName = objFileUpEE[1].ClientFileName;
objFileUpEE[1].DbSchema.Add("File Name", dbFileName);
...

[VB.NET]
...
objFileUpEE(1).SaveMethod = saSaveMethod.saDatabase
...
Dim dbFileName As String = objFileUpEE(1).ClientFileName
objFileUpEE(1).DbSchema.Add("File Name", dbFileName)
...
In ASP:
[VBScript]
...
objFileUpEE(1).SaveMethod = saDatabase
...
dbFileName = objFileUpEE(1).ClientFileName
objFileUpEE(1).DbSchema.Add "File Name", dbFileName
...
Top
ClientPath
Syntax
objFileEe.ClientPath [= Path and File Name]
Description

In an upload, ClientPath returns the original path and file name of the uploaded file. In a download, ClientPath sets a name to display in the browser's "Open or Save" dialog.

ClientPath is a Read/Write property.

Example
In ASP.NET:
[C#]
...
foreach(FileEe file in objFileUpEE.Files)
{
    Response.Write("Original file name and location: " + file.ClientPath);
    ...
}

[VB.NET]
...
For Each file As FileEe In objFileUpEE.Files
    Response.Write("Original file name and location: " & file.ClientPath)
    ...
Next
In ASP:
[VBScript]
...
For each file in objFileUpEE.Files
    Response.Write "Original file name and location: " & file.ClientPath
    ...
next
Top
ContentDisposition
Syntax
objFileEe.ContentDisposition [= MIME Content-Disposition as String]
Description

ContentDisposition specifies the file's MIME content-disposition. For example, when uploading a file from a web form, the content-disposition value is "form-data."

Top
ContentId
Syntax
objFileUpEE(Key).ContentId [= String]
Description

ContentId specifies a unique content-id for each file in a file transfer. FileUpEE automatically generates a ContentId. Alternatively, you may set ContentId in script.

ContentId is a Read/Write property.

See Also

SOAP Messages with Attachments [image] and MIME Part One: Format of Internet Message Bodies [image].

Example
In ASP.NET:
[C#]
...
objFileUpEE[1].SaveMethod = saSaveMethod.saDatabase;
objFileUpEE[1].DbConnection = "Provider=Microsoft.Jet.OLEDB.4.0;" +
    @"Data Source=C:\Uploads\files.mdb;" +
    "Persist Security Info=False";

//--- DbTableName specifies the upload's destination table in the database
objFileUpEE[1].DbTableName = "Images";
String dbFileName = objFileUpEE[1].ClientFileName;
objFileUpEE[1].DbSchema.Add("File Name", dbFileName);
objFileUpEE[1].DbSchema.Add("ContentId", objFileUpEE[1].ContentId);
...

[VB.NET]
...
objFileUpEE(1).SaveMethod = saSaveMethod.saDatabase
objFileUpEE(1).DbConnection = "Provider=Microsoft.Jet.OLEDB.4.0;" & _
    "Data Source=C:\Uploads\files.mdb;" & _
    "Persist Security Info=False"

'--- DbTableName specifies the upload's destination table in the database
objFileUpEE(1).DbTableName = "Images"
Dim dbFileName As String = objFileUpEE(1).ClientFileName
objFileUpEE(1).DbSchema.Add("File Name", dbFileName)
objFileUpEE(1).DbSchema.Add("ContentId", objFileUpEE(1).ContentId)
...
In ASP:
[VBScript]
...
objFileUpEE(1).SaveMethod = saDatabase
objFileUpEE(1).DbConnection = "Provider=Microsoft.Jet.OLEDB.4.0;" & _
    "Data Source=C:\Uploads\files.mdb;" & _
    "Persist Security Info=False"

'--- DbTableName specifies the upload's destination table in the database
objFileUpEE(1).DbTableName = "Images"
dbFileName = objFileUpEE(1).ClientFileName
objFileUpEE(1).DbSchema.Add "File Name", dbFileName
objFileUpEE(1).DbSchema.Add "ContentId", objFileUpEE(1).ContentId
...
Top
ContentType
Syntax
objFileEE.ContentType[= MIME Content-Type as String]
Description

ContentType specifies the transferred file's MIME content type (e.g., text/plain, application/msword, image/jpeg, application/pdf).

ContentType is a Read/Write property.

In ASP.NET:
[C#]
FileUpEE objFileUpEE = new FileUpEE();
objFileUpEE.TransferStage = saTransferStage.saWebServer;
objFileUpEE.ProcessRequest(Request);

//--- Set a file to download.
FileEe File = objFileUpEE.AddDownloadFile(objFileUpEE.Form["ServerFilePath"],
    objFileUpEE.Form["ClientFilePath"], "file", true);

//--- To let the browser know how to handle a download, set the
//--- content-type response header to the file's content type before
//--- downloading to the browser.
Response.ContentType = File.ContentType;

//--- Download the file.
File.WriteToResponse(Response);

[VB.NET]
Dim objFileUpEE As New FileUpEE()
objFileUpEE.TransferStage = saTransferStage.saWebServer
objFileUpEE.ProcessRequest(Request)

'--- Set a file to download.
Dim File As FileEe = objFileUpEE.AddDownloadFile(objFileUpEE.Form("ServerFilePath"), _
    objFileUpEE.Form("ClientFilePath"), "file", True)

'--- To let the browser know how to handle a download, set the
'--- content-type response header to the file's content type before
'--- downloading to the browser.
Response.ContentType = File.ContentType

'--- Download the file.
File.WriteToResponse(Response)
In ASP:
[VBScript]
Dim objFileUpEE
Set objFileUpEE = Server.CreateObject("SoftArtisans.FileUpEE")
objFileUpEE.TransferStage = saWebServer
objFileUpEE.ProcessRequest Request

'--- Set a file to download.
Dim File
Set File = objFileUpEE.AddDownloadFile(objFileUpEE.Form("ServerFilePath"), _
    objFileUpEE.Form("ClientFilePath"), "file", True)

'--- To let the browser know how to handle a download, set the
'--- content-type response header to the file's content type before
'--- downloading to the browser.
Response.ContentType = File.ContentType

'--- Download the file.
File.WriteToResponse Response
Top
CreateUniqueFileName
Syntax
objFileEe.CreateUniqueFileName(Prefix, MaxFiles, Separator) [= Boolean]
Description

By default, if you upload a file and a file with the same name exists in the destination directory, the uploaded file will overwrite the existing file. If FileEe.OverwriteFile is set to false, the uploaded file will not be saved if a file with the same name exists in the destination directory.

When OverwriteFiles is false, if you set CreateUniqueFileName to true, FileUpEE will append an underscore and a number to the name of the uploaded file, if a file with the same name exists in the destination directory.

Parameters
Prefix | Optional. Specifies whether the separator and number are appended before or after the file name. If Prefix is false they will be appended after the file name (for example, filename_4.ext). If Prefix is true they will be appended before the file name (for example, 4_filename.ext). Default value: false
MaxFiles | Optional. Specifies the highest number that FileUpEE will append to a file name. The first number FileUpEE appends is 0. So the maximum number of unique names FileUpEE will create is MaxFiles + 1. Default value: 999.
Separator | Optional. Specifies the the character the FileUpEE will use to separate the file name and the number appended to it. Default value: "_"
Example

The directory C:\temp contains the file report.doc. The FileUpEE code contains:

In ASP.NET:
[C#]
oFile.set_CreateUniqueFileName(false, 3, "&", true);
oFile.OverwriteFile = false;
oFile.SaveAs(@"C:\temp\report.doc");

[VB.NET]
oFile.CreateUniqueFileName(False, 3, "&") = True
oFile.OverwriteFile = False
oFile.SaveAs("C:\temp\report.doc")
In ASP:
[VBScript]
oFile.CreateUniqueFileName(false,3,"&") = true
oFile.OverwriteFile = false
oFile.SaveAs "C:\temp\report.doc"

If you upload four files named report.doc to C:\temp, the directory will contain: report.doc, report&0.doc, report&1.doc, report&2.doc, and report&3.doc.

Top
DbConnection
Syntax
objFileUpEE(Key).DbConnection [= Connection String]
Description

Use DbConnection to set the database connection string when transferring a file to or from a database.

DbConnection is a Read/Write property.

See Also

Per-upload database properties: FileUpEE.DbConnection, FileUpEE.DbPrimaryKey, FileUpEE.DbPrimaryKeyValue, FileUpEE.DbSqlCommand, FileUpEE.DbTableName, and FileUpEE.SaveMethod.

Per-file database properties: FileEe.DbFileColumnName, FileEe.DbPrimaryKey, FileEe.DbPrimaryKeyValue, FileEe.DbSqlCommand, FileEe.DbTableName, FileEe.SaveAsBlob, FileEe.SaveMethod, and FileEe.DbSchema.

Example
In ASP.NET:
[C#]
objFileUpEE[1].DbConnection = "Provider=Microsoft.Jet.OLEDB.4.0;" +
    @"Data Source=C:\Uploads\Images.mdb;" +
    "Persist Security Info=False";

[VB.NET]
objFileUpEE(1).DbConnection = "Provider=Microsoft.Jet.OLEDB.4.0;" & _
    "Data Source=C:\Uploads\Images.mdb;" & _
    "Persist Security Info=False"
In ASP:
[VBScript]
objFileUpEE(1).DbConnection = "Provider=Microsoft.Jet.OLEDB.4.0;" & _
    "Data Source=C:\Uploads\Images.mdb;" & _
    "Persist Security Info=False"
Top
DbFileColumnName
Syntax
objFileEE.DbFileColumnName [= File Column Name as String]
Description

When transferring a file to or from a database, set DbFileColumnName to the name of the table column that contains the file.

DbFileColumnName is a Read/Write property.

See Also

Per-upload database properties: FileUpEE.DbConnection, FileUpEE.DbPrimaryKey, FileUpEE.DbPrimaryKeyValue, FileUpEE.DbSqlCommand, FileUpEE.DbTableName, and FileUpEE.SaveMethod.

Per-file database properties: FileEe.DbConnection, FileEe.DbPrimaryKey, FileEe.DbPrimaryKeyValue, FileEe.DbSqlCommand, FileEe.DbTableName, FileEe.SaveAsBlob, FileEe.SaveMethod, and FileEe.DbSchema.

Example
In ASP.NET:
[C#]
objFileUpEE[1].SaveMethod = saSaveMethod.saDatabase;
objFileUpEE[1].DbTableName = "Files";
objFileUpEE[1].DbConnection = "Provider=Microsoft.Jet.OLEDB.4.0;" +
    @"Data Source=[PATH]\FileUpEE\files.mdb;" +
    "Persist Security Info=False";
dbFileName = objFileUpEE[1].ClientFileName;
objFileUpEE[1].DbSchema.Add("FileName", dbFileName);
objFileUpEE[1].DbSchema.Add("ContentId", objFileUpEE[1].ContentId);
objFileUpEE[1].DbFileColumnName = "File";
...

[VB.NET]
objFileUpEE(1).SaveMethod = saSaveMethod.saDatabase
objFileUpEE(1).DbTableName = "Files"
objFileUpEE(1).DbConnection = "Provider=Microsoft.Jet.OLEDB.4.0;" & _
    "Data Source=[PATH]\FileUpEE\files.mdb;" & _
    "Persist Security Info=False"
dbFileName = objFileUpEE(1).ClientFileName
objFileUpEE(1).DbSchema.Add("FileName", dbFileName)
objFileUpEE(1).DbSchema.Add("ContentId", objFileUpEE(1).ContentId)
objFileUpEE(1).DbFileColumnName = "File"
...
In ASP:
[VBScript]
objFileUpEE(1).SaveMethod = saDatabase
objFileUpEE(1).DbTableName = "Files"
objFileUpEE(1).DbConnection = "Provider=Microsoft.Jet.OLEDB.4.0;" & _
    "Data Source=[PATH]\FileUpEE\files.mdb;" & _
    "Persist Security Info=False"
dbFileName = objFileUpEE(1).ClientFileName
objFileUpEE(1).DbSchema.Add "FileName", dbFileName
objFileUpEE(1).DbSchema.Add "ContentId", objFileUpEE(1).ContentId
objFileUpEE(1).DbFileColumnName = "File"
...
Top
DbIdentityColumnName
Syntax
objFileEE.DbIdentityColumnName = [= Identity Column Name]
Description

When uploading to a database, if DbIdentityColumnName is set, FileUpEE will return the identity value for the new row. The row identity value will be in the DbSchema collection under the name of the identity column specified by DbIdentityColumnName. For example, if a file's identity column is set to "FileId," after SendRequest returns, the file's DbSchema("FileId") collection member will hold the identity value for that database row.

Example
In ASP.NET:
[C#]
objFileUpEE[1].DbIdentityColumnName = "FileId";

[VB.NET]
objFileUpEE(1).DbIdentityColumnName = "FileId"
In ASP:
objFileUpEE(1).DbIdentityColumnName = "FileId"
Top
DbPrimaryKey
Syntax
objFileUpEE(Key).DbPrimaryKey [= Primary Key Column Name]
Description

Sets or returns a database table's primary key column name.

When uploading a file to a database, to update a row, you must set DbPrimaryKey and DbPrimaryKeyValue. Do not set these values to add a row.

DbPrimaryKey is a Read/Write property.

See Also

Per-upload database properties: FileUpEE.DbConnection, FileUpEE.DbPrimaryKey, FileUpEE.DbPrimaryKeyValue, FileUpEE.DbSqlCommand, FileUpEE.DbTableName, and FileUpEE.SaveMethod.

Per-file database properties: FileEe.DbConnection, FileEe.DbFileColumnName, FileEe.DbPrimaryKeyValue, FileEe.DbSqlCommand, FileEe.DbTableName, FileEe.SaveAsBlob, FileEe.SaveMethod, and FileEe.DbSchema.

Example
In ASP.NET:
[C#]
objFileUpEE[2].DbTableName = "Files";
objFileUpEE[2].DbSqlCommand = "Select * from Files where FileId = 184";
objFileUpEE[2].DbPrimaryKey = "FileId";
objFileUpEE[2].DbPrimaryKeyValue = "6325";
...

[VB.NET]
objFileUpEE(2).DbTableName = "Files"
objFileUpEE(2).DbSqlCommand = "Select * from Files where FileId = 184"
objFileUpEE(2).DbPrimaryKey = "FileId"
objFileUpEE(2).DbPrimaryKeyValue = "6325"
...
In ASP:
[VBScript]
objFileUpEE(2).DbTableName = "Files"
objFileUpEE(2).DbSqlCommand = "Select * from Files where FileId = 184"
objFileUpEE(2).DbPrimaryKey = "FileId"
objFileUpEE(2).DbPrimaryKeyValue = "6325"
...
Top
DbPrimaryKeyValue
Syntax
objFileUpEE(Key).DbPrimaryKeyValue [= Primary Key Value]
Description

DbPrimaryKeyValue sets or returns a database record's primary key value.

When uploading a file to a database, to update a row, you must set DbPrimaryKeyValue and DbPrimaryKey. Do not set these values to add a row.

When downloading a file from database, you must set DbPrimaryKeyValue for the record containing the file.

DbPrimaryKeyValue is a Read/Write property.

See Also

Per-upload database properties: FileUpEE.DbConnection, FileUpEE.DbPrimaryKey, FileUpEE.DbPrimaryKeyValue, FileUpEE.DbSqlCommand, FileUpEE.DbTableName, and FileUpEE.SaveMethod.

Per-file database properties: FileEe.DbConnection, FileEe.DbFileColumnName, FileEe.DbPrimaryKey, FileEe.DbSqlCommand, FileEe.DbTableName, FileEe.SaveAsBlob, FileEe.SaveMethod, and FileEe.DbSchema.

Example
In ASP.NET:
[C#]
objFileUpEE[1].DbTableName = "Files";
objFileUpEE[1].DbSqlCommand = "Select * from Files where FileId = 184";
objFileUpEE[1].DbPrimaryKey = "FileId";
objFileUpEE[1].DbPrimaryKeyValue = "6954";
...

[VB.NET]
objFileUpEE(1).DbTableName = "Files"
objFileUpEE(1).DbSqlCommand = "Select * from Files where FileId = 184"
objFileUpEE(1).DbPrimaryKey = "FileId"
objFileUpEE(1).DbPrimaryKeyValue = "6954"
...
In ASP:
[VBScript]
objFileUpEE(1).DbTableName = "Files"
objFileUpEE(1).DbSqlCommand = "Select * from Files where FileId = 184"
objFileUpEE(1).DbPrimaryKey = "FileId"
objFileUpEE(1).DbPrimaryKeyValue = "6954"
...
Top
DbSchema
Syntax
objFileEE.DbSchema.Add Column Name, Value
Description

DbSchema is a collection of name-value pairs representing the column names and values of a database row. Use DbSchema to add or update a database field.

DbSchema is a Read Only property.

See Also

Per-upload database properties: FileUpEE.DbConnection, FileUpEE.DbPrimaryKey, FileUpEE.DbPrimaryKeyValue, FileUpEE.DbSqlCommand, FileUpEE.DbTableName, and FileUpEE.SaveMethod.

Per-file database properties: FileEe.DbConnection, FileEe.DbFileColumnName, FileEe.DbPrimaryKey, FileEe.DbPrimaryKeyValue, FileEe.DbSqlCommand, FileEe.DbTableName, FileEe.SaveAsBlob, and FileEe.SaveMethod.

Example
In ASP.NET:
[C#]
objFileUpEE[1].SaveMethod = saSaveMethod.saDatabase;
objFileUpEE[1].DbConnection = "Provider=Microsoft.Jet.OLEDB.4.0;" +
    @"Data Source=C:\Uploads\files.mdb;" +
    "Persist Security Info=False";

//--- DbTableName specifies the upload's destination table in the database
objFileUpEE[1].DbTableName = "Images";
String dbFileName = objFileUpEE[1].ClientFileName;
objFileUpEE[1].DbSchema.Add("File Name", dbFileName);
objFileUpEE[1].DbSchema.Add("ContentId", objFileUpEE[1].ContentId);
...

[VB.NET]
objFileUpEE(1).SaveMethod = saSaveMethod.saDatabase
objFileUpEE(1).DbConnection = "Provider=Microsoft.Jet.OLEDB.4.0;" & _
    "Data Source=C:\Uploads\files.mdb;" & _
    "Persist Security Info=False"

'--- DbTableName specifies the upload's destination table in the database
objFileUpEE(1).DbTableName = "Images"
Dim dbFileName As String = objFileUpEE(1).ClientFileName
objFileUpEE(1).DbSchema.Add("File Name", dbFileName)
objFileUpEE(1).DbSchema.Add("ContentId", objFileUpEE(1).ContentId)
...
In ASP:
[VBScript]
objFileUpEE(1).SaveMethod = saDatabase
objFileUpEE(1).DbConnection = "Provider=Microsoft.Jet.OLEDB.4.0;" & _
    "Data Source=C:\Uploads\files.mdb;" & _
    "Persist Security Info=False"

'--- DbTableName specifies the upload's destination table in the database
objFileUpEE(1).DbTableName = "Images"
dbFileName = objFileUpEE(1).ClientFileName
objFileUpEE(1).DbSchema.Add "File Name", dbFileName
objFileUpEE(1).DbSchema.Add "ContentId", objFileUpEE(1).ContentId
...
Top
DbSqlCommand
Syntax
objFileEE.DbSqlCommand [= SQL Query]
Description

Use DbSqlCommand to set a SQL query when transferring files to or from a database.

DbSqlCommand is a Read/Write property.

See Also

Per-upload database properties: FileUpEE.DbConnection, FileUpEE.DbPrimaryKey, FileUpEE.DbPrimaryKeyValue, FileUpEE.DbSqlCommand, FileUpEE.DbTableName and FileUpEE.SaveMethod .

Per-file database properties: FileEe.DbConnection, FileEe.DbFileColumnName, FileEe.DbPrimaryKey, FileEe.DbPrimaryKeyValue, FileEe.DbTableName, FileEe.SaveAsBlob, FileEe.SaveMethod, and FileEe.DbSchema.

Example
In ASP.NET:
[C#]
objFileUpEE[1].DbTableName = "Files";
objFileUpEE[1].DbSqlCommand = "Select * from Files where FileId = 184";
objFileUpEE[1].DbPrimaryKey = "FileName";
objFileUpEE[1].DbPrimaryKeyValue = "file.txt";
...

[VB.NET]
objFileUpEE(1).DbTableName = "Files"
objFileUpEE(1).DbSqlCommand = "Select * from Files where FileId = 184"
objFileUpEE(1).DbPrimaryKey = "FileName"
objFileUpEE(1).DbPrimaryKeyValue = "file.txt"
...
In ASP:
[VBScript]
objFileUpEE(1).DbTableName = "Files"
objFileUpEE(1).DbSqlCommand = "Select * from Files where FileId = 184"
objFileUpEE(1).DbPrimaryKey = "FileName"
objFileUpEE(1).DbPrimaryKeyValue = "file.txt"
...
Top
DbTableName
Syntax
objFileUpEE(Key).DbTableName [= Database Table Name]
Description

When uploading a file to a database, set DbTableName to the destination table for your upload.

When downloading files from a database, set DbTableName to the table containing the files to download.

DbTableName is a Read/Write property.

See Also

Per-upload database properties: FileUpEE.DbConnection, FileUpEE.DbPrimaryKey, FileUpEE.DbPrimaryKeyValue, FileUpEE.DbSqlCommand, FileUpEE.DbTableName, and FileUpEE.SaveMethod.

Per-file database properties: FileEe.DbConnection, FileEe.DbFileColumnName, FileEe.DbPrimaryKey, FileEe.DbPrimaryKeyValue, FileEe.DbSqlCommand, FileEe.SaveAsBlob, FileEe.SaveMethod, and FileEe.DbSchema.

Example
In ASP.NET:
[C#]
objFileUpEE[1].SaveMethod = saSaveMethod.saDatabase;
objFileUpEE[1].DbConnection = "Provider=Microsoft.Jet.OLEDB.4.0;" +
    @"Data Source=C:\Uploads\files.mdb;" +
    "Persist Security Info=False";

//--- DbTableName specifies the upload's destination table in the database
objFileUpEE[1].DbTableName = "Images";
String dbFileName = objFileUpEE[1].ClientFileName;
objFileUpEE[1].DbSchema.Add("File Name", dbFileName);
objFileUpEE[1].DbSchema.Add("ContentId", objFileUpEE[1].ContentId);
...

[VB.NET]
objFileUpEE(1).SaveMethod = saSaveMethod.saDatabase
objFileUpEE(1).DbConnection = "Provider=Microsoft.Jet.OLEDB.4.0;" & _
    "Data Source=C:\Uploads\files.mdb;" & _
    "Persist Security Info=False"

'--- DbTableName specifies the upload's destination table in the database
objFileUpEE(1).DbTableName = "Images"
dbFileName = objFileUpEE(1).ClientFileName
objFileUpEE(1).DbSchema.Add "File Name", dbFileName
objFileUpEE(1).DbSchema.Add "ContentId", objFileUpEE(1).ContentId
...
In ASP:
[VBScript]
objFileUpEE(1).SaveMethod = saDatabase
objFileUpEE(1).DbConnection = "Provider=Microsoft.Jet.OLEDB.4.0;" & _
    "Data Source=C:\Uploads\files.mdb;" & _
    "Persist Security Info=False"

'--- DbTableName specifies the upload's destination table in the database
objFileUpEE(1).DbTableName = "Images"
dbFileName = objFileUpEE(1).ClientFileName
objFileUpEE(1).DbSchema.Add "File Name", dbFileName
objFileUpEE(1).DbSchema.Add "ContentId", objFileUpEE(1).ContentId
...
Top
Description
Syntax
objFileEe.Description [= String]
Description

Use Description to send any meta-data with the file transfer request. Description is a Read/Write property.

Example
In ASP.NET:
[C#]
FileUpEE oFileUpEE = new FileUpEE();
oFileUpEE.TransferStage = saTransferStage.saWebServer;
oFileUpEE.DestinationDirectory = Server.MapPath(@"/FileUpEE/samples/temp");
FileEe oFile = oFileUpEE.Files("myFile");
oFile.Description = "Uploaded file";
oFile.Save();
...

[VB.NET]
Dim oFileUpEE As New FileUpEE()
oFileUpEE.TransferStage = saTransferStage.saWebServer
oFileUpEE.DestinationDirectory = Server.MapPath("/FileUpEE/samples/temp")
Dim oFile As FileEe = oFileUpEE.Files("myFile")
oFile.Description = "Uploaded file"
oFile.Save()
...
In ASP:
[VBScript]
Set oFileUpEE = Server.CreateObject("SoftArtisans.FileUpEE")
oFileUpEE.TransferStage = saWebServer
oFileUpEE.DestinationDirectory = Server.MapPath("/FileUpEE/samples/temp")
Set oFile = oFileUpEE.Files("myFile")
oFile.Description = "Uploaded file"
oFile.Save
...

Top
DestinationFileExists
Syntax
objFileEe.DestinationFileExists(File Name as String)
Description

DestinationFileExists returns true if a file with the same name as the specified file exists in the destination directory. You can use this property to find out if a file with the same name exists before setting CreateUniqueFileName.

Top
DestinationFileName
Syntax
objFileUpEE(Key).DestinationFileName [=File Name]
Description

DestinationFileName specifies the name with which to save an uploaded file. DestinationFileName does not include a directory path. If you assign DestinationFileName, use FileUpEE.DestinationDirectory to set the Save directory. If you do not set the DestinationFileName of the file, the DestinationFileName property will return nothing.

Alternatively, use DestinationPath .

Example
In ASP.NET:
[C#]
objFileUpEE.DestinationDirectory = @"C:\Uploads\Images\";
objFileUpEE[1].DestinationFileName = "image1.jpg";

[VB.NET]
objFileUpEE.DestinationDirectory = "C:\Uploads\Images\"
objFileUpEE(1).DestinationFileName = "image1.jpg"
In ASP:
[VBScript]
objFileUpEE.DestinationDirectory = "C:\Uploads\Images\"
objFileUpEE(1).DestinationFileName = "image1.jpg"
Top
DestinationPath
Syntax
objFileUpEE(Key).DestinationPath [=Server Path & File Name]
Description

When uploading a file to a directory, set DestinationPath to the Save location. Set DestinationPath to a complete directory path and file name.

DestinationPath is a Read/Write property.

Alternatively, use FileUpEE.DestinationDirectory with DestinationFileName.

Example
In ASP.NET:
[C#]
objFileUpEE[1].DestinationPath = @"C:\Uploads\Images\file.gif";

[VB.NET]
objFileUpEE(1).DestinationPath = "C:\Uploads\Images\file.gif"
In ASP:
[VBScript]
objFileUpEE(1).DestinationPath = "C:\Uploads\Images\file.gif"
Top
DownloadedFileName
Syntax
objFileEE.DownloadedFileName [=File Name]
Description

DownloadedFileName sets or returns the name of a downloaded file on the client, without a path.

DownloadedFileName is a Read/Write property.

Top
DownloadedPath
Syntax
objFileEE.DownloadedPath [=Path & File Name]
Description

DownloadedPath sets or returns the path and name of a file to download from the server.

DownloadedPath is a Read/Write property.

Top
Error
Syntax
objFileEE.Error
Description

Error returns an error message, if an error occurred when transferring the specified file.

Error is a Read Only property.

Example
In ASP.NET:
[C#]
if (oFileEE.Processed == saSaveResult.saSaved)
{
    Response.Write("Upload successful");
}
else
{
    Response.Write("Upload failed");
    Response.Write("File error string: " + oFileEE.Error + "<BR>");
    Response.Write("File error code: " + oFileEE.ErrorCode + "<BR>");
}

[VB.NET]
If oFileEE.Processed = saSaveResult.saSaved Then
    Response.Write("Upload successful")
Else
    Response.Write("Upload failed")
    Response.Write("File error string: " & oFileEE.Error & "<BR>")
    Response.Write("File error code: " & oFileEE.ErrorCode & "<BR>")
End If
In ASP:
[VBScript]
If oFileEE.Processed = saSaved Then
    Response.Write "Upload successful"
Else
    Response.Write "Upload failed"
    Response.Write "File error string: " & oFileEE.Error & "<BR>"
    Response.Write "File error code: " & oFileEE.ErrorCode & "<BR>"
End If
Top
ErrorCode
Syntax
objFileEe.ErrorCode
Description

ErrorCode returns a system error code, if an error occurred when transferring the specified file.

ErrorCode is a Read Only property.

Example
In ASP.NET:
[C#]
if (oFile.Processed == saSaveResult.saSaved)
{
    Response.Write("Upload successful");
}
else
{
    Response.Write("Upload failed");
    Response.Write("File error string: " + oFile.Error + "<BR>");
    Response.Write("File error code: " + oFile.ErrorCode + "<BR>");
}

[VB.NET]
If oFile.Processed = saSaveResult.saSaved Then
    Response.Write("Upload successful")
Else
    Response.Write("Upload failed")
    Response.Write("File error string: " & oFile.Error & "<BR>")
    Response.Write("File error code: " & oFile.ErrorCode & "<BR>")
End If
In ASP:
[VBScript]
If oFile.Processed = saSaved Then
    Response.Write "Upload successful"
Else
    Response.Write "Upload failed"
    Response.Write "File error string: " & oFile.Error & "<BR>"
    Response.Write "File error code: " & oFile.ErrorCode & "<BR>"
End If

Top
FileMethod
Syntax
objFileEE.FileMethod [=saFileMethod]
Description

For server-to-server file transfers, FileMethod sets the transfer type.

FileMethod is a Read/Write property.

Parameter

Set FileMethod to an saFileMethod name or number:

saFileMethod Values
saUpload | 0
saDownload | 1
saRoundtrip | 2

Top
FormName
Syntax
objFileEe.FormName [= String]
Description

FormName returns the name of the HTML form field from which the specified file was uploaded.

FormName is a Read/Write property.

Example

In the upload form, if the file field is:

<input type="file" name="myFile">

oFileEe.FormName will return "myFile".

Top
Name
Syntax
objFileEe.Name [= String]
Description

When uploading a file from a web form, Name returns the the value of the <INPUT> field's name attribute. For example, if a file is uploaded from <INPUT type="file" name="file1">, its objFileEe.Name value will be "file1".

To reference a single file in a multi-file upload, you can use the value of Name as the file's key.

Name is a Read/Write property.

Example
In ASP.NET:
[C#]
FileUpEE objFileUpEE = new FileUpEE();
...
objFileUpEE[1].Name = "FirstFile";
objFileUpEE["FirstFile"].OverwriteFile = false;
...

[VB.NET]
Dim objFileUpEE As New FileUpEE()
...
objFileUpEE(1).Name = "FirstFile"
objFileUpEE("FirstFile").OverwriteFile = False
...
In ASP:
[VBScript]
Set objFileUpEE = Server.CreateObject("SoftArtisans.FileUpEE")
...
objFileUpEE(1).Name = "FirstFile"
objFileUpEE("FirstFile").OverwriteFile = False
...
Top
OverwriteFile
Syntax
objFileEe.OverwriteFile [= Boolean]
Description

When set to true, an uploaded file will overwrite an existing file with the same name. When set to false, the uploaded file will not be saved if a file with the same name exists.

OverwriteFile is a Read/Write property, and is set to true by default.

See Also

To set this property for all files in an upload, use FileUpEE.OverwriteFiles.

Top
Params
Syntax
objFileEe.Params.Add Param Name, Param Value
Description

Params is a key/value collection that may be used to send custom values with a SOAP request from web server to file server.

Params is a Read Only property.

Top
PreserveMacBinary
Syntax
objFileEe.PreserveMacBinary
Description

PreserveMacBinary returns a boolean. PreserveMacBinary is a Read Only property.

Note: In order to set PreserveMacBinary on an upload request, you must set it on the FileUpEE object. It is important to understand that this property is not effective when the HttpModule is being used. When it is not implemented and PreserveMacBinary is set to true, a file uploaded from a Macintosh will be saved in MacBinary format. If this property is set to false, the data fork will be extracted and saved as the uploaded file. PreserveMacBinary is set to false by default.

Example
In ASP.NET:
[C#]
if (oFileEE.PreserveMacBinary)
{
    Response.Write("The first uploaded file is set to have both " +
        "the data and resource forks preserved.");
}
else if (!oFileEE.PreserveMacBinary)
{
    Response.Write("The first uploaded file is NOT set to have " +
        "both the data and resource forks preserved.");
}

[VB.NET]
If oFileEE.PreserveMacBinary = True Then
    Response.Write("The first uploaded file is set to have both " & _
    "the data and resource forks preserved.")
ElseIf oFileEE.PreserveMacBinary = False Then
    Response.Write("The first uploaded file is NOT set to have " & _
        "both the data and resource forks preserved.")
End If
In ASP:
[VBScript]
If (oFileEE.PreserveMacBinary = True) Then
    Response.Write("The first uploaded file is set to have both " & _
    "the data and resource forks preserved.")
ElseIf (oFileEE.PreserveMacBinary = False) Then
    Response.Write("The first uploaded file is NOT set to have " & _
        "both the data and resource forks preserved.")
End If
Top
PreviousChecksum
Syntax
objFileEe.PreviousChecksum
Description

FileUpEE allows you to verify the integrity of data uploaded from web server to file server. If FileEe.UseChecksum is enabled on the web server, FileUpEE will generate a file content checksum for the specified file and send the file's checksum with the upload to the file server. On the file server, use FileEe.ValidateChecksum to verify that the data was not corrupted during transfer.

PreviousChecksum contains the file content checksum that was generated on the web server, before the upload was sent to the file server.

PreviousChecksum is a Read Only property.

See Also

You can generate and validate a content checksum for a single file or for the whole upload. For information on using per-upload checksums, see FileUpEE.UseChecksum and FileUpEE.ValidateChecksums.

For more information on using per-file checksums, see FileEe.Checksum, FileEe.UseChecksum, and FileEe.ValidateChecksum.

Top
Processed
Syntax
objFileEe.Processed [=saSaveResult]
Description

Specifies the status of an upload. Check the FileEE.Processed property after calling FileEE.Save to check the status of the file.

Processed is a Read/Write property.

Parameter
saSaveResult Values
saSaved | 0 | Uploaded file saved.
saDownloaded | 0 | File downloaded. Use this value to check the success of a server-to-server download. You cannot use this value to verify that a download was processed successfully on a client.
saExists | 1 | The file was not saved because OverwriteFile is set to false and a file with the same name exists in the destination directory.
saError | 2 | An error occurred.
saEmpty | 3 | No file was submitted for upload.
saUnknown | 4 | An unknown error occurred.
saNoAction | 5 | No action was taken. This may occur when trying to save to a directory that does not exist when the CreateDirectoryPath property is set to false, which is its default value.
Example

The following example displays an error message to the user if Processed returns 2 (saError).

In ASP.NET:
[C#]
foreach FileEe file in objFileUpEE.Files
{
    ...
    file.Save();
    If (file.Processed == 2)
    {
        Response.Write("Error uploading " +
            file.ClientFileName + ":<br>");
        Response.Write(file.Error);
    }
    ...
}

[VB.NET]
For Each file As FileEe In objFileUpEE.Files
    ...
    file.Save()
    If file.Processed = 2 Then
        Response.Write("Error uploading " & _
            file.ClientFileName & ":<br>")
        Response.Write(file.Error)
    End if
    ...
Next
In ASP:
[VBScript]
For each file in objFileUpEE.Files
    ...
    file.Save
    If file.Processed = 2 then
        Response.Write "Error uploading " & _
            file.ClientFileName & ":<br>"
        Response.Write file.Error
    End if
    ...
Next
Top
RelativeName
Syntax
objFileEe.RelativeName
Description

XFileEE allows you to upload a directory from the client. With each file in a directory upload, XFileEE sends an X-RelativeFileName header which contains the file's directory path. For example if you upload the directory \Folder, and \Folder contains the file File.ext, the value of X-RelativeFileName will be "\Folder\File.ext".

A file's RelativeName property returns the value of the file's X-RelativeFileName header, if the file was submitted through a directory upload from XFileEE. RelativeName allows you to save an uploaded directory and maintain the original directory structure.

In a directory upload from client to web server, to process the upload on the server, iterate over the FileUpEE.Files collection, and use RelativeName to specify the file paths. For example:

In ASP.NET:
[C#]
oFileUpEE.DestinationDirectory = @"C:\Uploads\";
foreach (FileEe File in oFileUpEE.Files)
{
    File.SaveAs(File.RelativeName);
}

[VB.NET]
oFileUpEE.DestinationDirectory = "C:\Uploads\"
For Each File As FileEe In oFileUpEE.Files
    File.SaveAs(File.RelativeName)
Next
In ASP:
[VBScript]
oFileUpEE.DestinationDirectory = "C:\Uploads\"
For each File in Files
    File.SaveAs File.RelativeName
Next

In a 3-tier directory upload from client (using XFileEE) to web server to file server, where AutoProcess is set to true on the file server, FileUpEE will automatically look for each file's X-RelativeFileName header and save the files according to their original directory paths. In this case, it is not necessary to get the value of RelativeName or set the file paths in code.

RelativeName is a Read Only property.

Top
SaveMethod
Syntax
objFileEE.SaveMethod [= saSaveMethod]
Description

SaveMethod specifies whether an uploaded file will be saved to a file directory or in a database. SaveMethod is a Read/Write property.

Parameter

Set SaveMethod to an saSaveMethod by name or number:

saSaveMethod Values
saDatabase | 0
saDiskFile | 1 (Default value)
See Also

FileUpEE.SaveMethod

Example
In ASP.NET:
[C#]
objFileUpEE[1].SaveMethod = saSaveMethod.saDatabase;
objFileUpEE.DbConnection = "Provider=Microsoft.Jet.OLEDB.4.0;" +
    @"Data Source=C:\Uploads\files.mdb;" +
    "Persist Security Info=False";
objFileUpEE.DbTableName = "Images";
String dbFileName = objFileUpEE[1].ClientFileName;
objFileUpEE[1].DbSchema.Add("File Name", dbFileName);
...

[VB.NET]
objFileUpEE(1).SaveMethod = saSaveMethod.saDatabase
objFileUpEE.DbConnection = "Provider=Microsoft.Jet.OLEDB.4.0;" & _
    "Data Source=C:\Uploads\files.mdb;" & _
    "Persist Security Info=False"
objFileUpEE.DbTableName = "Images"
Dim dbFileName As String = objFileUpEE(1).ClientFileName
objFileUpEE(1).DbSchema.Add("File Name", dbFileName)
...
In ASP:
[VBScript]
objFileUpEE(1).SaveMethod = saDatabase
objFileUpEE.DbConnection = "Provider=Microsoft.Jet.OLEDB.4.0;" & _
    "Data Source=C:\Uploads\files.mdb;" & _
    "Persist Security Info=False"
objFileUpEE.DbTableName = "Images"
dbFileName = objFileUpEE(1).ClientFileName
objFileUpEE(1).DbSchema.Add "File Name", dbFileName
...
Top
ServerFileName
Syntax
objFileEe.ServerFileName
Description

ServerFileName returns a string representing the name of the file on the server.

ServerFileName is a Read Only property.

Top
Size
Syntax
objFileEe.Size
Description

Size returns the size of the uploaded file, in bytes.

Size is a Read Only property.

Note

FileUpEE can read the size of a file on the server before a download or after an upload. Size cannot be used for client-side file size filtering.

Top
TempFile (ASP only)
Syntax
objFileEe.TempFile [= Temp Directory]
Description

When a file is uploaded to a server, it is cached. TempFile specifies the uploaded file's temporary directory and name on the server. In ASP, the default behavior is for uploads to be cached in the system's default directory for cached files, typically c:\windows\temp; in ASP.NET, the temporary directory is set using the HttpModule application key setting FileUpEETempDir.

After the file is saved, the value of TempFile is the same as the value of DestinationPath.

TempFile is a Read only property.

Note

To change the system's default directory for cached files, reset the TEMP environment variable, as follows:

  • Open the Control Panel.
  • Select System .
  • Select the Advanced tab.
  • Click Environment variables...
  • Select TEMP from the System Variables list.
  • Click Edit .
  • Enter a new Variable Value, and click Ok .
Top
UseChecksum
Syntax
objFileUpEE.UseChecksum [= Boolean]
Description

FileUpEE allows you to verify the integrity of data uploaded from web server to file server. If UseChecksum is set to true on the web server, FileUpEE will generate a file content checksum for the specified file and send the file's checksum with the upload to the file server. On the file server, use FileEe.ValidateChecksum to verify that the data was not corrupted during transfer.

In very large uploads, generating a checksum for each file can take so long that the upload may fail. Enabling UseChecksum is not recommended for very large uploads.

UseChecksum is a Read/Write property.

See Also

You can generate and validate a content checksum for a single file or for the whole upload. For information on using per-upload checksums, see FileUpEE.UseChecksum and FileUpEE.ValidateChecksums.

For more information on using per-file checksums, see FileEe.Checksum, FileEe.PreviousChecksum, and FileEe.ValidateChecksum.

Top

FileEe Methods
Download
Syntax
objFileEe.Download
Description

When downloading a file from a file server to a web server, if in the file server script AutoProcess is set to false, call Download.

Call Download after setting ClientPath and DownloadedPath. Call Download before calling SendResponse .

Example

In the following example the download request is sent from web server to file server, but the download source and destination directories are set on the file server. Since the file server script does not automatically execute instructions from the web server script, AutoProcess is set to false, and the file server script must call download .

web server script:

In ASP.NET:
[C#]
FileUpEE objFileUpEE = new FileUpEe();
objFileUpEE.ProcessRequest(Page.Request, true, false);

//--- You can pass empty strings to AddDownloadFile, and
//--- set the download source and destination directories
//--- on the file server.
objFileUpEE.AddDownloadFile("", "");
objFileUpEE.TargetUrl = @"http://localhost/fileupee/Download/DownloadFS.aspx";
objFileUpEE.SendRequest(Response);

[VB.NET]
Dim objFileUpEE As New FileUpEe()
objFileUpEE.ProcessRequest(Page.Request, True, False)

'--- You can pass empty strings to AddDownloadFile, and
'--- set the download source and destination directories
'--- on the file server.
objFileUpEE.AddDownloadFile("", "")
objFileUpEE.TargetUrl = "http://localhost/fileupee/Download/DownloadFS.aspx"
objFileUpEE.SendRequest(Response)
In ASP:
[VBScript]
Set objFileUpEE = Server.CreateObject("SoftArtisans.FileUpEe")
objFileUpEE.ProcessRequest Request, True, False

'--- You can pass empty strings to AddDownloadFile, and
'--- set the download source and destination directories
'--- on the file server.
objFileUpEE.AddDownloadFile "", ""
objFileUpEE.TargetUrl = "http://localhost/fileupee/Download/DownloadFS.asp"
objFileUpEE.SendRequest Response

File server script:

In ASP.NET:
[C#]
FileUpEE objFileUpEE = new FileUpEe();
objFileUpEE.ProcessRequest(Page.Request, true, false);

//--- Source path:
objFileUpEE[1].DownloadedPath = @"c:\images\file.gif";

//--- Destination path:
objFileUpEE[1].ClientPath = @"c:\downloads\file.gif";
objFileUpEE[1].Download();
objFileUpEE.SendResponse(Response);
Response.End();

[VB.NET]
Dim objFileUpEE As New FileUpEe()
objFileUpEE.ProcessRequest(Page.Request, True, False)

'--- Source path:
objFileUpEE(1).DownloadedPath = "c:\images\file.gif"

'--- Destination path:
objFileUpEE(1).ClientPath = "c:\downloads\file.gif"
objFileUpEE(1).Download()
objFileUpEE.SendResponse(Response)
Response.End()
In ASP:
[VBScript]
Set objFileUpEE = Server.CreateObject("SoftArtisans.FileUpEe")
objFileUpEE.ProcessRequest Request, True, False

'--- Source path:
objFileUpEE(1).DownloadedPath = "c:\images\file.gif"

'--- Destination path:
objFileUpEE(1).ClientPath = "c:\downloads\file.gif"
objFileUpEE(1).Download
objFileUpEE.SendResponse Response
Response.End
Top
Save
Syntax
objFileEE.Save()
Description

Saves an uploaded file to a directory or a database, depending on the value of SaveMethod.

When saving to a directory, set either FileEe.DestinationPath or FileUpEE.DestinationDirectory and FileEe.DestinationFileName.

For instructions on saving a file to a database (adding or updating a record), see FileUpEE.DbConnection, FileUpEE.DbPrimaryKey, FileUpEE.DbPrimaryKeyValue, FileUpEE.DbSqlCommand, FileUpEE.DbTableName, FileEe.DbConnection, FileEe.DbPrimaryKey, FileEe.DbPrimaryKeyValue, FileEe.DbSchema FileEe.DbSqlCommand, and FileUpEE.DbTableName .

See Also

FileEe.SaveAsBlob and FileEe.SaveAs

Example
In ASP.NET:
[C#]
FileUpEE objFileUpEE = new FileUpEE();
objFileUpEE.ProcessRequest(Request, false, false);
...
String FileName = objFileUpEE[1].ClientFileName;
objFileUpEE[1].DestinationPath = @"c:\temp\upload\" + FileName;
objFileUpEE[1].Save();
...

[VB.NET]
Dim objFileUpEE As New FileUpEE()
objFileUpEE.ProcessRequest(Request, False, False)
...
Dim FileName As String = objFileUpEE(1).ClientFileName
objFileUpEE(1).DestinationPath = "c:\temp\upload\" & FileName
objFileUpEE(1).Save()
...
In ASP:
[VBScript]
Set objFileUpEE = Server.CreateObject("SoftArtisans.FileUpEE")
objFileUpEE.ProcessRequest Request
...
FileName = objFileUpEE(1).ClientFileName
objFileUpEE(1).DestinationPath = "c:\temp\upload\" & FileName
objFileUpEE(1).Save
...
Top
SaveAs
Syntax
objFileEE.SaveAs (Path & File Name)
Description

Saves a file to a directory specified by the method's FileName parameter.

Example
In ASP.NET:
[C#]
FileUpEE objFileUpEE = new FileUpEE();
objFileUpEE.ProcessRequest(Request, false, false);
...
String FileName = objFileUpEE[1].ClientFileName;
objFileUpEE[1].SaveAs(@"c:\temp\upload\" + FileName);

[VB.NET]
Dim objFileUpEE As New FileUpEE()
objFileUpEE.ProcessRequest(Request, False, False)
...
Dim FileName As String = objFileUpEE(1).ClientFileName
objFileUpEE(1).SaveAs("c:\temp\upload\" & FileName)
In ASP:
[VBScript]
Set objFileUpEE = Server.CreateObject("SoftArtisans.FileUpEE")
objFileUpEE.ProcessRequest Request
...
FileName = objFileUpEE(1).ClientFileName
objFileUpEE(1).SaveAs "c:\temp\upload\" & FileName
Top
SaveAsBlob
Syntax
objFileEE.SaveAsBlob (Variant Blob)
Description

Saves a file to a database. You can also save to a database by setting SaveMethod to saDatabase and calling the Save method.

There are two overloads for FileEE.SaveAsBlob(). The first takes a single parameter, an Object representing the Blob into which you want the file uploaded. The second is available only in ASP.NET using a SQL Database and takes three parameters: a SqlCommand that provides a connection command to the SQL Server Database, a first SqlParameter as the input parameter, and a second SqlParameter that provides an output parameter. In order to use the latter overload, you will need to have ADO.NET components available from the server in which you have installed FileUpEE. If multiple files are uploaded to be inserted into the database, the datarecord must be located for each file in the collection and the appropriate SQLCommand object must be created for each file in the collection.

Example

The following is an example of how to use FileEE.SaveAsBlob() to insert a single file into a SQL Server Database. This database is named "Files" with a data table named "FileSave". Within the "FileSave" data table is an integer column named "FileID" and a BLOB column named "FileData". The example code will upload a file into the blob column row corresponding with the "FileID" value of "35".

This example assumes that only one file is uploaded and inserted into the database. The database transaction reads directly from the temporary file that was saved by the FileUpEEModule filter and inserts the file into the database column for the record identified.

[C#]
FileEe oFile = oFileUpEE.Files[FTDEV:"file1"];
try
{
    //--- create a connection to the database
    SqlConnection cn = new SqlConnection("Data Source=<Your Server Name>;Persist Security Info=False;
        User ID=<your user id>;pwd=<your password>;Initial Catalog=Files;");
    cn.Open();

    //--- locate the record to be updated and set the first byte in the
    //--- FileData column to NULL, and retrieve a pointer to the starting
    //--- byte in the blob column.  This example uses the record where the
    //--- value of the FileID column is '35'
    String strSql = "SET NOCOUNT ON;UPDATE FileSave SET FileData = 0x0 WHERE FileID=35;
        SELECT @Pointer=TEXTPTR(FileData) FROM FileSave WHERE FileID=35";
    SqlCommand cmdGetPointer = new SqlCommand(strSql, cn);
    SqlParameter pCategoryIdParam = cmdGetPointer.Parameters.Add("@FileID", SqlDbType.Int);
    pCategoryIdParam.Value = 35;
    SqlParameter OutParam = cmdGetPointer.Parameters.Add("@Pointer", SqlDbType.VarBinary, 100);
    OutParam.Direction = ParameterDirection.Output;

    //--- Open the row with the 'UPDATE' sql command and get a 'TEXTPTR'
    //--- pointer to the blob column.
    intnRows = cmdGetPointer.ExecuteNonQuery();

    //--- Verify that the row was opened.
    if(OutParam.Value == System.DBNull.Value)
    {
        Response.Write("Failed to open row");
        cn.Close();
        return;
    }

    //--- Create an System.Data.SqlClient.SqlCommand reference using the
    //--- 'UPDATETEXT' sql command, creating 'Pointer',  'Offset', and 'Delete'
    //--- parameters so that FileEE can properly chunk data to the database column.
    SqlCommand pSqlCmd = new SqlCommand("UPDATETEXT FileSave.FileData @Pointer @Offset @Delete WITH LOG @Bytes", cn);
    SqlParameter InParam = pSqlCmd.Parameters.Add("@Pointer", SqlDbType.Binary, 16);

    //--- call SaveAsBlob to read the file in chunks and
    //--- update the column in the database.
    oFile.SaveAsBlob(pSqlCmd, InParam, OutParam);

    //--- Close the database connection.
    cn.Close();
}
catch(Exception exc)
{
    Response.Write(exc.ToString());
}

[VB.NET]
FileEe oFile = oFileUpEE.Files(FTDEV:"file1");
Try
    '--- create a connection to the database
    Dim cn As New SqlConnection("Data Source=<Your Server Name>;Persist Security Info=False;" & _
        "User ID=<your user id>;pwd=<your password>;Initial Catalog=Files;")
    cn.Open()

    '--- locate the record to be updated and set the first byte in the
    '--- FileData column to NULL, and retrieve a pointer to the starting
    '--- byte in the blob column.  This example uses the record where the
    '--- value of the FileID column is '35'
    String strSql = "SET NOCOUNT ON;UPDATE FileSave SET FileData = 0x0 WHERE FileID=35;" & _
        "SELECT @Pointer=TEXTPTR(FileData) FROM FileSave WHERE FileID=35"
    Dim cmdGetPointer As New SqlCommand(strSql, cn)
    Dim pCategoryIdParam As SqlParameter = cmdGetPointer.Parameters.Add("@FileID", SqlDbType.Int)
    pCategoryIdParam.Value = 35
    Dim OutParam As SqlParameter = cmdGetPointer.Parameters.Add("@Pointer", SqlDbType.VarBinary, 100)
    OutParam.Direction = ParameterDirection.Output

    '--- Open the row with the 'UPDATE' sql command and get a 'TEXTPTR'
    '--- pointer to the blob column.
    intnRows = cmdGetPointer.ExecuteNonQuery()

    '--- Verify that the row was opened.
    If OutParam.Value = System.DBNull.Value Then
        Response.Write("Failed to open row")
        cn.Close()
        Return
    End If

    '--- Create an System.Data.SqlClient.SqlCommand reference using the
    '--- 'UPDATETEXT' sql command, creating 'Pointer',  'Offset', and 'Delete'
    '--- parameters so that FileEE can properly chunk data to the database column.
    Dim pSqlCmd As New SqlCommand("UPDATETEXT FileSave.FileData @Pointer @Offset @Delete WITH LOG @Bytes", cn)
    Dim InParam As SqlParameter = pSqlCmd.Parameters.Add("@Pointer", SqlDbType.Binary, 16)

    '--- call SaveAsBlob to read the file in chunks and
    '--- update the column in the database.
    oFile.SaveAsBlob(pSqlCmd, InParam, OutParam)

    '--- Close the database connection.
    cn.Close()
Catch exc As Exception
    Response.Write(exc.ToString())
End Try
Top
ValidateChecksum
Syntax
objFileEE.ValidateChecksum
Description

Use ValidateChecksum to verify the integrity of data transferred from web server to file server. If FileEe.UseChecksum is set to true on the web server, FileUpEE will generate a content checksum for the specified file and send the checksum with the upload. On the file server, use ValidateChecksums to verify that the data was not corrupted during transfer.

If the file content checksum received from the web server and the checksum generated on the file server are identical, ValidateChecksums returns true. If the file checksums are not identical, the file was corrupted during transfer, and ValidateChecksum returns false.

See Also

You can generate and validate a content checksum for a single file or for the whole upload. For information on using per-upload checksums, see FileUpEE.UseChecksum and FileUpEE.ValidateChecksums.

For more information on using per-file checksums, see FileEe.Checksum, FileEe.PreviousChecksum, and FileEe.UseChecksum.

Top
WriteToResponse
Syntax
objFileEE.WriteToResponse(Response)
Description

WriteToResponse writes the specified file to the ASP Response.

Using WriteToResponse in a Server-to-Client Download

When downloading a file from a web server to a client using FileUpEE.AddDownloadFile, use WriteToResponse to send the file to the browser. For an example using the FileUpEE.AddDownloadFile method, see A Simple Download. Note that the FileUpEE.TransferFile method is the recommended method for performing FileUpEE downloads.

Using WriteToResponse in a Server-to-Server-to-Client Download

WriteToResponse allows you to include operations in script that will be executed between a file's arrival on the web server and its transfer to the client.

If in the web server script, you pass the ASP Request object to SendRequest, the file will be downloaded from the file server to the web server, and immediately sent to the client. If you do not pass the ASP Request object to SendRequest, the file will be downloaded to the web server, but will not be sent to the client. Later in the script, you can use WriteToResponse to send the file to the client.

Note

To let the browser know how to handle a download, set the content-type response header to the file's ContentType before sending the file to the browser.

Example

The following is the web server script in a download from file server to web server to client. The script gets the download source and destination directories from a form.

[VBScript]
Set objFileUpEE = Server.CreateObject("SoftArtisans.FileUpEE")
objFileUpEE.ProcessRequest Request
objFileUpEE.AddDownloadFile objFileUpEE.Form("Download"), objFileUpEE.Form("Client")
objFileUpEE.TargetUrl = "http://localhost/fileupee/download/fsDown.asp"
enumRetVal = objFileUpEE.SendRequest()
...
'--- Script included between SendRequest() and WriteToResponse
'--- will be executed after a file is downloaded to the web
'--- server but before it is transferred to the client.
...
If objFileUpEE(1).Processed = saSaved then
    objFileUpEE(1).WriteToResponse(Response)
End if
Top


The Encryption Object (ASP.NET only)

The Encryption object.

Encryption in ASP.NET

The Encryption object is a member of the SoftArtisans.Net.Utilities namespace. To minimize typing or errors, use a using statement in C# or an Import statement in VB.NET to add the namespace to the ASP.NET page, after which you can reference the class by name alone without the namespace name.

[C#]

using SoftArtisans.Net.Utilities;

[VB.NET]

Imports SoftArtisans.Net.Utilities

To create an Encryption object in ASP.NET:

[C#]

Encryption encryption = new Encryption();

[VB.NET]

Dim encryption as New Encryption()
Encryption Method
Encrypt
Encryption Method
Encrypt
Syntax
Encryption.Encrypt(String)
Description

The static Encrypt method take a string as its paramater and returns an encrypted string. This method works in conjunction with SoftArtisans XFileEE’s AddEncryptedRequestHttpHeader method which takes a value that was encrypted with FileUpEE's Encryption.Encrypt method in the server-side script as its second parameter. Note: For a use-case scenario for this new feature, please see the following KB article: Session loss in ASP.NET 2.0 using XFileEE with FileUpEE

Example

Client-side code:

[javascript]
XFile.AddEncryptedRequestHttpHeader("headerName",
    '<%= SoftArtisans.Net.Utilities.Encryption.Encrypt("headerValue") %>', true);
Top


The Progress Object

FileUpEE includes a server-side progress indicator that allows you to log and display the progress of an upload. Note that the progress indicator monitors the whole upload, and cannot watch the progress of an individual file within an upload. You can, however, monitor the progress of individual files by using XFileEE's client-side progress indicator.

FileUpEE's progress indicator can monitor uploads from client to web server, and from web server to file server. The progress from client to web server is measured as the number of bytes received on the web server. Progress from web server to file server is measured as the number of bytes sent from the web server; note that this is not proof of arrival on the file server.

FileUpEEProgress in ASP.NET

The FileUpEE objects for ASP.NET are in the SoftArtisans.Net namespace. The objects can be referenced as fully qualified names, such as SoftArtisans.Net.FileUpEe. To minimize typing and errors, use an Import directive to import the namespace to the ASP.NET page. This allows you to reference objects by name alone, without the namespace prefix. Add a reference to FileUpEE in ASP.NET by including this statement at the top of your code behind page:

In C#:      using SoftArtisans.Net;
In VB.NET:  Imports SoftArtisans.Net

To create an instance of the progress object in an ASP.NET page, use:

In C#:      FileUpEeProgress oFileUpEEProgress = new FileUpEeProgress();
In VB.NET:  Dim oFileUpEEProgress As New FileUpEeProgress()
FileUpEEProgress in ASP

To create an instance of the progress indicator in an ASP page, use:

Set objFileUpProgress = Server.CreateObject("Softartisans.FileUpEEProgress")
Progress Indicator Properties | Progress Indicator Methods
Percentage | Dispose
ProgressId | NextProgressID
TotalBytes |
TransferredBytes |
Watch |
Progress Indicator Properties
Percentage
Syntax
objProgress.Percentage
Description

The Percentage property returns the percentage of the upload that was:

  • Received on the web server (if the upload is from client to web server)

    OR

  • Sent to the file server (if the upload is from web server to file server)
Top
ProgressId
Syntax
objProgress.ProgressId [=Progress Id]
Description

The ProgressId property sets or returns a progress id number for an upload. FileUpEE automatically generates a unique progress id for each upload.

Top
TotalBytes
Syntax
objProgress.TotalBytes
Description

The TotalBytes property returns the total number of bytes to be uploaded.

Top
TransferredBytes
Syntax
objProgress.TransferredBytes
Description

The TransferredBytes property returns the number of bytes that were:

  • Received on the web server (if the upload is from client to web server)

    OR

  • Sent to the file server (if the upload is from web server to file server)
Top
Watch
Syntax
objProgress.Watch =SATransferStage
Description

The Watch property specifies the transfer stage that the progress indicator should watch: saClient for client to web server, or saWebServer for web server to file server.

Example

The following is from the client script (upload form) in a 3-tier (client to web server to file server) upload:

In ASP.NET:
[C#]
//--- Watch the upload from client to web server. That is,
//--- monitor the upload as it is RECEIVED on the web server.
oFileUpEEProgressClient.Watch = saTransferStage.saClient;

//--- Watch the upload from web server to file server. That
//--- is, monitor the upload as it is SENT FROM the web server.
oFileUpEEProgressClient.Watch = saTransferStage.saWebServer;

[VB.NET]
'--- Watch the upload from client to web server. That is,
'--- monitor the upload as it is RECEIVED on the web server.
oFileUpEEProgressClient.Watch = saTransferStage.saClient

'--- Watch the upload from web server to file server. That
'--- is, monitor the upload as it is SENT FROM the web server.
oFileUpEEProgressClient.Watch = saTransferStage.saWebServer
In ASP:
[VBScript]
'--- Watch the upload from client to web server. That is,
'--- monitor the upload as it is RECEIVED on the web server.
oFileUpEEProgressClient.Watch = saClient

'--- Watch the upload from web server to file server. That
'--- is, monitor the upload as it is SENT FROM the web server.
oFileUpEEProgressClient.Watch = saWebServer
Top

Progress Indicator Methods
Dispose
Syntax
objProgress.Dispose
Description

When you are finished using an instance of the progress indicator under .NET, always call Dispose to ensure thorough cleanup of the FileUpEEProgress object.

Example
[C#]
finally
{
    //--- Always call FileUpEEProgress.Dispose() in finally
    if(oFileUpEEProgress!=null)
        oFileUpEEProgress.Dispose();
    oFileUpEEProgress = null;
}

[VB.NET]
Finally
    '--- Always call FileUpEEProgress.Dispose() in finally
    If Not oFileUpEEProgress = Nothing
        oFileUpEEProgress.Dispose()
    oFileUpEEProgress = Nothing
End Try
Top
NextProgressID
Syntax
objProgress.NextProgressID
Description

NextProgressId returns the next unused ProgressId.

Example
In ASP.NET:
[C#]
int ProgID = oFileUpEEProgress.NextProgressID();

[VB.NET]
Dim ProgID As Integer = oFileUpEEProgress.NextProgressID()

ProgID = oFileUpEEProgress.NextProgressID
Top


Windows System Error Codes

The FileEe object's ErrorCode property returns a system error code, if an error occurred when transferring the specified file.

0 | ERROR_SUCCESS | The operation completed successfully.
1 | ERROR_INVALID_FUNCTION | Incorrect function.
2 | ERROR_FILE_NOT_FOUND | The system cannot find the file specified.
3 | ERROR_PATH_NOT_FOUND | The system cannot find the path specified.
4 | ERROR_TOO_MANY_OPEN_FILES | The system cannot open the file.
5 | ERROR_ACCESS_DENIED | Access is denied.
6 | ERROR_INVALID_HANDLE | The handle is invalid.
7 | ERROR_ARENA_TRASHED | The storage control blocks were destroyed.
8 | ERROR_NOT_ENOUGH_MEMORY | Not enough storage is available to process this command.
9 | ERROR_INVALID_BLOCK | The storage control block address is invalid.
10 | ERROR_BAD_ENVIRONMENT | The environment is incorrect.
11 | ERROR_BAD_FORMAT | An attempt was made to load a program with an incorrect format.
12 | ERROR_INVALID_ACCESS | The access code is invalid.
13 | ERROR_INVALID_DATA | The data is invalid.
14 | ERROR_OUTOFMEMORY | Not enough storage is available to complete this operation.
15 | ERROR_INVALID_DRIVE | The system cannot find the drive specified.
16 | ERROR_CURRENT_DIRECTORY | The directory cannot be removed.
17 | ERROR_NOT_SAME_DEVICE | The system cannot move the file to a different disk drive.
18 | ERROR_NO_MORE_FILES | There are no more files.
19 | ERROR_WRITE_PROTECT | The media is write protected.
20 | ERROR_BAD_UNIT | The system cannot find the device specified.
21 | ERROR_NOT_READY | The device is not ready.
22 | ERROR_BAD_COMMAND | The device does not recognize the command.
23 | ERROR_CRC | Data error (cyclic redundancy check).
24 | ERROR_BAD_LENGTH | The program issued a command but the command length is incorrect.
25 | ERROR_SEEK | The drive cannot locate a specific area or track on the disk.
26 | ERROR_NOT_DOS_DISK | The specified disk or diskette cannot be accessed.
27 | ERROR_SECTOR_NOT_FOUND | The drive cannot find the sector requested.
28 | ERROR_OUT_OF_PAPER | The printer is out of paper.
29 | ERROR_WRITE_FAULT | The system cannot write to the specified device.
30 | ERROR_READ_FAULT | The system cannot read from the specified device.
31 | ERROR_GEN_FAILURE | A device attached to the system is not functioning.
32 | ERROR_SHARING_VIOLATION | The process cannot access the file because it is being used by another process.
33 | ERROR_LOCK_VIOLATION | The process cannot access the file because another process has locked a portion of the file.
34 | ERROR_WRONG_DISK | The wrong diskette is in the drive. Insert %2 (Volume Serial Number: %3) into drive %1.
36 | ERROR_SHARING_BUFFER_EXCEEDED | Too many files opened for sharing.
38 | ERROR_HANDLE_EOF | Reached the end of the file.
39 | ERROR_HANDLE_DISK_FULL | The disk is full.
50 | ERROR_NOT_SUPPORTED | The request is not supported.
51 | ERROR_REM_NOT_LIST | Windows cannot find the network path. Verify that the network path is correct and the destination computer is not busy or turned off. If Windows still cannot find the network path, contact your network administrator.
52 | ERROR_DUP_NAME | You were not connected because a duplicate name exists on the network. Go to System in the Control Panel to change the computer name and try again.
53 | ERROR_BAD_NETPATH | The network path was not found.
54 | ERROR_NETWORK_BUSY | The network is busy.
55 | ERROR_DEV_NOT_EXIST | The specified network resource or device is no longer available.
56 | ERROR_TOO_MANY_CMDS | The network BIOS command limit has been reached.
57 | ERROR_ADAP_HDW_ERR | A network adapter hardware error occurred.
58 | ERROR_BAD_NET_RESP | The specified server cannot perform the requested operation.
59 | ERROR_UNEXP_NET_ERR | An unexpected network error occurred.
60 | ERROR_BAD_REM_ADAP | The remote adapter is not compatible.
61 | ERROR_PRINTQ_FULL | The printer queue is full.
62 | ERROR_NO_SPOOL_SPACE | Space to store the file waiting to be printed is not available on the server.
63 | ERROR_PRINT_CANCELLED | Your file waiting to be printed was deleted.
64 | ERROR_NETNAME_DELETED | The specified network name is no longer available.
65 | ERROR_NETWORK_ACCESS_DENIED | Network access is denied.
66 | ERROR_BAD_DEV_TYPE | The network resource type is not correct.
67 | ERROR_BAD_NET_NAME | The network name cannot be found.
68 | ERROR_TOO_MANY_NAMES | The name limit for the local computer network adapter card was exceeded.
69 | ERROR_TOO_MANY_SESS | The network BIOS session limit was exceeded.
70 | ERROR_SHARING_PAUSED | The remote server has been paused or is in the process of being started.
71 | ERROR_REQ_NOT_ACCEP | No more connections can be made to this remote computer at this time because there are already as many connections as the computer can accept.
72 | ERROR_REDIR_PAUSED | The specified printer or disk device has been paused.
80 | ERROR_FILE_EXISTS | The file exists.
82 | ERROR_CANNOT_MAKE | The directory or file cannot be created.
83 | ERROR_FAIL_I24 | Fail on INT 24.
84 | ERROR_OUT_OF_STRUCTURES | Storage to process this request is not available.
85 | ERROR_ALREADY_ASSIGNED | The local device name is already in use.
86 | ERROR_INVALID_PASSWORD | The specified network password is not correct.
87 | ERROR_INVALID_PARAMETER | The parameter is incorrect.
88 | ERROR_NET_WRITE_FAULT | A write fault occurred on the network.

Top


HTTP Status Codes

100 | HTTP_STATUS_CONTINUE | The request can be continued.
101 | HTTP_STATUS_SWITCH_PROTOCOLS | The server has switched protocols in an upgrade header.
200 | HTTP_STATUS_OK | The request completed successfully.
201 | HTTP_STATUS_CREATED | The request has been fulfilled and resulted in the creation of a new resource.
202 | HTTP_STATUS_ACCEPTED | The request has been accepted for processing, but the processing has not been completed.
203 | HTTP_STATUS_PARTIAL | The returned meta information in the entity-header is not the definitive set available from the originating server.
204 | HTTP_STATUS_NO_CONTENT | The server has fulfilled the request, but there is no new information to send back.
205 | HTTP_STATUS_RESET_CONTENT | The request has been completed, and the client program should reset the document view that caused the request to be sent to allow the user to easily initiate another input action.
206 | HTTP_STATUS_PARTIAL_CONTENT | The server has fulfilled the partial GET request for the resource.
207 | HTTP_STATUS_WEBDAV_MULTI_STATUS | During a World Wide web Distributed Authoring and Versioning (WebDAV) operation, this indicates multiple status codes for a single response. The response body contains Extensible Markup Language (XML) describing the status codes. For more information, see HTTP Extensions for Distributed Authoring .
300 | HTTP_STATUS_AMBIGUOUS | The requested resource is available at one or more locations.
301 | HTTP_STATUS_MOVED | The requested resource has been assigned to a new permanent Uniform Resource Identifier (URI), and any future references to this resource should be done using one of the returned URIs.
302 | HTTP_STATUS_REDIRECT | The requested resource resides temporarily under a different URI.
303 | HTTP_STATUS_REDIRECT_METHOD | The response to the request can be found under a different URI and should be retrieved using a GET HTTP verb on that resource.
304 | HTTP_STATUS_NOT_MODIFIED | The requested resource has not been modified.
305 | HTTP_STATUS_USE_PROXY | The requested resource must be accessed through the proxy given by the location field.
307 | HTTP_STATUS_REDIRECT_KEEP_VERB | The redirected request keeps the same HTTP verb. HTTP/1.1 behavior.
400 | HTTP_STATUS_BAD_REQUEST | The request could not be processed by the server due to invalid syntax.
401 | HTTP_STATUS_DENIED | The requested resource requires user authentication.
402 | HTTP_STATUS_PAYMENT_REQ | Not implemented in the HTTP protocol.
403 | HTTP_STATUS_FORBIDDEN | The server understood the request, but will not fulfill it.
404 | HTTP_STATUS_NOT_FOUND | The server has not found anything matching the requested URI.
405 | HTTP_STATUS_BAD_METHOD | The HTTP verb used is not allowed.
406 | HTTP_STATUS_NONE_ACCEPTABLE | No responses acceptable to the client were found.
407 | HTTP_STATUS_PROXY_AUTH_REQ | Proxy authentication required.
408 | HTTP_STATUS_REQUEST_TIMEOUT | The server timed out waiting for the request.
409 | HTTP_STATUS_CONFLICT | The request could not be completed due to a conflict with the current state of the resource. The user should resubmit with more information.
410 | HTTP_STATUS_GONE | The requested resource is no longer available at the server, and no forwarding address is known.
411 | HTTP_STATUS_LENGTH_REQUIRED | The server will not accept the request without a defined content length.
412 | HTTP_STATUS_PRECOND_FAILED | The precondition given in one or more of the request header fields evaluated to false when it was tested on the server.
413 | HTTP_STATUS_REQUEST_TOO_LARGE | The server will not process the request because the request entity is larger than the server is willing or able to process.
414 | HTTP_STATUS_URI_TOO_LONG | The server will not service the request because the request URI is longer than the server can interpret.
415 | HTTP_STATUS_UNSUPPORTED_MEDIA | The server will not service the request because the entity of the request is in a format not supported by the requested resource for the requested method.
449 | HTTP_STATUS_RETRY_WITH | The request should be retried after doing the appropriate action.
500 | HTTP_STATUS_SERVER_ERROR | The server encountered an unexpected condition that prevented it from fulfilling the request.
501 | HTTP_STATUS_NOT_SUPPORTED | The server does not support the functionality required to fulfill the request.
502 | HTTP_STATUS_BAD_GATEWAY | The server, while acting as a gateway or proxy, received an invalid response from the upstream server it accessed in attempting to fulfill the request.
503 | HTTP_STATUS_SERVICE_UNAVAIL | The service is temporarily overloaded.
504 | HTTP_STATUS_GATEWAY_TIMEOUT | The request was timed out waiting for a gateway.
505 | HTTP_STATUS_VERSION_NOT_SUP | The server does not support, the HTTP protocol version that was used in the request message.

Top


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 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 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.


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.

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.

  • 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


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
...


Backwards Compatibility

ISAPI Filter

HttpModule version 5.0.33

JFile


ISAPI Filter

  • The FileUpEE ISAPI filter
  • Installing the FileUpEE ISAPI filter
  • Allowing ASP to Process Files with the .upl Extension
  • The ISAPI Filter Temp Directory
  • Using the Progress Indicator
  • Resumability
  • FilterASPFlagExtension
  • MaxClientRequestBuffer

The FileUpEE ISAPI filter

The FileUpEE ISAPI filter was introduced in version 4 of FileUpEE as a solution for overcoming upload limitations in the ASP.NET environment. The filter was designed for use with version 5 of IIS. With the introduction of IIS 6, there was no longer support for Read_Raw_Data ISAPI level filters in the native processing model. To address this incompatibility with IIS 6 the same pre-processing functionality that was available in the ISAPI filter was made available in the FileUpEE HttpModule. The HttpModule provides the same functionality as the ISAPI filter, but is compatible with both IIS 5 and IIS 6. As such, the ISAPI filter is now considered a deprecated technology.

There are two remaining reasons to use the FileUpEE ISAPI filter in a new application, both relating to large downloads in ASP on servers running IIS 5:

  • Large uploads (over 2GB) in ASP may see a performance benefit when using the ISAPI filter.
  • Large uploads in ASP can cause problems in ASP's Request.BinaryRead method, which can throw intermittent errors.

It should be noted that both of these issues are also addressed and corrected by the FileUpEE HttpModule. For this reason, the use of the ISAPI filter with .NET file transfers has been deprecated.

If you intend to support legacy applications that use the ISAPI filter, you should be aware of the following:

  • A legacy application employing the ISAPI filter cannot be moved to an IIS 6 server, unless you are able to run that server in IIS 5 isolation mode.

  • In order to access documentation that provides instructions for use of the ISAPI filter, you will need to download version 5.0 of the FileUpEE docs.

Installing the ISAPI Filter

For security reasons, FileUpEE's automatic installation does not automatically install the ISAPI filter in IIS. To install the filter in IIS:

  1. Open IIS, right-click the machine name icon, and select Properties.

    FileUp's ISAPI filter must be installed at the machine level, not the web site or web application level.

  2. Select the Internet Information Services tab.

  3. From the Master Properties drop-down list, select WWW Service, and click Edit.

  4. Select the ISAPI Filters tab.

  5. Click Add.

  6. In the Filter Properties dialog box, enter the filter name FileUpEE, browse to FileUpEEIsapi.dll, and click Ok.

  7. Restart IIS to load the filter: right-click the machine name icon, select Restart IIS..., select Restart Internet Services from the drop-down list, and click Ok.

Top

Allowing ASP to Process Files with the .upl Extension

FileUpEE's ISAPI filter will intercept requests to files with the extension .upl. After the filter handles a request to a .upl file, the request is forwarded to ASP. To allow ASP to process files with the extension .upl, you must add a script map to IIS (for security reasons, FileUpEE's automatic installation does not add the script map automatically).

In the Windows XP IIS console, the Web Sites and Default web Site nodes have identical properties dialogs. The script maps can be installed in the Web Sites properties, but they will be ignored by IIS. The script maps must be installed from the Default web Site node.
  • Add .upl to the Default web Site's App Mappings
    1. Open IIS, right-click the Default web Site, and select Properties.

    2. Select the Home Directory tab.

    3. Click Configuration.

    4. Select the App Mappings tab.

    5. Click Add.

    6. Browse to asp.dll (typically in C:\WINNT\System32\inetsrv\).

    7. In the Extension field, enter upl.

    8. Select All Verbs.

    9. Check Script Engine, and click Ok.

    OR

  • Add .upl to the Application's App Mappings
    1. Open IIS, right-click your application's virtual directory, and select Properties.

    2. Select the Virtual Directory tab.

    3. Click Configuration.

    4. Select the App Mappings tab.

    5. Click Add.

    6. Browse to asp.dll (typically in C:\WINNT\System32\inetsrv\).

    7. In the Extension field, enter upl.

    8. Select All Verbs.

    9. Check Script Engine, and click Ok.

Top

The ISAPI Filter Temp Directory

The ISAPI filter caches request data before it is processed by ASP or ASP.NET. The location of the cache files can be configured in the Windows registry. By default, the cache location is the system's default directory for cached files, which is determined by the system environment variable TEMP. To set a different ISAPI filter temp directory:

  1. Open the Start menu, and select Run.
  2. Enter regedit and click Ok.
  3. Open HKEY_LOCAL_MACHINE\SOFTWARE\SoftArtisans\FileUpEe\Parameters.
  4. Right-click FileUpEETempDir and select Modify.
  5. In Value Data, enter the path and folder name.

The ISAPI filter temp directory must be on a local drive, not on a network shared drive. The ISAPI filter writes to the server hard drive as the local SYSTEM account and this account does not have access to network drives.

To change the system's default directory for cached files, reset the TEMP environment variable, as follows:
  • Open the Control Panel.
  • Select System .
  • Select the Advanced tab.
  • Click Environment variables...
  • Select TEMP from the System Variables list.
  • Click Edit .
  • Enter a new Variable Value, and click Ok .

Top

Using the Progress Indicator

If you are using the ISAPI filter with progress indication, ProgressIndicator must be enabled the registry. Set the value of the ProgressIndicator registry key to 1 to enable progress indication with the ISAPI Filter.

Top

Resumability

If you are using the ISAPI filter with a resumable file transfer, Resumable must be enabled in the registry. Set the value of Resumable to 1 to enable resumable file transfers with the ISAPI filter.

Top

FilterAspFlagExtension

With the FileUpEE registry key FilterAspFlagExtension, you can change the file extension used to signal the filter in ASP (.upl) to a different extension of up to seven characters. By using a file extension other than .upl you can hide your web server implementation (Windows/IIS) from potential hackers.

Top

MaxClientRequestBuffer

The IIS parameter MaxClientRequestBuffer sets a maximum size for the first chunk of an HTTP request. The first chunk will usually contain only a request's header fields, which includes all data in a request that is not part of the request's entity body. The default value of MaxClientRequestBuffer is 128 KB.

FileUp's ISAPI filter creates a new request and sends the entire request to ASP as one chunk. When an upload contains many files, the ISAPI filter request may exceed the default value of MaxClientRequestBuffer and IIS might reject the request. To prevent this, add a MaxClientRequestBuffer key to the registry and set it to an appropriate value. Many factors can affect the size of the ISAPI filter request, but it will usually be around 128 KB per 600 uploaded files. To add MaxClientRequestBuffer to the registry and set it to a new value:

  1. Open the Start menu and select Run...

  2. Enter regedit and click Ok.

  3. Open the folder HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\W3SVC\.

  4. From the Edit menu select New -> DWORD Value.

  5. Right-click the new key and rename it MaxClientRequestBuffer.

  6. Double-click MaxClientRequestBuffer An Edit DWORD Value dialog will open.

  7. Under Base select Decimal.

  8. In the Value Data field, enter a buffer size in kilobytes.

Top


Installing the Old HttpModule

FileUpEE versions 5.1 and higher come with a new version of the HttpModule that has a number of significant improvements over the original. This page describes how to install and use the HttpModule for users who have not upgraded to the latest version of FileUpEE.

While the newest version of the HttpModule is configured using AppSettings in the application's web.config file, the older HttpModule is configured on the machine level using registry keys. A full description of these is found on the Registry Keys page.

The ISAPI filter and the HttpModule must not be used at the same time. Do not install the ISAPI filter if you plan to use the HttpModule. If you are upgrading, and plan to use the HttpModule, make sure you remove the ISAPI filter from IIS. To use the ISAPI filter, see Installing the ISAPI filter.

In IIS 5 or IIS 6 running in IIS 5 mode, you can use either the ISAPI filter or the HttpModule. However, both cannot be installed on the same machine. In IIS 6 running in native IIS 6 mode, you can only use the HttpModule.

During the automatic installation of FileUpEE, you were asked if you want to install FileUpEE for ASP or ASP.NET. If you selected the ASP.NET version, the HttpModule was installed automatically for FileUpEE's sample applications. If you would like the HttpModule to be available to all applications, install FileUpEeModule.dll in the Global Assembly Cache (GAC). To make the FileUpEeModule.dll available to a single application, include at the application's top level, a bin directory containing FileUpEeModule.dll.

To make FileUpEeModule.dll available to a single application:

  1. Within your application, include a top level direcory called bin that contains FileUpEE.dll, MimeClient.dll, and FileUpEEProgress.dll, and FileUpEeModule.dll. The bin directory should contain the dll files you will find in FileUpEE\DotNet, not the files in FileUpEE\COM.

  2. Create a text file containing the following lines, and save it as web.config. Save web.config at the top level of your application.

<configuration>
    <system.web>
        <!-- Allows upload requests to be processed by the module. -->
        <httpHandlers>
            <add verb="*" path="*.uplx" type="System.Web.UI.PageHandlerFactory"/>
        </httpHandlers>
        <!-- This loads the FileUpEE HttpModule for this application. Version numbers
                must match the FileUpEeModule.dll exactly. -->
        <httpModules>
            <add name="FileUpEeModule"
                    type="SoftArtisans.Net.FileUpEeModule,FileUpEeModule,
                          Version=x.x.x.x,
                          Culture=neutral,
                          PublicKeyToken=f593502af6ee46ae"/>
        </httpModules>
        <!--
                These httpRuntime settings set at the application level will override the
                machine.config settings. Default executionTimeout is 90 seconds which
                should be increased for very large uploads; here it is set to 1200 seconds
                (20 minutes) to allow large uploads.  Default maxRequestLength is 4 mb
                which can be increased or decreased based on upload size; here it is set
                to 102400 kb (100 mb) to allow large uploads.
                -->
        <httpRuntime
                executionTimeout="1200"
                maxRequestLength="102400"
                useFullyQualifiedRedirectUrl="false"
                minFreeThreads="8"
                minLocalRequestFreeThreads="4"
                appRequestQueueLimit="100" />
    </system.web>
</configuration>

To make FileUpEeModule.dll available to all .NET applications on your machine:

  1. Open a command prompt window and move to the directory FileUpEE\DotNet.

  2. Enter gacutil /i FileUpEeModule.dll.

  3. Open the file machine.config (in [Windows directory]\Microsoft.NET\Framework\[.NET version directory]\CONFIG).

  4. Add the following to the httpModules node of machine.config:

    <add name="FileUpEeModule" type="SoftArtisans.Net.FileUpEeModule, FileUpEeModule,
            Version=x.x.x.x, Culture=neutral, PublicKeyToken=f593502af6ee46ae"/>
The version attribute must correspond exactly to the version of FileUpEeModule.dll that you added to the GAC. If you add a new version of FileUpEeModule.dll to the GAC, update the version attribute in machine.config. To get the exact version of FileUpEeModule.dll, right-click the file and select the Properties tab.

Top


JFile

JFile was discontinued after the version 3 release (2004). If you are supporting a legacy application that uses JFile, samples were available in the FileUpEE documentation through the 4.0 release of the FileUpEE documentation. JFile samples can also be downloaded from the SoftArtisans Sample Code page.


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.


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 ActiveX 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 ActiveX control 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.


Client Side Solutions

SoftArtisans XFileEE

XFileEE Resumable Upload

XFileEE Resumable Download

Preserving Form Elements While Using XFileEE


Debugging

The FileUpEE Debug Log

To enable debugging for the FileUpEE object, you must set an appropriate value for DebugLevel and specify a location for the debug file by setting a value for DebugLogFile. These values can be set server-wide or at the script level.

Server-wide settings:

  • DebugLevel needs to be set as a registry setting .
  • DebugLogFile needs to be set as a registry setting .

Script level settings:

  • DebugLevel needs to be set as a property of the FileUpEE object .
  • DebugLogFile needs to be set as a property of the FileUpEE object .

Values set in the script through the FileUp EE object will take precedence over the values set in the registry.

When running the FileUpEE samples, if the web server and the file server reside on the same machine, registry settings will be applicable to both the web server and file server. To differentiate between logging comments, the log entries will have a "1" to indicate "web server" and "2" to indicate "file server".

Possible values for DebugLevel:
Values | Level of Detail
0 | No debug output.
1 | Outputs trace log that includes which methods are used.
2 | More detailed debugging.
3 | Verbose debugging. Includes dumps of headers and the SOAP envelope. It is not recommended to use this level of debugging in a production environment as it will slow the application.

The FileUpEE Error Log

To enable error logging for the FileUpEE object, you must set an appropriate value for ErrorLogDestination and specify the corresponding location for either the ErrorLogDatabase or ErrorLogFile settings. These values can be set server-wide or at the script level.

Server-wide settings:

  • ErrorLogDestination needs to be set as a registry setting.
      And optionally,
    • ErrorLogDatabase needs to be set as a registry setting if you have choosen to send error logging messages to a database.
      Or
    • ErrorLogFile needs to be set as a registry setting if you have choosen to send error logging messages to a file.

Script level settings:

  • ErrorLogDestination needs to be set as a property of the FileUpEE object.
      And optionally,
    • ErrorLogDatabase needs to be set as a property of the FileUpEE object if you have choosen to send error logging messages to a database.
      Or
    • ErrorLogFile needs to be set as a property of the FileUpEE object if you have choosen to send error logging messages to a file.

Values set in the script through the FileUp EE object will take precedence over the values set in the registry.

When running the FileUpEE samples, if the web server and the file server reside on the same machine, registry settings will be applicable to both the web server and file server.

Possible values for ErrorLogDestination:

Values | Description
1 | Errors will be logged in the file set by ErrorLogFile.
2 | Errors will be logged in a database set by ErrorLogDatabase.
4 | Errors will be logged in the Windows EventLog. To view the errors go to Start/Control Panel/Administrative Tools/Event Viewer.
8 | Errors will be logged in the system debugger. You can view the errors with tools such as Sysinternals DebugView [image] .

Tracing in .NET and the HttpModule

FileUpEE's HttpModule is compatible with page level tracing, but it is not compatible with application level tracing. The following explains how to enable page level tracing and how to disable application level tracing.

Enable Page Level Tracing

Page-level tracing is compatible with the HttpModule. For debugging during development, you can turn on tracing in the Page directive at the top of your aspx or .uplx pages:

<%@Page trace="true" ... %>

Disable Application Level Tracing

FileUpEE's HttpModule is incompatible with application-level tracing. If you are using the HttpModule, you must either remove the trace element from your web.config, or set the enabled attribute to "false".

The trace parameters are located within the system.web node of the web.config:

<system.web>
   <trace
      enabled="false"
      requestLimit="10"
      pageOutput="false"
      traceMode="SortByTime"
      localOnly="true"/>
</system.web>

If you need to enable application level tracing in ASP.NET, you must disable the HttpModule. Enabling tracing in ASP.NET causes the HttpModule to fail to receive and process the Request.

Top

Confirming your version number

There are multiple ways to confirm the version of FileUpEE that is running on your web server:

  • Use the Version property of the FileUpEE object.
  • Enable debug logging either via the registry or object model, and check the log file for the version number. To find it quickly, search your log file for the string "Version:".

I. XFileEE II. FileUpEE A. Troubleshooting notes in Confluence
B. Notes on Trace


Limiting the Upload Size

You've seen how to upload multiple files and access each of their individual properties, as well as how to read properties of the file, such as the TotalBytes of the upload.

There are several properties that can be set as well. One very useful property is MaxBytes. MaxBytes allows you to set a firm limit on the size of the uploaded file, ensuring that malicious users do not fill up your server's hard disk with huge files.

When you set the MaxBytes property, FileUp will write up to the number of bytes you specify and then stop. Any additional data will be discarded. You can set MaxBytes once and it will apply to all files in the current upload, limiting each of them to the value that you specify.

The default value of the MaxBytes property is zero (0). fileUpload.MaxBytes = 0 When MaxBytes is set to its default value of zero, there is no limit on the size of files that can be uploaded.

Set MaxBytes before referencing any form elements.

As soon as a form element is referenced, FileUp will cache the upload on the server. If you set MaxBytes after referencing a form element, by the time the MaxBytes property is set, the upload will have been cached. Note: if you set MaxBytes after referencing a form element, but before saving the uploaded files, MaxBytes will take effect when you save.

In the following example, we use the same simple form used in the first upload:

The Client Code
<html>

<head>
<title>Please Upload Your File</title>
</head>

<body>

<form enctype="multipart/form-data" method="post"
   action="formresp.asp">

Enter filename to upload:
<input type="file" id="myFile" name="myFile" /><br />

A file larger than 1000 bytes will be truncated on the server.<br />
<input type="submit" />

</form>
</body>
</html>

Here is the response file, formresp.asp:

The Server Code
<%@ language="vbscript" %>
<html>

<head>
<title>Upload File Results</title>
</head>

<body>
<%
Dim fileUpload
Set fileUpload = Server.CreateObject("SoftArtisans.FileUp")

fileUpload.Path = "C:\Temp"
fileUpload.MaxBytes = 1000

'--- Check to be sure there was a file selected in the form
'--- If so, continue processing
 If IsObject(fileUpload.Form("myFile")) Then
   If Not fileUpload.Form("myFile").IsEmpty Then

      fileUpload.Form("myFile").Save

      Response.Write "FileUp Saved the File Successfully." & "<br />
      Response.Write "Total Bytes sent by the browser: " & Request.TotalBytes & _
         " <br /> "
      Response.Write "Total Bytes Saved: " & _
         fileUpload.Form("myFile").TotalBytes & "<br />"
   Else
      Response.Write "There was no file submitted in the form field."
   End If
Else
   Response.Write "The referenced field does not exist " & _
      "or is not of type=""file"""
End If

'--- Dereference FileUp
Set fileUpload = Nothing
%>
</body>
</html>

In the upload processing script (formresp.asp), MaxBytes is set to 1000. That means that FileUp will save up to 1000 bytes of each uploaded file. If you try to upload a file larger than 1000 bytes, notice that only the first 1000 bytes would be written to the hard disk. No error will be raised, indicating that the file was truncated.

MaxBytes is Read/Write property, meaning that it is possible to both set its value and retrieve its value.

Because the MaxBytes setting truncates the file without raising an error, the server code is set up to display the number of bytes sent by the browser in comparison to the number of bytes actually saved on the server. This is a comparison between Request.TotalBytes and FileUp's TotalBytes property.

You may have noticed that the total number of bytes transmitted by you is larger than your original file's size on the client file system. This is normal, since the browser must add information such as headers and encoding information. Request.TotalBytes reports the total including the file, encoding information, and other form elements that may be present.

Summary

  • It is possible to limit the size of the upload by using the MaxBytes property.

  • The amount of information transmitted by the browser is always larger than the file alone because of additional encoding information and form elements.

  • MaxBytes does not raise an error when it truncates files.

See also, MaxBytesToCancel.

Top


Using RequestHeaders

FileUpEE will look for certain optional Request Headers, that can be added to or removed from a request using XFile.

XFile Methods
[XFRequest].AddRequestHttpHeader(HeaderName as string, HeaderArgument)
[XFRequest].RequestHTTPHeaders.Remove(HeaderName as string)
Request Headers
Header Name | X-SaWsMaxKBytesToCancel
Argument | Size in Kilobytes at which failure should occur
Usage | Dynamically set a cancel/failure point for an upload request on the web server. This is especially useful in testing your resumability code. When the httpModule or FileUpEe processes a request that contains these headers, if the uploaded data exceeds the value given, then nothing more will be written to disk and the server will return a 500 server error. (see also: Limiting the Upload Size)
Code | [XFRequest].AddRequestHttpHeader("X-SaWsMaxKBytesToCancel", KBytesToFail)

Header Name | X-SaFsMaxKBytesToCancel
Argument | Size in Kilobytes at which failure should occur
Usage | Dynamically set a cancel/failure point for an upload request on the file server. This is especially useful in testing your resumability code. When the httpModule or FileUpEe processes a request that contains these headers, if the uploaded data exceeds the value given, then nothing more will be written to disk and the server will return a 500 server error. (see also: Limiting the Upload Size)
Code | [XFRequest].AddRequestHttpHeader("X-SaFsMaxKBytesToCancel", KBytesToFail)

Top


<% Select Case Request.QueryString("lang") Case "vb" strLang = "VB.NET" Case "c#" strLang = "C#" Case Else strLang = "C#" End Select strSampRoot = Application("sampleroot") %>

FileUpEE ASP Samples Index

  • Upload Samples
  • Download Samples
Upload Samples
<% svpath = strSampRoot & "uploadsamples/basic/Simple2Tier/asp/" %> <% svpath = strSampRoot & "uploadsamples/basic/Simple3Tier/asp/" %> <% svpath = strSampRoot & "uploadsamples/basic/ThreeTierDBUpload/asp/" %> <% svpath = strSampRoot & "uploadsamples/basic/ThreeTierFileAndForm/asp/" %> <% svpath = strSampRoot & "uploadsamples/Intermediate/servertoserver/asp/" %> <% svpath = strSampRoot & "uploadsamples/basic/SaveAllInLoop/asp/" %> <% svpath = strSampRoot & "uploadsamples/intermediate/streamingupload/asp/" %> <% svpath = strSampRoot & "uploadsamples/intermediate/chunked/asp/" %> <% svpath = strSampRoot & "uploadsamples/intermediate/threetierprogress/asp/" %> <% svpath = strSampRoot & "uploadsamples/intermediate/Resume/asp/" %> <% svpath = strSampRoot & "uploadsamples/client/XFileResumeUpload/" %> <% svpath = strSampRoot & "uploadsamples/intermediate/FileUpCompat/asp/" %> <% svpath = strSampRoot & "uploadsamples/intermediate/SaveAsBinaryWebServer/asp/" %> <% svpath = strSampRoot & "uploadsamples/intermediate/SaveAsBinaryFileServer/asp/" %>
Run Sample | Code View | Description
2-Tier Upload | <%ViewSource "uploadsamples/basic/Simple2Tier/asp/Form.asp", "Form"%> <%ViewSource "uploadsamples/basic/Simple2Tier/asp/Webserver.asp", "Web server"%> | A 2-tier client to web server form-base file upload.
3-Tier Upload | <%ViewSource "uploadsamples/basic/Simple3Tier/asp/Form.asp", "Form"%> <%ViewSource "uploadsamples/basic/Simple3Tier/asp/Webserver.asp", "Web server"%> <%ViewSource "uploadsamples/basic/Simple3Tier/asp/fileserver.asp", "File server"%> | A 3-Tier upload from client to web server to file server.
3-Tier Upload to a Database | <%ViewSource "uploadsamples/basic/ThreeTierDBUpload/asp/Form.asp", "Form"%> <%ViewSource "uploadsamples/basic/ThreeTierDBUpload/asp/Webserver.asp", "Web server"%> <%ViewSource "uploadsamples/basic/ThreeTierDBUpload/asp/fileserver.asp", "File server"%> | 3-Tier upload of a file to a database.
3-Tier File & Form Upload | <%ViewSource "uploadsamples/basic/ThreeTierFileAndForm/asp/Form.asp", "Form"%> <%ViewSource "uploadsamples/basic/ThreeTierFileAndForm/asp/Webserver.asp", "Web server"%> <%ViewSource "uploadsamples/basic/ThreeTierFileAndForm/asp/fileserver.asp", "File server"%> | Demonstrates how to handle both file and text-based HTML file elements with FileUpEE.
Server to Server File Transfer | <%ViewSource "uploadsamples/Intermediate/servertoserver/asp/Form.asp", "Form"%> <%ViewSource "uploadsamples/Intermediate/servertoserver/asp/Webserver.asp", "Web server"%> <%ViewSource "uploadsamples/Intermediate/servertoserver/asp/fileserver.asp", "File server"%> | Demonstrates a transfer that is initiated on the web server instead of by an HTML client form. The file to be uploaded to the file server already exists on the web server. The file is added to the Files collection by using the AddFile method. Because there's no request from a HTML form to process, this web server script does not need to call ProcessRequest.
3-Tier Save-All-In-Loop Sample | <%ViewSource "uploadsamples/basic/SaveAllInLoop/asp/Form.asp", "Form"%> <%ViewSource "uploadsamples/basic/SaveAllInLoop/asp/Webserver.asp", "Web server"%> <%ViewSource "uploadsamples/basic/SaveAllInLoop/asp/fileserver.asp", "File server"%> | Handles file and text-based HTML elements in a loop. This sample is designed to handle a post from any form. Illustrates how to handle text element subcollections (checkboxes, multi-select boxes, etc.).
3-Tier Streaming Upload | <%ViewSource "uploadsamples/intermediate/streamingupload/asp/Form.asp", "Form"%> <%ViewSource "uploadsamples/intermediate/streamingupload/asp/Webserver.asp", "Web server"%> <%ViewSource "uploadsamples/intermediate/streamingupload/asp/fileserver.asp", "File server"%> | Demonstrates streaming the files from client to web server to file server without writing temporary files on the web server.
3-Tier Chunked Upload | <%ViewSource "uploadsamples/intermediate/chunked/asp/Form.asp", "Form"%> <%ViewSource "uploadsamples/intermediate/chunked/asp/Webserver.asp", "Web server"%> <%ViewSource "uploadsamples/intermediate/chunked/asp/fileserver.asp", "File server"%> | 3-tier upload with chunked transfer-encoding.
3-Tier Progress Indicator | <%ViewSource "uploadsamples/intermediate/threetierprogress/asp/Form.asp", "Form"%> <%ViewSource "uploadsamples/intermediate/threetierprogress/asp/Webserver.asp", "Web server"%> <%ViewSource "uploadsamples/intermediate/threetierprogress/asp/fileserver.asp", "File server"%> <%ViewSource "uploadsamples/intermediate/threetierprogress/asp/progress.asp", "Progress Indicator"%> | The server-side progress indicator lets you monitor the progress of both the client to web server and web server to file server layers.
3-Tier Resumable Upload | <%ViewSource "uploadsamples/intermediate/resume/asp/Form.asp", "Form"%> <%ViewSource "uploadsamples/intermediate/resume/asp/Webserver.asp", "Web server"%> <%ViewSource "uploadsamples/intermediate/resume/asp/fileserver.asp", "File server"%> <%ViewSource "uploadsamples/intermediate/resume/asp/resume.asp", "Resume Upload"%> <%ViewSource "uploadsamples/intermediate/resume/asp/status.asp", "Status server"%> <%ViewSource "uploadsamples/intermediate/resume/asp/listresumable.asp", "List resumable"%> | If a SOAP request from the web server to the file server should happen to fail, you can resume the upload job at a later time to complete the transfer.
XFileEE Resumable 3-Tier Upload | <%ViewSource "uploadsamples/client/XFileResumeUpload/uploadresume.html", "Form"%> <%ViewSource "uploadsamples/client/XFileResumeUpload/webserver.asp", "Web Server"%> <%ViewSource "uploadsamples/client/XFileResumeUpload/fileserver.asp", "File Server"%> <%ViewSource "uploadsamples/client/XFileResumeUpload/status.asp", "Status server"%> | A 3-Tier resumable upload with XFile.
FileUpSE Compatibility Sample | <%ViewSource "uploadsamples/intermediate/FileUpCompat/asp/Form.asp", "Form"%> <%ViewSource "uploadsamples/intermediate/FileUpCompat/asp/Webserver.asp", "Web server"%> <%ViewSource "uploadsamples/intermediate/FileUpCompat/asp/fileupresp.asp", "File server"%> | FileUpCompat mode allows you to easily turn your FileUpSE upload scripts into a FileUpEE application.
Web Server 2-Tier SaveAsBinary Sample | <%ViewSource "uploadsamples/intermediate/SaveAsBinaryWebServer/asp/Form.asp", "Form"%> <%ViewSource "uploadsamples/intermediate/SaveAsBinaryWebServer/asp/Webserver.asp", "Web server"%> | Save the RFC1867 post as a text file on the web server. This can be useful for debugging.
File Server 3-Tier SaveAsBinary Sample | <%ViewSource "uploadsamples/intermediate/SaveAsBinaryFileServer/asp/Form.asp", "Form"%> <%ViewSource "uploadsamples/intermediate/SaveAsBinaryFileServer/asp/Webserver.asp", "Web server"%> <%ViewSource "uploadsamples/intermediate/SaveAsBinaryFileServer/asp/fileserver.asp", "File server"%> | Shows how to save the web server to file server SOAP request as a flat file that you can view with any text editor.
Download Samples
<% svpath = strSampRoot & "downloadsamples/basic/TwoTierDownload/asp/" %> <% svpath = strSampRoot & "downloadsamples/basic/ThreeTierDownload/asp/" %> <% svpath = strSampRoot & "downloadsamples/basic/ThreeTierDBDownload/asp/" %> <% svpath = strSampRoot & "downloadsamples/Client/XFileResumeDownload/" %>
Run Sample | Code View | Description
2-Tier Download Sample | <%ViewSource "downloadsamples/basic/TwoTierDownload/asp/download.asp", "Web server"%> | 2-Tier download from a directory on the web server to the client.
3-Tier Download Sample | <%ViewSource "downloadsamples/basic/ThreeTierDownload/asp/download.asp", "Web server"%> <%ViewSource "downloadsamples/basic/ThreeTierDownload/asp/fileserver.asp", "File server"%> | 3-Tier download from a directory on the file server to the web server to the client.
3-Tier Download-From-Database Sample | <%ViewSource "downloadsamples/basic/ThreeTierDBDownload/asp/form.asp", "Form"%> <%ViewSource "downloadsamples/basic/ThreeTierDBDownload/asp/download.asp", "Web server"%> <%ViewSource "downloadsamples/basic/ThreeTierDBDownload/asp/fileserver.asp", "File server"%> | 3-Tier download from a database on the file server to a web server to the client.
Resumable 3-Tier Download with XFileEE | <%ViewSource "downloadsamples/Client/XFileResumeDownload/xfileresumedownload.htm", "Form"%> <%ViewSource "downloadsamples/Client/XFileResumeDownload/webserver.asp", "Web server"%> <%ViewSource "downloadsamples/Client/XFileResumeDownload/fileserver.asp", "File server"%> | 3-Tier resumable download with XFileEE on the client.

Copyright © 2010 SoftArtisans, Inc. All rights reserved.

<% Function ShowSrc(ByVal text, ByVal vpath, ByVal bColorize) Dim outString outString = "[" & text & "]" ShowSrc = outString End Function Function ShowSrcNet(ByVal text, ByVal vpath, ByVal bColorize, ByVal lang) Dim outString Dim filename Dim curpath If lang = "VB.NET" Then curpath = Left(vpath, InStrRev(vpath, "/")) filename = Mid(vpath, InStrRev(vPath, "/") + 1) filename = "vb-" & filename Else curpath = vpath filename = "" End If outString = "[" & text & "]" ShowSrcNet = outString End Function Function Ternary(byRef boolExpr, ByRef ifTrue, ByRef ifFalse) If boolExpr Then Ternary = ifTrue Else Ternary = ifFalse End If End Function %>


<% Select Case Request.QueryString("lang") Case "vb" strLang = "VB.NET" Case "c#" strLang = "C#" Case Else strLang = "C#" End Select strSampRoot = Application("sampleroot") %>

FileUpEE ASP.NET Samples Index

  • Upload Samples
  • Download Samples
Upload Samples
<% svpath = strSampRoot & "uploadsamples/basic/Simple2Tier/aspnet/vb/" %> <% svpath = strSampRoot & "uploadsamples/basic/Simple2Tier/aspnet/csharp/" %> <% svpath = strSampRoot & "uploadsamples/basic/Simple3Tier/aspnet/vb/" %> <% svpath = strSampRoot & "uploadsamples/basic/Simple3Tier/aspnet/csharp/" %> <% svpath = strSampRoot & "uploadsamples/basic/ThreeTierDBUpload/aspnet/vb/" %> <% svpath = strSampRoot & "uploadsamples/basic/ThreeTierDBUpload/aspnet/csharp/" %> <% svpath = strSampRoot & "uploadsamples/basic/ThreeTierFileAndForm/aspnet/vb/" %> <% svpath = strSampRoot & "uploadsamples/basic/ThreeTierFileAndForm/aspnet/csharp/" %> <% svpath = strSampRoot & "uploadsamples/basic/SaveAllInLoop/aspnet/vb/" %> <% svpath = strSampRoot & "uploadsamples/basic/SaveAllInLoop/aspnet/csharp/" %> <% svpath = strSampRoot & "uploadsamples/Intermediate/servertoserver/aspnet/vb/" %> <% svpath = strSampRoot & "uploadsamples/Intermediate/servertoserver/aspnet/csharp/" %> <% svpath = strSampRoot & "uploadsamples/intermediate/chunked/aspnet/vb/" %> <% svpath = strSampRoot & "uploadsamples/intermediate/chunked/aspnet/csharp/" %> <% svpath = strSampRoot & "uploadsamples/intermediate/threetierprogress/aspnet/vb/" %> <% svpath = strSampRoot & "uploadsamples/intermediate/threetierprogress/aspnet/csharp/" %> <% svpath = strSampRoot & "uploadsamples/intermediate/resume/aspnet/vb/" %> <% svpath = strSampRoot & "uploadsamples/intermediate/resume/aspnet/csharp/" %> <% svpath = strSampRoot & "uploadsamples/intermediate/SaveAsBinaryWebServer/aspnet/vb/" %> <% svpath = strSampRoot & "uploadsamples/intermediate/SaveAsBinaryWebServer/aspnet/csharp/" %> <% svpath = strSampRoot & "uploadsamples/intermediate/SaveAsBinaryFileServer/aspnet/vb/" %> <% svpath = strSampRoot & "uploadsamples/intermediate/SaveAsBinaryFileServer/aspnet/csharp/" %>
Run Sample | Code View | Description
2-Tier Upload in VB.NET | <%ViewSource "uploadsamples/basic/Simple2Tier/aspnet/vb/simple2tier.uplx", "Form"%> <%ViewSource "uploadsamples/basic/Simple2Tier/aspnet/vb/Simple2Tier.uplx.vb", "Web server"%> | A 2-tier client to web server form-base file upload.
2-Tier Upload in C# | <%ViewSource "uploadsamples/basic/Simple2Tier/aspnet/csharp/simple2tier.uplx", "Form"%> <%ViewSource "uploadsamples/basic/Simple2Tier/aspnet/csharp/Simple2Tier.uplx.cs", "Web server"%> | A 2-tier client to web server form-base file upload.
3-Tier Upload in VB.NET | <%ViewSource "uploadsamples/basic/Simple3Tier/aspnet/vb/simple3tier.uplx", "Form"%> <%ViewSource "uploadsamples/basic/Simple3Tier/aspnet/vb/Simple3Tier.uplx.vb", "Code behind: web server"%> <%ViewSource "FileSvrAutoProcess/FileSvrAutoProcess-vb.uplx", "File server"%> <%ViewSource "FileSvrAutoProcess/FileSvrAutoProcess-vb.uplx.vb", "Code behind: file server"%> | A 3-Tier upload from client to web server to file server.
3-Tier Upload in C# | <%ViewSource "uploadsamples/basic/Simple3Tier/aspnet/csharp/simple3tier.uplx", "Form"%> <%ViewSource "uploadsamples/basic/Simple3Tier/aspnet/csharp/Simple3Tier.uplx.cs", "Code behind: web server"%> <%ViewSource "FileSvrAutoProcess/FileSvrAutoProcess.uplx", "File server"%> <%ViewSource "FileSvrAutoProcess/FileSvrAutoProcess.uplx.cs", "Code behind: file server"%> | A 3-Tier upload from client to web server to file server.
3-Tier Upload to a Database in VB.NET | <%ViewSource "uploadsamples/basic/ThreeTierDBUpload/aspnet/vb/ThreeTierDBUpload.uplx", "Form"%> <%ViewSource "uploadsamples/basic/ThreeTierDBUpload/aspnet/vb/ThreeTierDBUpload.uplx.vb", "Code behind: web server"%> <%ViewSource "uploadsamples/basic/ThreeTierDBUpload/aspnet/vb/ThreeTierDBUploadFileServer.uplx", "File server"%> <%ViewSource "uploadsamples/basic/ThreeTierDBUpload/aspnet/vb/ThreeTierDBuploadFileServer.uplx.vb", "Code behind: File server"%> | 3-Tier upload of a file to a database.
3-Tier Upload to a Database in C# | <%ViewSource "uploadsamples/basic/ThreeTierDBUpload/aspnet/csharp/ThreeTierDBUpload.uplx", "Form"%> <%ViewSource "uploadsamples/basic/ThreeTierDBUpload/aspnet/csharp/ThreeTierDBUpload.uplx.cs", "Code behind: web server"%> <%ViewSource "uploadsamples/basic/ThreeTierDBUpload/aspnet/csharp/ThreeTierDBUploadFileServer.uplx", "File server"%> <%ViewSource "uploadsamples/basic/ThreeTierDBUpload/aspnet/csharp/ThreeTierDBuploadFileServer.uplx.cs", "Code behind: File server"%> | 3-Tier upload of a file to a database.
3-Tier File & Form Upload in VB.NET | <%ViewSource "uploadsamples/basic/ThreeTierFileAndForm/aspnet/vb/ThreeTierFileAndForm.uplx", "Form"%> <%ViewSource "uploadsamples/basic/ThreeTierFileAndForm/aspnet/vb/ThreeTierFileAndForm.uplx.vb", "Code behind: web server"%> <%ViewSource "FileSvrAutoProcess/FileSvrAutoProcess-vb.uplx", "File server"%> <%ViewSource "FileSvrAutoProcess/FileSvrAutoProcess-vb.uplx.vb", "Code behind: file server"%> | Demonstrates how to handle both file and text-based HTML file elements with FileUpEE.
3-Tier File & Form Upload in C# | <%ViewSource "uploadsamples/basic/ThreeTierFileAndForm/aspnet/csharp/ThreeTierFileAndForm.uplx", "Form"%> <%ViewSource "uploadsamples/basic/ThreeTierFileAndForm/aspnet/csharp/ThreeTierFileAndForm.uplx.cs", "Code behind: web server"%> <%ViewSource "FileSvrAutoProcess/FileSvrAutoProcess.uplx", "File server"%> <%ViewSource "FileSvrAutoProcess/FileSvrAutoProcess.uplx.cs", "Code behind: file server"%> | Demonstrates how to handle both file and text-based HTML file elements with FileUpEE.
3-Tier Save-All-In-Loop Sample in VB.NET | <%ViewSource "uploadsamples/basic/SaveAllInLoop/aspnet/vb/SaveAllInLoop.uplx", "Form"%> <%ViewSource "uploadsamples/basic/SaveAllInLoop/aspnet/vb/SaveAllInLoop.uplx.vb", "Code behind: web server"%> <%ViewSource "FileSvrAutoProcess/FileSvrAutoProcess-vb.uplx", "File server"%> <%ViewSource "FileSvrAutoProcess/FileSvrAutoProcess-vb.uplx.vb", "Code behind: file server"%> | Handles file and text-based HTML elements in a loop. This sample is designed to handle a post from any form. Illustrates how to handle text element subcollections (checkboxes, multi-select boxes, etc.).
3-Tier Save-All-In-Loop Sample in C# | <%ViewSource "uploadsamples/basic/SaveAllInLoop/aspnet/csharp/SaveAllInLoop.uplx", "Form"%> <%ViewSource "uploadsamples/basic/SaveAllInLoop/aspnet/csharp/SaveAllInLoop.uplx.cs", "Code behind: web server"%> <%ViewSource "FileSvrAutoProcess/FileSvrAutoProcess.uplx", "File server"%> <%ViewSource "FileSvrAutoProcess/FileSvrAutoProcess.uplx.cs", "Code behind: file server"%> | Handles file and text-based HTML elements in a loop. This sample is designed to handle a post from any form. Illustrates how to handle text element subcollections (checkboxes, multi-select boxes, etc.).
Server to Server File Transfer in VB.NET | <%ViewSource "uploadsamples/Intermediate/servertoserver/aspnet/vb/ServerToServer.aspx", "Form"%> <%ViewSource "uploadsamples/Intermediate/servertoserver/aspnet/vb/servertoserver.aspx.vb", "Code behind: web server"%> <%ViewSource "FileSvrAutoProcess/FileSvrAutoProcess-vb.uplx", "File server"%> <%ViewSource "FileSvrAutoProcess/FileSvrAutoProcess-vb.uplx.vb", "Code behind: file server"%> | Demonstrates a transfer that is initiated on the web server instead of by an HTML client form. The file to be uploaded to the file server already exists on the web server. The file is added to the Files collection by using the AddFile method. Because there's no request from a HTML form to process, this web server script does not need to call ProcessRequest.
Server to Server File Transfer in C# | <%ViewSource "uploadsamples/Intermediate/servertoserver/aspnet/csharp/ServerToServer.aspx", "Form"%> <%ViewSource "uploadsamples/Intermediate/servertoserver/aspnet/csharp/servertoserver.aspx.cs", "Code behind: web server"%> <%ViewSource "FileSvrAutoProcess/FileSvrAutoProcess.uplx", "File server"%> <%ViewSource "FileSvrAutoProcess/FileSvrAutoProcess.uplx.cs", "Code behind: file server"%> | Demonstrates a transfer that is initiated on the web server instead of by an HTML client form. The file to be uploaded to the file server already exists on the web server. The file is added to the Files collection by using the AddFile method. Because there's no request from an HTML form to process, this web server script does not need to call ProcessRequest.
3-Tier Chunked Upload in VB.NET | <%ViewSource "uploadsamples/intermediate/chunked/aspnet/vb/Chunked.uplx", "Form"%> <%ViewSource "uploadsamples/intermediate/chunked/aspnet/vb/chunked.uplx.vb", "Code behind: web server"%> <%ViewSource "FileSvrAutoProcess/FileSvrAutoProcess-vb.uplx", "File server"%> <%ViewSource "FileSvrAutoProcess/FileSvrAutoProcess-vb.uplx.vb", "Code behind: file server"%> | 3-tier upload with chunked transfer-encoding.
3-Tier Chunked Upload in C# | <%ViewSource "uploadsamples/intermediate/chunked/aspnet/csharp/Chunked.uplx", "Form"%> <%ViewSource "uploadsamples/intermediate/chunked/aspnet/csharp/chunked.uplx.cs", "Code behind: web server"%> <%ViewSource "FileSvrAutoProcess/FileSvrAutoProcess.uplx", "File server"%> <%ViewSource "FileSvrAutoProcess/FileSvrAutoProcess.uplx.cs", "Code behind: file server"%> | 3-tier upload with chunked transfer-encoding.
3-Tier Progress Indicator in VB.NET | <%ViewSource "uploadsamples/intermediate/threetierprogress/aspnet/vb/Progress3Tier.uplx", "Form"%> <%ViewSource "uploadsamples/intermediate/threetierprogress/aspnet/vb/progress3tier.uplx.vb", "Code behind: web server"%> <%ViewSource "FileSvrAutoProcess/FileSvrAutoProcess-vb.uplx", "File server"%> <%ViewSource "FileSvrAutoProcess/FileSvrAutoProcess-vb.uplx.vb", "Code behind: file server"%> <%ViewSource "uploadsamples/intermediate/threetierprogress/aspnet/vb/progressindicator.aspx", "Progress Indicator"%> <%ViewSource "uploadsamples/intermediate/threetierprogress/aspnet/vb/progressindicator.aspx.vb", "Code behind: Progress Indicator"%> | The server-side progress indicator lets you monitor the progress of both the client to web server and web server to file server layers.
3-Tier Progress Indicator in C# | <%ViewSource "uploadsamples/intermediate/threetierprogress/aspnet/csharp/Progress3Tier.uplx", "Form"%> <%ViewSource "uploadsamples/intermediate/threetierprogress/aspnet/csharp/progress3tier.uplx.cs", "Code behind: web server"%> <%ViewSource "FileSvrAutoProcess/FileSvrAutoProcess.uplx", "File server"%> <%ViewSource "FileSvrAutoProcess/FileSvrAutoProcess.uplx.cs", "Code behind: file server"%> <%ViewSource "uploadsamples/intermediate/threetierprogress/aspnet/csharp/progressindicator.aspx", "Progress Indicator"%> <%ViewSource "uploadsamples/intermediate/threetierprogress/aspnet/csharp/progressindicator.aspx.cs", "Code behind: Progress Indicator"%> | The server-side progress indicator lets you monitor the progress of both the client to web server and web server to file server layers.
3-Tier Resumable Upload in VB.NET | <%ViewSource "uploadsamples/intermediate/resume/aspnet/vb/ResumeWebServer.uplx", "Form"%> <%ViewSource "uploadsamples/intermediate/resume/aspnet/vb/resumewebserver.uplx.vb", "Code behind: web server"%> <%ViewSource "uploadsamples/intermediate/resume/aspnet/vb/ResumeFileServer.uplx", "File Server"%> <%ViewSource "uploadsamples/intermediate/resume/aspnet/vb/resumefileserver.uplx.vb", "Code behind: File server"%> | Demonstrates how to set up an application to support resumability in case of a failed transfer.
3-Tier Resumable Upload in C# | <%ViewSource "uploadsamples/intermediate/resume/aspnet/csharp/ResumeWebServer.uplx", "Form"%> <%ViewSource "uploadsamples/intermediate/resume/aspnet/csharp/resumewebserver.uplx.cs", "Code behind: web server"%> <%ViewSource "uploadsamples/intermediate/resume/aspnet/csharp/ResumeFileServer.uplx", "File Server"%> <%ViewSource "uploadsamples/intermediate/resume/aspnet/csharp/resumefileserver.uplx.cs", "Code behind: File server"%> | Demonstrates how to set up an application to support resumability in case of a failed transfer.
Web Server 2-Tier SaveAsBinary Sample in VB.NET | <%ViewSource "uploadsamples/intermediate/SaveAsBinaryWebServer/aspnet/vb/SaveAsBinaryWebSvr.uplx", "Form"%> <%ViewSource "uploadsamples/intermediate/SaveAsBinaryWebServer/aspnet/vb/SaveAsBinaryWebSvr.uplx.vb", "Code behind: web server"%> | Save the RFC1867 post as a text file on the web server. This can be useful for debugging.
Web Server 2-Tier SaveAsBinary Sample in C# | <%ViewSource "uploadsamples/intermediate/SaveAsBinaryWebServer/aspnet/csharp/SaveAsBinaryWebSvr.uplx", "Form"%> <%ViewSource "uploadsamples/intermediate/SaveAsBinaryWebServer/aspnet/csharp/SaveAsBinaryWebSvr.uplx.cs", "Code behind: web server"%> | Save the RFC1867 post as a text file on the web server. This can be useful for debugging.
File Server 3-Tier SaveAsBinary Sample in VB.NET | <%ViewSource "uploadsamples/intermediate/SaveAsBinaryFileServer/aspnet/vb/SaveBinaryFileSvrWS.uplx", "Form"%> <%ViewSource "uploadsamples/intermediate/SaveAsBinaryFileServer/aspnet/vb/SaveBinaryFileSvrWS.aspx.vb", "Code behind: web server"%> <%ViewSource "uploadsamples/intermediate/SaveAsBinaryFileServer/aspnet/vb/SaveBinaryFileSvrFS.uplx", "File server"%> <%ViewSource "uploadsamples/intermediate/SaveAsBinaryFileServer/aspnet/vb/SaveBinaryFileSvrFS.aspx.vb", "Code behind: File server"%> | Shows how to save the web server to file server SOAP request as a flat file that you can view with any text editor.
File Server 3-Tier SaveAsBinary Sample in C# | <%ViewSource "uploadsamples/intermediate/SaveAsBinaryFileServer/aspnet/csharp/SaveBinaryFileSvrWS.uplx", "Form"%> <%ViewSource "uploadsamples/intermediate/SaveAsBinaryFileServer/aspnet/csharp/SaveBinaryFileSvrWS.aspx.cs", "Code behind: web server"%> <%ViewSource "uploadsamples/intermediate/SaveAsBinaryFileServer/aspnet/csharp/SaveBinaryFileSvrFS.uplx", "File server"%> <%ViewSource "uploadsamples/intermediate/SaveAsBinaryFileServer/aspnet/csharp/SaveBinaryFileSvrFS.aspx.cs", "Code behind: File server"%> | Shows how to save the web server to file server SOAP request as a flat file that you can view with any text editor.
Download Samples
<% svpath = strSampRoot & "downloadsamples/basic/TwoTierDownload/aspnet/vb/" %> <% svpath = strSampRoot & "downloadsamples/basic/TwoTierDownload/aspnet/csharp/" %> <% svpath = strSampRoot & "downloadsamples/basic/ThreeTierDownload/aspnet/vb/" %> <% svpath = strSampRoot & "downloadsamples/basic/ThreeTierDownload/aspnet/csharp/" %> <% svpath = strSampRoot & "downloadsamples/basic/ThreeTierDBDownload/aspnet/vb/" %> <% svpath = strSampRoot & "downloadsamples/basic/ThreeTierDBDownload/aspnet/csharp/" %>
Run Sample | Code View | Description
2-Tier Download Sample in VB.NET | <%ViewSource "downloadsamples/basic/TwoTierDownload/aspnet/vb/TwoTierDownload.aspx", "Form"%> <%ViewSource "downloadsamples/basic/TwoTierDownload/aspnet/vb/TwoTierDownload.aspx.vb", "Code behind: web server"%> | 2-Tier download from a directory on the web server to the client.
2-Tier Download Sample in C# | <%ViewSource "downloadsamples/basic/TwoTierDownload/aspnet/csharp/TwoTierDownload.aspx", "Form"%> <%ViewSource "downloadsamples/basic/TwoTierDownload/aspnet/csharp/TwoTierDownload.aspx.cs", "Code behind: web server"%> | 2-Tier download from a directory on the web server to the client.
3-Tier Download Sample in VB.NET | <%ViewSource "downloadsamples/basic/ThreeTierDownload/aspnet/vb/ThreeTierDownload.aspx", "Form"%> <%ViewSource "downloadsamples/basic/ThreeTierDownload/aspnet/vb/ThreeTierDownload.aspx.vb", "Code behind: web server"%> <%ViewSource "FileSvrAutoProcess/FileSvrAutoProcess-vb.uplx", "File server"%> <%ViewSource "FileSvrAutoProcess/FileSvrAutoProcess-vb.uplx.vb", "Code behind: file server"%> | 3-Tier download from a directory on the file server to the web server to the client.
3-Tier Download Sample in C# | <%ViewSource "downloadsamples/basic/ThreeTierDownload/aspnet/csharp/ThreeTierDownload.aspx", "Form"%> <%ViewSource "downloadsamples/basic/ThreeTierDownload/aspnet/csharp/ThreeTierDownload.aspx.cs", "Code behind: web server"%> <%ViewSource "FileSvrAutoProcess/FileSvrAutoProcess.uplx", "File server"%> <%ViewSource "FileSvrAutoProcess/FileSvrAutoProcess.uplx.cs", "Code behind: file server"%> | 3-Tier download from a directory on the file server to the web server to the client.
3-Tier Download-From-Database Sample in VB.NET | <%ViewSource "downloadsamples/basic/ThreeTierDBDownload/aspnet/vb/ThreeTierDBDownload.aspx", "Form"%> <%ViewSource "downloadsamples/basic/ThreeTierDBDownload/aspnet/vb/ThreeTierDBDownload.aspx.vb", "Code behind: web server"%> <%ViewSource "downloadsamples/basic/ThreeTierDBDownload/aspnet/vb/ThreeTierDBDownloadFS.aspx", "File server"%> <%ViewSource "downloadsamples/basic/ThreeTierDBDownload/aspnet/vb/ThreeTierDBDownloadFS.aspx.vb", "Code behind: file server"%> | 3-Tier download from a database on the file server to a web server to the client.
3-Tier Download-From-Database Sample in C# | <%ViewSource "downloadsamples/basic/ThreeTierDBDownload/aspnet/csharp/ThreeTierDBDownload.aspx", "Form"%> <%ViewSource "downloadsamples/basic/ThreeTierDBDownload/aspnet/csharp/ThreeTierDBDownload.aspx.cs", "Code behind: web server"%> <%ViewSource "downloadsamples/basic/ThreeTierDBDownload/aspnet/csharp/ThreeTierDBDownloadFS.aspx", "File server"%> <%ViewSource "downloadsamples/basic/ThreeTierDBDownload/aspnet/csharp/ThreeTierDBDownloadFS.aspx.cs", "Code behind: file server"%> | 3-Tier download from a database on the file server to a web server to the client.

Copyright © 2010 SoftArtisans, Inc. All rights reserved.

<% Function ShowSrc(ByVal text, ByVal vpath, ByVal bColorize) Dim outString outString = "[" & text & "]" ShowSrc = outString End Function Function ShowSrcNet(ByVal text, ByVal vpath, ByVal bColorize, ByVal lang) Dim outString Dim filename Dim curpath If lang = "VB.NET" Then curpath = Left(vpath, InStrRev(vpath, "/")) filename = Mid(vpath, InStrRev(vPath, "/") + 1) filename = "vb-" & filename Else curpath = vpath filename = "" End If outString = "[" & text & "]" ShowSrcNet = outString End Function Function Ternary(byRef boolExpr, ByRef ifTrue, ByRef ifFalse) If boolExpr Then Ternary = ifTrue Else Ternary = ifFalse End If End Function %>


XFileEE Resumable Upload
XFileEE Documentation
You will find the complete XFileEE documentation at FileUpEE/XFile/XFile.chm, or on the SoftArtisans support site.

XFile Enterprise Edition (XFileEE) supports resumable uploading from client to web server. 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.

In a resumable upload, XFileEE stores upload data in a temporary directory on the client, before starting the upload. XFileEE's ResumeInfo.CacheRequest property 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, but caching large files can use a significant amount of disk space. If you are only going to resume the current upload, it may be better not to cache.

When using ASP 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 XFileEE Script

For complete instructions on using XFileEE, see the XFileEE documentation.

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 XFileEE's 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 from XFileEE:

  1. To load the XFResume object into your page, use:

<object classid="clsid:53B29E97-9753-44B4-AE57-D51322B2BD49" id="XFResume" >
</object>
    • Set a ResumeInfo object through the XFRequest object's ResumeInfo property, for example:
      Set XFileResumeInfo = SAXFileEE.ResumeInfo
    • Set ResumeInfo's Resumable property to true to tell XFileEE that the upload is resumable, for example:
      XFileResumeInfo.Resumable = True
    • Set ResumeInfo's StatusURL property, for example:
      XFileResumeInfo.StatusUrl = "http://localhost/xfilesamples/status.asp"
    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.

  2. 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
  3. 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.

  4. 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 VerifyChecksums property to true, for example:
    XFileResumeInfo.VerifyChecksums = True
  5. Create a message to display if the upload fails. The message should tell the user that the transfer failed and can be resumed.

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

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

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

In the sample above, 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(SAXFileEE.ResumeInfo.JobID)

Top

The FileUpEE Upload Processing Script

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. (ASP Only) 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 FileUpEE script in the sample above 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 1 kb 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) = 1
    End If
End If
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.

Top

The FileUpEE Status Script

When the user clicks the "Resume" button in the XFileEE sample above, the XFileEE's Resume method is called. To resume the upload, XFileEE sends a status request to the FileUpEE status page specified by XFileEE's ResumeInfo.StatusURL property. 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.

Top

The Upload Status Database (ASP Only)

When a resumable XFileEE to FileUpEE upload fails, FileUpEE saves information about the upload in a status database on the server. When the user clicks XFileEE's "Resume" button, 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 XFileEE, and XFileEE resumes the upload from the point at which it stopped. The upload status database FileUpEEWS.mdb is included in the FileUpEE samples directory.

There are two ways to set the connection string for an upload status database:

  • Set the ResumeConnectionString property for the specified upload database (Web server or file server).

    OR

  • Set the web server and file server connection strings in two udl files. On the web server, in WINDOWS\system32\fileupee.udl, save the web server's status database connection string. On the file server, in WINDOWS\system32\fileupee.udl, save the file server's status database connection string.

    To store a database connection string in a udl file:

    1. Go to C:\WINDOWS\system32.
    2. Right click within the system32 directory and select New -> Text Document.
    3. Name the file fileupee.udl.
    4. Double-click fileupee.udl to open it.
    5. Select the Provider tab.
    6. Select the appropriate Provider, and click Next. (If you are using the Microsoft Access files included with FileUpEE, select Microsoft Jet 4.0 OLE DB Provider).
    7. Configure the database provider. (If you are using the Microsoft Access files included with FileUpEE, browse to FileUpEEWS.mdb if you are at the web server, or FileUpEEFS.mdb if you are at the file server.)
    8. Click Test Connection.

Top


Backwards Compatibility

  • The FileUpEE ISAPI filter
  • Installing the FileUpEE ISAPI filter
  • Allowing ASP to Process Files with the .upl Extension
  • The ISAPI Filter Temp Directory
  • JFile

The FileUpEE ISAPI filter

The FileUpEE ISAPI filter was introduced in version 4 of FileUpEE as a solution for overcoming upload limitations in the ASP.NET environment. The filter was designed for use with version 5 of IIS. With the introduction of IIS 6, there was no longer support for Read_Raw_Data ISAPI level filters in the native processing model. To address this incompatibility with IIS 6 the same pre-processing functionality that was available in the ISAPI filter was made available in the FileUpEE HttpModule. The HttpModule provides the same functionality as the ISAPI filter, but is compatible with both IIS 5 and IIS 6. As such, the ISAPI filter is now considered a deprecated technology.

There are two remaining reasons to use the FileUpEE ISAPI filter in a new application, both relating to large downloads in ASP on servers running IIS 5:

  • Large uploads (over 2GB) in ASP may see a performance benefit when using the ISAPI filter.
  • Large uploads in ASP can cause problems in ASP's Request.BinaryRead method, which can throw intermittent errors.

It should be noted that both of these issues are also addressed and corrected by the FileUpEE HttpModule. For this reason, the use of the ISAPI filter with .NET file transfers has been deprecated.

If you intend to support legacy applications that use the ISAPI filter, you should be aware of the following:

  • A legacy application employing the ISAPI filter cannot be moved to an IIS 6 server, unless you are able to run that server in IIS 5 isolation mode.

  • In order to access documentation that provides instructions for use of the ISAPI filter, you will need to download version 5.0 of the FileUpEE docs.

Installing the ISAPI Filter

For security reasons, FileUpEE's automatic installation does not automatically install the ISAPI filter in IIS. To install the filter in IIS:

  1. Open IIS, right-click the machine name icon, and select Properties.

    FileUp's ISAPI filter must be installed at the machine level, not the web site or web application level.

  2. Select the Internet Information Services tab.

  3. From the Master Properties drop-down list, select WWW Service, and click Edit.

  4. Select the ISAPI Filters tab.

  5. Click Add.

  6. In the Filter Properties dialog box, enter the filter name FileUpEE, browse to FileUpEEIsapi.dll, and click Ok.

  7. Restart IIS to load the filter: right-click the machine name icon, select Restart IIS..., select Restart Internet Services from the drop-down list, and click Ok.

Top

Allowing ASP to Process Files with the .upl Extension

FileUpEE's ISAPI filter will intercept requests to files with the extension .upl. After the filter handles a request to a .upl file, the request is forwarded to ASP. To allow ASP to process files with the extension .upl, you must add a script map to IIS (for security reasons, FileUpEE's automatic installation does not add the script map automatically).

In the Windows XP IIS console, the Web Sites and Default web Site nodes have identical properties dialogs. The script maps can be installed in the Web Sites properties, but they will be ignored by IIS. The script maps must be installed from the Default web Site node.
  • Add .upl to the Default web Site's App Mappings
    1. Open IIS, right-click the Default web Site, and select Properties.

    2. Select the Home Directory tab.

    3. Click Configuration.

    4. Select the App Mappings tab.

    5. Click Add.

    6. Browse to asp.dll (typically in C:\WINNT\System32\inetsrv\).

    7. In the Extension field, enter upl.

    8. Select All Verbs.

    9. Check Script Engine, and click Ok.

    OR

  • Add .upl to the Application's App Mappings
    1. Open IIS, right-click your application's virtual directory, and select Properties.

    2. Select the Virtual Directory tab.

    3. Click Configuration.

    4. Select the App Mappings tab.

    5. Click Add.

    6. Browse to asp.dll (typically in C:\WINNT\System32\inetsrv\).

    7. In the Extension field, enter upl.

    8. Select All Verbs.

    9. Check Script Engine, and click Ok.

Top

The ISAPI Filter Temp Directory

The ISAPI filter caches request data before it is processed by ASP or ASP.NET. The location of the cache files can be configured in the Windows registry. By default, the cache location is the system's default directory for cached files, which is determined by the system environment variable TEMP. To set a different ISAPI filter temp directory:

  1. Open the Start menu, and select Run.
  2. Enter regedit and click Ok.
  3. Open HKEY_LOCAL_MACHINE\SOFTWARE\SoftArtisans\FileUpEe\Parameters.
  4. Right-click FileUpEETempDir and select Modify.
  5. In Value Data, enter the path and folder name.

The ISAPI filter temp directory must be on a local drive, not on a network shared drive. The ISAPI filter writes to the server hard drive as the local SYSTEM account and this account does not have access to network drives.

To change the system's default directory for cached files, reset the TEMP environment variable, as follows:
  • Open the Control Panel.
  • Select System .
  • Select the Advanced tab.
  • Click Environment variables...
  • Select TEMP from the System Variables list.
  • Click Edit .
  • Enter a new Variable Value, and click Ok .

Top

JFile

JFile was discontinued after the version 3 release (2004). If you are supporting a legacy application that uses JFile, samples were available in the FileUpEE documentation through the 4.0 release of the FileUpEE documentation. JFile samples can also be downloaded from the SoftArtisans Sample Code page.

Top


ISAPI Filter for ASP

The FileUpEE ISAPI filter is a deprecated interceptor that was originally built to bypass .NET restrictions on upload size. It can still be used in order to correct some issues in ASP related to large downloads, though it has been completely replaced by the HttpModule in the .NET version. SoftArtisans has deprecated the use of the ISAPI filter because it is not supported in IIS 6 and above.

The ISAPI filter is configured by editing the registry. A list of ISAPI filter registry keys can be found here.

For security reasons, FileUpeEE's automatic installation does not automatically install the ISAPI filter in IIS. To install the filter in IIS:

  1. Open IIS, right-click the machine name icon, and select Properties.

    FileUpEE's ISAPI filter must be installed at the machine level, not the web site or web application level.

  2. Select the Internet Information Services tab.

  3. From the Master Properties drop-down list, select WWW Service, and click Edit.

  4. Select the ISAPI Filters tab.

  5. Click Add.

  6. In the Filter Properties dialog box, enter the filter name FileUpEE, browse to FileUpEEIsapi.dll, and click Ok.

  7. Restart IIS to load the filter: righ-click the machine name icon, select Restart IIS..., select Restart Internet Services from the drop-down list, and click Ok.

Top


Here are some preliminary results for performance testing of HTML forms versus XFile with and without resume.

It shows XFile without resume is much faster than forms.
With resume (It needs to constantly update the file telling it how much it has uploaded) it is slightly faster than HTML forms.
With resume and local caching (It needs to make a copy of the file locally before it starts the upload) it is slightly slower.

These are with default XFile settings. I’m hopeful with some tweaking (Bufffer size, etc.. ) I will be able to increase the performance. Starting Monday I will also be testing with uploads > 4GB.

Time is in seconds.

 | HTML Form | Xfile (No Resume) | Xfile Resume (No cache) | Xfile Resume (Cache Locally)
100 MB | 31 | 19 | 28 | 33
250 MB | 73 | 44 | 75 | 82
500 MB | 151 | 87 | 143 | 166
1 GB | 300 | 173 | 280 | 343


Removing FileUpEE

Automatic Removal

If FileUpEE was installed with the automatic installer, use Add/Remove Programsto unregister and remove FileUpEE and all of its associated documentation and samples:

  1. From the Start menu, select Settings -> Control Panel.
  2. Double-click Add/Remove Programs.
  3. Select SoftArtisans FileUp Enterprise Edition.
  4. Click the Change/Remove button to remove the old copy of FileUpEE.

Manual Removal

If FileUpEE.dll, MimeClient.dll, and FileUpEEProgress.dll were manually registered with regsvr32, unregister the dlls and delete them.

To manually remove FileUpEE:

  1. Unregister the dll Files in FileUpEE/COM
    1. Open a DOS prompt window.

    2. Go to FileUpEE's COM directory.

    3. Enter regsvr32 FileUpEE.dll /u and click Ok.

    4. Enter regsvr32 MimeClient.dll /u and click Ok.

    5. Enter regsvr32 FileUpEEProgress.dll /u and click Ok.

    6. To reset IIS, enter iisreset.

  2. Remove the ASP.NET Assemblies from the Global Assembly Cache
    Note: this step is only necessary if you installed FileUpEE on the machine level.
    1. Open a DOS prompt window.

    2. Go to FileUpEE's DotNet directory.

    3. Enter gacutil.exe /u FileUpEE and click Ok.

    4. Enter gacutil.exe /u MimeClient and click Ok.

    5. Enter gacutil.exe /u FileUpEEProgress and click Ok.

    6. Delete the following lines from machine.config:
      <add assembly="FileUpEE, Version=x.x.x.x, Culture=neutral, PublicKeyToken=f593502af6ee46ae"/>
<add assembly="MimeClient, Version=x.x.x.x, Culture=neutral, PublicKeyToken=f593502af6ee46ae"/>
<add assembly="FileUpEEProgress, Version=x.x.x.x, Culture=neutral, PublicKeyToken=f593502af6ee46ae"/>
  3. Delete these files from both FileUpEE/DotNet and FileUpEE/COM:
    • FileUpEE.dll
    • MimeClient.dll
    • FileUpEEProgress.dll
    • FileUpEeIsapi.dll
    • FileUpEeErrorMsgs.dll
If you used FileUpEE in ASP.NET, you may have copies of FileUpEE.dll, MimeClient.dll, and FileUpEEProgress.dll in several bin directories. Delete all copies.


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 XFileEE to a Web server, two sets of dlls are copied to the following directory: C:\Program Files\SoftArtisans\FileUpEE\XFile. One set is wrapped in a cabinet file, SAXFileEE.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 XFileEE:

XFileEE | Description
SAXFileEE.cab | Cabinet file containing all XFileEE dlls except XFShExEE.dll.
XFileEE.dll | Non-visual file-transfer engine
XFClient.dll | HTTP client components
SAAXFileEE.dll | Visual upload and download controls
Resume.dll | Resumability components
XFShExEE.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 XFileEE 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 XFileEE 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 XFileEE 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 XFileEE 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 XFileEE. 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 XFileEE.

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:7B7929AB-E06A-4508-BE68-1CC7A6997808" id="AXFFile"
    codebase="/FileUpEESamples/XFileEEASPSamples/cab/SAXFileEE.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 XFileEE is specified. This is convenient for forcing an upgrade of internet distributed dlls. For more information on this, see Upgrading SoftArtisans XFileEE.

Solution

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

  1. If you are planning to distribute XFileEE to your users using SoftArtisans (or your own) signed CAB file, then manually unregister the XFileEE 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 XFileEE (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 XFileEE.

    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 XFileEE was not installed to compare behavior.

With either solution, it is important to understand that once XFileEE 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 XFileEE from the client each time. For instructions on removing these files from Internet Explorer see Removing SoftArtisans XFileEE.


A Simple Upload in ASP.NET (C#)

The following C# example uploads a file from a client to a web server. The application uses a web form to submit the upload from the client. SoftArtisans FileUpEE receives and processes the upload on the web server. To run the example:

  1. Click the link Run sample.

  2. Browse to select a file to upload, and click Upload.

To allow file uploads, NTFS permissions must be set appropriately for FileUpEE's temporary and destination directories. For more information, see Security Considerations.

The sample uses a web form to upload a file from the client. The web form submitting the file must contain:

  • A <form> ACTION attribute that calls the upload processing script on the server.

  • The <form> tag attribute ENCTYPE="multipart/form-data".

  • An <input type="file"> tag, including a name attribute.

On the web server, FileUpEE receives and saves the uploaded file. The FileUpEE objects are in the SoftArtisans.Net namespace. The objects can be referenced as fully qualified names, such as SoftArtisans.Net.FileUpEe. To minimize typing and errors, use an Import directive to import the namespace to the ASP.NET page. This allows you to reference objects by name alone, without the namespace prefix. If you are coding directly in the .aspx page, following the Page directive in the aspx page, include:

<%@Import namespace="SoftArtisans.Net"%>

If you are coding in the "code behind" page, include a Using statement at the top of the "code behind" page:

using SoftArtisans.Net;

In the FileUpEE code, the following lines process the upload request, and save the uploaded file:

  • FileUpEe oFileUpEE = new FileUpEe();
    Creates an instance of FileUpEE.

  • oFileUpEE.TransferStage = saTransferStage.saWebServer;
    This property tells FileUpEE the stage of the file transfer, that is, the server on which the current code should run. The transfer stage can be client, web server, or file server. The transfer stage can be set to saWebServer or saFileServer. The TransferStage property is required. Set this property immediately after creating an instance of FileUpEE.

  • oFileUpEE.ProcessRequest(Page.Request, false, false);
    The ProcessRequest method passes the Request object to FileUpEE. The collection of transferred files is not available until after ProcessRequest is called. In addition to the ASP Request object, ProcessRequest takes two boolean parameters:

    SoapRequest
    The SoapRequest parameter tells FileUpEE whether the file transfer is a SOAP request or not. Since WebServer.asp receives a form-based request, and not a SOAP request, SoapRequest is set to false.
    AutoProcess
    If the AutoProcess parameter is set to true, FileUpEE will process the Request according to the SOAP payload (the XML document tranferred with a SOAP request), and it is not required to "manually" save the files by calling FileEe.Save in the script that passes true as the AutoProcess parameter of ProcessRequest. AutoProcess can only be true if the script is processing a SOAP request. WebServer.asp is processing a form-based file upload, not a SOAP request, so AutoProcess must be false.

  • oFileUpEE.DestinationDirectory = Page.MapPath("/FileUpEE/Samples/temp");
    Sets the destination directory for the uploaded file.

  • oFile.DestinationFileName = oFile.ClientFileName;
    Sets the destination file name to the file's original name.

  • oFile.Save();
    Saves the file.

When you are finished using an instance of FileUpEE under .NET, always call FileUpEE.Dispose(). This ensures thorough cleanup of temporary files.

finally
{
    if(oFileUpEE!=null)
        oFileUpEE.Dispose();
}

Top


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


Add Method

Object: | ArchiveItemCollection
Syntax: | Add
Description: | This method adds a file to the collection of files in an archive.


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 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


ArchiveItemCollection Methods

This section contains the methods implemented by the ArchiveItemCollection object.

Add Method

Remove Method


ArchiveItemCollection Properties

This section contains the properties implemented by the ArchiveItemCollection object.

Count Property

Item Property


Remove Method

Object: | ArchiveItemCollection
Syntax: | Remove
Description: | This method removes a file from the collection of files in an archive.


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


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.


Extract Method

Object: | ArchiveItem
Syntax: | Extract
Description: | This method extracts an item from an archive.


ArchiveItem Methods

This section contains the methods implemented by the ArchiveItem object.

Extract Method

Remove Method


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 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.


ArchiveItem Properties

This section contains the properties implemented by the ArchiveItem object.

CompressedSize Property

Name Property

Path Property

UnCompressedSize Property


Remove Method

Object: | ArchiveItem
Syntax: | Remove
Description: | This method removes an item from an archive.


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 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


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


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 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


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 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.


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 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 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 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>


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() ... %>


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() ... %>


Archive Methods

This section contains the methods implemented by the Archive object.

AddFile Method
CloseArchive Method
CreateArchive Method
Extract Method
OpenArchive Method
RemoveFile Method


OpenArchive Method

Object: | Archive
Syntax: | OpenArchive ([in] filename)
Description: | This method opens an existing archive.


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 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


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


RemoveFile Method

Object: | Archive
Syntax: | RemoveFile ([in] Filename)
Description: | This method removes the specified file from an archive.


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 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 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 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 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 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


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.


Close Method

Object: | BinaryStream
Syntax: | Close ()
Description: | This method closes the currently open file.


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.


BinarySteam Methods

Close
Fill
Read
ReadAll
ReadVar
ReadVarAll
Skip
Write


BinaryStream Properties

AtEndOfStream


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 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 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 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 Method

Object: | BinaryStream
Syntax: | Skip ([in] numBytes)
Description: | This method moves the file cursor ahead the specified number of bytes.


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.


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


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 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 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 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 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 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.


Drive Methods

The Drive Object does not contain methods, only properties.


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:.


Drive Properties

All properties are read-only unless otherwise noted.

AvailableSpace
DriveLetter
DriveType
FileSystem
FreeSpace
IsReady
Path
RootFolder
SerialNumber
ShareName
TotalSize
VolumeName (Read / Write)


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 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 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 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 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.


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.


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.


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.


prog_ref_file_checksum_fmgr

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>


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.


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 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 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.


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 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 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.


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.


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


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 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 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 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>" %>


File Methods

AllowAccess
Copy
Decrypt
Delete
DenyAccess
Encrypt
Move
OpenAsBinaryStream
OpenAsTextStream
RevokeAllowance
OrderPermissions
RevokeDenial


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.


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.


Name Property

Object: | File
Syntax: | Name
Type: | String
Read/Write: | Read/Write
Description: | This property returns or sets the name of the specified file.


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 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 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.


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 Property

Object: | File
Syntax: | ParentFolder
Type: | String
Read/Write: | Read Only
Description: | This property returns the parent folder of the specified file.


Path Property

Object: | File
Syntax: | Path
Type: | String
Read/Write: | Read Only
Description: | This property returns the path for the specified file.


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.


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


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 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.


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 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 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 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


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 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 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 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 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 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 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 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.


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.


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 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 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 Method

Object: | FileManager
Syntax: | DriveExists ([in] Drivename)
Returns: | True or False
Description: | This method determines whether a specified Drive exists.


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.


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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 Method

Object: | FileManager
Syntax: | INIDeleteKey ([in] Filename, [in] Section, [in] Key)
Description: | This method deletes the specified key from the INI file.


INIDeleteSection Method

Object: | FileManager
Syntax: | INIDeleteSection ([in] Filename, [in] Section)
Description: | This method deletes the specified section from the INI file.


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 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 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 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 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 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 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.


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


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 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 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 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.


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.


FileManager Properties

CurrentUser
Drives
ProcessUser


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 Method

Object: | FileManager
Syntax: | RevertToSelf ()
Description: | RevertToSelf restores the security context prior to executing LogonUser method. Every LogonUser should have a corresponding RevertToSelf.


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


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.


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.


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.


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.


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 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.


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 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 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.


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 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.


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 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 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 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.


Folder Methods

AllowAccess
Copy
CreateBinaryFile
CreateTextFile
Delete
DenyAccess
Move
OrderPermissions
RevokeAllowance
RevokeDenial


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.


Name Property

Object: | Folder
Syntax: | Name
Type: | String
Read/Write: | Read/Write
Description: | This property returns or sets the name of the specified folder.


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.


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 Property

Object: | Folder
Syntax: | ParentFolder
Type: | String
Read/Write: | Read Only
Description: | This property returns the parent folder of the current folder.


Path Property

Object: | Folder
Syntax: | Path
Type: | String
Read/Write: | Read Only
Description: | This property returns the path for the specified folder.


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.


Folder Properties

Accessible
Attributes
DateCreated
DateLastAccessed
DateLastModified
Drive
Files
FileSystem
IsRootFolder
Name
Owner
ParentFolder
Path
Permissions
SearchWildCard
ShortName
ShortPath
Size
SubFolders
Type


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 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.


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 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 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 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 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 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.


HTTP Headers

The HttpModule and FileUpEE will recongize certain Request headers.
X-SaWsMaxKBytesToCancel | Sets the cancel value on the web server. Specifies the maximum size in kilobytes of the entire Request before the HttpModule of FileUpEE will abort the Request. Setting this key to 0 disables MaxKBytesToCancel.
X-SaFsMaxKBytesToCancel | Sets the cancel value on the file server. Specifies the maximum size in kilobytes of the entire Request before the HttpModule of FileUpEE will abort the Request. Setting this key to 0 disables MaxKBytesToCancel.

Top


The PermItem Object

The PermItem object represents a single trustee's permissions on a single securable object.

PermItem Methods

PermItem Properties


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 Property

Object: | PermItem
Syntax: | Delete
Type: | Boolean
Read/Write: | Read Only
Description: | This property indicates that the trustee can delete the file.


Execute Property

Object: | PermItem
Syntax: | Execute
Type: | Boolean
Read/Write: | Read Only
Description: | This property indicates that execute access is available.


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 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.


PermItem Methods

RemoveEntry


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 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 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 Property

Object: | PermItem
Syntax: | Permissions
Type: | Boolean
Read/Write: | Read Only
Description: | This property indicates that the trustee has rights to changes the permissions.


PermItem Properties

AccessRights
Delete
Execute
FullControl2
ListContents2
Modify2
NoAccess
Ownership
Permissions
Read
Read2
ReadExecute2
RightsType
Trustee
Write
Write2


Read Property

Object: | PermItem
Syntax: | Read
Type: | Boolean
Read/Write: | Read Only
Description: | This property indicates that read access is available.


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 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.


RemoveEntry Method

Object: | PermItem
Syntax: | RemoveEntry ()
Description: | This method removes this entry from the ACL.


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 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 Property

Object: | PermItem
Syntax: | Write
Type: | Boolean
Read/Write: | Read Only
Description: | This property indicates that write access is available.


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.


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.


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


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 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 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.


Close Method

Object: | TextStream
Syntax: | Close ()
Description: | This method closes the currently open file.


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 Property

Object: | TextStream
Syntax: | Line ()
Type: | Integer
Read/Write: | Read Only
Description: | This property returns the current line number, numbered from 1-n.


TextSteam Methods

Close
Read
ReadAll
ReadLine
Skip
SkipLine
Write
WriteBlankLines
WriteLine


TextStream Properties

AtEndOfLine
AtEndOfStream
Column
Line


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 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 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 Method

Object: | TextStream
Syntax: | Skip ([in] numBytes)
Description: | This method moves the file cursor ahead the specified number of bytes.


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 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 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 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.


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