Botan  1.10.9
pipe.h
Go to the documentation of this file.
1 /*
2 * Pipe
3 * (C) 1999-2007 Jack Lloyd
4 *
5 * Distributed under the terms of the Botan license
6 */
7 
8 #ifndef BOTAN_PIPE_H__
9 #define BOTAN_PIPE_H__
10 
11 #include <botan/data_src.h>
12 #include <botan/filter.h>
13 #include <botan/exceptn.h>
14 #include <iosfwd>
15 
16 namespace Botan {
17 
18 /**
19 * This class represents pipe objects.
20 * A set of filters can be placed into a pipe, and information flows
21 * through the pipe until it reaches the end, where the output is
22 * collected for retrieval. If you're familiar with the Unix shell
23 * environment, this design will sound quite familiar.
24 */
25 class BOTAN_DLL Pipe : public DataSource
26  {
27  public:
28  /**
29  * An opaque type that identifies a message in this Pipe
30  */
31  typedef size_t message_id;
32 
33  /**
34  * Exception if you use an invalid message as an argument to
35  * read, remaining, etc
36  */
37  struct BOTAN_DLL Invalid_Message_Number : public Invalid_Argument
38  {
39  /**
40  * @param where the error occured
41  * @param msg the invalid message id that was used
42  */
43  Invalid_Message_Number(const std::string& where, message_id msg) :
44  Invalid_Argument("Pipe::" + where + ": Invalid message number " +
45  to_string(msg))
46  {}
47  };
48 
49  /**
50  * A meta-id for whatever the last message is
51  */
52  static const message_id LAST_MESSAGE;
53 
54  /**
55  * A meta-id for the default message (set with set_default_msg)
56  */
57  static const message_id DEFAULT_MESSAGE;
58 
59  /**
60  * Write input to the pipe, i.e. to its first filter.
61  * @param in the byte array to write
62  * @param length the length of the byte array in
63  */
64  void write(const byte in[], size_t length);
65 
66  /**
67  * Write input to the pipe, i.e. to its first filter.
68  * @param in the MemoryRegion containing the data to write
69  */
70  void write(const MemoryRegion<byte>& in);
71 
72  /**
73  * Write input to the pipe, i.e. to its first filter.
74  * @param in the string containing the data to write
75  */
76  void write(const std::string& in);
77 
78  /**
79  * Write input to the pipe, i.e. to its first filter.
80  * @param in the DataSource to read the data from
81  */
82  void write(DataSource& in);
83 
84  /**
85  * Write input to the pipe, i.e. to its first filter.
86  * @param in a single byte to be written
87  */
88  void write(byte in);
89 
90  /**
91  * Perform start_msg(), write() and end_msg() sequentially.
92  * @param in the byte array containing the data to write
93  * @param length the length of the byte array to write
94  */
95  void process_msg(const byte in[], size_t length);
96 
97  /**
98  * Perform start_msg(), write() and end_msg() sequentially.
99  * @param in the MemoryRegion containing the data to write
100  */
101  void process_msg(const MemoryRegion<byte>& in);
102 
103  /**
104  * Perform start_msg(), write() and end_msg() sequentially.
105  * @param in the string containing the data to write
106  */
107  void process_msg(const std::string& in);
108 
109  /**
110  * Perform start_msg(), write() and end_msg() sequentially.
111  * @param in the DataSource providing the data to write
112  */
113  void process_msg(DataSource& in);
114 
115  /**
116  * Find out how many bytes are ready to read.
117  * @param msg the number identifying the message
118  * for which the information is desired
119  * @return number of bytes that can still be read
120  */
121  size_t remaining(message_id msg = DEFAULT_MESSAGE) const;
122 
123  /**
124  * Read the default message from the pipe. Moves the internal
125  * offset so that every call to read will return a new portion of
126  * the message.
127  *
128  * @param output the byte array to write the read bytes to
129  * @param length the length of the byte array output
130  * @return number of bytes actually read into output
131  */
132  size_t read(byte output[], size_t length);
133 
134  /**
135  * Read a specified message from the pipe. Moves the internal
136  * offset so that every call to read will return a new portion of
137  * the message.
138  * @param output the byte array to write the read bytes to
139  * @param length the length of the byte array output
140  * @param msg the number identifying the message to read from
141  * @return number of bytes actually read into output
142  */
143  size_t read(byte output[], size_t length, message_id msg);
144 
145  /**
146  * Read a single byte from the pipe. Moves the internal offset so
147  * that every call to read will return a new portion of the
148  * message.
149  *
150  * @param output the byte to write the result to
151  * @param msg the message to read from
152  * @return number of bytes actually read into output
153  */
154  size_t read(byte& output, message_id msg = DEFAULT_MESSAGE);
155 
156  /**
157  * Read the full contents of the pipe.
158  * @param msg the number identifying the message to read from
159  * @return SecureVector holding the contents of the pipe
160  */
161  SecureVector<byte> read_all(message_id msg = DEFAULT_MESSAGE);
162 
163  /**
164  * Read the full contents of the pipe.
165  * @param msg the number identifying the message to read from
166  * @return string holding the contents of the pipe
167  */
168  std::string read_all_as_string(message_id = DEFAULT_MESSAGE);
169 
170  /** Read from the default message but do not modify the internal
171  * offset. Consecutive calls to peek() will return portions of
172  * the message starting at the same position.
173  * @param output the byte array to write the peeked message part to
174  * @param length the length of the byte array output
175  * @param offset the offset from the current position in message
176  * @return number of bytes actually peeked and written into output
177  */
178  size_t peek(byte output[], size_t length, size_t offset) const;
179 
180  /** Read from the specified message but do not modify the
181  * internal offset. Consecutive calls to peek() will return
182  * portions of the message starting at the same position.
183  * @param output the byte array to write the peeked message part to
184  * @param length the length of the byte array output
185  * @param offset the offset from the current position in message
186  * @param msg the number identifying the message to peek from
187  * @return number of bytes actually peeked and written into output
188  */
189  size_t peek(byte output[], size_t length,
190  size_t offset, message_id msg) const;
191 
192  /** Read a single byte from the specified message but do not
193  * modify the internal offset. Consecutive calls to peek() will
194  * return portions of the message starting at the same position.
195  * @param output the byte to write the peeked message byte to
196  * @param offset the offset from the current position in message
197  * @param msg the number identifying the message to peek from
198  * @return number of bytes actually peeked and written into output
199  */
200  size_t peek(byte& output, size_t offset,
201  message_id msg = DEFAULT_MESSAGE) const;
202 
203  /**
204  * @return currently set default message
205  */
206  size_t default_msg() const { return default_read; }
207 
208  /**
209  * Set the default message
210  * @param msg the number identifying the message which is going to
211  * be the new default message
212  */
213  void set_default_msg(message_id msg);
214 
215  /**
216  * Get the number of messages the are in this pipe.
217  * @return number of messages the are in this pipe
218  */
219  message_id message_count() const;
220 
221  /**
222  * Test whether this pipe has any data that can be read from.
223  * @return true if there is more data to read, false otherwise
224  */
225  bool end_of_data() const;
226 
227  /**
228  * Start a new message in the pipe. A potential other message in this pipe
229  * must be closed with end_msg() before this function may be called.
230  */
231  void start_msg();
232 
233  /**
234  * End the current message.
235  */
236  void end_msg();
237 
238  /**
239  * Insert a new filter at the front of the pipe
240  * @param filt the new filter to insert
241  */
242  void prepend(Filter* filt);
243 
244  /**
245  * Insert a new filter at the back of the pipe
246  * @param filt the new filter to insert
247  */
248  void append(Filter* filt);
249 
250  /**
251  * Remove the first filter at the front of the pipe.
252  */
253  void pop();
254 
255  /**
256  * Reset this pipe to an empty pipe.
257  */
258  void reset();
259 
260  /**
261  * Construct a Pipe of up to four filters. The filters are set up
262  * in the same order as the arguments.
263  */
264  Pipe(Filter* = 0, Filter* = 0, Filter* = 0, Filter* = 0);
265 
266  /**
267  * Construct a Pipe from range of filters passed as an array
268  * @param filters the set of filters to use
269  * @param count the number of elements in filters
270  */
271  Pipe(Filter* filters[], size_t count);
272  ~Pipe();
273  private:
274  Pipe(const Pipe&) : DataSource() {}
275  Pipe& operator=(const Pipe&) { return (*this); }
276  void init();
277  void destruct(Filter*);
278  void find_endpoints(Filter*);
279  void clear_endpoints(Filter*);
280 
281  message_id get_message_no(const std::string&, message_id) const;
282 
283  Filter* pipe;
284  class Output_Buffers* outputs;
285  message_id default_read;
286  bool inside_msg;
287  };
288 
289 /**
290 * Stream output operator; dumps the results from pipe's default
291 * message to the output stream.
292 * @param out an output stream
293 * @param pipe the pipe
294 */
295 BOTAN_DLL std::ostream& operator<<(std::ostream& out, Pipe& pipe);
296 
297 /**
298 * Stream input operator; dumps the remaining bytes of input
299 * to the (assumed open) pipe message.
300 * @param in the input stream
301 * @param pipe the pipe
302 */
303 BOTAN_DLL std::istream& operator>>(std::istream& in, Pipe& pipe);
304 
305 }
306 
307 #if defined(BOTAN_HAS_PIPE_UNIXFD_IO)
308  #include <botan/fd_unix.h>
309 #endif
310 
311 #endif
Invalid_Message_Number(const std::string &where, message_id msg)
Definition: pipe.h:43
size_t message_id
Definition: pipe.h:31
std::invalid_argument Invalid_Argument
Definition: exceptn.h:20
int operator>>(int fd, Pipe &pipe)
Definition: fd_unix.cpp:39
static const message_id DEFAULT_MESSAGE
Definition: pipe.h:57
unsigned char byte
Definition: types.h:22
int operator<<(int fd, Pipe &pipe)
Definition: fd_unix.cpp:17
static const message_id LAST_MESSAGE
Definition: pipe.h:52
size_t default_msg() const
Definition: pipe.h:206
std::string to_string(u64bit n, size_t min_len)
Definition: parsing.cpp:42