[][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 Ok(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 Ok(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 Ok(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 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();

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_eof(&self) -> bool[src]

Returns true if the result is EOF.

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

Returns true if the result is Some.

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

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

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

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

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.

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

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

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.