Struct sequoia_openpgp::armor::Reader

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

A filter that strips ASCII Armor from a stream of data.

Implementations

impl<'a> Reader<'a>

pub fn new<R, M>(inner: R, mode: M) -> Self where
    R: 'a + Read + Send + Sync,
    M: Into<Option<ReaderMode>>, 

Constructs a new filter for the given type of data.

ASCII Armor, designed to protect OpenPGP data in transit, has been a source of problems if the armor structure is damaged. For example, copying data manually from one program to another might introduce or drop newlines.

By default, the reader operates in robust mode. It will extract the first armored OpenPGP data block it can find, even if the armor frame is damaged, or missing.

To select strict mode, specify a kind argument. In strict mode, the reader will match on the armor frame. The reader ignores any data in front of the Armor Header Line, as long as the line the header is only prefixed by whitespace.

Examples

use std::io::{self, Read};
use sequoia_openpgp as openpgp;
use openpgp::Message;
use openpgp::armor::{Reader, ReaderMode};
use openpgp::parse::Parse;

let data = "yxJiAAAAAABIZWxsbyB3b3JsZCE="; // base64 over literal data packet

let mut cursor = io::Cursor::new(&data);
let mut reader = Reader::new(&mut cursor, ReaderMode::VeryTolerant);

let mut buf = Vec::new();
reader.read_to_end(&mut buf)?;

let message = Message::from_bytes(&buf)?;
assert_eq!(message.body().unwrap().body(),
           b"Hello world!");

Or, in strict mode:

use std::io::{self, Result, Read};
use sequoia_openpgp as openpgp;
use openpgp::armor::{Reader, ReaderMode, Kind};

let data =
    "-----BEGIN PGP ARMORED FILE-----

     SGVsbG8gd29ybGQh
     =s4Gu
     -----END PGP ARMORED FILE-----";

let mut cursor = io::Cursor::new(&data);
let mut reader = Reader::new(&mut cursor, ReaderMode::Tolerant(Some(Kind::File)));

let mut content = String::new();
reader.read_to_string(&mut content)?;
assert_eq!(content, "Hello world!");
assert_eq!(reader.kind(), Some(Kind::File));

pub fn from_reader<R, M>(reader: R, mode: M) -> Self where
    R: 'a + Read + Send + Sync,
    M: Into<Option<ReaderMode>>, 

Creates a Reader from an io::Reader.

pub fn from_file<P, M>(path: P, mode: M) -> Result<Self> where
    P: AsRef<Path>,
    M: Into<Option<ReaderMode>>, 

Creates a Reader from a file.

pub fn from_bytes<M>(bytes: &'a [u8], mode: M) -> Self where
    M: Into<Option<ReaderMode>>, 

Creates a Reader from a buffer.

pub fn kind(&self) -> Option<Kind>

Returns the kind of data this reader is for.

Useful if the kind of data is not known in advance. If the header has not been encountered yet (try reading some data first!), this function returns None.

pub fn headers(&mut self) -> Result<&[(String, String)]>

Returns the armored headers.

The tuples contain a key and a value.

Note: if a key occurs multiple times, then there are multiple entries in the vector with the same key; values with the same key are not combined.

Examples

use std::io::{self, Read};
use sequoia_openpgp as openpgp;
use openpgp::armor::{Reader, ReaderMode, Kind};

let data =
    "-----BEGIN PGP ARMORED FILE-----
     First: value
     Header: value

     SGVsbG8gd29ybGQh
     =s4Gu
     -----END PGP ARMORED FILE-----";

let mut cursor = io::Cursor::new(&data);
let mut reader = Reader::new(&mut cursor, ReaderMode::Tolerant(Some(Kind::File)));

let mut content = String::new();
reader.read_to_string(&mut content)?;
assert_eq!(reader.headers()?,
   &[("First".into(), "value".into()),
     ("Header".into(), "value".into())]);

Trait Implementations

impl BufferedReader<Cookie> for Reader<'_>

fn buffer(&self) -> &[u8]

Returns a reference to the internal buffer.

fn data(&mut self, amount: usize) -> Result<&[u8]>

Ensures that the internal buffer has at least amount bytes of data, and returns it.

fn data_hard(&mut self, amount: usize) -> Result<&[u8]>

Like data(), but returns an error if there is not at least amount bytes available.

fn consume(&mut self, amount: usize) -> &[u8]

Consumes some of the data.

fn data_consume(&mut self, amount: usize) -> Result<&[u8]>

A convenience function that combines data() and consume().

fn data_consume_hard(&mut self, amount: usize) -> Result<&[u8]>

A convenience function that effectively combines data_hard() and consume().

fn get_mut(&mut self) -> Option<&mut dyn BufferedReader<Cookie>>

Returns a mutable reference to the inner BufferedReader, if any.

fn get_ref(&self) -> Option<&dyn BufferedReader<Cookie>>

Returns a reference to the inner BufferedReader, if any.

fn into_inner<'b>(
    self: Box<Self>
) -> Option<Box<dyn BufferedReader<Cookie> + 'b>> where
    Self: 'b, 

