The File.Transfer Post object represents a multipart/form-data post from an HTML form. It is functionally similar to the Request Object. Because of this similarity, you can not mix code that accesses the Form collection of the Request object with code that accesses the FormInputs collection of the Post object within the same request. If you are modifying an existing application to use File.Transfer, be sure to always use the FormInputs collection to get at any of the form data, even non-file data, when you are mixing both file and non-file data on the same form.

Properties         CheckMacBinary, CodePage, Directory, MaxFileSize, MaxTotalFileSize

Methods             Flush, Upload

Collections

FormInputs

A collection of FormInput objects representing each of the INPUT elements in the HTML FORM element. This collection is the default property of the Post object.

Notes: FormInputs is the default property of the Post object representing a collection of all of the data supplied in the upload request. The FormInputs collection can be accessed in different ways:

• Using a For Each loop:
   For Each Input In Post.FormInputs
             :
   Next
  
• Indexing the collection by position:
   sValue = Post.FormInputs(1).Value
  
• Indexing the collection by the INPUT element name:
   Set UploadFile = Post.FormInputs("UploadFile").File
  
• Indexing the collection but not specifying FormInputs since it is the default property
   sValue = Post(1)
   Set UploadFile = Post("UploadFile").File

Warning

The Post.Upload method must be called before referencing the FormInputs collection.

Example: The following example shows how to iterate the collection in reverse order:

Classic  ASP ' Code showing initialization of the Post object omitted For I = Post.FormInputs.Count To 1 Step -1     Response.Write Post.FormInputs(I).Name & " = " & Post.FormInputs(I).Value & "<BR>" Next

VB.NET ' Code showing initialization of the Post object omitted For I = Post.FormInputs.Count To 1 Step -1     Response.Write Post.FormInputs(I).Name & " = " & Post.FormInputs(I).Value & "<BR>" Next

C# ' Code showing initialization of the Post object omitted for (int I=Post.FormInputs.Count(); i< Step; i--) { Post.FormInputs(I).Name + '=' + Post.FormInputs(I).Value + '<BR>' }

See Also: FormInput object, Post.Upload method

CheckMacBinary

A boolean indicating whether to check for MacBinary files.

Access: Read/Write
Default: True

Notes: Internet Explorer for the Macintosh encodes some files in MacBinary format.  This causes files to appear to be "corrupt" because they contain the MacBinary header, the data fork and the resource fork.  The default is to only write the data fork to the upload file so that the file can be used by other applications.  If you do need to preserve the MacBinary format you should specify False.  You may want to still extract only the data fork using the Archive object.

Example: The following example shows how to set the CheckMacBinary property:

Post.CheckMacBinary = False

See Also: Archive object

CodePage

Long value that specifies the client side code page.  Setting this preserves the code page for form values and file names processed by the Post object.

Access: Read/Write
Default: 0 (Server Code Page)

Example: The following example shows how to set the code page.

Set Post = Server.CreateObject("File.Transfer.Post")
Post.CodePage = Session.CodePage

Directory

A Directory object that will be used to hold all attached files associated with the post object.

Access: Read/Write
Default: None

Notes: This property is automatically initialized using the Path parameter of the Upload method. However, if you do not call Upload with a Path parameter before accessing the FormInputs collection, the Directory property must be set to a valid Directory object that references an existing directory. The directory does not need to be URL accessible through a virtual directory mapping.

Example: The following example shows how to initialize the Directory property:

Set Dir = Server.CreateObject("File.Transfer.Directory")
Set Post = Server.CreateObject("File.Transfer.Post")
Dir.CreateTemp "C:\TEMP"
Set Post.Directory = Dir

See Also: Directory object, Post.Upload method

MaxFileSize

Long value restricting the size in bytes of any one attached file.  An error occurs if this value is exceeded.  Setting this value to a negative number allows unlimited size.

Access: Read/Write
Default: -1 (unlimited)

