When you work in a collaborative environment, being able to easily share and update documents is a requirement. One way to satisfy this requirement is to let team members post their documents to a project Web site. HTTP posting, which is defined in Internet Engineering Task Force (IETF) Request for Comments (RFC) 1867, lets you access a page on the project Web site, select documents from your local computer, and upload those documents to the project Web server. Posting occurs through HTTP requests, normally on port 80, and you can use it to let developers behind different companies’ corporate firewalls update files on a server outside those firewalls. IIS supports two tools that help you post documents to an intranet or extranet—Microsoft Posting Acceptor and File Upload Control. The aptly named Posting Acceptor is the server-side DLL that does the dirty work; File Upload Control (flupl.ocx) is a browser component that enhances the user interface (UI). This month, I describe the basic steps for implementing Posting Acceptor.
Posting Acceptor is an Internet Server API (ISAPI) extension to IIS 5.0 and IIS 4.0 that lets Web clients take advantage of standard HTML for uploading files. Browsers such as Microsoft Internet Explorer (IE) 4.0 and later, which support HTML forms, recognize the input element with a type attribute of file. The browser automatically places an operational Browse button next to the input element on the user’s screen. (Although you can configure Posting Acceptor to allow Anonymous access, this is a security risk. Consider taking the extra steps to prevent users from uploading potentially damaging files to your server.)
Installing Posting Acceptor
You can find the latest version of Posting Acceptor as part of Microsoft Site Server 3.0, Site Server Express 3.0, or on the Microsoft Visual Studio (VS) 6.0 Enterprise Edition CD-ROM. The setup routine to install Posting Acceptor from VS 6.0 Enterprise Edition is pasetup.exe. (The setup routine is in the Deploy directory of Disk 2.)
To check the sites on your server for an existing installation of Posting Acceptor, access the Scripts directory under the default \inetpub folder on the server. Cpshost.dll implements Posting Acceptor: If cpshost.dll is already on your system, right-click the DLL and select Properties to check the version on the Version tab of the Properties dialog box. File Version: X.X.X.X appears at the top of the dialog box. If the version number is older than 7.0.794.7, remove the file and install the current version. (Problems with older versions make them virtually unusable.)
To use Posting Acceptor for a site other than a server’s default site, follow these steps to map the existing Scripts directory as a virtual directory for that site:
- Right-click the site in the Microsoft Management Console (MMC), then select New Virtual Directory.
- In the wizard that appears, enter the alias Scripts, which you’ll use to access the directory from the Web.
- On the next screen that appears, select the Physical Scripts directory in your \inetpub folder.
- Select the appropriate access, which includes Read and Execute permissions.
- When the wizard is complete, you’ll find a new virtual directory under the site you selected. Right-click this entry and select Properties to access the dialog box that Screen 1 shows.
The Local Path text box contains the physical directory in which cpshost.dll resides. After you create the Scripts virtual directory, you can use this directory to reference cpshost.dll from the Web. (Note that for each site, default or otherwise, the virtual directory you use to reference cpshost.dll must support the execution of DLLs.)
Creating the Upload Directory
For Posting Acceptor to function, you must specify a virtual directory for which clients have the Write permission necessary for creating new files. Don’t assign Execute or Script privileges to this directory because someone could upload and run destructive software on the server. Assigning permissions on this directory is a leading error when administrators initially set up Posting Acceptor. The directory supports Write by Everyone as the default setting. When Posting Acceptor is operational, you can modify the security settings.
Creating subdirectories based on topic or user account is an excellent way to partition the directory that accepts uploaded files. One feature of Posting Acceptor is that it lets users overwrite files with the same name: Partitioning the upload directory in an intranet or extranet scenario helps to prevent accidental overwrites.
When you’ve created the physical directory, you must identify it as a virtual directory within the Web site that will use it. Use these steps to identify the virtual directory:
- Access the MMC, and select the appropriate Web site.
- Right-click the Web site, and select New Virtual Directory.
- Respond to the wizard’s request to provide a name for the directory, then map this name to the directory of your choice.
- Set the permissions that IIS will apply to the directory. Be certain to remove the Run Script permission and select the Write permission for the upload directory.
After you create the virtual upload directory, right-click the directory and select Properties to adjust the access permissions. The intranet permits either NT LAN Manager (NTLM)/Integrated Windows authentication or Basic authentication. The advantage of Basic authentication is that it’s both browser independent and firewall friendly. However, because Basic authentication passes account information in plaintext, if you use Basic authentication, you also need to use Secure Sockets Layer (SSL). An added benefit of SSL, regardless of the authentication method you use, is that SSL encrypts the private documents that make up your extranet content.
Calling Posting Acceptor
Posting Acceptor requires two Active Server Pages (ASP) to function properly—upload.asp and postupload.asp. Upload.asp, which Screen 2 shows, submits the form, which initiates a call to Posting Acceptor. After Posting Acceptor uploads the client’s file, it redirects the form to postupload.asp, which Screen 3 shows. Set the security for upload.asp and cpshost.dll to match your selected security model. However, you must set postupload.asp to allow Anonymous access.
The first 12 lines of Listing 1 show the beginning of upload.asp and a sample form statement that defines a call to Posting Acceptor. When you call Posting Acceptor to upload a file, the form statement has two basic requirements. First, you must set the form’s Encoding Type attribute (enctype) to multipart/form-data. Second, you must set the Action attribute in the following two-part format:
- A reference to Posting Acceptor itself, which might look like
https://www.interknowlogy.com/scripts/cpshost.dll.
This reference tells IIS that the requested resource is an executable DLL rather than an ASP or HTML page.
- A reference to the page that Posting Acceptor calls after loading the submitted file (e.g., https://www.interknowlogy.com/postupload.asp).
The keyword ?PUBLISH? separates these two parts. The reason that both URLs that I mentioned reference a fully qualified domain name (FQDN) is that when you use SSL, referencing an FQDN is the only way in which Posting Acceptor can call the correct WinInet API. A simple way to maintain portability is to call Request.ServerVariables("SERVER_NAME") when you build URLs that include an FQDN.
Uploading the File
Although Posting Acceptor is an executable that IIS runs, you can think of the tool as an object that will be created and available after the upload to the page you designate. Construction of a successful call to Posting Acceptor requires submission of two properties—TargetURL and file. Three more properties—Filename, Extention, and Path—which are present after the upload, provide information about the uploaded file. Posting Acceptor associates the names of all five properties with any additional data from the form used to submit the upload request.
The form you submit to Posting Acceptor has two mandatory fields. As callout A in Listing 1 shows, the first required field, file, is the input field for the filename. This field is an input field of type file. The second field is TargetURL. Like the Action attribute, TargetURL uses an FQDN and references the virtual directory you defined with Write permission. If you don’t name these two values appropriately in the submitted form, Posting Acceptor can’t upload the desired file.
The simple example in Listing 1 builds the target URL in a hidden field to ensure that a user updates the appropriate file repository. The listing also demonstrates one way to manage a shared upload area—the use of subdirectories based on a user’s account. In its simplest form, Posting Acceptor uploads files to subfolders under a project folder. Individuals manage the files in their folders. Browsers use a page with a relatively simple ASP implementation of the File System Object to browse uploaded files, based on username. While Posting Acceptor doesn’t support deletions, clients can manage their individual repositories and upload empty files to replace obsolete files. These empty files are hidden from browsers because the File System Object screens out files with no size.
However, if you’re intent on using Posting Acceptor to maintain a series of directories, you might want a standard input field to edit the TargetURL. If, for example, a firewall separates your work from the site, you can create a virtual directory at the site’s root level. By using the Administrator account, supporting Write permission through the virtual directory, and editing the TargetURL for folders below the site root directory, you can upload to any folder in the site.
In addition, you can capture other values on the upload form as long as the input field names don’t conflict with those names Posting Acceptor uses. Additional fields are available with the uploaded file details after Posting Acceptor finishes uploading the user’s file. Keep in mind, however, that when Posting Acceptor calls postupload.asp, it calls the page with an Anonymous connection, and user-related variables aren’t available.
After the Upload Is Complete
When Posting Acceptor has processed the upload of the requested file, it redirects control to the page you identified in the second part of the Action attribute. Posting Acceptor performs the redirect with a call to the WinInet API, which bypasses the client browser. Thus, your postupload.asp page must support Anonymous access. The user information isn’t part of the server’s process and, as a result, when Posting Acceptor calls postupload.asp, it does so without the currently authenticated user’s privileges. (Note that after a return trip to the browser, the inclusion of a redirect call resets the user information from the browser’s cached credentials.) Failing to grant Anonymous access to postupload.asp is one of the most common mistakes administrators make when they attempt to use Posting Acceptor.
In addition to passing any other values collected as part of the input form, Posting Acceptor adds three values. As Listing 2 shows, Request.Form("Filename") is the name of the file that you uploaded in the file input field. Request.Form("FileExtention") contains the file extension for the uploaded file, whereas Request.Form("FilePath") contains the location the server TargetURL references. Because Posting Acceptor creates these values, be sure not to use the same names for other input fields on the form you submit to trigger the file upload. Also, note that the word extention is the correct spelling for the value Posting Acceptor creates.
As Listing 2 shows, postupload.asp loops through the form data Posting Acceptor created when it uploaded the files. The script looks for the filename(s) in the form data, then takes three values that describe the uploaded file and displays a confirmation message to the user. These values are Posting Acceptor’s remaining properties; they not only provide meaningful feedback to the user, but also let the server manage the uploaded files.
Getting It All to Work Together
As simple as the pages appear, getting Posting Acceptor to work is generally a frustrating experience. The biggest problem is setting up the permissions and security for a successful submission. Remember that postupload.asp needs to support Anonymous access; the user’s ID won’t be available. Ensure that the settings are consistent in both Windows 2000 and NT as well as in the MMC for your upload directory. In this directory, you must grant Everyone Write permission until you get the basic post capability working. For more information about Posting Acceptor, see Jeff Sandquist, Uploading Files: The Posting Acceptor, Part 1 (http://msdn.microsoft.com/ workshop/server/asp/server052499.asp) and Scott Stanfield, The Fitch & Mather Sample Web Site (http://msdn.microsoft.com/library/ default.asp?url=/library/techart/fmcorpweb.htm).
Next month, I’ll tell you how to implement the File Upload Control. I’ll also show you how to configure File Upload Control to communicate with Posting Acceptor.
