A Resumable Upload

• Resumable Uploading
• The Upload Status Databases
• Example: A Resumable Upload

Resumable Uploading

FileUpEE's Resume feature uses a database at all stages of the upload to persist information about the file transfer. For this reason the FileUpEe.ResumeConnectionString and FileUpEe.Resumable properties must be set on all stages of the upload. Also, FileUpEe must know that the transfer is resumable before reading the HTTP request, so make sure that these properties are set before calling FileUpEe.ProcessRequest.

For example, if you want an transfer between your Web server and file server to be resumable, the following code should be in you web server ASP page:

Dim oFileUpEe
Set oFileUpEe = Server.CreateObject("SoftArtisans.FileUpEe")

'--- Turn on resumability and set connection string.
oFileUpEe.Resumable(saWebServer) = true
oFileUp.ResumeConnectionString(saWebServer) = "Provider=SQLOLEDB.1;Persist Security Info=False;" &_
		"User ID=sa;Initial Catalog=FileUpEe;Data Source=C:\data\fileupeews.mdb"
oFileUpEe.Resumable(saFileServer) = true
oFileUpEe.ResumeConnectionString(saFileServer) = "Provider=Microsoft.Jet.OLEDB.4.0;" &_
		"Data Source=C:\data\fileupeefs.mdb;Persist Security Info=False"

Remember: Because FileUpEe automatically propagates its object model to all stages of a file transfer, you can set the file server resume properties on either the web server or the file server.

When a file transfer is resumed, FileUpEE needs to communicate with an ASP/ASP.NET page on your file server to determine the status of the transfer. The URL of this page is set on the Web server through the FileUpEe.StatusUrl property.

The status url page on the file server should call FileUpEE's ReturnStatus method. It can be a dedicated Web page or the same page as you post to during a typical file upload. This page will look up the status of the file transfer in the database, so be sure that FileUpEe's ResumeConnectionString property is set. A dedicated page would look like this:

Dim oFileUpEe
Set oFileUpEe = Server.CreateObject("SoftArtisans.FileUpEe")
oFileUpEe.ResumeConnectionString(saFileServer) = "Provider=Microsoft.Jet.OLEDB.4.0;" &_ 
		"Data Source=C:\data\fileupeefs.mdb;Persist Security Info=False"
oFileUpEe.ReturnStatus request, response

A page that is both a file server target url and a status url would need to call ReturnStatus if the HTTP request is a HEAD request:

Dim oFileUpEe
Set oFileUpEe = Server.CreateObject("SoftArtisans.FileUpEe")
oFileUpEe.ResumeConnectionString(saFileServer) = "Provider=Microsoft.Jet.OLEDB.4.0;" &_
		"Data Source=C:\data\fileupeefs.mdb;Persist Security Info=False"

if Request.ServerVariables("REQUEST_METHOD") = "HEAD" then
	oFileUpEe.ReturnStatus request, response
	response.end
else
	oFileUpEe.Resumable(saFileServer) = true
	oFileUpEe.ProcessRequest Request, true, true
	oFileUpEe.SendResponse response
end if

If you should need to resume this upload, call FileUpEe.Resume passing the JobId of the failed upload as a parameter. The page that initiates the resumed upload must have the ResumeConnectionString and StatusUrl set. The code below, uses a query string to send the JobId from the client:

Dim oFileUpEe
set oFileUpEe = server.createobject("SoftArtisans.FileUpEe")

oFileUp.ResumeConnectionString(saWebServer) = "Provider=SQLOLEDB.1;Persist Security Info=False;" &_
		"User ID=sa;Initial Catalog=FileUpEe;Data Source=C:\data\fileupeews.mdb"
enumRetVal = oFileUp.Resume(Request.QueryString("JobId"))

You can determine which uploads are incomplete by querying the FileUpEe database for any uploads whose 'State' is not '0'('saTransferComplete').

FileUpEE does not support resumable uploads from client to Web server. This would require a smart client that can maintain state and retrieve upload status information.

Top

The Upload Status Databases

