Botan  1.10.16
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  bool check_available(size_t n);
204  bool check_available_msg(size_t n, message_id msg);
205 
206  /**
207  * @return currently set default message
208  */
209  size_t default_msg() const { return default_read; }
210 
211  /**
212  * Set the default message
213  * @param msg the number identifying the message which is going to
214  * be the new default message
215  */
216  void set_default_msg(message_id msg);
217 
218  /**
219  * Get the number of messages the are in this pipe.
220  * @return number of messages the are in this pipe
221  */
222  message_id message_count() const;
223 
224  /**
225  * Test whether this pipe has any data that can be read from.
226  * @return true if there is more data to read, false otherwise
227  */
228  bool end_of_data() const;
229 
230  /**
231  * Start a new message in the pipe. A potential other message in this pipe
232  * must be closed with end_msg() before this function may be called.
233  */
234  void start_msg();
235 
236  /**
237  * End the current message.
238  */
239  void end_msg();
240 
241  /**
242  * Insert a new filter at the front of the pipe
243  * @param filt the new filter to insert
244  */
245  void prepend(Filter* filt);
246 
247  /**
248  * Insert a new filter at the back of the pipe
249  * @param filt the new filter to insert
250  */
251  void append(Filter* filt);
252 
253  /**
254  * Remove the first filter at the front of the pipe.
255  */
256  void pop();
257 
258  /**
259  * Reset this pipe to an empty pipe.
260  */
261  void reset();
262 
263  /**
264  * Construct a Pipe of up to four filters. The filters are set up
265  * in the same order as the arguments.
266  */
267  Pipe(Filter* = 0, Filter* = 0, Filter* = 0, Filter* = 0);
268 
269  /**
270  * Construct a Pipe from range of filters passed as an array
271  * @param filters the set of filters to use
272  * @param count the number of elements in filters
273  */
274  Pipe(Filter* filters[], size_t count);
275  ~Pipe();
276  private:
277  Pipe(const Pipe&) : DataSource() {}
278  Pipe& operator=(const Pipe&) { return (*this); }
279  void init();
280  void destruct(Filter*);
281  void find_endpoints(Filter*);
282  void clear_endpoints(Filter*);
283 
284  message_id get_message_no(const std::string&, message_id) const;
285 
286  Filter* pipe;
287  class Output_Buffers* outputs;
288  message_id default_read;
289  bool inside_msg;
290  };
291 
292 /**
293 * Stream output operator; dumps the results from pipe's default
294 * message to the output stream.
295 * @param out an output stream
296 * @param pipe the pipe
297 */
298 BOTAN_DLL std::ostream& operator<<(std::ostream& out, Pipe& pipe);
299 
300 /**
301 * Stream input operator; dumps the remaining bytes of input
302 * to the (assumed open) pipe message.
303 * @param in the input stream
304 * @param pipe the pipe
305 */
306 BOTAN_DLL std::istream& operator>>(std::istream& in, Pipe& pipe);
307 
308 }
309 
310 #if defined(BOTAN_HAS_PIPE_UNIXFD_IO)
311  #include <botan/fd_unix.h>
312 #endif
313 
314 #endif
size_t default_msg() const
Definition: pipe.h:209
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
std::string to_string(u64bit n, size_t min_len)
Definition: parsing.cpp:42