Struct sequoia_openpgp::parse::PacketPileParser[][src]

pub struct PacketPileParser<'a> { /* fields omitted */ }
Expand description

Parses an OpenPGP stream 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.

Examples

These examples demonstrate how to process packet bodies by parsing the simplest possible OpenPGP message containing just a single literal data packet with the body “Hello world.”. There are three options. First, the body can be dropped. Second, it can be buffered. Lastly, the body can be streamed. In general, streaming should be preferred, because it avoids buffering in Sequoia.

This example demonstrates simply ignoring the packet body:

use sequoia_openpgp as openpgp;
use openpgp::Packet;
use openpgp::parse::{Parse, PacketPileParser};

// By default, the `PacketPileParser` will drop packet bodies.
let mut ppp =
    PacketPileParser::from_bytes(
        b"\xcb\x12b\x00\x00\x00\x00\x00Hello world.")?;
while ppp.is_some() {
    // Start parsing the next packet, recursing.
    ppp.recurse()?;
}

let pile = ppp.finish();
// Process the packet.
if let Some(Packet::Literal(literal)) = pile.path_ref(&[0]) {
    // The body was dropped.
    assert_eq!(literal.body(), b"");
} else {
    unreachable!("We know it is a literal packet.");
}

This example demonstrates how the body can be buffered by configuring the PacketPileParser to buffer all packet bodies:

use std::convert::TryFrom;

use sequoia_openpgp as openpgp;
use openpgp::Packet;
use openpgp::parse::{Parse, PacketPileParser, PacketParserBuilder};

// By default, the `PacketPileParser` will drop packet bodies.
// Use a `PacketParserBuilder` to change that.
let mut ppb =
    PacketParserBuilder::from_bytes(
        b"\xcb\x12b\x00\x00\x00\x00\x00Hello world.")?
    .buffer_unread_content();
let mut ppp = PacketPileParser::try_from(ppb)?;
while ppp.is_some() {
    // Start parsing the next packet, recursing.
    ppp.recurse()?;
}

let pile = ppp.finish();
// Process the packet.
if let Some(Packet::Literal(literal)) = pile.path_ref(&[0]) {
    // The body was buffered.
    assert_eq!(literal.body(), b"Hello world.");
} else {
    unreachable!("We know it is a literal packet.");
}

This example demonstrates how the body can be buffered by buffering an individual packet:

use sequoia_openpgp as openpgp;
use openpgp::Packet;
use openpgp::parse::{Parse, PacketPileParser};

// By default, the `PacketPileParser` will drop packet bodies.
let mut ppp =
    PacketPileParser::from_bytes(
        b"\xcb\x12b\x00\x00\x00\x00\x00Hello world.")?;
while let Ok(pp) = ppp.as_mut() {
    if let Packet::Literal(_) = pp.packet {
        // Buffer this packet's body.
        pp.buffer_unread_content()?;
    }

    // Start parsing the next packet, recursing.
    ppp.recurse()?;
}

let pile = ppp.finish();
// Process the packet.
if let Some(Packet::Literal(literal)) = pile.path_ref(&[0]) {
    // The body was buffered.
    assert_eq!(literal.body(), b"Hello world.");
} else {
    unreachable!("We know it is a literal packet.");
}

This example demonstrates how to stream the packet body:

use std::io::Read;

use sequoia_openpgp as openpgp;
use openpgp::Packet;
use openpgp::parse::{Parse, PacketPileParser};

// By default, the `PacketPileParser` will drop packet bodies.
let mut ppp =
    PacketPileParser::from_bytes(
        b"\xcb\x12b\x00\x00\x00\x00\x00Hello world.")?;
while let Ok(pp) = ppp.as_mut() {
    if let Packet::Literal(_) = pp.packet {
        // Stream the body.
        let mut buf = Vec::new();
        pp.read_to_end(&mut buf)?;
        assert_eq!(buf, b"Hello world.");
    }

    // Start parsing the next packet, recursing.
    ppp.recurse()?;
}

let pile = ppp.finish();
// Process the packet.
if let Some(Packet::Literal(literal)) = pile.path_ref(&[0]) {
    // The body was streamed, not buffered.
    assert_eq!(literal.body(), b"");
} else {
    unreachable!("We know it is a literal packet.");
}

Implementations

