Botan 1.10.17

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
Botan::Pipe::default_msg
size_t default_msg() const
Definition: pipe.h:209
Botan::Pipe::Invalid_Message_Number::Invalid_Message_Number
Invalid_Message_Number(const std::string &where, message_id msg)
Definition: pipe.h:43
Botan::Pipe::message_id
size_t message_id
Definition: pipe.h:31
Botan::Invalid_Argument
std::invalid_argument Invalid_Argument
Definition: exceptn.h:20
Botan::DataSource
Definition: data_src.h:20
Botan::operator>>
int operator>>(int fd, Pipe &pipe)
Definition: fd_unix.cpp:39
Botan::Pipe::DEFAULT_MESSAGE
static const message_id DEFAULT_MESSAGE
Definition: pipe.h:57
Botan::byte
unsigned char byte
Definition: types.h:22
Botan::operator<<
int operator<<(int fd, Pipe &pipe)
Definition: fd_unix.cpp:17
Botan::Pipe::LAST_MESSAGE
static const message_id LAST_MESSAGE
Definition: pipe.h:52
Botan::Filter
Definition: filter.h:19
Botan::MemoryRegion< byte >
Botan
Definition: algo_base.h:14
Botan::Pipe::Invalid_Message_Number
Definition: pipe.h:37
Botan::to_string
std::string to_string(u64bit n, size_t min_len)
Definition: parsing.cpp:42
Botan::SecureVector< byte >
Botan::Pipe
Definition: pipe.h:25