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>
49typedef HANDLE Q_PIPE_ID;
50#define INVALID_Q_PIPE_ID INVALID_HANDLE_VALUE
51#else
52typedef 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
62namespace 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*/
74class QCA_EXPORT QPipeDevice : public QObject
75{
76 Q_OBJECT
77public:
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
194Q_SIGNALS:
195 /**
196 Emitted when the pipe end can be read from or written to (depending on its Type).
197 */
198 void notify();
199
200private:
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*/
217class QCA_EXPORT QPipeEnd : public QObject
218{
219 Q_OBJECT
220public:
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
416Q_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
454private:
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*/
478class QCA_EXPORT QPipe
479{
480public:
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
530private:
531 Q_DISABLE_COPY(QPipe)
532
533 QPipeEnd i, o;
534};
535
536}
537
538#endif
539

source code of qca/include/QtCrypto/qpipe.h