view release on metacpan or  search on metacpan

lib/Apache2/API/Request/Upload.pm  view on Meta::CPAN

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

=head2 fh

Returns a seekable filehandle representing the file-upload content.

=head2 info

Get or set the L<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 L</type>, but be careful C<< $up->info->{'Content-type'} >> is not necessarily the same.

=head2 io

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

This is more efficient than L</fh>

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

    $io->read( $buffer );

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

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

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

    $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 C<$/> instead.

=head2 is_tainted

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

Get or set the param's internal tainted flag.

=head2 length

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

May also be called as B<size>

=head2 link

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 ) );

=head2 make

Fast XS param constructor.

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

=head2 name

    $param->name();

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

=head2 size

    $param->size();

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

=head2 slurp

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

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

=head2 tempname

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

=head2 type

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

=head2 upload

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

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

=head2 upload_fh

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

Returns a seekable filehandle representing the file-upload content.

=head2 upload_filename

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

Returns the client-side filename associated with this param.

=head2 upload_io

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