Botan::Pipe Class Reference

#include <pipe.h>

Inheritance diagram for Botan::Pipe:

Classes
struct	Invalid_Message_Number

Public Types
typedef size_t	message_id

Public Member Functions
void	append (Filter *filt)
bool	check_available (size_t n)
bool	check_available_msg (size_t n, message_id msg)
size_t	default_msg () const
size_t	discard_next (size_t N)
void	end_msg ()
bool	end_of_data () const
virtual std::string	id () const
message_id	message_count () const
size_t	peek (byte &output, size_t offset, message_id msg=DEFAULT_MESSAGE) const
size_t	peek (byte output[], size_t length, size_t offset) const
size_t	peek (byte output[], size_t length, size_t offset, message_id msg) const
size_t	peek_byte (byte &out) const
	Pipe (Filter *=0, Filter *=0, Filter *=0, Filter *=0)
	Pipe (Filter *filters[], size_t count)
void	pop ()
void	prepend (Filter *filt)
void	process_msg (const byte in[], size_t length)
void	process_msg (const MemoryRegion< byte > &in)
void	process_msg (const std::string &in)
void	process_msg (DataSource &in)
size_t	read (byte &output, message_id msg=DEFAULT_MESSAGE)
size_t	read (byte output[], size_t length)
size_t	read (byte output[], size_t length, message_id msg)
SecureVector< byte >	read_all (message_id msg=DEFAULT_MESSAGE)
std::string	read_all_as_string (message_id=DEFAULT_MESSAGE)
size_t	read_byte (byte &out)
size_t	remaining (message_id msg=DEFAULT_MESSAGE) const
void	reset ()
void	set_default_msg (message_id msg)
void	start_msg ()
void	write (byte in)
void	write (const byte in[], size_t length)
void	write (const MemoryRegion< byte > &in)
void	write (const std::string &in)
void	write (DataSource &in)
	~Pipe ()

Static Public Attributes
static const message_id	DEFAULT_MESSAGE
static const message_id	LAST_MESSAGE

Detailed Description

This class represents pipe objects. A set of filters can be placed into a pipe, and information flows through the pipe until it reaches the end, where the output is collected for retrieval. If you're familiar with the Unix shell environment, this design will sound quite familiar.

Definition at line 25 of file pipe.h.

Member Typedef Documentation

message_id

typedef size_t Botan::Pipe::message_id

An opaque type that identifies a message in this Pipe

Definition at line 31 of file pipe.h.

Constructor & Destructor Documentation

Pipe() [1/2]

Botan::Pipe::Pipe	(	Filter *	f1 = 0,
		Filter *	f2 = 0,
		Filter *	f3 = 0,
		Filter *	f4 = 0 )

Construct a Pipe of up to four filters. The filters are set up in the same order as the arguments.

Definition at line 34 of file pipe.cpp.

   {
   init();
   append(f1);
   append(f2);
   append(f3);
   append(f4);
   }

References append().

Pipe() [2/2]

Botan::Pipe::Pipe	(	Filter *	filters[],
		size_t	count )

Construct a Pipe from range of filters passed as an array

Parameters

filters	the set of filters to use
count	the number of elements in filters

Definition at line 46 of file pipe.cpp.

   {
   init();
   for(size_t j = 0; j != count; ++j)
      append(filter_array[j]);
   }

References append().

~Pipe()

Botan::Pipe::~Pipe

(

)

Definition at line 56 of file pipe.cpp.

   {
   destruct(pipe);
   delete outputs;
   }

Member Function Documentation

append()

void Botan::Pipe::append

(

Filter *

filt

)

Insert a new filter at the back of the pipe

Parameters

filt	the new filter to insert

Definition at line 215 of file pipe.cpp.

   {
   if(inside_msg)
      throw Invalid_State("Cannot append to a Pipe while it is processing");
   if(!filter)
      return;
   if(dynamic_cast<SecureQueue*>(filter))
      throw Invalid_Argument("Pipe::append: SecureQueue cannot be used");
   if(filter->owned)
      throw Invalid_Argument("Filters cannot be shared among multiple Pipes");
 
   filter->owned = true;
 
   if(!pipe) pipe = filter;
   else      pipe->attach(filter);
   }

References Botan::Invalid_State::Invalid_State().

Referenced by Pipe(), and Pipe().

check_available()

bool Botan::Pipe::check_available ( size_t n )

virtual

Implements Botan::DataSource.

Definition at line 143 of file pipe_rw.cpp.

   {
   return (n <= remaining(DEFAULT_MESSAGE));
   }

