Overview:
========
What is ASPUploader?
-------------------
ASPUploader is ASP script to upload files via web browsers to websites.
Why should I use it?
-------------------
1. Portability:
ASPUploader is written in pure ASP in single file (Upload.asp 20KB).
This file can be copied and used as regular ASP file (no setup).
It can be freely moved with website from one web server to another.
2. Efficiency:
ASPUploader works fast (1MB/Sec) and uses only 64KB of memory.
3. Huge files:
ASPUploader can upload tiny and huge files (tested with 2GB files).
4. Progress bar:
ASPUploader has progress bar for users to monitor upload process.
5. HTML forms:
ASPUploader can read submitted form fields (text, checkbox, etc).
6. Security:
ASPUploader lets you restrict upload size and file extensions.
7. Flexability:
ASPUploader has properties to let you change any detail of upload.
ASPUploader can be used in either VBScript or JScript (ASP).
8. Unlimited trial:
ASPUploader provides unlimited trial which is fully-functional.
How can it be that efficient?
---------------------------------
ASPUploader utilizes highly optimized QuickParsing algorithm to provide
maximum performance while minimizing usage of server resources.
How to get started?
------------------
ASPUploader comes with simple examples that show how to use it. All examples
are ready and working. You can look into their source code and modify it for
your website. Also, this manual can be useful but most developers do not even
need it because the examples are quite easy to read and understand.
I have a question. Where do I ask it?
------------------------------------
Contact us:
http://www.igra.ws/Contact/
Why should I pay for ASPUploader?
--------------------------------
To help us develop high quality scripts and to get a legal copy of ASPUploader
licensed to you.
I am already using it. How to buy?
---------------------------------
Please visit our website:
http://www.igra.ws/
Basics:
======
To upload files, you need HTML form with file field(s) and ASP script that
uses ASPUploader to receive the submitted form with file(s). Let's call it
Receive.asp.
Below is a simple example of HTML form with required attributes:
...............................................................................
...............................................................................
The form can contain multiple file fields as well as other input fields such as
textarea, checkbox, etc.
Below is a simple example of Receive.asp with required statements:
...............................................................................
<%
dim ASPUploader
set ASPUploader = GetASPUploader()
ASPUploader.Destination = "C:\Folder"
ASPUploader.Upload()
Response.Write("Text1 = " & ASPUploader.Form("Text1"))
%>
...............................................................................
In Receive.asp you do the following:
1. Include Upload.asp to use ASPUploader:
2. Get reference to ASPUploader object:
dim ASPUploader
set ASPUploader = GetASPUploader()
3. Set Destination property of ASPUploader:
ASPUploader.Destination = "C:\Folder"
Destination can also be database field or memory buffer (see examples).
4. (Optional)
Set other properties of ASPUploader such as ValidFileTypes, MaxTotalBytes,
etc. For multi-file uploads, you can set properties of each file
separately (see examples).
5. Start receiving and saving files:
ASPUploader.Upload()
6. (Optional)
Use Files collection to read properies of uploaded files such as Name, Size.
Use methods to delete, rename, move, or copy the uploaded files, if needed.
Use Form collection to read fields submitted with the HTML form, for example
Text1, FirstName, Notes, etc. (see examples).
Note:
Request.Form collection is unavailable after upload. Use ASPUploader.Form
collection instead. For example: MyVariable = ASPUploader.Form("FirstName")
Reference:
=========
function GetASPUploader() Returns an instance of ASPUploader class to use in
----------------------- your script.
class ASPUploader: Contains collections, properties, and methods to
----------------- control the upload.
Collections:
Files Contains list of UploadFile objects after calling
Upload() method of ASPUploader. Files collection
is Dictionary object where Key is InputName that
identifies the file in HTML form, Value is
UploadFile object that represents the uploaded
file (see examples).
Form Contains list of submitted form fields after
calling Upload() method of ASPUploader. Form
collection is Dictionary object where Key is
InputName, and Value is field value (see
examples). This collection is similar to Form
collection of Request object (built-in ASP).
Properties:
Destination Sets where to save uploaded files. Destination can
be one of the folowing:
- string specifying directory path e.g. "C:\Temp"
- ADO Field object to save the file(s) in database
- empty string "" which means each file to be
saved in Stream property of the corresponding
UploadFile object so that you can examine and
process file content and properties in memory
before saving it if needed.
If Destination is directory path, it can be either
physical ("C:\MyFolder"), relative
("..\MyFolder"), or virtual ("/MyFolder").
If Destination does not exist, it will be created.
ValidFileTypes Sets file extensions that users can upload.
ValidFileTypes is string of comma-delimited file
extensions, e.g. "txt,doc,jpg,gif", or empty
string "" which means no restrictions (default).
MaxTotalBytes Sets maximum total size that users can upload.
Overwrite Sets boolean value. If true, uploaded files
replace existing files in Destination if they have
the same filename. If false (default), a number is
appended to the filename of uploaded file (e.g.
MyFile001.txt, MyFile002.txt, and so on) if such
a filename already exists in Destination.
DeleteIncomplete Sets boolean value. If true (default),
ASPUploader deletes files uploaded incompletely.
This happens if user cancels the upload, if you
run out of disk space, or an error occurs.
If false, incomplete files stay in Destination
after Upload() method returns.
ID Sets integer value that uniquely identifies the
upload session. This property is needed for
progress bar only (see examples).
Methods:
function AddFile(InputName) Adds UploadFile object to Files collection and
returns reference to the added object. Use this
reference to set properties of the UploadFile
object before upload to represent the
corresponding file field in HTML form.
For example:
set MyFile1 = ASPUploader.AddFile(InputName)
MyFile1.MaxSize = 1024
Use of AddFile(InputName) method is optional.
You only use it if you need to manually add
UploadFile object and set different properies
(and restrictions) of individual files before
upload. For example, if you have two file fields
in your HTML form, you might want to specify
different Destination for each file field, or
different file-extensions or maximum file-size
allowed in each file field. Also, you can specify
different filename to use when saving the uploaded
file.
When you set a property of UploadFile object, it
overrides the same property of ASPUploader for
that file.
If you do not use AddFile(InputName) method to add
UploadFile objects to Files collection, it will be
automatically filled with UploadFile objects after
calling Upload() method.
InputName parameter is the string you have used in
HTML form to identify the file. For example, given
the HTML:
"MyFile1" is InputName to use in
AddFile(InputName) method.
Use this InputName to retrieve UploadFile object
from Files collection, if needed. For example:
set MyFile1 = ASPUploader.Files(InputName)
sub Upload() Uploads and saves all files.
class UploadFile: Objects of this class are retrieved from Files
---------------- collection of ASPUploader. Each one represents
uploaded file with its properties.
Properties:
Name Sets or returns the file name. Set this property
before calling Upload() method, if you need to
save the file with a different name. If you do
not set this property, the file is saved with its
original name which can then be read from this
property after calling Upload() method.
Note: You can read values of the following properties after calling Upload()
method.
InputName Returns the value of NAME attribute identifying
the file in HTML form. In the following example
InputName is "MyFile1":
Size Returns the file size in bytes.
ContentType Returns the file content type.
ClientPath Returns the file path on the client computer from
where the file has been uploaded.
Stream Returns ADO Stream object where the file content
is stored if the file has been saved in memory (by
setting Destination = ""). File content is stored
in text format which allows you examine and
process it as text string. Then you can save the
entire file or any part of it. Binary files can be
read from Stream and can be saved as well using
FileSystemObject (see examples).
Note: You can set the following properties before calling Upload() method.
If you set a property, it overrides the corresponding property of ASPUploader
for this UploadFile object only. For more info about each property, see
reference of ASPUploader class above.
Destination Sets the file Destination.
MaxSize Sets the maximum file size.
ValidFileTypes Sets the allowed file extensions.
Overwrite Sets whether the file is overwritten.
DeleteIncomplete Sets whether the file is automatically deleted
if an error occurs (incomplete upload).
Methods:
sub Delete() Deletes the file.
sub Rename(NewName) Renames the file.
sub Move(NewDestination) Moves the file.
sub Copy(NewDestination) Copies the file.
Note: If NewDestination parameter of Move or Copy methods ends with path
separator "\", e.g. "C:\MyFolder\", it specifies a folder in which to move or
copy the file (with its original filename). Otherwise, it specifies the path
and new name of destination file to create, e.g. "C:\MyFolder\MyFile.jpg",
allowing you to rename the file while moving or copying it. NewDestination can
be either physical ("C:\MyFile.jpg"), relative ("..\MyFile.jpg"), or virtual
("/MyFile.jpg"). If NewDestination does not exist, it will be created.
Troubleshooting:
===============
- Make sure your web server has "Write" permission to directory where
you save uploaded files. Otherwise, "Permission denied" error occurs.
- Make sure Server.ScriptTimeout is long enough to upload large files.
Otherwise, the script times out before files get uploaded.
- Make sure you always use ASPUploader.Form instead of Request.Form object
(built-in ASP). Otherwise, "Cannot use Request.Form" or
"Cannot call BinaryRead" error occurs. This also applies to ASP files that
you may have included in your script where you use ASPUploader and to ASP
files you may have used as parameters in calls to Server.Transfer() or
Server.Execute() from your script where you use ASPUploader.
- Enable error handling (on error resume next) before calling Upload() method
and check the Err object (built-in VBScript) after calling Upload() method
to see whether the upload has been successful, i.e. not canceled by user
and no errors occurred (see examples).
- Setting Destination property to empty string "" instructs ASPUploader to
store uploaded file(s) in server memory. This technique has special uses,
e.g. processing the content of uploaded file(s) in memory. This option is not
recommended for regular upload routine or for large files.
Known problems:
==============
- In certain IIS configurations, the content of progress bar window is not
updated during the upload process. The following are possible causes and
solutions:
- If your server has script debugging enabled, it is downgraded to single
thread, so Progress.asp is not executed until upload completes.
Turn off script debugging and restart IIS to test the progress bar
functionality.
- Special server configuration related to threading or sessions may be a
possible cause. Progress bar works properly in default IIS configuration
though.
- Some 3rd party components can cause IIS to operate in single thread per
session. This may prevent the progress bar from being updated as well.
In the worst case, if progress bar window is not updated from your server and
you do not have access to that server to solve the problem, you can choose to
remove progress bar at all (this will not affect upload), or you can leave the
progress bar enabled so users will see "Please wait" until upload completes.
- If user tries to upload a file with invalid file extension (see
ValidFileTypes property) or if the size of files is greater than maximum
allowed size (see MaxTotalBytes property), ASPUploader does not even begin to
receive such file(s). In this case, Upload() method immediately raises an
exception (error) with relevant description which you can catch in your
script and handle as appropriate the standard way with VBScript Err object
(see examples). Normally, you handle such errors by sending into the web
browser some kind of response detailing what is wrong and what the user
should do. For example, you could remind the user about valid file extensions
and maximum file size and then let the user retry the upload.
Unfortunately, there is a known problem with getting such a response to most
browsers for users to see. This is a known problem of http upload via
browsers and it is not connected to ASPUploader. Below are technical details
of this problem.
Most web browsers do not display response from server before they finish
sending request. File upload is a kind of request that browsers performs
against server. Browser continues sending submitted files regardless of
whether the files are being received by server. Browser does not display
any response until all files are "sent" (even to nowhere). Some browsers even
try to submit html forms (with files to be uploaded) over and over if their
previous submittal has been unsuccessful because of invalid file extension
or size. This means that user may have to wait until the browser stops trying
to upload the file(s) even though your script has immediately sent the
response with error message and terminated.
When uploading small files, this problem is hardly noticeable. But the larger
the file, the longer it takes the browser to give up sending it. If user tries
to upload a large file (with invalid extension or size), your response may not
even be displayed in browser at all because your script sends the error
message and terminates long time before the browser gives up uploading.
Neither client-side nor server-side scripting can control this behavior of
browsers.
To ensure your response eventually gets the browser and is displayed, you can
put the following line of script at the beginning of your error handler after
a call to ASPUploader.Upload():
MyVar = Request.BinaryRead(Request.TotalBytes)
This line puts the entire upload into MyVar variable and causes your script
to wait until the browser has finished "sending" bad file(s). Only then can
you call Response.Write or Response.Redirect to send your response to browser
which is ready to display the response since in has finished his send
operation. But this is not a good solution because it would waste the server
resources while your script is simulating that it is receiving files. Also,
with this solution, if bad users try to upload very large files, your server
may run out of memory. So this solution is not recommeded.
So, what should you do about this problem? The answer is nothing. Just keep in
mind that users may not get your error message if an error occurs during
upload. So it is a good idea to make sure users know the valid file types and
the maximum size you allow to upload before they start uploading large files.
Otherwise, some users might never know the reason why they cannot upload some
files.