NAME
    Apache2::UploadProgress - Track Upload Progress

SYNOPSIS
        PerlLoadModule             Apache2::UploadProgress
        PerlPostReadRequestHandler Apache2::UploadProgress

        <Location /progress>
            SetHandler modperl
            PerlResponseHandler Apache2::UploadProgress->progress
        </Location>

DESCRIPTION
    This module allows you to track the progress of a file upload in order
    to provide a user with realtime updates on the progress of their file
    upload.

    The information that is provided by this module is very basic. It just
    includes the total size of the upload, and the current number of bytes
    that have been received. However, this information is sufficient to
    display lots of information about the upload to the user. Generally this
    is achieved using some JavaScript and AJAX calls in the browser,
    however, it could also be accomplished using a popup window with a meta
    refresh that continuously reloads the progress URL.

EXAMPLE
    Please see the examples directory for a complete example that includes a
    dynamic progress bar, and extended status information like transfer
    rates, and ETA.

HANDLERS
    handler
        This handler should be run at the PerlPostReadRequestHandler stage,
        and will detect whether we need to track the upload progress of the
        current request. There are 5 ways for the handler to determine if
        the upload progress should be tracked:

        X-Upload-ID
            There is an incoming header called X-Upload-ID which contains
            the progess ID

        X-Progress-ID
            There is an incoming header called X-Progress-ID which contains
            the progess ID

        Query contains ID
            The query portion of the URL consists of just a 32 character
            hexadecimal string (for example
            http://localhost/upload.cgi?1234567890abcdef1234567890abcdef)

        Query contains progress_id
            There is a query parameter in the query string called
            progress_id, and it contains a 32 character hexadecimal number
            (for example
            http://localhost/upload.cgi?progress_id=1234567890abcdef12345678
            90abcdef)

        Query contains upload_id
            There is a query parameter in the query string called upload_id,
            and it contains a 32 character hexadecimal number (for example
            http://localhost/upload.cgi?upload_id=1234567890abcdef1234567890
            abcdef)

        Note that you can not pass the progress_id as a hidden POST
        parameter, since the Apache2::UploadProgress module never actually
        decodes the POST request so it will not be able to determine what
        the ID is. The reason for this is that we are trying to track the
        rate at which the POST request takes to upload, so we need that ID
        before we even start counting the incoming POST request. So the ID
        must be passed as a header, or as a simple query parameter, as part
        of the action attribute of the form.

    progress
        When called, this handler will return the upload progress of the
        request identified by the given ID. The ID can be provided in
        exactly the same way as in the handler method given above (Although
        is usually easiest to just provide is as a query parameter called
        progress_id).

        This handler can return the results in several different formats. By
        default, it will return XML data, but that can be changed by
        altering the Accept header of the request (if multiple mimes are
        present in the Accept header, they are tried in order of qvalue
        according to RFC 2616).

        For example, if you set the Accept header to the following:

            Accept:  text/plain; q=0.5, text/x-json

        Then the preferred mime type would be text/x-json, but if it was not
        available, the data would be sent in text/plain.

        The following formats are currently supported:

        HTML ( text/html application/xhtml+xml )
        JSON ( text/x-json application/x-json )
        TEXT ( text/plain )
        YAML ( text/x-yaml application/x-yaml )
        XML ( text/xml application/xml )

        For an example of how to alter the incoming Accept header see the
        example script that is included in the examples directory.

INTERNAL METHODS
    The following internal methods should never need to be called directly
    but are documented for completeness.

    progress_id( $r )
            $progress_id = Apache2::UploadProgress->progress_id($r);

        Determine the progress ID for the current request (if it exists)

    fetch_progress( $progress_id )
            $progress = Apache2::UploadProgress->fetch_progress($progress_id);
            printf "size:     %d", $progress->[0];
            printf "received: %d", $progress->[1];

        Pulls the progress values from the cache based on the provided ID

    store_progress( $progress_id, [ $size, $received ] )
            Apache2::UploadProgress->store_progress( $progress_id, [ $size, $received ] );

        Update the progress values in the cache for the given ID

    track_progress
        An Input filter handler that totals up the number of bytes that have
        been sent as part of the current request, and updates the current
        progress through calls to "store_progress".

SEE ALSO
    <http://perl.apache.org/docs/2.0/>.

    <http://www.modperlbook.org/>.

    Apache2::Filter.

    Apache2::RequestRec.

AUTHOR(S)
    Christian Hansen "chansen@cpan.org"

    Cees Hek "ceeshek@cpan.org"

COPYRIGHT
    This program is free software, you can redistribute it and/or modify it
    under the same terms as Perl itself.