Returns the underlying reader, if any.

fn cookie_set(&mut self, cookie: Cookie) -> Cookie

Sets the BufferedReader’s cookie and returns the old value.

fn cookie_ref(&self) -> &Cookie

Returns a reference to the BufferedReader’s cookie.

fn cookie_mut(&mut self) -> &mut Cookie

Returns a mutable reference to the BufferedReader’s cookie.

fn data_eof(&mut self) -> Result<&[u8], Error>

Returns all of the data until EOF. Like data(), this does not actually consume the data that is read.

fn eof(&mut self) -> bool

Checks whether the end of the stream is reached.

fn consummated(&mut self) -> bool

Checks whether this reader is consummated.

fn read_be_u16(&mut self) -> Result<u16, Error>

A convenience function for reading a 16-bit unsigned integer in big endian format.

fn read_be_u32(&mut self) -> Result<u32, Error>

A convenience function for reading a 32-bit unsigned integer in big endian format.

fn read_to(&mut self, terminal: u8) -> Result<&[u8], Error>

Reads until either terminal is encountered or EOF.

fn drop_until(&mut self, terminals: &[u8]) -> Result<usize, Error>

Discards the input until one of the bytes in terminals is encountered.

fn drop_through(
    &mut self,
    terminals: &[u8],
    match_eof: bool
) -> Result<(Option<u8>, usize), Error>

Discards the input until one of the bytes in terminals is encountered.

fn steal(&mut self, amount: usize) -> Result<Vec<u8, Global>, Error>

Like data_consume_hard(), but returns the data in a caller-owned buffer.

fn steal_eof(&mut self) -> Result<Vec<u8, Global>, Error>

Like steal(), but instead of stealing a fixed number of bytes, steals all of the data until the end of file.

fn drop_eof(&mut self) -> Result<bool, Error>

Like steal_eof(), but instead of returning the data, the data is discarded.

fn dump(&self, sink: &mut dyn Write) -> Result<(), Error>

A helpful debugging aid to pretty print a Buffered Reader stack.

fn as_boxed<'a>(self) -> Box<dyn BufferedReader<C> + 'a, Global> where
    Self: 'a, 

Boxes the reader.

impl<'a> Debug for Reader<'a>

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

Formats the value using the given formatter.

impl<'a> Display for Reader<'a>

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

Formats the value using the given formatter.

impl Read for Reader<'_>

fn read(&mut self, buf: &mut [u8]) -> Result<usize>

Pull some bytes from this source into the specified buffer, returning how many bytes were read.

fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> Result<usize, Error>

Like read, except that it reads into a slice of buffers.

fn is_read_vectored(&self) -> bool

🔬 This is a nightly-only experimental API. (can_vector)

Determines if this Reader has an efficient read_vectored implementation.

unsafe fn initializer(&self) -> Initializer

🔬 This is a nightly-only experimental API. (read_initializer)

Determines if this Reader can work with buffers of uninitialized memory.

fn read_to_end(&mut self, buf: &mut Vec<u8, Global>) -> Result<usize, Error>

Read all bytes until EOF in this source, placing them into buf.

fn read_to_string(&mut self, buf: &mut String) -> Result<usize, Error>

Read all bytes until EOF in this source, appending them to buf.

fn read_exact(&mut self, buf: &mut [u8]) -> Result<(), Error>

Read the exact number of bytes required to fill buf.

fn by_ref(&mut self) -> &mut Self

Creates a “by reference” adaptor for this instance of Read.

fn bytes(self) -> Bytes<Self>

Transforms this Read instance to an Iterator over its bytes.

fn chain<R>(self, next: R) -> Chain<Self, R> where
    R: Read, 

Creates an adaptor which will chain this stream with another.

fn take(self, limit: u64) -> Take<Self>

Creates an adaptor which will read at most limit bytes from it.