UploadManager Object

Overview

This is the top-level object which provides the main file upload functionality.

Member List

Properties


CodePage As Long (Read/Write)

Enables translation of characters in POSTed text items and file names from the specified code page to Unicode. If the data is posted in the UTF-8 format, set this property to 65001. Other valid values include, but are not limited to, 1251 (Cyrillic), 1255 (Hebrew), 1256 (Arabic), etc.

Usage:
Upload.CodePage = 65001

Relevant Chapters: 8


DetectMacBinary As Boolean (Read/Write)

True by default. Controls whether to detect if the uploaded files are in the MacBinary format and if so extract the "data fork" from them. If set to False, files will be uploaded "as-is". Not implemented in AspUpload 3.0 or later.

Usage:
Upload.DetectMacBinary = False

Directory (Path As String, Optional SortBy, Optional Ascending) As Object (Read-only)

Returns a collection of DirItem objects representing all files and subdirectories in a directory specified by Path. In this collection, subdirectories always precede files.

Path may contain wildcard characters * and ?.

SortBy can be one of the following values: SORTBY_NAME (1, default). SORTBY_TYPE (2), SORTBY_SIZE (3), SORTBY_CREATIONTIME (4), SORTBY_LASTWRITETIME (5), and SORTBY_LASTACCESSTIME (6).

Ascending is True by default.

Usage:
<!--METADATA TYPE="TypeLib" UUID="{B4E1B2DE-151B-11D2-926A-006008123235}"-->
Set Dir = Upload.Directory("c:\path\*.*", SORTBY_SIZE)
For Each Item in Dir
...
Next

Relevant Chapters: 9


Expires As Date (Read-only)

Returns 9/9/9999 if a valid registration key is installed in the registry or specified via the RegKey property. Otherwise returns the date/time when the component expires.

Usage:
Response.Write Upload.Expires

Relevant Chapters: 1


Files As Object (Read-only)

Returns a collection of UploadedFile objects representing the uploaded files. Before this collection can be used, you must call the methods Save or SaveVirtual.

To reference an individual file object from the collection you may use a 1-based integer index, or a string corresponding to the NAME attribute of an <INPUT TYPE="FILE"> item of your upload form.

To enumerate items in the collection, you may use the For/Each statement.

Usage:
Set File = Upload.Files(1)

Set File = Upload.Files("FILE1")

For Each File in Upload.Files
...
Next

Relevant Chapters: 2


Form As Object (Read-only)

Returns a collection of FormItem objects representing the non-file form items. Before this collection can be used, you must call the methods Save or SaveVirtual.

To reference an individual form item of the collection you may use a 1-based integer index, or a string corresponding to the NAME attribute of a text item of your upload form.

To enumerate items in the collection, you may use the For/Each statement.

Usage:
Name = Upload.Form(1)

Name = Upload.Form("Name")

For Each Item in Upload.Form
   Response.Write Item.Value
Next

Relevant Chapters: 2


IgnoreNoPost As Boolean (Read/Write)

Suppresses the run-time error "Wrong Content-Type" when the Upload.Save method is called from a script invoked directly rather than via a multipart/form-data form. This property is useful if the form and its corresponding upload script are placed in the same file.

Usage:
Upload.IgnoreNoPost = True

Relevant Chapters: 2


OverwriteFiles As Boolean (Read/Write)

True by default. If set to False, AspUpload generates a unique file name by appending a numeric index in parentheses to the original file name if a file with this name already exists in the upload directory. This property affects the methods Save, SaveVirtual and File.SaveAs.

Usage:
Upload.OverwriteFiles = False

Relevant Chapters: 2


PreserveFileTime As Boolean (Read/Write)

False by default. If set to True, attempts to preserve the original Last-Modified date of the uploaded file.

This property is only applicable when using XUpload or JUpload on the client side. It has no effect when a regular HTML form is used to upload files. See the XUpload or JUpload manuals for more information.

Usage:
Upload.PreserveFileTime = False

ProgressID As String (Read/Write)

Assign this property to a Progress ID passed from the upload form when the progress bar is used.

Usage:
Upload.ProgressID = Request.QueryString("PID")

Relevant Chapters: 5


RegKey As String (Read/Write)

Specifies the registration key. If this property is not set, AspUpload attempts to read the registration key from the system registry.

Usage:
Upload.RegKey = "12345-67890-12345"

Relevant Chapters: 1


TotalBytes As Long (Read-only)

Returns the total number of bytes uploaded. Call this property only after a successful call to the Save (SaveVirtual) method. This property is useful for reporting purposes.

Usage:
Response.Write Upload.TotalBytes

TotalSeconds As Long (Read-only)

Returns the total number of seconds an upload lasted. Call this property only after a successful call to the Save (SaveVirtual) method. This property is useful for reporting purposes.

