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).
That file can be copied and used as standard ASP file (no setup).
ASPUploader has no components to be installed - perfectly portable.
2. Efficiency:
ASPUploader works fast (8MB/Sec) and uses only 64KB of memory.
3. Huge files:
ASPUploader can upload very large files (tested with 2GB files).
4. Progress bar:
ASPUploader supports progress bar for users to see upload progress.
5. HTML forms:
ASPUploader can read submitted form fields (text, checkbox, etc).
6. Security:
ASPUploader lets you restrict file extensions and upload size.
7. Flexability:
ASPUploader has properties to let you change any detail of upload.
ASPUploader can be used in either VBScript or JScript (ASP files).
8. Unlimited trial:
You can download fully-functional ASPUploader for unlimited trial:
http://www.aveora.com/Download/ASPUploader.zip
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.
I have a question. Where do I ask it?
------------------------------------
Contact us:
http://www.aveora.com/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.aveora.com/
Basics:
======
To upload files, you need HTML form with file field(s) and ASP script that
uses ASPUploader to receive the submitted form. 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. In 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, etc (see examples).
Note:
Request.Form collection cannot be used. 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 a list of UploadFile objects after
calling Upload method of ASPUploader. Each
UploadFile object represents an uploaded file.
Files collection is Dictionary object where Key is
InputName that identifies the file in HTML form,
and Value is UploadFile object (see examples).
Form Contains a list of submitted form fields after
calling Upload method of ASPUploader. Form
collection is Dictionary object where Key is
InputName, and Value is the field value (see
examples). This collection is similar to Form
collection of Request object (built-in ASP).
Properties:
Destination Sets where to save the 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) to 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 a 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 a boolean value. If true, uploaded files will
replace existing files in Destination if they have
the same filename. If false (default), a number
will be appended to the filename of uploaded file,
if such filename already exists in Destination
(e.g. MyFile001.txt, MyFile002.txt, and so on).
DeleteIncomplete Sets a boolean value. If true (default),
ASPUploader deletes files uploaded incompletely.
This happens if user cancels the upload, or you
run out of disk space, or an error occurs. If
false, incomplete files stay in Destination when
Upload method returns.
Charset Sets a character set (e.g. "iso-8859-1",
"Windows-1252", "utf-8", etc) to use when reading
field values of HTML form. Default value is
"us-ascii". See Example 6.
ID Sets integer value that uniquely identifies the
upload session. This property is needed for
progress bar only. See Example 2.
Methods:
function AddFile(InputName) Adds UploadFile object to Files collection and
returns reference to the added object. Use this
reference to modify properties of UploadFile
object (before upload) to represent the
corresponding file field in HTML form.
For example:
set MyFile1 = ASPUploader.AddFile("File1")
MyFile1.MaxSize = 1024
Use of AddFile method is optional. You only use
it in multi-file upload if you need to manually
add UploadFile object(s) in order to set different
properies (or restrictions) for individual files
before upload. For example, if you have two file
fields in the HTML form, you might want to specify
different Destination for each file, or different
file-extensions or maximum file-size allowed in
each file field. Also, you can specify a different
filename to use when saving the uploaded file.
If you do not use AddFile method, Files collection
will be automatically populated 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 method.
Use this InputName to retrieve the UploadFile
object from the Files collection afterwards if
needed. For example:
set MyFile1 = ASPUploader.Files(InputName)
See Example 3.
sub Upload Starts the upload.
class UploadFile: Objects of this class are retrieved from Files
---------------- collection of ASPUploader. Each one represents
an uploaded file with its properties.
Properties:
Name Sets or returns the file name. Set this property
before calling Upload method if you need the file
to be uploaded with a different filename. If you
do not set this property, the file will be saved
with its original filename 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 to memory (by
setting Destination = ""). You can examine and
process the file content as binary data or as text
string. Then you can save the entire file or any
part of it. See example 4.
Note: You can set the following properties before calling Upload method. If you
set a property, it will override the corresponding property of ASPUploader. 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 overwrites existing file.
DeleteIncomplete Sets whether the file will be automatically
deleted if its upload is incomplete.
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 the 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 the destination directory has suffecient security permissions for
your web server to create and write files in it. Otherwise,
"Permission denied" error occurs.
- If you are using Norton, McAfee, or another antivirus software, make sure
Script Blocking feature is disabled. Otherwise, FileSystemObject cannot
create uploaded files and hangs until your script eventually times out.
- Make sure Server.ScriptTimeout is long enough to upload large files.
Otherwise, the script times out before files get uploaded.
- If your server is using Chinese, Japanese, or Korean as default language
for non-Unicode programs, you may receive "Codepage not supported" error.
In this case, in order to test ASPUploader, go to
Start > Settings > Control Panel > Regional and Language Options,
then click Advanced and select any other language in the drop-down list.
Another solution is to set the upload destination to "" (empty string) and
then use Stream.SaveToFile to save the files to disk (see Example 4), but
this is not recommended for large files (over 100MB).
- Make sure you always use ASPUploader.Form instead of Request.Form collection
to read submitted form fields. Otherwise, "Cannot use Request.Form" or
"Cannot call BinaryRead" error occurs. This rule applies to all scripts
in the same Request/Response context, i.e. the scripts included with #include
directive and the scripts executed by your script via Server.Transfer or
Server.Execute methods.
- 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.asp 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 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 exception (error)
with relevant description that 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 to 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 response to most
browsers if you send the response before the browser has finished sending
his request. This is a known problem of http upload via browsers and it is
not connected to ASPUploader in any way. Below are technical details of this
problem.
Most web browsers do not display response from server before they have
finished sending request. File upload is a kind of request that browser
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). Internet Explorer
even tries to automatically re-submit html forms (re-upload files) over and
over if the previous submittal has been unsuccessful (due to invalid file
extension or size or another exception). This means that user may have to
wait until browser stops trying to upload files even though your script has
immediately sent the response with error message and terminated in the very
beginning of upload.
When uploading small files, this problem is hardly noticeable. But the larger
the file, the longer it takes the browser to give up uploading it. If user
tries to upload large file (with invalid extension or size), your response
may not even be displayed in browser at all because your script sends the
response and terminates while the browser is still busy and not ready to
receive and display any response. Neither client-side nor server-side
scripting can control this behavior of browsers.
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 maximum size you allow to upload before they start uploading large files.
Otherwise, users might never know the reason why they cannot upload some
files and get frustrated.
There is a work around to ensure that browser will eventually get your
response and display it to user in any case. You can use the following
code snippet:
on error resume next
ASPUploader.Upload
if Err then
do
Unused = Request.BinaryRead(4096)
loop while lenb(Unused) > 0
Response.Write "Error occurred "
Response.Write Err.Source & ": " & Err.Description
else
Response.Write "Upload successful"
end if
This code simulates receiving the request from browser till the end of
request. So browser will not panic trying to re-submit the file(s) and will
eventually display the error message.