References DEFAULT_MESSAGE, and remaining().

check_available_msg()

bool Botan::Pipe::check_available_msg	(	size_t	n,
		message_id	msg )

Definition at line 148 of file pipe_rw.cpp.

   {
   return (n <= remaining(msg));
   }

References remaining().

default_msg()

size_t Botan::Pipe::default_msg ( ) const

inline

Returns

currently set default message

Definition at line 209 of file pipe.h.

{ return default_read; }

Referenced by read_all(), and read_all_as_string().

discard_next()

size_t Botan::DataSource::discard_next ( size_t N )

inherited

Discard the next N bytes of the data

Parameters

N	the number of bytes to discard

Returns

number of bytes actually discarded

Definition at line 35 of file data_src.cpp.

   {
   size_t discarded = 0;
   byte dummy;
   for(size_t j = 0; j != n; ++j)
      discarded += read_byte(dummy);
   return discarded;
   }

References read_byte().

Referenced by check_available().

end_msg()

void Botan::Pipe::end_msg

(

)

End the current message.

Definition at line 166 of file pipe.cpp.

   {
   if(!inside_msg)
      throw Invalid_State("Pipe::end_msg: Message was already ended");
   pipe->finish_msg();
   clear_endpoints(pipe);
   if(dynamic_cast<Null_Filter*>(pipe))
      {
      delete pipe;
      pipe = 0;
      }
   inside_msg = false;
 
   outputs->retire();
   }

References Botan::Invalid_State::Invalid_State().

Referenced by Botan::EAC_Signed_Object::BER_encode(), Botan::check_passhash9(), Botan::PEM_Code::decode(), Botan::generate_passhash9(), Botan::EAC_Signed_Object::PEM_encode(), Botan::PGP_decode(), process_msg(), and process_msg().

end_of_data()

bool Botan::Pipe::end_of_data ( ) const

virtual

Test whether this pipe has any data that can be read from.

Returns

true if there is more data to read, false otherwise

Implements Botan::DataSource.

Definition at line 98 of file pipe.cpp.

   {
   return (remaining() == 0);
   }

References remaining().

id()

virtual std::string Botan::DataSource::id ( ) const

inlinevirtualinherited

return the id of this data source

Returns

std::string representing the id of this data source

Reimplemented in Botan::DataSource_Command, and Botan::DataSource_Stream.

Definition at line 57 of file data_src.h.

{ return ""; }

message_count()

Pipe::message_id Botan::Pipe::message_count

(

)

const

Get the number of messages the are in this pipe.

Returns

number of messages the are in this pipe

Definition at line 282 of file pipe.cpp.

   {
   return outputs->message_count();
   }

Referenced by set_default_msg().

peek() [1/3]

size_t Botan::Pipe::peek	(	byte &	output,
		size_t	offset,
		message_id	msg = DEFAULT_MESSAGE ) const

Read a single byte from the specified message but do not modify the internal offset. Consecutive calls to peek() will return portions of the message starting at the same position.

Parameters

output	the byte to write the peeked message byte to
offset	the offset from the current position in message
msg	the number identifying the message to peek from

Returns

number of bytes actually peeked and written into output

Definition at line 173 of file pipe_rw.cpp.

   {
   return peek(&out, 1, offset, msg);
   }

References peek().

peek() [2/3]

size_t Botan::Pipe::peek ( byte output[], size_t length, size_t offset ) const

virtual

Read from the default message but do not modify the internal offset. Consecutive calls to peek() will return portions of the message starting at the same position.

Parameters

output	the byte array to write the peeked message part to
length	the length of the byte array output
offset	the offset from the current position in message

Returns

number of bytes actually peeked and written into output

Implements Botan::DataSource.

Definition at line 165 of file pipe_rw.cpp.

   {
   return peek(output, length, offset, DEFAULT_MESSAGE);
   }

References DEFAULT_MESSAGE, and peek().

Referenced by peek(), and peek().

peek() [3/3]

size_t Botan::Pipe::peek	(	byte	output[],
		size_t	length,
		size_t	offset,
		message_id	msg ) const

Read from the specified message but do not modify the internal offset. Consecutive calls to peek() will return portions of the message starting at the same position.

Parameters

output	the byte array to write the peeked message part to
length	the length of the byte array output
offset	the offset from the current position in message
msg	the number identifying the message to peek from

Returns

number of bytes actually peeked and written into output

