Botan  1.11.15
Classes | Public Types | Public Member Functions | Static Public Attributes
Botan::Pipe Class Reference

#include <pipe.h>

Inheritance diagram for Botan::Pipe:
Botan::DataSource

List of all members.

Classes

struct  Invalid_Message_Number

Public Types

typedef size_t message_id

Public Member Functions

void append (Filter *filt)
size_t default_msg () const
size_t discard_next (size_t N)
void end_msg ()
bool end_of_data () const
size_t get_bytes_read () const
size_t get_bytes_read (message_id msg=DEFAULT_MESSAGE) const
virtual std::string id () const
message_id message_count () const
Pipeoperator= (const Pipe &)
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 &output, size_t offset, message_id msg=DEFAULT_MESSAGE) const
size_t peek_byte (byte &out) const
 Pipe (Filter *=nullptr, Filter *=nullptr, Filter *=nullptr, Filter *=nullptr)
 Pipe (std::initializer_list< Filter * > filters)
 Pipe (const Pipe &)
void pop ()
void prepend (Filter *filt)
void process_msg (const byte in[], size_t length)
void process_msg (const secure_vector< byte > &in)
void process_msg (const std::vector< byte > &in)
void process_msg (const std::string &in)
void process_msg (DataSource &in)
size_t read (byte output[], size_t length)
size_t read (byte output[], size_t length, message_id msg)
size_t read (byte &output, message_id msg=DEFAULT_MESSAGE)
secure_vector< byteread_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 (const byte in[], size_t length)
void write (const secure_vector< byte > &in)
void write (const std::vector< byte > &in)
void write (const std::string &in)
void write (DataSource &in)
void write (byte 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 27 of file pipe.h.


Member Typedef Documentation

typedef size_t Botan::Pipe::message_id

An opaque type that identifies a message in this Pipe

Definition at line 33 of file pipe.h.


Constructor & Destructor Documentation

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

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.

References append().

   {
   init();
   append(f1);
   append(f2);
   append(f3);
   append(f4);
   }
Botan::Pipe::Pipe ( std::initializer_list< Filter * >  filters)

Construct a Pipe from a list of filters

Parameters:
filtersthe set of filters to use

Definition at line 46 of file pipe.cpp.

References append().

   {
   init();

   for(auto i = args.begin(); i != args.end(); ++i)
      append(*i);
   }
Botan::Pipe::Pipe ( const Pipe )

Definition at line 57 of file pipe.cpp.

   {
   destruct(pipe);
   delete outputs;
   }

Member Function Documentation

void Botan::Pipe::append ( Filter filt)

Insert a new filter at the back of the pipe

Parameters:
filtthe new filter to insert

Definition at line 221 of file pipe.cpp.

Referenced by Pipe().

   {
   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);
   }
size_t Botan::Pipe::default_msg ( ) const [inline]
Returns:
currently set default message

Definition at line 232 of file pipe.h.

Referenced by read_all(), and read_all_as_string().

{ return default_read; }
size_t Botan::DataSource::discard_next ( size_t  N) [inherited]

Discard the next N bytes of the data

Parameters:
Nthe number of bytes to discard
Returns:
number of bytes actually discarded

Definition at line 35 of file data_src.cpp.

References n, and Botan::DataSource::read_byte().

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

End the current message.

Definition at line 172 of file pipe.cpp.

References Botan::Output_Buffers::retire().

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

   {
   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 = nullptr;
      }
   inside_msg = false;

   outputs->retire();
   }
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 99 of file pipe.cpp.

References remaining().

   {
   return (remaining() == 0);
   }
size_t Botan::Pipe::get_bytes_read ( ) const [virtual]
Returns:
the number of bytes read from the default message.

Implements Botan::DataSource.

Definition at line 161 of file pipe_rw.cpp.

References DEFAULT_MESSAGE, and Botan::Output_Buffers::get_bytes_read().

   {
   return outputs->get_bytes_read(DEFAULT_MESSAGE);
   }
Returns:
the number of bytes read from the specified message.

Definition at line 166 of file pipe_rw.cpp.

References Botan::Output_Buffers::get_bytes_read().

   {
   return outputs->get_bytes_read(msg);
   }