In a resumable upload, FileUpEE saves information about the upload in two upload status databases, one on the Web server and one on the file server. If the upload from Web server to file server is suspended, and the Resume method is called, FileUpEE will get the status of the upload - the number of bytes uploaded to the file server - from the file server database. FileUpEE will then resume the upload from the point at which it stopped.

There are two ways to set the connection string for an upload status database:

• Set the ResumeConnectionString property for the specified upload database (Web server or file server).
  
  OR



• Set the Web server and file server connection strings in two udl files. On the Web server, in WINNT\system32\fileupee.udl, save the Web server's status database connection string. On the file server, in WINNT\system32\fileupee.udl, save the file server's status database connection string.
  
  To store a database connection string in a udl file:
  
  
  1. Go to C:\WINNT\system32.
  2. Right click within the system32 directory and select New -> Text Document.
  3. Name the file fileupee.udl.
  4. Double-click fileupee.udl to open it.
  5. Select the Provider tab.
  6. Select Microsoft Jet 4.0 OLE DB Provider, and click Next.
  7. Browse to FileUpEEWS.mdb if you are at the Web server, or FileUpEEFS.mdb if you are at the file server.
  8. Click Test Connection.

* NOTE: The internet user account must have write access the directory where the databases are held. For this samples, that directory is 'FileUpEE\doc-samples\samples\features\resume'. Please make sure that the IUSR_MACHINENAME account has Read, Write, and Delete access to this directory. For security reasons the FileUpEE install package does not grant this access.

Top

Example: A Resumable Upload

A 100K size limit has been set on upload samples.

In the previous example there are separate status url and file server target url scripts. This example uses a page that is both a file server target url and a status url (StatFileServer.asp). Note that the asp scripts in this example use the include file include.inc.asp.

Important: The example saves the upload to the folder FileUpEE\doc-samples\samples\temp. The IUSR_MACHINENAME or authenticated user account must have Read, Write, and Modify access to this folder.

The resumable upload example includes:

• Form.asp
  The upload form.



• WebServer.asp
  The Web server script. Webserver.asp includes all server-side upload processing instructions. If the upload fails, WebServer.asp will display a link to ListResumable.asp.



• ListResumable.asp
  Displays all suspended uploads with "Resume" links for each. If the user clicks Resume, FileUpEE will continue the specified upload at the point at which it stopped.



• Resume.asp
  Resumes a suspended upload.



• StatFileServer.asp
  The file and status server script. If an upload fails, the Resume method will get the status from this page. If the upload completes as expected (without stopping), this page saves the upload on the file server.

Form.asp

Form.asp contains the upload form. The form includes a file <input> field, and a radio <input> field that allows the user to force an upload failure. If you select Yes, the MaxKBytesToCancel(saFileServer) property will be set to 1 KB (in WebServer.asp) and uploads that are larger than 1 KB will fail.

WebServer.asp

WebServer.asp runs on the Web server. It includes all upload processing information: the save method (directory or database), save location, etc. WebServer.asp sends the upload request to the file server script set by the TargetURL property. The request to the file server is a SOAP message (an XML file).

When Resumable is set to True, FileUpEE will be able to resume a server-to-server upload that was suspended because of a network connection failure, or because the upload size was greater than MaxKBytesToCancel. Resumable is set to False by default. Resumable takes the parameter SATransferStage which specifies the stage of the upload - client -> Web server or Web server -> file server. In the Web server script, before calling ProcessRequest, to enable resumable server-to-server uploads, you must set:

	objFileUpEE.Resumable(saWebServer) = True

A resumable upload application uses two status databases, one on the Web server and one on the file server. In WebServer.asp, ResumeConnectionString(saWebServer) sets the connection string for the upload status database on the Web server. Set ResumeConnectionString before calling ProcessRequest:

	oFileUpEE.ResumeConnectionString(saWebServer) ="Provider=Microsoft.Jet.OLEDB.4.0;" & _
		"Persist Security Info=False;Data Source=" & _ 
		Server.MapPath("./FileUpEEWS.mdb")