Definition at line 156 of file pipe_rw.cpp.

   {
   return outputs->peek(output, length, offset, get_message_no("peek", msg));
   }

peek_byte()

size_t Botan::DataSource::peek_byte ( byte & out ) const

inherited

Peek at one byte.

Parameters

out	an output byte

Returns

length in bytes that was actually read and put into out

Definition at line 27 of file data_src.cpp.

   {
   return peek(&out, 1, 0);
   }

References peek().

Referenced by check_available(), and Botan::ASN1::maybe_BER().

pop()

void Botan::Pipe::pop

(

)

Remove the first filter at the front of the pipe.

Definition at line 255 of file pipe.cpp.

   {
   if(inside_msg)
      throw Invalid_State("Cannot pop off a Pipe while it is processing");
 
   if(!pipe)
      return;
 
   if(pipe->total_ports() > 1)
      throw Invalid_State("Cannot pop off a Filter with multiple ports");
 
   Filter* f = pipe;
   size_t owns = f->owns();
   pipe = pipe->next[0];
   delete f;
 
   while(owns--)
      {
      f = pipe;
      pipe = pipe->next[0];
      delete f;
      }
   }

References Botan::Invalid_State::Invalid_State().

prepend()

void Botan::Pipe::prepend

(

Filter *

filt

)

Insert a new filter at the front of the pipe

Parameters

filt	the new filter to insert

Definition at line 235 of file pipe.cpp.

   {
   if(inside_msg)
      throw Invalid_State("Cannot prepend to a Pipe while it is processing");
   if(!filter)
      return;
   if(dynamic_cast<SecureQueue*>(filter))
      throw Invalid_Argument("Pipe::prepend: SecureQueue cannot be used");
   if(filter->owned)
      throw Invalid_Argument("Filters cannot be shared among multiple Pipes");
 
   filter->owned = true;
 
   if(pipe) filter->attach(pipe);
   pipe = filter;
   }

References Botan::Invalid_State::Invalid_State().

process_msg() [1/4]

void Botan::Pipe::process_msg	(	const byte	in[],
		size_t	length )

Perform start_msg(), write() and end_msg() sequentially.

Parameters

in	the byte array containing the data to write
length	the length of the byte array to write

Definition at line 116 of file pipe.cpp.

   {
   start_msg();
   write(input, length);
   end_msg();
   }

References end_msg(), start_msg(), and write().

Referenced by Botan::aont_package(), Botan::aont_unpackage(), Botan::PKCS8::BER_encode(), Botan::CMS_Encoder::compress(), Botan::CryptoBox::decrypt(), Botan::PEM_Code::encode(), Botan::CryptoBox::encrypt(), Botan::PGP_encode(), process_msg(), and process_msg().

process_msg() [2/4]

void Botan::Pipe::process_msg

(

const MemoryRegion< byte > &

in

)

Perform start_msg(), write() and end_msg() sequentially.

Parameters

in	the MemoryRegion containing the data to write

Definition at line 126 of file pipe.cpp.

   {
   process_msg(&input[0], input.size());
   }

References process_msg(), and Botan::MemoryRegion< T >::size().

process_msg() [3/4]

void Botan::Pipe::process_msg

(

const std::string &

in

)

Perform start_msg(), write() and end_msg() sequentially.

Parameters

in	the string containing the data to write

Definition at line 134 of file pipe.cpp.

   {
   process_msg(reinterpret_cast<const byte*>(input.data()), input.length());
   }

References process_msg().

process_msg() [4/4]

void Botan::Pipe::process_msg

(

DataSource &

in

)

Perform start_msg(), write() and end_msg() sequentially.

Parameters

in	the DataSource providing the data to write

Definition at line 142 of file pipe.cpp.

   {
   start_msg();
   write(input);
   end_msg();
   }

References Botan::DataSource::DataSource(), end_msg(), start_msg(), and write().

read() [1/3]

size_t Botan::Pipe::read	(	byte &	output,
		message_id	msg = DEFAULT_MESSAGE )

Read a single byte from the pipe. Moves the internal offset so that every call to read will return a new portion of the message.

Parameters

output	the byte to write the result to
msg	the message to read from

Returns

number of bytes actually read into output

Definition at line 97 of file pipe_rw.cpp.

   {
   return read(&out, 1, msg);
   }

References read().

read() [2/3]

size_t Botan::Pipe::read ( byte output[], size_t length )

virtual

Read the default message from the pipe. Moves the internal offset so that every call to read will return a new portion of the message.

Parameters