virtual std::string Botan::DataSource::id ( ) const [inline, virtual, inherited]

return the id of this data source

Returns:
std::string representing the id of this data source

Reimplemented in Botan::DataSource_Stream.

Definition at line 58 of file data_src.h.

{ return ""; }

Get the number of messages the are in this pipe.

Returns:
number of messages the are in this pipe

Definition at line 288 of file pipe.cpp.

References Botan::Output_Buffers::message_count().

Referenced by set_default_msg().

   {
   return outputs->message_count();
   }
Pipe& Botan::Pipe::operator= ( const Pipe )
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:
outputthe byte array to write the peeked message part to
lengththe length of the byte array output
offsetthe offset from the current position in message
Returns:
number of bytes actually peeked and written into output

Implements Botan::DataSource.

Definition at line 148 of file pipe_rw.cpp.

References DEFAULT_MESSAGE.

Referenced by peek().

   {
   return peek(output, length, offset, DEFAULT_MESSAGE);
   }
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:
outputthe byte array to write the peeked message part to
lengththe length of the byte array output
offsetthe offset from the current position in message
msgthe number identifying the message to peek from
Returns:
number of bytes actually peeked and written into output

Definition at line 139 of file pipe_rw.cpp.

References Botan::Output_Buffers::peek().

   {
   return outputs->peek(output, length, offset, get_message_no("peek", msg));
   }
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:
outputthe byte to write the peeked message byte to
offsetthe offset from the current position in message
msgthe 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.

References peek().

   {
   return peek(&out, 1, offset, msg);
   }
size_t Botan::DataSource::peek_byte ( byte out) const [inherited]

Peek at one byte.

Parameters:
outan output byte
Returns:
length in bytes that was actually read and put into out

Definition at line 27 of file data_src.cpp.

References Botan::DataSource::peek().

Referenced by Botan::ASN1::maybe_BER().

   {
   return peek(&out, 1, 0);
   }
void Botan::Pipe::pop ( )

Remove the first filter at the front of the pipe.

Definition at line 261 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;
      }
   }
void Botan::Pipe::prepend ( Filter filt)

Insert a new filter at the front of the pipe

Parameters:
filtthe new filter to insert

Definition at line 241 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;
   }
void Botan::Pipe::process_msg ( const byte  in[],
size_t  length 
)

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

Parameters:
inthe byte array containing the data to write
lengththe length of the byte array to write

Definition at line 117 of file pipe.cpp.

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

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

   {
   start_msg();
   write(input, length);
   end_msg();
   }
void Botan::Pipe::process_msg ( const secure_vector< byte > &  in)

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

Parameters:
inthe secure_vector containing the data to write

Definition at line 127 of file pipe.cpp.

References process_msg().

   {
   process_msg(input.data(), input.size());
   }
void Botan::Pipe::process_msg ( const std::vector< byte > &  in)

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

Parameters:
inthe secure_vector containing the data to write

Definition at line 132 of file pipe.cpp.

References process_msg().

   {
   process_msg(input.data(), input.size());
   }
void Botan::Pipe::process_msg ( const std::string &  in)

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

Parameters:
inthe string containing the data to write

Definition at line 140 of file pipe.cpp.

References process_msg().

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

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

Parameters:
inthe DataSource providing the data to write

Definition at line 148 of file pipe.cpp.

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

   {
   start_msg();
   write(input);
   end_msg();
   }
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:
outputthe byte array to write the read bytes to
lengththe length of the byte array output
Returns:
number of bytes actually read into output

Implements Botan::DataSource.

Definition at line 82 of file pipe_rw.cpp.

References DEFAULT_MESSAGE.

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

   {
   return read(output, length, DEFAULT_MESSAGE);
   }
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:
outputthe byte array to write the read bytes to
lengththe length of the byte array output
msgthe number identifying the message to read from
Returns:
number of bytes actually read into output

Definition at line 74 of file pipe_rw.cpp.

References Botan::Output_Buffers::read().

   {
   return outputs->read(output, length, get_message_no("read", msg));
   }
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:
outputthe byte to write the result to
msgthe message to read from
Returns:
number of bytes actually read into output

