File Property Discovery For Better Asset Management

 The FutureWare Web Library's FileUpload component is a server-side object that accepts a file upload from a web browser for selected file types, and then saving them to the server's file system. For uploaded image files (i.e., BMP, JPG, GIF and PNG) the object can abstract certain image properties (e.g., height and width in pixels) for subsequent processing. For JPG files, the object can additionally abstract the COMMENT and the 16 application-specific descriptions (i.e., the APPnn markers) that can be imbedded within the binary image stream. The object does not allow any modification to any uploaded file.

Server Operating Requirements

 The FileUpload object's operating environment is any Windows NT/2K server. It is included in this FutureWare product distribution as a class object for Microsoft's Active Server Pages that is added as a class to the server's Registry as an installed DLL, and is being used successfully with Microsoft's Internet Information Server, O'Reilly's WebSitePro server, and Omnicron Technologies' OHTTPD server, and can be used with Chili!Soft's ASP products that operate under Windows NT/2K Servers.

It is also available as a Delphi DCU (included in this FutureWare product distribution) that can be included in any project that uses the TWebBroker object, by including the object's DCU in the invoking Object Pascal source file interface uses section.

In addition to web browser uploads of image files, it can also handle Microsoft's Word and Excel documents, text and HTML files.

Fileupload Object's Typical Usage

File uploads are submitted within an HTML form, using the "FILE" input type. An example of such a form is contained in the "fwlfileuploaddemo.html" page, which would be filled out by a user at a browser that complies with the HTML 3.2 specification.
The server processes the form and abstracts the uploaded file, along with other form data, by using the following general steps:

1. Create the FileUpload object
2. Call the object's "AnalyzeContent" method
3. Access and manipulate the object properties as required
4. Call the object's "SaveFileUpload" method
5. Release the object

Examples of how to use the FileUpload object are included in this FutureWare product distribution, and described in several following sections.

Restricting File Type Submittals At The Client

File submittals from a browser client can be restricted to specific file types by a javascript function invoked on the form's OnSubmit event, which is described in the included reference document and included in the demo HTML pages.

Accessing Form Data

Most servers have a read-forward-only mode of retrieving form data, such as name-value pairs. To avoid possible loss, form data should not be accessed directly from the server's request object, but instead accessed through the FWLFileUpload object's several form properties after the object has been created and the "AnalyzeContent" method has been invoked.

Form Design Requirements

An example of a form that invokes the FWL FileUpload object is contained in the "fwlfileuploaddemo.html" page, which has to have the form's ACTION value set to the appropriate web server target (ASP or DLL as noted). Additionally, the following declaration must be included in the FORM's attributes section: ENCTYPE="multipart/form-data". If this declaration is missing then the error message "3: No Content" will occur as noted in the "sErrorMessage" property described below.

ASP Script Example

The ASP script "fwlfu_asp_demo.asp" gives an example of how the FWL FileUpload object can be used in an interpreted ASP environment. This ASP script can be invoked from the "fwlfu_asp_demo.html" page by replacing the 'asp_demo_path_here' placeholder with the server path to the folder containing the "fwlfu_asp_demo.asp" script.

ISAPI/NSAPI Example

The Delphi project "FWLFU_DelphiDemo.dpr" gives an example of how the FWL FileUpload object can be used in an ISAPI/NSAPI environment. The "uFWLFU_DelphiDemo.pas" source file contains the Object Delphi code as a sample of how to use the Delphi version of the FileUpload object. This dll can be invoked from the "fwlfu_delphi_demo.html" page by replacing the 'delphi_demo_path_here' placeholder with the server path to the folder containing the "FWLFU_DelphiDemo.dll" file.

Properties

The FWL FileUpload object has eight read-only properties that have valid values only after the "AnalyzeContent" method (described below) has been invoked.

sErrorMessage: string
If an error is detected during either the "AnalyzeContent" or "SaveFileUpload" methods then this property will describe the error. If no error is detected then this property will be empty. The number preceding a colon will be the error number; the error description will follow the colon. The possible error numbers and messages are:

