QCA

qpipe.h
Go to the documentation of this file.
1 /*
2  * Copyright (C) 2003-2007 Justin Karneges <[email protected]>
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  */
518  {
519  return i;
520  }
521 
522  /**
523  The write end of the pipe.
524  */
526  {
527  return o;
528  }
529 
530 private:
531  Q_DISABLE_COPY(QPipe)
532 
533  QPipeEnd i, o;
534 };
535 
536 }
537 
538 #endif
Type
The type of device.
Definition: qpipe.h:81
virtual void release(quint64 objid)
QCA - the Qt Cryptographic Architecture.
Definition: qca_basic.h:41
@ ErrorEOF
End of file error.
Definition: qpipe.h:226
QPipeEnd & readEnd()
The read end of the pipe.
Definition: qpipe.h:517
typedef HANDLE
@ Read
The pipe end can be read from.
Definition: qpipe.h:83
QPipeEnd & writeEnd()
The write end of the pipe.
Definition: qpipe.h:525
Error
The type of error.
Definition: qpipe.h:224
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Sun Jun 4 2023 03:50:13 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.