mod_upload is an input filter module for multipart/form-data,
as submitted from File Upload forms on the Web. mod_upload decodes the
data, so the handler gets the file itself without the MIME encoding.
Other fields from the form are provided as a table of names/values.
A second filter, formerly mod_tmpfile, is available to store the file contents in a tempfile. This ensures that all the Form data are available when the file is processed, and is useful for handlers that need to run synchronously.
Consider a simple HTML file upload fragment:
<form method="post" action="my-handler" enctype="multipart/form-data">
Your name: <input name="name">
Your email address: <input name="email">
<br>File: <input name="file" type="file">
<br>Additional comments <textarea rows=4 cols=40 name="comments">
</textarea>
</form>
This will generate an HTTP POST request containing an uploaded file with three additional user-supplied text fields. The data are MIME-encoded and normally the Handler has to decode them.
Using upload-filter as an input filter, the handler will be passed
instead the decoded file contents. It can access the other
Form data (the values of name, email and comments
through a table exported by the function
apr_table_t* mod_upload_form(request_rec* r)
which is available to any Handler or other module that needs the data.
In the above example, the handler receives the upload asynchronously.
So for example, if a browser passes Form fields in the order they appear
in the HTML Form, then when processing the file starts, the values of
name and email are available, but the value
of comments may not yet have reached the server.
For applications requiring synchronous data, a second filter tmpfile-filter is provided. tmpfile-filter ensures that the upload is complete before data are passed through to the handler. To avoid the risk of overloading memory with a big upload, it saves the file to a tempfile and passes only the filename through to the handler.
To insert mod_upload, use the AddInputFilter or
SetInputFilter directives. For pipelined applications,
SetInputFilter upload-filter
or for synchronous applications, add both upload and tmpfile
SetInputFilter tmpfile-filter;upload-filter
mod_upload defines two further configuration directives:
mod_upload.c source code is available under the GNU General Public License (GPL). As with other opensource modules, we can consider alternative licenses by request.