If the upload from Web server to file server is suspended, and the user clicks the Resume link, the resume-upload script (Resume.asp) will be called. When the Resume method is called (within Resume.asp), a request will be made to the status server script. The response will tell FileUpEE the point at which the upload was suspended. StatusUrl specifies the URL of the status server script. You can set StatusUrl in the Web server script, before calling SendRequest, or in the resume-upload script, before calling Resume. Note that in this example StatFileServer.asp is both the status and file server page.

	'--- Set the URL to the file server script.
	'--- getTargetURL() is a function used in these samples
	'--- to get the virtual path to the current directory.
	'--- Find the source for this function in the include file 
	'--- include.inc.asp.
	oFileUpEE.TargetURL = getTargetURL(False) & "/statfileserver.asp"
	
	'--- For resumable uploads, set the StatusURL.
	'--- In this sample, the TargetURL and StatusURL are the same. 
	oFileUpEE.StatusURL = getTargetURL(False) & "/statfileserver.asp"

FileUpEE will abort a file upload when the size of the transfer reaches the value of MaxKBytesToCancel. In WebServer.asp MaxKBytesToCancel(saFileServer) is set to 1. Upload a file that is larger than 1 KB to run a resumable upload. To allow the upload to be resumed, MaxKBytesToCancel(saFileServer) will be reset to a higher value in Resume.asp.

If the upload stops before it is complete, ListResumable.asp is called. This page displays all suspended uploads and a Resume link for each.

	If eSAResult <> saAllProcessed Then
	Response.Write("<P ALIGN=center><B>Error!</B> Your upload has failed.")
	Response.Write("Click <a href=""listresumable.asp"">here</a> to see if the_ 
		transfer is resumable.</P>")
	End If

ListResumable.asp

If the upload stops, ListResumable.asp displays a table of all suspended uploads, with a Resume link for each upload. Clicking Resume submits a request to Resume.asp with the specified upload's JobId in the query string.

Resume.asp

Before resuming the upload, MaxKBytesToCancel(saFileServer) is reset to a value that will allow the upload to complete:

	oFileUpEE.MaxKBytesToCancel(saFileServer) = 999

The Resume method takes an upload's JobId and uses it to get the suspended upload's status from the database. Resume requests the status from StatFileServer.asp (the status URL). The ReturnStatus method in StatFileServer.asp returns the uploads status to the Resume method, and Resume then continues the upload from the point at which it stopped.

	eSAResult = oFileUpEE.Resume(guidJobID)

StatFileServer.asp

StatFileServer.asp is on the file server. It is both a status server page and a file server page. If a suspended upload is resumed, this page will get the upload status from the status database on the file server, and Resume.asp will resume the upload. When an upload completes as expected (that is, when resuming is not necessary), StatFileServer.asp executes the instructions that were set in WebServer.asp, and saves the upload on the file server.

To allow FileUpEE to resume a suspended upload, objFileUpEE.Resumable(saFileServer) must be set to True, before ProcessRequest is called on the file server:

	oFileUpEE.Resumable(saFileServer) = True

To get the upload status on the file server (the number of bytes received), set ResumeConnectionString(saFileServer):

	oFileUpEE.ResumeConnectionString(saFileServer) = "Provider=Microsoft.Jet.OLEDB.4.0;" & _
		"Persist Security Info=False;Data Source=" & _ 
		Server.MapPath("./FileUpEEFS.mdb")

StatFileServer.asp functions either as the upload processing script on the file server, or the status script for a suspended upload. If the request to StatFileServer.asp is a HEAD request, it is a status request, and ReturnStatus will return the upload status (the number of bytes received) to Resume.asp on the Web server.

	If Request.ServerVariables("REQUEST_METHOD") = "HEAD" Then
		oFileUpEE.ReturnStatus Request, Response
		
		'--- Stop script processing, we're done for now
		Response.End

If the request to StatFileServer.asp is not a HEAD request, this page functions as a standard file server upload processing page. Since AutoProcess (the third parameter of ProcessRequest is set to True, StatFileServer.asp will automatically execute the upload instructions set in WebServer.asp.

	Else
		oFileUpEE.ProcessRequest Request, True, True
		oFileUpEE.SendResponse Response
	End If

Top

Copyright © 2003, SoftArtisans, Inc.