Struct MessageHeaders

Source

pub struct MessageHeaders { /* private fields */ }

Expand description

This type is used to parse and generate the headers of Internet messages, which consist of text lines, with an empty line separating the headers from the body. The format is specified in IETF RFC 5322.

Implementations§

Source §

impl MessageHeaders

Source

pub fn add_header<H>(&mut self, header: H)
where H: Into<Header>,

Append the given header. This does not change or remove any previously added headers, even if they have the same name. To replace a previously added header, use set_header instead.

Source

pub fn add_header_multi_value<N, V>( &mut self, name: N, values: V, mode: HeaderMultiMode, )
where N: AsRef<str>, V: Into<Vec<String>>,

Append one or more headers with the given name and values derived from the given vector, depending on the given mode (see HeaderMultiMode for more information). This does not change or remove any previously added headers, even if they have the same name. To replace a previously added header, use set_header_multi_value instead.

Source

pub fn generate(&self) -> Result<Vec<u8>, Error>

Produce the text string form of the message, according to the rules of RFC 5322:

Each header is separated by a carriage-return line-feed sequence (CRLF).
Headers may be folded onto multiple lines at whitespace characters (which are strictly space (‘\x20’) and horizontal tab (‘\x09’).
The first line of a header consists of the header name followed by a colon (‘:’) followed by a space (‘\x20’) followed by part or all of the header value.
After all headers, an empty line is placed to mark where the body begins.

§Errors

Error::HeaderLineCouldNotBeFolded is returned if the generator is configured with a line limit constraint and one or more headers are too long and cannot be folded to fit within the constraint.

While technically it shouldn’t happen, logically we may return Error::StringFormat if one of the internal string formatting functions should fail (which they shouldn’t unless something used internally doesn’t implement Display properly.

Source

pub fn headers(&self) -> &Vec<Header>

Borrow the list of headers.

Source

pub fn header_multi_value<T>(&self, name: T) -> Vec<String>
where T: AsRef<str>,

Produce a list of the values for the headers with the given name. If no headers have the given name, an empty list is returned.

Source

pub fn header_tokens<T>(&self, name: T) -> Vec<String>
where T: AsRef<str>,

Take the value of the header with the given name, interpret it as a comma-separated list of values, and produce that list. If no headers have the given name, an empty list is returned.

Source

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

Produce the value for the header with the given name, if any. If there are two or more headers with the same name, the produced string will be the joining of their values with commas.

Source

pub fn has_header_token<T>(&self, name: T, token: T) -> bool
where T: AsRef<str>,

This is a convenience function which essentially looks up the tokens in a header using header_tokens and searches them to see if the given token is among them.

Source

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

Determine whether or not the given header is present.

Source

pub fn new() -> Self

Create a new instance with no headers in it.

Source

pub fn parse<T>(&mut self, raw_message: T) -> Result<ParseResults, Error>
where T: AsRef<[u8]>,

Feed more Internet message text into the parser, building the collection of headers internally, and detecting when the end of the headers and the beginning of the body is found.

This function may be called multiple times to parse input incrementally. Each call returns an indication of whether or not a message was parsed and how many input bytes were consumed.

§Errors

HeaderLineTooLong &nash; the parser is configured with a line length constraint and the input exceeds it on a line
HeaderLineMissingColon – there is no colon between the name and value of a header line
HeaderNameContainsIllegalCharacter – the name of a header contains an illegal character
HeaderValueContainsIllegalCharacter – the value of a header contains an illegal character

§Examples

use rhymessage::{MessageHeaders, ParseResults, ParseStatus};

let mut headers = MessageHeaders::new();

// `parse` does not consume first line because the next line
// it hasn't seen yet might contain part of the "From" header.
assert_eq!(
    ParseResults{
        status: ParseStatus::Incomplete,
        consumed: 0,
    },
    headers.parse("From: joe@example.com\r\n")?
);

// So we re-send the "From" line along with the content that follows.
// At this point, `parse` knows it has the full "From" header, and
// consumes it, but not the "To" header, since the next line might
// be a continuation of it.
assert_eq!(
    ParseResults{
        status: ParseStatus::Incomplete,
        consumed: 23,
    },
    headers.parse(concat!(
        "From: joe@example.com\r\n",
        "To: sal@example.com\r\n",
    ))?
);

// So we re-send the "To" line along with the content that follows.
// At this point, `parse` knows it has the full "To" header, and
// consumes it, but not the "Subject" header, since the next line might
// be a continuation of it.
assert_eq!(
    ParseResults{
        status: ParseStatus::Incomplete,
        consumed: 21,
    },
    headers.parse(concat!(
        "To: sal@example.com\r\n",
        "Subject: Hello,\r\n",
    ))?
);

// So we re-send the "Subject" line along with the content that
// follows.  At this point, `parse` still doesn't know it has the
// full "Subject" header, so nothing is consumed.
assert_eq!(
    ParseResults{
        status: ParseStatus::Incomplete,
        consumed: 0,
    },
    headers.parse(concat!(
        "Subject: Hello,\r\n",
        " World!\r\n",
    ))?
);

// So we re-send again with even more content.  At this point,
// `parse` sees the empty line separating headers from body,
// so it can finally consume the "Subject" header as well as
// indicate that parsing the headers is complete.
assert_eq!(
    ParseResults{
        status: ParseStatus::Complete,
        consumed: 28,
    },
    headers.parse(concat!(
        "Subject: Hello,\r\n",
        " World!\r\n",
        "\r\n",
    ))?
);

Source

pub fn remove_header<N>(&mut self, name: N)
where N: AsRef<str>,

Remove all headers with the given name.

Source

pub fn set_header<N, V>(&mut self, name: N, value: V)
where N: AsRef<str>, V: Into<String>,

Add or replace a header with the given name and value. If one or more previously added headers has the same name, the first one is changed to hold the given value, and the others are removed. To add a new header without replacing or removing previously added ones with the same name, use add_header instead.

Source

pub fn set_header_multi_value<N, V>( &mut self, name: N, values: V, mode: HeaderMultiMode, )
where N: AsRef<str>, V: Into<Vec<String>>,

Add or replace one or more headers with the given name and values derived from the given vector, depending on the given mode (see HeaderMultiMode for more information). If one or more previously added headers has the same name, the first one is changed to hold the given value(s), and the others are removed. To add new headers without replacing or removing previously added ones with the same name, use add_header_multi_value instead.

Source

pub fn set_line_limit(&mut self, limit: Option<usize>)

This configures the parser and generator to constrain the lengths of header lines to no more than the given number, if any. Setting None removes any constraint.