output	the byte array to write the read bytes to
length	the length of the byte array output

Returns

number of bytes actually read into output

Implements Botan::DataSource.

Definition at line 89 of file pipe_rw.cpp.

   {
   return read(output, length, DEFAULT_MESSAGE);
   }

References DEFAULT_MESSAGE, and read().

Referenced by Botan::aont_package(), Botan::aont_unpackage(), Botan::CryptoBox::decrypt(), Botan::CryptoBox::encrypt(), Botan::operator<<(), Botan::operator<<(), read(), read(), read_all(), and read_all_as_string().

read() [3/3]

size_t Botan::Pipe::read	(	byte	output[],
		size_t	length,
		message_id	msg )

Read a specified message from the pipe. Moves the internal offset so that every call to read will return a new portion of the message.

Parameters

output	the byte array to write the read bytes to
length	the length of the byte array output
msg	the number identifying the message to read from

Returns

number of bytes actually read into output

Definition at line 81 of file pipe_rw.cpp.

   {
   return outputs->read(output, length, get_message_no("read", msg));
   }

read_all()

SecureVector< byte > Botan::Pipe::read_all

(

message_id

msg = DEFAULT_MESSAGE

)

Read the full contents of the pipe.

Parameters

msg	the number identifying the message to read from

Returns

SecureVector holding the contents of the pipe

Definition at line 105 of file pipe_rw.cpp.

   {
   msg = ((msg != DEFAULT_MESSAGE) ? msg : default_msg());
   SecureVector<byte> buffer(remaining(msg));
   size_t got = read(&buffer[0], buffer.size(), msg);
   buffer.resize(got);
   return buffer;
   }

References DEFAULT_MESSAGE, default_msg(), read(), remaining(), Botan::MemoryRegion< T >::resize(), and Botan::MemoryRegion< T >::size().

Referenced by Botan::EAC_Signed_Object::BER_encode(), Botan::PKCS8::BER_encode(), Botan::check_passhash9(), Botan::CMS_Encoder::compress(), Botan::PEM_Code::decode(), and Botan::PGP_decode().

read_all_as_string()

std::string Botan::Pipe::read_all_as_string

(

message_id

msg = DEFAULT_MESSAGE

)

Read the full contents of the pipe.

Parameters

msg	the number identifying the message to read from

Returns

string holding the contents of the pipe

Definition at line 117 of file pipe_rw.cpp.

   {
   msg = ((msg != DEFAULT_MESSAGE) ? msg : default_msg());
   SecureVector<byte> buffer(DEFAULT_BUFFERSIZE);
   std::string str;
   str.reserve(remaining(msg));
 
   while(true)
      {
      size_t got = read(&buffer[0], buffer.size(), msg);
      if(got == 0)
         break;
      str.append(reinterpret_cast<const char*>(&buffer[0]), got);
      }
 
   return str;
   }

References DEFAULT_MESSAGE, default_msg(), read(), remaining(), and Botan::MemoryRegion< T >::size().

Referenced by Botan::CryptoBox::decrypt(), Botan::PEM_Code::encode(), Botan::generate_passhash9(), Botan::EAC_Signed_Object::PEM_encode(), Botan::PGP_decode(), and Botan::PGP_encode().

read_byte()

size_t Botan::DataSource::read_byte ( byte & out )

inherited

Read one byte.

Parameters

out	the byte to read to

Returns

length in bytes that was actually read and put into out

Definition at line 19 of file data_src.cpp.

   {
   return read(&out, 1);
   }

References read().

Referenced by check_available(), Botan::PEM_Code::decode(), discard_next(), and Botan::PGP_decode().

remaining()

size_t Botan::Pipe::remaining

(

message_id

msg = DEFAULT_MESSAGE

)

const

Find out how many bytes are ready to read.

Parameters

msg	the number identifying the message for which the information is desired

Returns

number of bytes that can still be read

Definition at line 138 of file pipe_rw.cpp.

   {
   return outputs->remaining(get_message_no("remaining", msg));
   }

Referenced by Botan::aont_package(), Botan::aont_unpackage(), check_available(), check_available_msg(), Botan::CryptoBox::encrypt(), end_of_data(), Botan::operator<<(), Botan::operator<<(), read_all(), and read_all_as_string().

reset()

void Botan::Pipe::reset

(

)

Reset this pipe to an empty pipe.

Definition at line 76 of file pipe.cpp.

   {
   destruct(pipe);
   pipe = 0;
   inside_msg = false;
   }

set_default_msg()