Finishes parsing the current packet and starts parsing the next one, recursing if possible.

This method is similar to the next() method (see that method for more details), but if the current packet is a container (and we haven’t reached the maximum recursion depth, and the user hasn’t started reading the packet’s contents), we recurse into the container, and return a PacketParser for its first child. Otherwise, we return the next packet in the packet stream. If this function recurses, then the new packet’s recursion depth will be last_recursion_depth() + 1; because we always visit interior nodes, we can’t recurse more than one level at a time.

Examples
use sequoia_openpgp as openpgp;
use openpgp::parse::{Parse, PacketPileParser};

// Parse a message.
let message_data: &[u8] = // ...
let mut ppp = PacketPileParser::from_bytes(message_data)?;
while let Ok(pp) = ppp.as_ref() {
    // Do something interesting with `pp` here.

    // Start parsing the next packet, recursing.
    ppp.recurse()?;
}

let pile = ppp.finish();

Finishes parsing the current packet and starts parsing the next one.

This function finishes parsing the current packet. By default, any unread content is dropped. (See PacketParsererBuilder for how to configure this.) It then creates a new packet parser for the next packet. If the current packet is a container, this function does not recurse into the container, but skips any packets it contains. To recurse into the container, use the recurse() method.

Examples
use sequoia_openpgp as openpgp;
use openpgp::parse::{Parse, PacketPileParser};

// Parse a message.
let message_data: &[u8] = // ...
let mut ppp = PacketPileParser::from_bytes(message_data)?;
while let Ok(pp) = ppp.as_ref() {
    // Do something interesting with `pp` here.

    // Start parsing the next packet.
    ppp.next()?;
}

let pile = ppp.finish();

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.

Examples
use sequoia_openpgp as openpgp;
use openpgp::Packet;
use openpgp::parse::{Parse, PacketPileParser};

// Parse a simple compressed message.
let message_data: &[u8] = // ...
let mut ppp = PacketPileParser::from_bytes(message_data)?;
while let Ok(pp) = ppp.as_ref() {
    match pp.packet {
        Packet::CompressedData(_) =>
            assert_eq!(ppp.recursion_depth(), Some(0)),
        Packet::Literal(_) =>
            assert_eq!(ppp.recursion_depth(), Some(1)),
        _ => unreachable!(),
    }

    // Alternatively, the recursion depth can be queried
    // from the packet parser.
    assert_eq!(ppp.recursion_depth(), Some(pp.recursion_depth()));

    // Start parsing the next packet.
    ppp.next()?;
}

let pile = ppp.finish();

Returns whether the message has been completely parsed.

Examples
use sequoia_openpgp as openpgp;
use openpgp::Packet;
use openpgp::parse::{Parse, PacketPileParser};

// Parse a message.
let message_data: &[u8] = // ...
let mut ppp = PacketPileParser::from_bytes(message_data)?;
while ppp.is_some() {
    // Start parsing the next packet.
    ppp.next()?;
}

assert!(ppp.is_done());
let pile = ppp.finish();

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.

Examples
use sequoia_openpgp as openpgp;
use openpgp::Packet;
use openpgp::parse::{Parse, PacketPileParser};

// Parse a message.
let message_data: &[u8] = // ...
let mut ppp = PacketPileParser::from_bytes(message_data)?;
ppp.next()?;

let pp = ppp.finish();
assert_eq!(pp.children().count(), 1);

Methods from Deref<Target = PacketParserResult<'a>>

Returns true if the result is EOF.

Returns true if the result is Some.

Converts from PacketParserResult to Result<&PacketParser, &PacketParserEOF>.

Produces a new Result, containing references into the original PacketParserResult, leaving the original in place.

Converts from PacketParserResult to Result<&mut PacketParser, &mut PacketParserEOF>.

Produces a new Result, containing mutable references into the original PacketParserResult, leaving the original in place.

Takes the value out of the PacketParserResult, leaving a EOF in its place.

The EOF left in place carries a PacketParserEOF with default values.

Trait Implementations

Formats the value using the given formatter. Read more

The resulting type after dereferencing.

Dereferences the value.

Mutably dereferences the value.

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

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

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

Finishes configuring the PacketParser and returns a PacketPileParser.

The type returned in the event of a conversion error.

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Performs the conversion.

Performs the conversion.

Should always be Self

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.