The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Apache2-API-v0.3.1
River stage one • 1 direct dependent • 2 total dependents
/ Apache2::API::Request::Upload

NAME

Apache2::API::Request::Upload - Apache2 Request Upload Object

SYNOPSIS

use Apache2::API::Request::Params;
## $r is the Apache2::RequestRec object
my $req = Apache2::API::Request::Params->new(
    request         => $r,
    # pool of 2Mb
    brigade_limit   => 2097152,
    disable_uploads => 0,
    # For example: 3Mb
    read_limit      => 3145728,
    temp_dir        => '/home/me/my/tmp'
    upload_hook     => sub
    {
        my( $upload, $new_data ) = @_; 
        # do something
    },
);

my $file = $req->upload( 'file_upload' );

# or more simply
use parent qw( Apache2::API )

# in your sub
my $self = shift( @_ );
my $file = $self->request->upload( 'file_upload' );
# or
my $file = $self->request->param( 'file_upload' );

print( "No check done on data? ", $file->is_tainted ? 'no' : 'yes', "\n" );
print( "Is it encoded in utf8? ", $file->charset == 8 ? 'yes' : 'no', "\n" );

my $field_header = $file->info;

# Returns the APR::Brigade object content for file_upload
my $brigade = $field->bucket

printf( "File name provided by client is: %s\n", $file->filename );

# link to the temporary file or make a copy if on different file system
$file->link( '/to/my/temp/file.png' );

my $buff;
# Read in our buffer if this is less than 500Kb
$file->slurp( $buff ) if( $file->length < 512000 );

print( "Uploaded data is %d bytes big\n, $file->length );

print( "MIME type of uploaded data is: %s\n", $file->type );

print( "Temporary file name is: %s\n", $file->tempname );

my $io = $file->io;
print while( $io->read( $_ ) );

# overloaded object reverting to $file->value
print( "Data is: $file\n" );

print( "Data is: ", $file->value, "\n" );

VERSION

v0.1.0

DESCRIPTION

This is a module that inherits from APR::Request::Param to deal with data upload leveraging directly Apache mod_perl's methods making it fast and powerful.

METHODS

bucket

Get or set the APR::Brigade file-upload content for this param.

May also be called as upload

charset

$param->charset();
$param->charset( $set );

Get or sets the param's internal charset. The charset is a number between 0 and 255; the current recognized values are

0 APREQ_CHARSET_ASCII

7-bit us-ascii

1 APREQ_CHARSET_LATIN1

8-bit iso-8859-1

2 APREQ_CHARSET_CP1252

8-bit Windows-1252

8 APREQ_CHARSET_UTF8

utf8 encoded Unicode

my $charset = $up->charset;
$up->charset( 8 );
print( "Data in utf8 ? ", $up->charset == 8 ? 'yes' : 'no', "\n" );

filename

Returns the client-side filename associated with this param.

Depending on the user agent, this may be the file full path name or just the file base name.

fh

Returns a seekable filehandle representing the file-upload content.

info

Get or set the APR::Table headers for this param.

my $info = $up->info;
while( my( $hdr_name, $hdr_value ) = each( %$info ) )
{
    # etc
}
printf( "Content type is: %s\n", $up->info->{'Content-type'} );

# could yield for example: application/json; charset=utf-8

See also "type", but be careful $up->info->{'Content-type'} is not necessarily the same.

io

Returns an APR::Request::Brigade::IO object, which can be treated as a non-seekable IO stream.

This is more efficient than "fh"

This object has the read and readline methods corresponding to the methods READ and READLINE from APR::Request::Brigade

$io->read( $buffer );

# or
$io->read( $buffer, $length );

# or
$io->read( $buffer, $length, $offset );

Reads data from the brigade $io into $buffer. When omitted $length defaults to -1, which reads the first bucket into $buffer. A positive $length will read in $length bytes, or the remainder of the brigade, whichever is greater. $offset represents the index in $buffer to read the new data.

$io->readline;

Returns the first line of data from the bride. Lines are terminated by linefeeds (the '\012' character), but this may be changed to $/ instead.

is_tainted

$param->is_tainted();
$param->is_tainted(0); # untaint it

Get or set the param's internal tainted flag.

length

Returns the size of the param's file-upload content.

May also be called as size

Provided with a file path and this will link the file-upload content with the local file named $path. Creates a hard-link if the spoolfile's (see upload_tempname) temporary directory is on the same device as $path; otherwise this writes a copy.

This is useful to avoid recreating the data. This works on *nix-like systems

my $up = $req->param( 'file_upload' );
$up->link( '/to/my/location.png' ) ||
    die( sprintf( "Cannot symlink from %s: $!\n", $up->tempname ) );

make

Fast XS param constructor.

my $param = Apache2::API::Request::Param::Upload->make( $pool, $name, $value );

name

$param->name();

Returns the param's name, i.e. the html form field name. This attribute cannot be modified.

size

$param->size();

Returns the size of the param's file-upload content.

slurp

Provided with a variable, such as $data and this reads the entire file-upload content into $data and returns an integer representing the size of $data.

my $up = $req->param( 'file_upload' );
my $size = $up->slurp( $data );

tempname

Provided with a string and this returns the name of the local spoolfile for this param.

type

Provided with a string and this returns the MIME-type of the param's file-upload content.

upload

my $brigade = $param->upload();
$param->upload( $brigade );

Get or set the APR::Brigade file-upload content for this param.

upload_fh

my $fh = $param->upload_fh();

Returns a seekable filehandle representing the file-upload content.

upload_filename

my $filename = $param->upload_filename();

Returns the client-side filename associated with this param.

upload_io

my $fh = $param->upload_io();

Returns an APR::Request::Brigade::IO object, which can be treated as a non-seekable IO stream.

See also "upload_fh"

$param->upload_link( $path );

Links the file-upload content with the local file named $path. Creates a hard-link if the spoolfile's (see upload_tempname) temporary directory is on the same device as $path; otherwise this writes a copy.

upload_size

my $nbytes = $param->upload_size();

Returns the size of the param's file-upload content.

upload_slurp

$param->upload_slurp( $data );

Reads the entire file-upload content into $data.

upload_tempname

my $filename = $param->upload_tempname();

Returns the name of the local spoolfile for this param.

upload_type

my $type = $param->upload_type();

Returns the MIME-type of the param's file-upload content.

value

$param->value();

Returns the param's value. This attribute cannot be modified.

AUTHOR

Jacques Deguest <jack@deguest.jp>

SEE ALSO

Apache2::Request, APR::Request, APR::Request::Param, APR::Request::Apache2

COPYRIGHT & LICENSE

Copyright (c) 2023 DEGUEST Pte. Ltd.

You can use, copy, modify and redistribute this package and associated files under the same terms as Perl itself.