Struct rhymessage::MessageHeaders

pub struct MessageHeaders { /* fields omitted */ }

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

impl MessageHeaders

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.

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.

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.

#[must_use]pub fn headers(&self) -> &Vec<Header>

Borrow the list of headers.

#[must_use]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.

#[must_use]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.

#[must_use]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.

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.

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

Determine whether or not the given header is present.

#[must_use]pub fn new() -> Self

Create a new instance with no headers in it.

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",
    ))?
);

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

Remove all headers with the given name.

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.

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.

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.

Trait Implementations

impl Clone for MessageHeaders

fn clone(&self) -> MessageHeaders

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for MessageHeaders

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

Formats the value using the given formatter.

impl Default for MessageHeaders

fn default() -> MessageHeaders

Returns the "default value" for a type.

impl IntoIterator for MessageHeaders

type IntoIter = IntoIter<Header>

Which kind of iterator are we turning this into?

type Item = Header

The type of the elements being iterated over.

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<'a> IntoIterator for &'a MessageHeaders

type IntoIter = Iter<'a, Header>

Which kind of iterator are we turning this into?

type Item = &'a Header

The type of the elements being iterated over.

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.