1 | /* |
2 | * Copyright (C) 2003-2007 Justin Karneges <justin@affinix.com> |
3 | * |
4 | * This library is free software; you can redistribute it and/or |
5 | * modify it under the terms of the GNU Lesser General Public |
6 | * License as published by the Free Software Foundation; either |
7 | * version 2.1 of the License, or (at your option) any later version. |
8 | * |
9 | * This library is distributed in the hope that it will be useful, |
10 | * but WITHOUT ANY WARRANTY; without even the implied warranty of |
11 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
12 | * Lesser General Public License for more details. |
13 | * |
14 | * You should have received a copy of the GNU Lesser General Public |
15 | * License along with this library; if not, write to the Free Software |
16 | * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA |
17 | * 02110-1301 USA |
18 | * |
19 | */ |
20 | |
21 | /** |
22 | \file qpipe.h |
23 | |
24 | Header file for the QPipe FIFO class |
25 | |
26 | \note You should not use this header directly from an |
27 | application. You should just use <tt> \#include \<QtCrypto> |
28 | </tt> instead. |
29 | */ |
30 | |
31 | #ifndef QPIPE_H |
32 | #define QPIPE_H |
33 | |
34 | #ifndef DOXYGEN_SHOULD_SKIP_THIS |
35 | |
36 | #ifndef QPIPE_NO_SECURE |
37 | #define QPIPE_SECURE |
38 | #endif |
39 | |
40 | #ifdef QPIPE_SECURE |
41 | #include "QtCrypto" |
42 | #else |
43 | #define QCA_EXPORT |
44 | #endif |
45 | |
46 | // defs adapted qprocess_p.h |
47 | #ifdef Q_OS_WIN |
48 | #include <windows.h> |
49 | typedef HANDLE Q_PIPE_ID; |
50 | #define INVALID_Q_PIPE_ID INVALID_HANDLE_VALUE |
51 | #else |
52 | typedef int Q_PIPE_ID; |
53 | #define INVALID_Q_PIPE_ID -1 |
54 | #endif |
55 | |
56 | #endif |
57 | |
58 | // Note: for Windows console, I/O must be in UTF-8. Reads are guaranteed to |
59 | // to completely decode (no partial characters). Likewise, writes must |
60 | // not contain partial characters. |
61 | |
62 | namespace QCA { |
63 | |
64 | /** |
65 | \class QPipeDevice qpipe.h QtCrypto |
66 | |
67 | Unbuffered direct pipe. |
68 | |
69 | This class is not usually required except for very low level operations. |
70 | You should use QPipe and QPipeEnd for most applications. |
71 | |
72 | \ingroup UserAPI |
73 | */ |
74 | class QCA_EXPORT QPipeDevice : public QObject |
75 | { |
76 | Q_OBJECT |
77 | public: |
78 | /** |
79 | The type of device |
80 | */ |
81 | enum Type |
82 | { |
83 | Read, ///< The pipe end can be read from |
84 | Write ///< The pipe end can be written to |
85 | }; |
86 | |
87 | /** |
88 | Standard constructor |
89 | |
90 | \param parent the parent object to this object |
91 | */ |
92 | QPipeDevice(QObject *parent = nullptr); |
93 | ~QPipeDevice() override; |
94 | |
95 | /** |
96 | The Type of the pipe device (that is, read or write) |
97 | */ |
98 | Type type() const; |
99 | |
100 | /** |
101 | Test whether this object corresponds to a valid pipe |
102 | */ |
103 | bool isValid() const; |
104 | |
105 | /** |
106 | The low level identification for this pipe. |
107 | |
108 | On Windows, this is a HANDLE. On Unix, this is a file descriptor (i.e. integer). |
109 | |
110 | Code using this method should be carefully tested for portability. |
111 | |
112 | \sa idAsInt |
113 | */ |
114 | Q_PIPE_ID id() const; |
115 | |
116 | /** |
117 | The low level identification for this pipe, returned as an integer. |
118 | |
119 | Code using this method should be carefully tested for portability. |
120 | |
121 | \sa id(). |
122 | */ |
123 | int idAsInt() const; |
124 | |
125 | /** |
126 | Take over an existing pipe id, closing the old pipe if any. |
127 | |
128 | \param id the identification of the pipe end to take over. |
129 | \param t the type of pipe end (read or write). |
130 | */ |
131 | void take(Q_PIPE_ID id, Type t); |
132 | |
133 | /** |
134 | Enable the pipe for reading or writing (depending on Type) |
135 | */ |
136 | void enable(); |
137 | |
138 | /** |
139 | Close the pipe end. |
140 | */ |
141 | void close(); |
142 | |
143 | /** |
144 | Release the pipe end, but do not close it. |
145 | */ |
146 | void release(); |
147 | |
148 | /** |
149 | Set the pipe end to be inheritable |
150 | |
151 | \note On Windows, this operation changes the pipe end id value. |
152 | |
153 | \param enabled whether the pipe is inheritable (true) or not (false) |
154 | */ |
155 | bool setInheritable(bool enabled); |
156 | |
157 | /** |
158 | Obtain the number of bytes available to be read. |
159 | */ |
160 | int bytesAvailable() const; |
161 | |
162 | /** |
163 | Read from the pipe end |
164 | |
165 | \param data where to put the data that has been read |
166 | \param maxsize the maximum number of bytes to be read. |
167 | |
168 | \return the actual number of bytes read, 0 on end-of-file, or -1 on error. |
169 | */ |
170 | int read(char *data, int maxsize); |
171 | |
172 | /** |
173 | Write to the pipe end. |
174 | |
175 | \param data the source of the data to be written |
176 | \param size the number of bytes in the data to be written |
177 | |
178 | \note the data source must remain valid |
179 | |
180 | \return the number of bytes written, or -1 on error. |
181 | */ |
182 | int write(const char *data, int size); |
183 | |
184 | /** |
185 | The result of a write operation |
186 | |
187 | \param written if not null, this will be set to the number of |
188 | bytes written in the last operation. |
189 | |
190 | \return 0 on success (all data written), or -1 on error |
191 | */ |
192 | int writeResult(int *written) const; |
193 | |
194 | Q_SIGNALS: |
195 | /** |
196 | Emitted when the pipe end can be read from or written to (depending on its Type). |
197 | */ |
198 | void notify(); |
199 | |
200 | private: |
201 | Q_DISABLE_COPY(QPipeDevice) |
202 | |
203 | class Private; |
204 | friend class Private; |
205 | Private *d; |
206 | }; |
207 | |
208 | /** |
209 | \class QPipeEnd qpipe.h QtCrypto |
210 | |
211 | A buffered higher-level pipe end |
212 | |
213 | This is either the read end or write end of a QPipe. |
214 | |
215 | \ingroup UserAPI |
216 | */ |
217 | class QCA_EXPORT QPipeEnd : public QObject |
218 | { |
219 | Q_OBJECT |
220 | public: |
221 | /** |
222 | The type of error |
223 | */ |
224 | enum Error |
225 | { |
226 | ErrorEOF, ///< End of file error |
227 | ErrorBroken ///< Broken pipe error |
228 | }; |
229 | |
230 | /** |
231 | Standard constructor |
232 | |
233 | \param parent the parent object for this object |
234 | */ |
235 | QPipeEnd(QObject *parent = nullptr); |
236 | |
237 | ~QPipeEnd() override; |
238 | |
239 | /** |
240 | Reset the pipe end to an inactive state |
241 | */ |
242 | void reset(); |
243 | |
244 | /** |
245 | The type of pipe end (either read or write) |
246 | */ |
247 | QPipeDevice::Type type() const; |
248 | |
249 | /** |
250 | Determine whether the pipe end is valid. |
251 | |
252 | \note This does not mean the pipe is ready to be used - you |
253 | may need to call enable() first |
254 | */ |
255 | bool isValid() const; |
256 | |
257 | /** |
258 | Pipe identification |
259 | */ |
260 | Q_PIPE_ID id() const; |
261 | |
262 | /** |
263 | Pipe identification |
264 | */ |
265 | int idAsInt() const; |
266 | |
267 | /** |
268 | Take over an existing pipe handle |
269 | |
270 | \param id the pipe handle |
271 | \param t the type of the pipe (read or write) |
272 | */ |
273 | void take(Q_PIPE_ID id, QPipeDevice::Type t); |
274 | |
275 | #ifdef QPIPE_SECURE |
276 | /** |
277 | Sets whether the pipe uses secure memory for read/write |
278 | |
279 | Enabling this may reduce performance, and it should only be used if |
280 | sensitive data is being transmitted (such as a passphrase). |
281 | |
282 | \param secure whether the pipe uses secure memory (true) or not (false). |
283 | */ |
284 | void setSecurityEnabled(bool secure); |
285 | #endif |
286 | |
287 | /** |
288 | Enable the endpoint for the pipe |
289 | |
290 | When an endpoint is created, it is not |
291 | able to be used until it is enabled. |
292 | */ |
293 | void enable(); |
294 | |
295 | /** |
296 | Close the end of the pipe |
297 | |
298 | \sa closed() |
299 | */ |
300 | void close(); |
301 | |
302 | /** |
303 | Let go of the active pipe handle, but don't close it |
304 | |
305 | Use this before destructing QPipeEnd, if you don't want the pipe |
306 | to automatically close. |
307 | */ |
308 | void release(); |
309 | |
310 | /** |
311 | Sets whether the pipe should be inheritable to child processes |
312 | |
313 | Returns true if inheritability was successfully changed, otherwise |
314 | false. |
315 | |
316 | \param enabled whether the pipe is inheritable (true) or not (false). |
317 | */ |
318 | bool setInheritable(bool enabled); |
319 | |
320 | /** |
321 | Clear the contents of the pipe, and invalidate the pipe |
322 | */ |
323 | void finalize(); |
324 | |
325 | /** |
326 | Clear the contents of the pipe, and release the pipe |
327 | */ |
328 | void finalizeAndRelease(); |
329 | |
330 | /** |
331 | Determine how many bytes are available to be read. |
332 | |
333 | This only makes sense at the read end of the pipe |
334 | |
335 | \sa readyRead() for a signal that can be used to determine |
336 | when there are bytes available to read. |
337 | */ |
338 | int bytesAvailable() const; |
339 | |
340 | /** |
341 | Returns the number of bytes pending to write |
342 | |
343 | This only makes sense at the write end of the pipe |
344 | |
345 | \sa bytesWritten() for a signal that can be used to determine |
346 | when bytes have been written |
347 | */ |
348 | int bytesToWrite() const; |
349 | |
350 | /** |
351 | Read bytes from the pipe. |
352 | |
353 | You can only call this on the read end of the pipe |
354 | |
355 | If the pipe is using secure memory, you should use readSecure() |
356 | |
357 | \param bytes the number of bytes to read (-1 for all |
358 | content). |
359 | */ |
360 | QByteArray read(int bytes = -1); |
361 | |
362 | /** |
363 | Write bytes to the pipe. |
364 | |
365 | You can only call this on the write end of the pipe. |
366 | |
367 | If the pipe is using secure memory, you should use writeSecure(). |
368 | |
369 | \param a the array to write to the pipe |
370 | */ |
371 | void write(const QByteArray &a); |
372 | |
373 | #ifdef QPIPE_SECURE |
374 | /** |
375 | Read bytes from the pipe. |
376 | |
377 | You can only call this on the read end of the pipe |
378 | |
379 | If the pipe is using insecure memory, you should use read() |
380 | |
381 | \param bytes the number of bytes to read (-1 for all |
382 | content). |
383 | */ |
384 | SecureArray readSecure(int bytes = -1); |
385 | |
386 | /** |
387 | Write bytes to the pipe. |
388 | |
389 | You can only call this on the write end of the pipe. |
390 | |
391 | If the pipe is using insecure memory, you should use write(). |
392 | |
393 | \param a the array to write to the pipe |
394 | */ |
395 | void writeSecure(const SecureArray &a); |
396 | #endif |
397 | |
398 | /** |
399 | Returns any unsent bytes queued for writing |
400 | |
401 | If the pipe is using secure memory, you should use |
402 | takeBytesToWriteSecure(). |
403 | */ |
404 | QByteArray takeBytesToWrite(); |
405 | |
406 | #ifdef QPIPE_SECURE |
407 | /** |
408 | Returns any unsent bytes queued for writing |
409 | |
410 | If the pipe is using insecure memory, you should use |
411 | takeBytesToWrite(). |
412 | */ |
413 | SecureArray takeBytesToWriteSecure(); |
414 | #endif |
415 | |
416 | Q_SIGNALS: |
417 | /** |
418 | Emitted when there are bytes available to be read |
419 | from the read end of the pipe. |
420 | |
421 | \sa bytesAvailable() |
422 | */ |
423 | void readyRead(); |
424 | |
425 | /** |
426 | Emitted when bytes have been written to the |
427 | write end of the pipe. |
428 | |
429 | \param bytes the number of bytes written |
430 | */ |
431 | void bytesWritten(int bytes); |
432 | |
433 | /** |
434 | Emitted when this end of the pipe is closed as a result of calling |
435 | close() |
436 | |
437 | If this is the write end of the pipe and there is data still |
438 | pending to write, this signal will be emitted once all of the data |
439 | has been written. |
440 | |
441 | To be notified if the other end of the pipe has been closed, see |
442 | error(). |
443 | */ |
444 | void closed(); |
445 | |
446 | /** |
447 | Emitted when the pipe encounters an error trying to read or write, |
448 | or if the other end of the pipe has been closed |
449 | |
450 | \param e the reason for error |
451 | */ |
452 | void error(QCA::QPipeEnd::Error e); |
453 | |
454 | private: |
455 | Q_DISABLE_COPY(QPipeEnd) |
456 | |
457 | class Private; |
458 | friend class Private; |
459 | Private *d; |
460 | }; |
461 | |
462 | /** |
463 | \class QPipe qpipe.h QtCrypto |
464 | |
465 | A FIFO buffer (named pipe) abstraction |
466 | |
467 | This class creates a full buffer, consisting of two ends |
468 | (QPipeEnd). You can obtain each end (after calling create()) using |
469 | readEnd() and writeEnd(), however you must call enable() on each end |
470 | before using the pipe. |
471 | |
472 | By default, the pipe ends are not inheritable by child processes. On |
473 | Windows, the pipe is created with inheritability disabled. On Unix, the |
474 | FD_CLOEXEC flag is set on each end's file descriptor. |
475 | |
476 | \ingroup UserAPI |
477 | */ |
478 | class QCA_EXPORT QPipe |
479 | { |
480 | public: |
481 | /** |
482 | Standard constructor |
483 | |
484 | \note You must call create() before using the pipe ends. |
485 | |
486 | \param parent the parent object for this object |
487 | */ |
488 | QPipe(QObject *parent = nullptr); |
489 | |
490 | ~QPipe(); |
491 | |
492 | /** |
493 | Reset the pipe. |
494 | |
495 | At this point, the readEnd() and writeEnd() calls |
496 | will no longer be valid. |
497 | */ |
498 | void reset(); |
499 | |
500 | #ifdef QPIPE_SECURE |
501 | /** |
502 | Create the pipe |
503 | |
504 | \param secure whether to use secure memory (true) or not (false) |
505 | */ |
506 | bool create(bool secure = false); |
507 | #else |
508 | /** |
509 | Create the pipe |
510 | */ |
511 | bool create(); |
512 | #endif |
513 | |
514 | /** |
515 | The read end of the pipe. |
516 | */ |
517 | QPipeEnd &readEnd() |
518 | { |
519 | return i; |
520 | } |
521 | |
522 | /** |
523 | The write end of the pipe. |
524 | */ |
525 | QPipeEnd &writeEnd() |
526 | { |
527 | return o; |
528 | } |
529 | |
530 | private: |
531 | Q_DISABLE_COPY(QPipe) |
532 | |
533 | QPipeEnd i, o; |
534 | }; |
535 | |
536 | } |
537 | |
538 | #endif |
539 | |