Usage:
Response.Write Upload.TotalSeconds

Version As String (Read-only)

Returns the current version of the component in the format "3.0.0.0".

Usage:
Response.Write Upload.Version

Methods


Sub CopyFile(FromPath As String, ToPath As String, Optional Overwrite)

Copies a file from FromPath to ToPath.

Overwrite is True by default. If set to False, the method will fail if the destination path exists.

Usage:

Upload.CopyFile "c:\path1\file.ext", "c:\path2\file.ext"

Sub CreateDirectory(Path As String, Optional IgnoreAlreadyExists)

Creates a new directory and the entire path of sub-directories leading to it, if necessary.

IgnoreAlreadyExists is False by default. If set to True, no error will be thrown if the directory already exists.

Usage:

Upload.CreateDirectory "c:\dir1\dir2", True

Relevant Chapters: 3


Sub CreateFile(Path As String)

Creates an empty file.

Usage:

Upload.CreateFile "c:\path\file.txt"

Relevant Chapters: 3


Sub DecryptAndSendBinary(Path As String, IncludeContentType As Boolean, ContentType As String, Key As CryptoKey, RemoveExt As Boolean, Optional Attachment, Optional FileName)

Same as SendBinary but decrypts a file before sending it to the client using the Key object creatable by the AspEncrypt component.

RemoveExt specifies whether the file extension appended by Save (with encryption enabled) should be removed from the file name in the Save As dialog. If Attachment is set to True, the Content-Disposition header will be include the keyword "attachment;" to force file downloads under IE. For more information, visit the AspEncrypt web site at www.aspencrypt.com/task_upload.html.

FileName (introduced in the AspUpload 3.0.0.2 patch) specifies a filename to appear in the Save As dialog box. If this argument is specified, it overrides the name of the file specified by Path.

Usage:

Upload.DecryptAndSendBinary "c:\dir\file.txt.xxx", True, "application/octet-stream", Key, True, True

Relevant Chapters: https:// aspencrypt.com / manual_02.html#2_6


Sub DeleteFile(Path As String)

Deletes a file specified by Path.

Usage:

Upload.DeleteFile "c:\path\file.txt"

Relevant Chapters: 9


Function FileExists(Path As String) As Boolean

Checks whether the specified file exists. Returns True if it does, False otherwise.

Usage:

If Upload.FileExists("c:\path\file.txt") Then ...

Relevant Chapters: 3


Sub FromDatabase(Connect As String, SQL As String, Path As String)

Exports a BLOB from the database table to hard drive using ODBC. Connect specified an ODBC connection string. SQL is a SELECT statement that must return one record containing a BLOB. The blob data field name must immediately follow the SELECT keyword. Path specifies the destination path. It must be a fully qualified file path, not just a directory name.

Usage:

Upload.FromDatabase "DSN=mydb;UID=sa;PWD=xxx;", "select image_blob from myimages where id = 3", "c:\path\file.txt"

Relevant Chapters: 4


Sub FromRecordset(RecorsetValue As Variant, Path As String)

Exports a BLOB from a database table using the ADO Recordset object. RecordsetValue is a recordset field containing the blob, such as rs("image_blob").Value. Path specifies the destination path. It must be a fully qualified file path, not just a directory name.

Usage:

Set rs = Server.CreateObject("adodb.recordset")
rs.Open "MYIMAGES", Connect, 2, 3
Upload.FromRecordset rs("image_blob").Value, "c:\path\file.txt"

Relevant Chapters: 4


Sub LogonUser(Domain As String, Username As String, Password As String, Optional Flags)

Impersonates the specified user account. If Domain is empty, the local computer will be used to validate the password. Use this function if your current security context does not allow you to perform an upload to a remote machine or certain other operations such as manipulating ACLs.

Flags may be set to one of the following values: LOGON_INTERACTIVE (2, default), LOGON_NETWORK (3), LOGON_BATCH (4), and LOGON_SERVICE (5). Using this optional parameter is not recommended.

Usage:

Upload.LogonUser "domain", "jsmith", "xxxxxx"

Relevant Chapters: 6


Sub MoveFile(FromPath As String, ToPath As String)

Moves a file from FromPath to ToPath. This method will fail if the destination path exists.

Usage:

Upload.MoveFile "c:\path1\file.ext", "c:\path2\file.ext"

Function OpenFile(Path As String) As Object

Useful if you want to take advantage of the UploadedFile.Binary property to save an arbitrary file to the database using ADO.

Usage:

Set File = Upload.OpenFile("c:\path1\file.ext")

Relevant Chapters: 10


Sub RegisterServer(Path As String, Optional Register)

