Struct sequoia_openpgp::parse::PacketPileParser

pub struct PacketPileParser<'a> {
    pub ppr: PacketParserResult<'a>,
    // some fields omitted
}

A PacketPileParser parses an OpenPGP message with the convenience of PacketPile::from_file and the flexibility of a PacketParser.

Like PacketPile::from_file (and unlike PacketParser), a PacketPileParser parses an OpenPGP message and returns a PacketPile. But, unlike PacketPile::from_file (and like PacketParser), it allows the caller to inspect each packet as it is being parsed.

Thus, using a PacketPileParser, it is possible to decide on a per-packet basis whether to stream, buffer or drop the packet's body, whether to recurse into a container, or whether to abort processing, for example. And, PacketPileParser conveniently packs the packets into a PacketPile.

If old packets don't need to be retained, then PacketParser should be preferred. If no per-packet processing needs to be done, then PacketPile::from_file will be slightly faster.

Note: due to how lifetimes interact, it is not possible for the next() and recurse() methods to return a mutable reference to the packet (&mut Packet) that is currently being processed while continuing to support streaming operations. It is also not possible to return a mutable reference to the PacketParser. Thus, we expose the Option<PacketParser> directly to the user. However, do not directly call PacketParser::next() or PacketParser::recurse(). This will break the PacketPileParser implementation.

Examples

let mut ppp = PacketPileParser::from_bytes(message_data)?;
while ppp.recurse() {
    let pp = ppp.ppr.as_mut().unwrap();
    eprintln!("{:?}", pp);
}
let message = ppp.finish();
message.pretty_print();

Fields

ppr: PacketParserResult<'a>

The current packet.

Methods

impl<'a> PacketPileParser<'a>

pub fn recurse(&mut self) -> bool

Finishes parsing the current packet and starts parsing the next one. This function recurses, if possible.

This function finishes parsing the current packet. By default, any unread content is dropped. It then creates a new packet parser for the next packet. If the current packet is a container, this function tries to recurse into it. Otherwise, it returns the following packet.

Due to lifetime issues, this function does not return a reference to the PacketParser, but a boolean indicating whether a new packet is available. Instead, the PacketParser can be accessed as self.ppo.

pub fn next(&mut self) -> bool

Finishes parsing the current packet and starts parsing the next one. This function does not recurse.

This function finishes parsing the current packet. By default, any unread content is dropped. It then creates a new packet parser for the following packet. If the current packet is a container, this function does not recurse into the container; it skips any packets that it may contain.

Due to lifetime issues, this function does not return a reference to the PacketParser, but a boolean indicating whether a new packet is available. Instead, the PacketParser can be accessed as self.ppo.

pub fn recursion_depth(&self) -> Option<u8>

Returns the current packet's recursion depth.

A top-level packet has a recursion depth of 0. Packets in a top-level container have a recursion depth of 1. Etc.

pub fn is_done(&self) -> bool

Returns whether the message has been completely parsed.

pub fn finish(self) -> PacketPile

Finishes parsing the message and returns the assembled PacketPile.

This function can be called at any time, not only when the message has been completely parsed. If the packet sequence has not been completely parsed, this function aborts processing, and the returned PacketPile just contains those packets that were completely processed; the packet that is currently being processed is not included in the PacketPile.

Trait Implementations

impl<'a> Parse<'a, PacketPileParser<'a>> for PacketPileParser<'a>

fn from_reader<R: Read + 'a>(reader: R) -> Result<PacketPileParser<'a>>

Creates a PacketPileParser to parse the OpenPGP message stored in the io::Read object.

fn from_file<P: AsRef<Path>>(path: P) -> Result<PacketPileParser<'a>>

Creates a PacketPileParser to parse the OpenPGP message stored in the file named by path.

fn from_bytes(data: &'a [u8]) -> Result<PacketPileParser<'a>>

Creates a PacketPileParser to parse the OpenPGP message stored in the provided buffer.

impl<'a> Debug for PacketPileParser<'a>

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

Formats the value using the given formatter.