aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorlloyd <[email protected]>2008-10-13 18:15:21 +0000
committerlloyd <[email protected]>2008-10-13 18:15:21 +0000
commit5a812df041ecba9ea8aeaa27d08d51ca55f34c3f (patch)
tree3f6f69e57f15da0c333eb74672b31013d86d2426
parenta838a020085a76484f0f8aadb5beebc0bdf74975 (diff)
Add a (very thorough!) set of Doxygen comments from InSiTo for the Pipe class
-rw-r--r--src/filters/pipe.h222
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() {}