void Botan::Pipe::set_default_msg

(

message_id

msg

)

Set the default message

Parameters

msg	the number identifying the message which is going to be the new default message

Definition at line 106 of file pipe.cpp.

   {
   if(msg >= message_count())
      throw Invalid_Argument("Pipe::set_default_msg: msg number is too high");
   default_read = msg;
   }

References message_count().

start_msg()

void Botan::Pipe::start_msg

(

)

Start a new message in the pipe. A potential other message in this pipe must be closed with end_msg() before this function may be called.

Definition at line 152 of file pipe.cpp.

   {
   if(inside_msg)
      throw Invalid_State("Pipe::start_msg: Message was already started");
   if(pipe == 0)
      pipe = new Null_Filter;
   find_endpoints(pipe);
   pipe->new_msg();
   inside_msg = true;
   }

References Botan::Invalid_State::Invalid_State().

Referenced by Botan::EAC_Signed_Object::BER_encode(), Botan::check_passhash9(), Botan::PEM_Code::decode(), Botan::generate_passhash9(), Botan::EAC_Signed_Object::PEM_encode(), Botan::PGP_decode(), process_msg(), and process_msg().

write() [1/5]

void Botan::Pipe::write

(

byte

in

)

Write input to the pipe, i.e. to its first filter.

Parameters

in	a single byte to be written

Definition at line 60 of file pipe_rw.cpp.

   {
   write(&input, 1);
   }

References write().

write() [2/5]

void Botan::Pipe::write	(	const byte	in[],
		size_t	length )

Write input to the pipe, i.e. to its first filter.

Parameters

in	the byte array to write
length	the length of the byte array in

Definition at line 34 of file pipe_rw.cpp.

   {
   if(!inside_msg)
      throw Invalid_State("Cannot write to a Pipe while it is not processing");
   pipe->write(input, length);
   }

References Botan::Invalid_State::Invalid_State().

Referenced by Botan::check_passhash9(), Botan::PEM_Code::decode(), Botan::EAC1_1_ADO::encode(), Botan::EAC1_1_gen_CVC< Derived >::encode(), Botan::X509_Object::encode(), Botan::generate_passhash9(), Botan::operator>>(), Botan::operator>>(), Botan::PGP_decode(), process_msg(), process_msg(), write(), write(), write(), and write().

write() [3/5]

void Botan::Pipe::write

(

const MemoryRegion< byte > &

in

)

Write input to the pipe, i.e. to its first filter.

Parameters

in	the MemoryRegion containing the data to write

Definition at line 44 of file pipe_rw.cpp.

   {
   write(&input[0], input.size());
   }

References Botan::MemoryRegion< T >::size(), and write().

write() [4/5]

void Botan::Pipe::write

(

const std::string &

in

)

Write input to the pipe, i.e. to its first filter.

Parameters

in	the string containing the data to write

Definition at line 52 of file pipe_rw.cpp.

   {
   write(reinterpret_cast<const byte*>(str.data()), str.size());
   }

References write().

write() [5/5]

void Botan::Pipe::write

(

DataSource &

in

)

Write input to the pipe, i.e. to its first filter.

Parameters

in	the DataSource to read the data from

Definition at line 68 of file pipe_rw.cpp.

   {
   SecureVector<byte> buffer(DEFAULT_BUFFERSIZE);
   while(!source.end_of_data())
      {
      size_t got = source.read(&buffer[0], buffer.size());
      write(&buffer[0], got);
      }
   }

References Botan::DataSource::DataSource(), Botan::DataSource::end_of_data(), Botan::DataSource::read(), Botan::MemoryRegion< T >::size(), and write().

Member Data Documentation

DEFAULT_MESSAGE

const Pipe::message_id Botan::Pipe::DEFAULT_MESSAGE

static

Initial value:

                                          =
static_cast<Pipe::message_id>(-1)

A meta-id for the default message (set with set_default_msg)

Definition at line 57 of file pipe.h.

Referenced by check_available(), peek(), read(), read_all(), and read_all_as_string().

LAST_MESSAGE

const Pipe::message_id Botan::Pipe::LAST_MESSAGE

static

Initial value:

                                       =
static_cast<Pipe::message_id>(-2)

A meta-id for whatever the last message is

Definition at line 52 of file pipe.h.

Referenced by Botan::Record_Reader::get_record().

---

The documentation for this class was generated from the following files:

• src/filters/pipe.h
• src/filters/pipe.cpp
• src/filters/pipe_rw.cpp