NAME

HTTP::Promise::Headers::ContentDisposition - Content-Disposition Header Field

SYNOPSIS

    use HTTP::Promise::Headers::ContentDisposition;
    my $cd = HTTP::Promise::Headers::ContentDisposition->new || 
        die( HTTP::Promise::Headers::ContentDisposition->error, "\n" );
    my $dispo = $cd->disposition;
    # For example, attachment
    $cd->disposition( 'inline' );
    $cd->filename( 'some-file.txt' );
    $cd->disposition( 'form-data' );
    $cd->name( 'someField' );
    my $name = $cd->name;
    # Same thing
    my $name = $cd->param( 'name' );
    $cd->params( name => 'someField', filename => 'some-file.txt' );

VERSION

    v0.1.0

DESCRIPTION

The following description is taken from Mozilla documentation.

    Content-Disposition: inline
    Content-Disposition: attachment
    Content-Disposition: attachment; filename="filename.jpg"
    Content-Disposition: form-data; name="fieldName"
    Content-Disposition: form-data; name="fieldName"; filename="filename.jpg"

METHODS

as_string

Returns a string representation of the Content-Disposition object.

disposition

Sets or gets the type of Content-Disposition this is. For example: attachment, form-data

name

Is followed by a string containing the name of the HTML field in the form that the content of this subpart refers to. When dealing with multiple files in the same field (for example, the multiple attribute of an <input type="file"> element), there can be several subparts with the same name.

A name with a value of '_charset_' indicates that the part is not an HTML field, but the default charset to use for parts without explicit charset information.

filename

Without any argument, this returns the string containing the original name of the file transmitted. The filename is always optional and must not be used blindly by the application: path information should be stripped, and conversion to the server file system rules should be done. This parameter provides mostly indicative information. When used in combination with Content-Disposition: attachment, it is used as the default filename for an eventual "Save As" dialog presented to the user.

If the property filename* is set instead, then it will be decoded and used instead, and the value for "filename_charset" and "filename_lang" will be set.

When setting the filename value, this takes an optional language iso 639 code (see rfc5987 and rfc2231). If the filename contains non ascii characters, it will be automatically encoded according to rfc5987. and the property filename* set instead. That property, by rfc standard, takes precedence over the filename one.

The language provided, if any, will be used then.

For example:

    $h->disposition( 'form-data' );
    $h->name( 'fileField' );
    $h->filename( q{file.txt} );
    say "$h";
    # form-data; name="fileField"; filename="file.txt"

    $h->disposition( 'form-data' );
    $h->name( 'fileField' );
    $h->filename( q{ファイル.txt} );
    say "$h";
    # form-data; name="fileField"; filename*="UTF-8''%E3%83%95%E3%82%A1%E3%82%A4%E3%83%AB.txt"
 
    $h->disposition( 'form-data' );
    $h->name( 'fileField' );
    $h->filename( q{ファイル.txt}, 'ja-JP' );
    say "$h";
    # form-data; name="fileField"; filename*="UTF-8'ja-JP'%E3%83%95%E3%82%A1%E3%82%A4%E3%83%AB.txt"

    # Using default value
    $h->filename_lang( 'ja-JP' );
    $h->disposition( 'form-data' );
    $h->name( 'fileField' );
    $h->filename( q{ファイル.txt} );
    say "$h";
    # form-data; name="fileField"; filename*="UTF-8'ja-JP'%E3%83%95%E3%82%A1%E3%82%A4%E3%83%AB.txt"

    $headers->header( Content_Disposition => "$h" );

The Content-Disposition header value would then contain a property filename* (with the trailing wildcard).

See also "decode_filename" in HTTP::Promise::Headers and "encode_filename" in HTTP::Promise::Headers which are used to decode and encode filenames.

filename_charset

Sets or gets the encoded filename charset.

This is used when the filename contains non-ascii characters, such as Japanese, Korean, or Cyrillic. Although theoretically one can set any character set, by design this only accepts UTF-8 (case insensitive).

This is set automatically when calling "filename". You actually need to call "filename" first to have a value set.

Returns a scalar object containing the filename charset.

filename_lang

Sets or gets the encoded filename language. This takes an iso 639 language code (see rfc1766).

This is set automatically when calling "filename". You actually need to call "filename" first to have a value set.

Returns a scalar object containing the filename language.

param

Sets or gets an arbitrary Content-Disposition property.

Note that if you use this, you bypass other specialised method who do some additional processing, so be mindful.

params

Sets or gets multiple arbitrary Content-Disposition properties at once.

If called without any arguments, this returns the hash object used to store the Content-Disposition properties.

AUTHOR

Jacques Deguest <jack@deguest.jp>

SEE ALSO

See rfc6266, section 4, rfc7578, section 4.2 and Mozilla documentation

HTTP::Promise, HTTP::Promise::Request, HTTP::Promise::Response, HTTP::Promise::Message, HTTP::Promise::Entity, HTTP::Promise::Headers, HTTP::Promise::Body, HTTP::Promise::Body::Form, HTTP::Promise::Body::Form::Data, HTTP::Promise::Body::Form::Field, HTTP::Promise::Status, HTTP::Promise::MIME, HTTP::Promise::Parser, HTTP::Promise::IO, HTTP::Promise::Stream, HTTP::Promise::Exception

COPYRIGHT & LICENSE

Copyright(c) 2022 DEGUEST Pte. Ltd.

All rights reserved.

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

cpanm HTTP::Promise

perl -MCPAN -e shell
install HTTP::Promise