Struct actix_web::http::header::ContentDisposition

pub struct ContentDisposition {
    pub disposition: DispositionType,
    pub parameters: Vec<DispositionParam, Global>,
}

A Content-Disposition header. It is compatible to be used either as a response header for the main body as (re)defined in RFC6266, or as a header for a multipart body as (re)defined in RFC7587.

In a regular HTTP response, the Content-Disposition response header is a header indicating if the content is expected to be displayed inline in the browser, that is, as a Web page or as part of a Web page, or as an attachment, that is downloaded and saved locally, and also can be used to attach additional metadata, such as the filename to use when saving the response payload locally.

In a multipart/form-data body, the HTTP Content-Disposition general header is a header that can be used on the subpart of a multipart body to give information about the field it applies to. The subpart is delimited by the boundary defined in the Content-Type header. Used on the body itself, Content-Disposition has no effect.

ABNF

content-disposition = "Content-Disposition" ":"
                      disposition-type *( ";" disposition-parm )

disposition-type    = "inline" | "attachment" | disp-ext-type
                      ; case-insensitive

disp-ext-type       = token

disposition-parm    = filename-parm | disp-ext-parm

filename-parm       = "filename" "=" value
                    | "filename*" "=" ext-value

disp-ext-parm       = token "=" value
                    | ext-token "=" ext-value

ext-token           = <the characters in token, followed by "*">

Note

filename is not supposed to contain any non-ASCII characters when used in a Content-Disposition HTTP response header, where filename* with charset UTF-8 may be used instead in case there are Unicode characters in file names. filename is acceptable to be UTF-8 encoded directly in a Content-Disposition header for multipart/form-data, though.

filename* must not be used within multipart/form-data.

Example

use actix_http::http::header::{
    Charset, ContentDisposition, DispositionParam, DispositionType,
    ExtendedValue,
};

let cd1 = ContentDisposition {
    disposition: DispositionType::Attachment,
    parameters: vec![DispositionParam::FilenameExt(ExtendedValue {
        charset: Charset::Iso_8859_1, // The character set for the bytes of the filename
        language_tag: None, // The optional language tag (see `language-tag` crate)
        value: b"\xa9 Copyright 1989.txt".to_vec(), // the actual bytes of the filename
    })],
};
assert!(cd1.is_attachment());
assert!(cd1.get_filename_ext().is_some());

let cd2 = ContentDisposition {
    disposition: DispositionType::FormData,
    parameters: vec![
        DispositionParam::Name(String::from("file")),
        DispositionParam::Filename(String::from("bill.odt")),
    ],
};
assert_eq!(cd2.get_name(), Some("file")); // field name
assert_eq!(cd2.get_filename(), Some("bill.odt"));

// HTTP response header with Unicode characters in file names
let cd3 = ContentDisposition {
    disposition: DispositionType::Attachment,
    parameters: vec![
        DispositionParam::FilenameExt(ExtendedValue {
            charset: Charset::Ext(String::from("UTF-8")),
            language_tag: None,
            value: String::from("\u{1f600}.svg").into_bytes(),
        }),
        // fallback for better compatibility
        DispositionParam::Filename(String::from("Grinning-Face-Emoji.svg"))
    ],
};
assert_eq!(cd3.get_filename_ext().map(|ev| ev.value.as_ref()),
           Some("\u{1f600}.svg".as_bytes()));

Security Note

If “filename” parameter is supplied, do not use the file name blindly, check and possibly change to match local file system conventions if applicable, and do not use directory path information that may be present. See RFC2183.

Fields

disposition: DispositionType

The disposition type

parameters: Vec<DispositionParam, Global>

Disposition parameters

Implementations

impl ContentDisposition

pub fn from_raw(hv: &HeaderValue) -> Result<ContentDisposition, ParseError>

Parse a raw Content-Disposition header value.

pub fn is_inline(&self) -> bool

Returns true if it is Inline.

pub fn is_attachment(&self) -> bool

Returns true if it is Attachment.

pub fn is_form_data(&self) -> bool

Returns true if it is FormData.

pub fn is_ext<T>(&self, disp_type: T) -> bool where
    T: AsRef<str>, 

Returns true if it is Ext and the disp_type matches.

pub fn get_name(&self) -> Option<&str>

Return the value of name if exists.

pub fn get_filename(&self) -> Option<&str>

Return the value of filename if exists.

pub fn get_filename_ext(&self) -> Option<&ExtendedValue>

Return the value of filename* if exists.

pub fn get_unknown<T>(&self, name: T) -> Option<&str> where
    T: AsRef<str>, 

Return the value of the parameter which the name matches.

pub fn get_unknown_ext<T>(&self, name: T) -> Option<&ExtendedValue> where
    T: AsRef<str>, 

Return the value of the extended parameter which the name matches.

Trait Implementations

impl Clone for ContentDisposition

pub fn clone(&self) -> ContentDisposition

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ContentDisposition

pub fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Display for ContentDisposition

pub fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Header for ContentDisposition

pub fn name() -> HeaderName

Returns the name of the header field

pub fn parse<T>(msg: &T) -> Result<ContentDisposition, ParseError> where
    T: HttpMessage, 

Parse a header

impl IntoHeaderValue for ContentDisposition

type Error = InvalidHeaderValue

The type returned in the event of a conversion error.

pub fn try_into(
    self
) -> Result<HeaderValue, <ContentDisposition as IntoHeaderValue>::Error>

Try to convert value to a Header value.

impl PartialEq<ContentDisposition> for ContentDisposition

pub fn eq(&self, other: &ContentDisposition) -> bool

This method tests for self and other values to be equal, and is used by ==.

pub fn ne(&self, other: &ContentDisposition) -> bool

This method tests for !=.

impl StructuralPartialEq for ContentDisposition