Definition at line 90 of file pipe_rw.cpp.

References read().

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

Read the full contents of the pipe.

Parameters:
msgthe number identifying the message to read from
Returns:
secure_vector holding the contents of the pipe

Definition at line 98 of file pipe_rw.cpp.

References DEFAULT_MESSAGE, default_msg(), read(), and remaining().

Referenced by Botan::EAC_Signed_Object::BER_encode(), Botan::PEM_Code::decode(), and Botan::PGP_decode().

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

Read the full contents of the pipe.

Parameters:
msgthe number identifying the message to read from
Returns:
string holding the contents of the pipe

Definition at line 110 of file pipe_rw.cpp.

References DEFAULT_MESSAGE, default_msg(), read(), and remaining().

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

   {
   msg = ((msg != DEFAULT_MESSAGE) ? msg : default_msg());
   secure_vector<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;
   }
size_t Botan::DataSource::read_byte ( byte out) [inherited]

Read one byte.

Parameters:
outthe 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.

References Botan::DataSource::read().

Referenced by Botan::PEM_Code::decode(), Botan::DataSource::discard_next(), Botan::BER_Decoder::discard_remaining(), Botan::PGP_decode(), and Botan::BER_Decoder::raw_bytes().

   {
   return read(&out, 1);
   }

Find out how many bytes are ready to read.

Parameters:
msgthe number identifying the message for which the information is desired
Returns:
number of bytes that can still be read

Definition at line 131 of file pipe_rw.cpp.

References Botan::Output_Buffers::remaining().

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

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

Reset this pipe to an empty pipe.

Definition at line 77 of file pipe.cpp.

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

Set the default message

Parameters:
msgthe number identifying the message which is going to be the new default message

Definition at line 107 of file pipe.cpp.

References message_count().

   {
   if(msg >= message_count())
      throw Invalid_Argument("Pipe::set_default_msg: msg number is too high");
   default_read = 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 158 of file pipe.cpp.

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

   {
   if(inside_msg)
      throw Invalid_State("Pipe::start_msg: Message was already started");
   if(pipe == nullptr)
      pipe = new Null_Filter;
   find_endpoints(pipe);
   pipe->new_msg();
   inside_msg = true;
   }
void Botan::Pipe::write ( const byte  in[],
size_t  length 
)

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

Parameters:
inthe byte array to write
lengththe length of the byte array in

Definition at line 35 of file pipe_rw.cpp.

References Botan::Filter::write().

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

   {
   if(!inside_msg)
      throw Invalid_State("Cannot write to a Pipe while it is not processing");
   pipe->write(input, length);
   }
void Botan::Pipe::write ( const secure_vector< byte > &  in) [inline]

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

Parameters:
inthe secure_vector containing the data to write

Definition at line 72 of file pipe.h.

References write().

Referenced by write().

         { write(in.data(), in.size()); }
void Botan::Pipe::write ( const std::vector< byte > &  in) [inline]

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

Parameters:
inthe std::vector containing the data to write

Definition at line 79 of file pipe.h.

References write().

Referenced by write().

         { write(in.data(), in.size()); }
void Botan::Pipe::write ( const std::string &  in)

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

Parameters:
inthe string containing the data to write

Definition at line 45 of file pipe_rw.cpp.

References write().

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

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

Parameters:
inthe DataSource to read the data from

Definition at line 61 of file pipe_rw.cpp.

References Botan::DataSource::end_of_data(), Botan::DataSource::read(), and write().

   {
   secure_vector<byte> buffer(DEFAULT_BUFFERSIZE);
   while(!source.end_of_data())
      {
      size_t got = source.read(&buffer[0], buffer.size());
      write(&buffer[0], got);
      }
   }
void Botan::Pipe::write ( byte  in)

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

Parameters:
ina single byte to be written

Definition at line 53 of file pipe_rw.cpp.

References write().

   {
   write(&input, 1);
   }

Member Data Documentation

Initial value:
   static_cast<Pipe::message_id>(-1)

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

Definition at line 59 of file pipe.h.

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

Initial value:
   static_cast<Pipe::message_id>(-2)

A meta-id for whatever the last message is

Definition at line 54 of file pipe.h.


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