Sloop::Multipart

DESCRIPTION

Class for parsing HTTP multipart POST request, as defined in RFCs 1867, 2046, 2388, etc. This is the normal way of uploading files from a browser, via a "multipart/form-data" HTML form.

REQUIRES

This refers only to modules not part of Sloop or the perl core.

URI::Encode

SYNOPSIS

 my $smp = Sloop::Multipart->new (
        $request,
        $max,
        $tmpdir,
        @expected
 );

$request is a Sloop::Client::Request object. The constructor will return undef if the request header is incorrect for a multipart upload. Be sure to check that.

$max is the maximum total size of the upload. This is checked as it proceeds primarily to prevent illegitimate oversized payloads; if you want to validate requests before the upload begins, you should check $request->header('content-length') yourself.

$tmpdir is the path to a directory that the Sloop process has write permissions on. This is required by Sloop::Multipart::Data objects to hold the upload data as it accumulates. If the value is '_MEM_', it will be stored in a scalar instead.

@expected is an optional array (i.e., the remainder of the args array); each element will be a key for the $smp->{expected} hash -- see {parts} and {expected} under ATTRIBUTES.

ATTRIBUTES

$smp->{error}: Used to store an error message, see $smp->process() under METHODS.
$smp->{parts}: Array reference of Sloop::Multipart::Data objects created by $smp->process(). These represent the seperate parts of the upload except those that are in $smp->{expected}.
$smp->{expected}: A hash ref of Sloop::Multipart::Data objects constructed by $smp->process() if '@expected' args were passed to the constructor (see SYNOPSIS). If the POST body contained more than one item for a given key, only the first one will be in this hash -- the rest will be in the {parts} array.

METHODS

`$smp->process($dataref)`

This is called to add data from the POST body for processing.

$dataref is a scalar reference to the data to be processed. Generally, it should be to the {body} field of a Sloop::Client::Request object, in a Sloop::Client::readPost() or simplePost() handler. $$dataref will be left empty by this call.

Returns -1 on error, 0 to indicate there should still be data to process, and 1 once the last part has been added. If 0, you may do as you wish with the Sloop::Multipart::Data objects attached (including remove them); they are complete even if the rest of the upload is not. If the upload turns out to be empty, process() will return -1 and report this as an error; thus success guarantees there is at least one element in $smp->{parts}. Calling process() again after it has returned -1 will be fatal to the server, so be sure to check this. The nature of the error will be reported as a string in $smp->{error}.

`$smp->valueFromExpected($partName, $max)`

A convenience wrapper around Sloop::Multipart::Data::getContent(); see that documentation regarding the side effects of calling this method.

$partName is a name submitted to the constructor in the @expected array.

$max is the maximum number of bytes to permit. If the length of the part's content is greater than this, the content (but not the rest of the Sloop::Multipart::Data object) is deleted and undef is returned.

Returns the content of the part, or undef if it does not exist or was too big.