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

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

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

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 Some(pp) = ppp.as_ref() {
    eprintln!("{:?}", pp);
    ppp.recurse()?;
}

let pile = ppp.finish();
pile.pretty_print();

Implementations

impl<'a> PacketPileParser<'a>[src]

pub fn recurse(&mut self) -> Result<()>[src]

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 Some(pp) = ppp.as_ref() {
    // Do something interesting with `pp` here.

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

let pile = ppp.finish();

pub fn next(&mut self) -> Result<()>[src]

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 Some(pp) = ppp.as_ref() {
    // Do something interesting with `pp` here.

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

let pile = ppp.finish();

pub fn recursion_depth(&self) -> Option<isize>[src]

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 Some(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();

pub fn is_done(&self) -> bool[src]

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();

pub fn finish(self) -> PacketPile[src]

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>>

pub fn is_none(&self) -> bool[src]

Like Option::is_none().

pub fn is_eof(&self) -> bool[src]

An alias for is_none().

pub fn is_some(&self) -> bool[src]

Like Option::is_some().

pub fn as_ref(&self) -> Option<&PacketParser<'a>>[src]

Like Option::as_ref().

pub fn as_mut(&mut self) -> Option<&mut PacketParser<'a>>[src]

Like Option::as_mut().

pub fn take(&mut self) -> Self[src]

Like Option::take().

self is replaced with a PacketParserEOF with default values.

Trait Implementations

impl<'a> Debug for PacketPileParser<'a>[src]

impl<'a> Deref for PacketPileParser<'a>[src]

type Target = PacketParserResult<'a>

The resulting type after dereferencing.

impl<'a> DerefMut for PacketPileParser<'a>[src]

impl<'a> Parse<'a, PacketPileParser<'a>> for PacketPileParser<'a>[src]

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

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>>[src]

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

fn from_bytes<D: AsRef<[u8]> + ?Sized>(
    data: &'a D
) -> Result<PacketPileParser<'a>>
[src]

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

impl<'a> TryFrom<PacketParserBuilder<'a>> for PacketPileParser<'a>[src]

type Error = Error

The type returned in the event of a conversion error.

fn try_from(ppb: PacketParserBuilder<'a>) -> Result<PacketPileParser<'a>>[src]

Finishes configuring the PacketParser and returns a PacketPileParser.

Auto Trait Implementations

impl<'a> !RefUnwindSafe for PacketPileParser<'a>

impl<'a> !Send for PacketPileParser<'a>

impl<'a> !Sync for PacketPileParser<'a>

impl<'a> Unpin for PacketPileParser<'a>

impl<'a> !UnwindSafe for PacketPileParser<'a>

Blanket Implementations

impl<T> Any for T where
    T: 'static + ?Sized
[src]

impl<T> Borrow<T> for T where
    T: ?Sized
[src]

impl<T> BorrowMut<T> for T where
    T: ?Sized
[src]

impl<T> From<T> for T[src]

impl<T, U> Into<U> for T where
    U: From<T>, 
[src]

impl<T, U> TryFrom<U> for T where
    U: Into<T>, 
[src]

type Error = Infallible

The type returned in the event of a conversion error.

impl<T, U> TryInto<U> for T where
    U: TryFrom<T>, 
[src]

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.