Notes: This property is useful for limiting how large of a file a client can upload to the system in order to prevent overuse of disk resources. If you are uploading multiple files, refer to the MaxTotalFileSize property for information on how to set a combined limit for all of the files.

Example: The following example shows how to limit the size of an uploaded file to 100000 bytes.

Set Post = Server.CreateObject("File.Transfer.Post")
Post.MaxFileSize = 100000

See Also: Post.MaxTotalFileSize property

MaxTotalFileSize

Long value restricting the total size in bytes of all attached files.  An error occurs if this value is exceeded.  Setting this value to a negative number allows unlimited size.

Access: Read/Write
Default: -1 (unlimited)

Notes: This property is useful for limiting how much file data a client can upload to the system in a single request in order to prevent overuse of disk resources. You can also limit the size of a single file through use of the MaxFileSize property.

Example: The following example shows how to limit the combined size of all uploaded files to one million bytes.

Set Post = Server.CreateObject("File.Transfer.Post")
Post.MaxTotalFileSize = 1000000

See Also: Post.MaxFileSize property

Methods

Flush

Flush

The Flush method can be used to flush the request stream.  Some browsers (for example, Netscape Communicator 4.5) will return a server error if a response is sent before the request stream is completely read.  You can call the Flush method as many times as you wish.

The Post.Flush method will read in the entire request stream.  If the client is running over a slow connection this may take some time.

Example: The following example shows how to trap an error and return it to browsers that require the request stream to be flushed:

Set Post = Server.CreateObject("File.Transfer.Post")
Post.MaxTotalFileSize = 1000000
On Error Resume Next
Post.Upload "incoming"
If Err.Number <> 0 Then
   ErrNumber = Err.Number
   ErrDescription = Err.Description
   Post.Flush
   Response.Write "<HTML><BODY>Error " & ErrNumber & ": " & ErrDescription & "</BODY></HTML>"
   Response.End
End If
On Error Goto 0

Upload

Upload {Path}{, UploadStyle}{, CheckMacBinary}

Perform upload processing

Parameter	Description
Path	Optional String containing the path or folder name
UploadStyle	Optional Number representing how file names for uploaded files are resolved
CheckMacBinary	Option Boolean representing whether to convert MacBinary files

Returns: Nothing
Notes: The Upload method is useful for controlling how and where files from an upload request are created. This method must be called prior to referencing the FormInputs collection. Furthermore, the Path parameter is only optional if you initialize the Directory property prior to calling Upload.

The UploadStyle parameter is useful for controlling how file names are resolved. Valid UploadStyle constants and values are described below.

UploadStyle Constant	Value	Description
AF_UPLOAD_USETEMP	0	Unique temporary file names are generated that match the pattern ~wf*.tmp.   This is the default behavior if you reference the FormInputs collection without first calling Upload. It is provided for compatibility with earlier releases of File.Transfer.
AF_UPLOAD_OVERWRITE	1	File names are derived from the original client path by parsing out the directory information. If a file already exists in the upload directory with the same name, it is overwritten.
AF_UPLOAD_MAKEVERSIONS  (default)	2	File names are derived from the original client path by parsing out the directory information. If a file already exists in the upload directory with the same name, it is not overwritten. Instead, a unique file name is generated by appending a version number to the base name of the file. These names match the pattern base(*).ext.
AF_UPLOAD_ERRORIFEXISTS	3	File names are derived from the original client path by parsing out the directory information. If a file already exists in the upload directory with the same name, an error is returned.
AF_UPLOAD_INMEMORY	4	Use memory instead of placing upload temp file on server hard drive.

The CheckMacBinary parameter is useful for controlling how to deal with MacBinary files.  Internet Explorer for the Macintosh encodes some files in MacBinary format.  This causes files to appear to be "corrupt" because they contain the MacBinary header, the data fork and the resource fork.  The default is to only write the data fork to the upload file so that the file can be used by other applications.

Example: The following example shows how to upload files into the relative virtual path, "incoming":

Set Post = Server.CreateObject("File.Transfer.Post")
Post.Upload "incoming"

See Also: Post.FormInputs collection