diff options
Diffstat (limited to 'src')
| -rw-r--r-- | src/filters/pipe.h | 222 |
1 files changed, 197 insertions, 25 deletions
diff --git a/src/filters/pipe.h b/src/filters/pipe.h index 3c41f6ebe..4ac59617d 100644 --- a/src/filters/pipe.h +++ b/src/filters/pipe.h @@ -12,9 +12,14 @@ namespace Botan { -/************************************************* -* Pipe * -*************************************************/ +/** +* 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. +*/ + class BOTAN_DLL Pipe : public DataSource { public: @@ -29,45 +34,212 @@ class BOTAN_DLL Pipe : public DataSource static const message_id LAST_MESSAGE; static const message_id DEFAULT_MESSAGE; - void write(const byte[], u32bit); - void write(const MemoryRegion<byte>&); - void write(const std::string&); - void write(DataSource&); - void write(byte); + /** + * Write input to the pipe, i.e. to its first filter. + * @param in the byte array to write + * @param length the length of the byte array in + */ + void write(const byte in[], u32bit length); + + /** + * Write input to the pipe, i.e. to its first filter. + * @param in the MemoryRegion containing the data to write + */ + void write(const MemoryRegion<byte>& in); + + /** + * Write input to the pipe, i.e. to its first filter. + * @param in the string containing the data to write + */ + void write(const std::string& in); + + /** + * Write input to the pipe, i.e. to its first filter. + * @param in the DataSource to read the data from + */ + void write(DataSource& in); + + /** + * Write input to the pipe, i.e. to its first filter. + * @param in a single byte to be written + */ + void write(byte in); + + /** + * Perform start_msg(), write() and end_msg() sequentially. + * @param in the byte array containing the data to write + * @param length the length of the byte array to write + */ + void process_msg(const byte in[], u32bit length); + + /** + * Perform start_msg(), write() and end_msg() sequentially. + * @param in the MemoryRegion containing the data to write + */ + void process_msg(const MemoryRegion<byte>& in); + + /** + * Perform start_msg(), write() and end_msg() sequentially. + * @param in the string containing the data to write + */ + void process_msg(const std::string& in); + + /** + * Perform start_msg(), write() and end_msg() sequentially. + * @param in the DataSource providing the data to write + */ + void process_msg(DataSource& in); + + /** + * Find out how many bytes are ready to read. + * @param msg the number identifying the message + * for which the information is desired + * @return the number of bytes that can still be read + */ + u32bit remaining(message_id msg = DEFAULT_MESSAGE) const; - void process_msg(const byte[], u32bit); - void process_msg(const MemoryRegion<byte>&); - void process_msg(const std::string&); - void process_msg(DataSource&); + /** + * 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. + * @param output the byte array to write the read bytes to + * @param length the length of the byte array output + * @return the number of bytes actually read into output + */ + u32bit read(byte output[], u32bit length); - u32bit remaining(message_id = DEFAULT_MESSAGE) const; + /** + * 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. + * @param output the byte array to write the read bytes to + * @param length the length of the byte array output + * @param msg the number identifying the message to read from + * @return the number of bytes actually read into output + */ + u32bit read(byte output[], u32bit length, message_id msg); - u32bit read(byte[], u32bit); - u32bit read(byte[], u32bit, message_id); - u32bit read(byte&, message_id = 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. + * @param output the byte to write the result to + * @return the number of bytes actually read into output + */ + u32bit read(byte& output, message_id msg = DEFAULT_MESSAGE); - SecureVector<byte> read_all(message_id = DEFAULT_MESSAGE); + /** + * Read the full contents of the pipe. + * @param msg the number identifying the message to read from + * @return a SecureVector holding the contents of the pipe + */ + SecureVector<byte> read_all(message_id msg = DEFAULT_MESSAGE); + + /** + * Read the full contents of the pipe. + * @param msg the number identifying the message to read from + * @return a string holding the contents of the pipe + */ std::string read_all_as_string(message_id = DEFAULT_MESSAGE); - u32bit peek(byte[], u32bit, u32bit) const; - u32bit peek(byte[], u32bit, u32bit, message_id) const; - u32bit peek(byte&, u32bit, message_id = DEFAULT_MESSAGE) const; + /** 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. + * @param output the byte array to write the peeked message part to + * @param length the length of the byte array output + * @param offset the offset from the current position in message + * @return the number of bytes actually peeked and written into output + */ + u32bit peek(byte output[], u32bit length, u32bit offset) 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. + * @param output the byte array to write the peeked message part to + * @param length the length of the byte array output + * @param offset the offset from the current position in message + * @param msg the number identifying the message to peek from + * @return the number of bytes actually peeked and written into output + */ + u32bit peek(byte output[], u32bit length, + u32bit offset, message_id msg) 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. + * @param output the byte to write the peeked message byte to + * @param offset the offset from the current position in message + * @param msg the number identifying the message to peek from + * @return the number of bytes actually peeked and written into output + */ + u32bit peek(byte& output, u32bit offset, + message_id msg = DEFAULT_MESSAGE) const; - message_id default_msg() const { return default_read; } - void set_default_msg(message_id); + u32bit default_msg() const { return default_read; } + + /** + * Set the default message + * @param msg the number identifying the message which is going to + * be the new default message + */ + void set_default_msg(message_id msg); + + /** + * Get the number of messages the are in this pipe. + * @return the number of messages the are in this pipe + */ message_id message_count() const; + + /** + * Test whether this pipe has any data that can be read from. + * @return true if there is more data to read, false otherwise + */ bool end_of_data() const; + /** + * 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. + */ void start_msg(); + + /** + * End the current message. + */ void end_msg(); - void prepend(Filter*); - void append(Filter*); + /** + * Insert a new filter at the front of the pipe + * @param filt the new filter to insert + */ + void prepend(Filter* filt); + + /** + * Insert a new filter at the back of the pipe + * @param filt the new filter to insert + */ + void append(Filter* filt); + + /** + * Remove the first filter at the front of the pipe. + */ void pop(); + + /** + * Reset this pipe to an empty pipe. + */ void reset(); + /** + * Construct a Pipe of up to four filters. The filters are set up + * in the same order as the arguments. + */ Pipe(Filter* = 0, Filter* = 0, Filter* = 0, Filter* = 0); - Pipe(Filter*[], u32bit); + + /** + * Construct a Pipe from range of filters passed as an array + * @param filters the set of filters to use + * @param count the number of elements in filters + */ + Pipe(Filter* filters[], u32bit count); ~Pipe(); private: Pipe(const Pipe&) : DataSource() {} |