newObjects.composite.UploadHelper

The class is implemented as an ASP object. I.e. it supports OnStartPage and OnEndPage methods that allow the object to directly access the ASP page's context and fetch the uploaded data while the object is created.

Post - collection that contains all the fields from the upload form with their values and additional information that allows the application to determine the content of the field. 

object.Post.Count - returns the number of the fields in the upload.

object(index) - returns the field addressed by the index parameter. The index can be numeric value between 1 and object.Post.Count or a field name. Each field may contain 1 or more values:

object(index).Count - returns the number of the values for the field. A field may contain more than one value if the form that has been submitted contains several user input elements sharing the same name (this behavior is the same like in Request(index).Count)

Each value is further described by several attributes:

object(index)(N) addresses a single value, N is the value number - most often it will be 1 if the form contains no repeated field names. The value attributes are addressed as follows:

object(index)(N)("Value") - the value data. Its type can be determined by inspecting the IsFile attribute. The file fields contain binary data, the non-file fields contain text.

object(index)(N)("IsFile") - True if the field contains an uploaded file and False otherwise

object(index)(N)("ContentLength") - The size of the value in the uploaded data in bytes.

object(index)(N)("ContentType") - The content type of the value. This is text/plain for non-file fields and may vary depending on the browser and user's system configuration for file fields.

Non-file fields:

object(index)(N)("Name") - the name of the field. This is the same as the index and is rarely useful

File fields:

object(index)(N)("RawFileName") - The file name as specified in the uploaded data. Depending on the browser it may contain full path name or just a file name. Do not use this attribute for something important because the different browsers will send different information.

object(index)(N)("FileName") - The file name (only) of the uploaded file. This value is always the file name no matter what the browser sends through the upload. 

object(index)(N)("FileNameExtension") -  The file name extension of the uploaded file. This is often used to determine the content of the file.

Close - Closes the object and frees the in-memory buffers. It is a good practice to call it once you have completed the work with the object.

Usage example:

    Set upl = Server.CreateObject("newObjects.composite.UploadHelper")
    If upl.Post.Count > 0 Then
        If upl.Post("MyFile").Count > 0 Then
            Set F = upl.Post("MyFile")(1)
            Set dir = sf.OpenDirectory(Server.MapPath("."))
            Set target = dir.CreateStream(F("FileName"))
            target.WriteBin F("Value")
            Set target = Nothing ' close the file
        End IF
    End If 

The sample code above checks if the field "MyFile" in the uploaded data actually contains data and if so saves it to a file in the same directory where the page that contains this code resides. The file name is obtained from the upload.

To support ASP environments not supporting ASP objects the class exposes 2 methods that are not needed in ALP or IIS:

InitFromData(binData) - initializes the object from binary data block containing multipart/form-data. This method can be used to process previously saved unprocessed upload data.

Init(req) - Initializes the object from the Request object: It is also used internally - OnStartPage calls it.

object.Init Request

Comments

The object implementation uses a memory stream. However it is a matter of a couple of lines to modify the object to use temporary file for upload buffer. If you are going to use this object on a WEB site that is expected to receive big number of concurrent user uploads it is recommended to make such a change in order to minimize the memory consumption. To apply such change see the Init method's implementation and replace the:

Set postStream = sf.CreateMemoryStream

with code that opens a file with a temporary name. Also add code in the OnEndPage to delete the used file.

If the number of the concurrent uploads and their size is relatively small it is better to leave the object in its present form. You can estimate the memory consumption by multiplying the expected number of concurrent uploads by their average size. If that value is about 50MB for example and you are sure that 100MB of RAM will be always available on your server this will give you better performance than temporary files used as buffers. It is also possible to implement something smarter - for instance by adding a few lines of code you can maintain an Application variable that counts the concurrent uploads and you can use memory streams as long as this number is under a certain limit acceptable for your server and create temporary files whenever it grows over the limit.