Botan

Pipe

License
Botan is released under the Simplified BSD License (see LICENSE.md)

struct  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.


alias  message_id = ulong;

An opaque type that identifies a message in this Pipe


class  InvalidMessageNumber: botan.utils.exceptn.InvalidArgument;

Exception if you use an invalid message as an argument to read, remaining, etc


this(in string where, message_id msg);

Parameters
string where the error occured
message_id msg the invalid message id that was used

static const message_id  LAST_MESSAGE;

A meta-id for whatever the last message is


static const message_id  DEFAULT_MESSAGE;

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


void  write(const(ubyte)* input, size_t length);

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

Parameters
const(ubyte)* input the ubyte array to  write
size_t length the length of the ubyte array in

void  write(T, ALLOC)(auto ref const RefCounted!(Vector!(T, ALLOC), ALLOC) input);

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

Parameters
RefCounted!(Vector!(T, ALLOC), ALLOC) input the SecureVector containing the data to  write

void  write(T, ALLOC)(auto ref const Vector!(T, ALLOC) input);

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

Parameters
Vector!(T, ALLOC) input the std::vector containing the data to  write

void  write(string input);

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

Parameters
string input the string containing the data to  write

void  write(DataSource source);

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

Parameters
DataSource source the DataSource to read the data from

void  write(ubyte input);

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

Parameters
ubyte input a single ubyte to be written

void  write(ubyte[] input);

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

Parameters
ubyte[] input a ubyte array to be written

void  processMsg(const(ubyte)* input, size_t length);

Perform startMsg(), write() and endMsg() sequentially.

Parameters
const(ubyte)* input the ubyte array containing the data to write
size_t length the length of the ubyte array to write

void  processMsg(ALLOC)(auto ref const Vector!(ubyte, ALLOC) input);

Perform startMsg(), write() and endMsg() sequentially.

Parameters
Vector!(ubyte, ALLOC) input the SecureVector containing the data to write

void  processMsg(ALLOC)(auto ref const RefCounted!(Vector!(ubyte, ALLOC), ALLOC) input);

Perform startMsg(), write() and endMsg() sequentially.

Parameters
RefCounted!(Vector!(ubyte, ALLOC), ALLOC) input the SecureVector containing the data to write

void  processMsg(string input);

Perform startMsg(), write() and endMsg() sequentially.

Parameters
string input the string containing the data to write

void  processMsg(DataSource input);

Perform startMsg(), write() and endMsg() sequentially.

Parameters
DataSource input the DataSource providing the data to write

const size_t  remaining(message_id msg = DEFAULT_MESSAGE);

Find out how many bytes are ready to read.

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

size_t  read(ubyte* output, size_t length);

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
ubyte* output the ubyte array to write the  read bytes to
size_t length the length of the ubyte array output
Returns
number of bytes actually  read into output

size_t  read(ubyte* 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
ubyte* output the ubyte array to write the  read bytes to
size_t length the length of the ubyte array output
message_id msg the number identifying the message to  read from
Returns
number of bytes actually  read into output

size_t  read(ref ubyte[] output, message_id msg = DEFAULT_MESSAGE);

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
ubyte[] output the ubyte array to write the  read bytes to
message_id msg the number identifying the message to  read from
Returns
number of bytes actually  read into output

size_t  read(ref ubyte output, message_id msg = DEFAULT_MESSAGE);

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

Parameters
ubyte output the ubyte to write the result to
message_id msg the message to  read from
Returns
number of bytes actually  read into output

SecureVector!ubyte  readAll(message_id msg = DEFAULT_MESSAGE);

Read the full contents of the pipe.

Parameters
message_id msg the number identifying the message to read from
Returns
SecureVector holding the contents of the pipe

string  toString(message_id msg = DEFAULT_MESSAGE);

Read the full contents of the pipe.

Parameters
message_id msg the number identifying the message to read from
Returns
string holding the contents of the pipe

const size_t  peek(ubyte* output, size_t length, size_t offset, message_id msg = DEFAULT_MESSAGE);

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
ubyte* output the ubyte array to write the peeked message part to
size_t length the length of the ubyte array output
size_t offset the offset from the current position in message
message_id msg the number identifying the message to  peek from
Returns
number of bytes actually peeked and written into output

const size_t  peek(ref ubyte[] output, size_t offset, message_id msg = DEFAULT_MESSAGE);

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
ubyte[] output the ubyte array to write the peeked message part to
size_t offset the offset from the current position in message
message_id msg the number identifying the message to  peek from
Returns
number of bytes actually peeked and written into output

const size_t  peek(ref ubyte output, size_t offset, message_id msg = DEFAULT_MESSAGE);

Read a single ubyte 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
ubyte output the ubyte to write the peeked message ubyte to
size_t offset the offset from the current position in message
message_id msg the number identifying the message to  peek from
Returns
number of bytes actually peeked and written into output

size_t  readByte(ref ubyte output);

Read one ubyte.

Parameters
ubyte output the ubyte to read to
Returns
length in bytes that was actually read and put into out

const size_t  peekByte(ref ubyte output);

Peek at one ubyte.

Parameters
ubyte output an output ubyte
Returns
length in bytes that was actually read and put into out

size_t  discardNext(size_t n);

Discard the next N bytes of the data

Parameters
size_t n the number of bytes to discard
Returns
number of bytes actually discarded

const size_t  getBytesRead();

Returns
the number of bytes read from the default message.

const size_t  getBytesRead(message_id msg = DEFAULT_MESSAGE);

Returns
the number of bytes read from the specified message.

const size_t  defaultMsg();

Returns
currently set default message

void  setDefaultMsg(message_id msg);

Set the default message

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

const message_id  messageCount();

Get the number of messages the are in this pipe.

Returns
number of messages the are in this pipe

const bool  endOfData();

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

Returns
true if there is more data to read, false otherwise

void  startMsg();

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


void  endMsg();

End the current message.


void  prepend(Filter filter);

Insert a new filter at the front of the pipe

Parameters
Filter filter the new filter to insert

void  append(Filter filter);

Insert a new filter at the back of the pipe

Parameters
Filter filter the new filter to insert

void  pop();

Remove the first filter at the front of the pipe.


void  reset();

Reset this pipe to an empty pipe.


this(Filter f1 = null, Filter f2 = null, Filter f3 = null, Filter f4 = null);

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


this(Filter[] filters);

Construct a Pipe from a list of filters

Parameters
Filter[] filters the set of filters to use