Mimics the behavior of REGSVR32 (/u) utility. Registers (unregisters) the specified ActiveX DLL. If Register is True or omitted, the method registers the DLL, otherwise unregisters it.

Usage:

Upload.RegisterServer "c:\path1\file.dll"

Upload.RegisterServer "c:\path1\file.ocx", False

Relevant Chapters: 9, 10


Sub RemoveDirectory(Path As String)

Removes the specified directory. This method fails if the directory contains files or subdirectories.

Usage:

Upload.RemoveDirectory "c:\path"

Sub RevertToSelf()

Ends an impersonation begun by LogonUser.

Usually there is no need to call this method as IIS ends all impersonations automatically after the ASP page finishes.

Usage:

Upload.RevertToSelf

Function Save(Optional Path, Optional Key, Optional Ext) As Long

The main "workhorse" method which captures uploaded files, saves them on disk or in memory, and populates the Files and Form collections.

Path, if specified, is the destination directory where files are to be saved.

If Path is omitted, files are saved in memory. A file in memory can be accessed via the property File.Binary or saved to hard drive via the method File.SaveAs.

The Key and Ext parameters are to be used if you wish to encrypt files being uploaded. Key is a CryptoKey object creatable with the AspEncrypt component. If this parameter is specified, the files will be encrypted with this key before being saved. Ext is an optional extension which will be added to the original file name.

For more information on file encryption and decryption, visit the AspEncrypt web site.

Return value: the number of successfully uploaded files.

Count = Upload.Save ' save to memory

Count = Upload.Save("c:\upload") ' save to hard drive

Upload.Save "c:\upload" ' save to hard drive, ignore return value

Upload.Save , Key, "xxx" ' Save to memory, encrypt with Key

Upload.Save "c:\upload", Key, "xxx" ' Save to hard drive, encrypt with Key

Relevant Chapters: 2, 3, and all others.


Function SaveEncrypted(Path As String, Key As Object, Ext As String) As Long

Obsolete. Supported for backwards compatibility only. Use Save instead.

Usage:

Upload.SaveEncrypted(Path, Key, Ext)

' is equivalent to

Upload.Save(Path, Key, Ext)

Function SaveToMemory() A Long

Obsolete. Supported for backwards compatibility only. Use Save instead.

Usage:

Upload.SaveToMemory

' is equivalent to

Upload.Save

Function SaveVirtual(Optional VirtualPath, Optional Key, Optional Ext) As Long

Same as Save but expects a virtual path rather than a physical path. This method internally calls the function Server.MapPath to convert the virtual into physical path. Therefore, Upload.SaveVirtual(path) is equivalent to Upload.Save(Server.MapPath(path)).

In a Web hosting environment, the system administrator may disable the Save method so that an AspUpload user would be forced to use SaveVirtual which would confine him to his home directory and subdirectories.

Usage:

Upload.SaveVirtual "/images"

Upload.SaveVirtual "/images", Key, "xxx"

Relevant Chapters: 10


Function SaveVirtualEncrypted(Optional VirtualPath, Optional Key, Optional Ext) As Long

Obsolete. Supported for backwards compatibility only. Use SaveVirtual instead.


Sub SendBinary(Path As String, Optional IncludeContentType, Optional ContentType, Optional Attachment, Optional FileName)

Used for file downloading. Takes an arbitrary file specified by Path on the server's hard drive and sends it to the client browser.

IncludeContentType is True by default. It controls whether this method should build the Content-Type, Content-Disposition and Content-Length headers. If set to False, the headers will not be built.

ContentType specifies the value for the Content-Type header.

Attachment is False by default. If set to True, the keyword "attachment;" will be included in the Content-Disposition header to force a Save As dialog box instead of opening a file in-place in the browser.

FileName (introduced in the AspUpload 3.0.0.2 patch) specifies a filename to appear in the Save As dialog box. If this argument is specified, it overrides the name of the file specified by Path.

Usage:

Upload.SendBinary "c:\path\file.ext", True, "application/octet-stream", True

Relevant Chapters: 9


Sub SetMaxSize(MaxSize As Long, Optional Reject)

Specified the maximum allowed size of the individual files to be uploaded. Reject specifies whether files larger than MaxSize should be rejected (if set to True) or truncated (if set to False or omitted).

Usage:

Upload.SetMaxSize 150000, True

Relevant Chapters: 2


Sub ToDatabaseEx(Path As String, Connect As String, SQL As String, Optional MSAccessHeaders)

Saves an arbitrary file specified by Path to the database. See the UploadedFile.ToDatabase method for the description of parameters Connect,SQL and MSAccessHeaders.

Usage:

Upload.ToDatabaseEx "c:\path\file.txt", "DSN=mydb;", "insert into myimages(image_blob) values(?)"

Relevant Chapters: 4