• 0: FWL Object Not Registered
• 1: Exceeds FileSize Limit
• 2: ClientRead Error
• 3: No Content
• 4: Incomplete Content
• 5: Missing Content
• 6: No File To Save
• 7: Uknown FileType
• 8: Boundry Missing
• 9: [SystemErrorMessage]

sFileName: string
Valid after the "AnalyzeContent" method call, the name of the file uploaded with its file extension. The case of the file name is not altered in any way. Set to UNK if the file is not a recognized MIME type.

iFileSize: integer
Valid after the "AnalyzeContent" method call, the size of the uploaded file. Set to 0 if the file is not a recognized type (i.e., BMP, JPG, GIF, PNG, DOC, TXT, XLS or HTML).

sFileType: string
Valid after the "AnalyzeContent" method call, describes the uploaded file extension:

• JPG: JPG (or JPEG as JPG) image file
• GIF: GIF (87a or 89a) image file
• PNG: Portable Network Graphics image file
• DOC: MS Word file
• TXT: ASCII Text file
• XLS: MS Excel spreadsheet file
• HTML: HTML file
• ZIP: ZIPed file
• UNK: Unknown

iFormElementCount: integer
Valid after the "AnalyzeContent" method call, the number of form element names which have non-empty associated values.

iImageHeight: integer
Valid after the "AnalyzeContent" method call and only for BMP, JPG, GIF and PNG image files, indicates the first image's height in pixels. For GIF image files, this is the height of the logical screen.

iImageWidth: integer
Valid after the "AnalyzeContent" method call and only for BMP, JPG, GIF and PNG image files, indicates the first image's width in pixels. For GIF image files, this is the width of the logical screen.

sJPGComment: string
Valid after the "AnalyzeContent" method call and only for JPG image files, the JPG's imbedded comment string (i.e., the COM marker), if any.

Methods

The FWL FileUpload object has five methods that return a value. The Delphi TWebModule version of the object has a sixth method, being the Create(), which does not return a value.

function AnalyzeContent: boolean
Called after the FWL FileUpload object is created, analyzes the web request object's payload for analysis and parsing. Returns TRUE if no problems were encountered, FALSE otherwise. If returns FALSE then the "sErrorMessage" property will describe the error as noted above.

procedure Create
For the Delphi TWebModule version only, creates the object and prepares the web request object's payload for analysis and parsing. Must be done before the "AnalyzeContent" method call is used. The object must be explicitly released before exiting from the TWebModule processing section.

function sJPGAppData(ziAppIndex: integer): string
Valid after the "AnalyzeContent" method call and only for JPG image files, returns the "Application" description (i.e., the APP0 through APP15 markers) for the "ziAppIndex" value, which can range from '0' to '15'. By convention, '0' usually returns the string "JFIF".

function sFormElementName(ziIndex: integer): string
Valid after the "AnalyzeContent" method call, returns the form element name, indexed by the "ziIndex" integer argument, that has a non-empty associated value. The first element's index is '1', and the last index is the value in the "iFormElementCount" property. Returns an empty string if the "ziIndex" integer argument is either zero or exceeds the "iFormElementCount" property value.

function sFormElementValue(zsName: string): string
Valid after the "AnalyzeContent" method call, returns the value associated with the form element name, as a string. as specified in the "zsName" string argument.

function SaveFileUpload(zsFilePath: string): boolean
Valid after the "AnalyzeContent" method call, saves the uploaded file as completely specified in the "zsFilePath" argument. Returns TRUE if the uploaded file was saved, FALSE otherwise. If returns FALSE then the "sErrorMessage" property will describe the error as noted above. **NOTE: XLS AND DOC FILES SHOULD BE CHECKED FOR POSSIBLE HARMFUL MACROS AND SCRIPT EXECUTIONS BEFORE THEY ARE MADE AVAILABLE TO THE APPLICATION ENVIRONMENT **