File indexing completed on 2024-04-28 04:43:42
0001 /* 0002 * Copyright (C) 2003-2007 Justin Karneges <justin@affinix.com> 0003 * 0004 * This library is free software; you can redistribute it and/or 0005 * modify it under the terms of the GNU Lesser General Public 0006 * License as published by the Free Software Foundation; either 0007 * version 2.1 of the License, or (at your option) any later version. 0008 * 0009 * This library is distributed in the hope that it will be useful, 0010 * but WITHOUT ANY WARRANTY; without even the implied warranty of 0011 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 0012 * Lesser General Public License for more details. 0013 * 0014 * You should have received a copy of the GNU Lesser General Public 0015 * License along with this library; if not, write to the Free Software 0016 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 0017 * 02110-1301 USA 0018 * 0019 */ 0020 0021 /** 0022 \file qpipe.h 0023 0024 Header file for the QPipe FIFO class 0025 0026 \note You should not use this header directly from an 0027 application. You should just use <tt> \#include \<QtCrypto> 0028 </tt> instead. 0029 */ 0030 0031 #ifndef QPIPE_H 0032 #define QPIPE_H 0033 0034 #ifndef DOXYGEN_SHOULD_SKIP_THIS 0035 0036 #ifndef QPIPE_NO_SECURE 0037 #define QPIPE_SECURE 0038 #endif 0039 0040 #ifdef QPIPE_SECURE 0041 #include "QtCrypto" 0042 #else 0043 #define QCA_EXPORT 0044 #endif 0045 0046 // defs adapted qprocess_p.h 0047 #ifdef Q_OS_WIN 0048 #include <windows.h> 0049 typedef HANDLE Q_PIPE_ID; 0050 #define INVALID_Q_PIPE_ID INVALID_HANDLE_VALUE 0051 #else 0052 typedef int Q_PIPE_ID; 0053 #define INVALID_Q_PIPE_ID -1 0054 #endif 0055 0056 #endif 0057 0058 // Note: for Windows console, I/O must be in UTF-8. Reads are guaranteed to 0059 // to completely decode (no partial characters). Likewise, writes must 0060 // not contain partial characters. 0061 0062 namespace QCA { 0063 0064 /** 0065 \class QPipeDevice qpipe.h QtCrypto 0066 0067 Unbuffered direct pipe. 0068 0069 This class is not usually required except for very low level operations. 0070 You should use QPipe and QPipeEnd for most applications. 0071 0072 \ingroup UserAPI 0073 */ 0074 class QCA_EXPORT QPipeDevice : public QObject 0075 { 0076 Q_OBJECT 0077 public: 0078 /** 0079 The type of device 0080 */ 0081 enum Type 0082 { 0083 Read, ///< The pipe end can be read from 0084 Write ///< The pipe end can be written to 0085 }; 0086 0087 /** 0088 Standard constructor 0089 0090 \param parent the parent object to this object 0091 */ 0092 QPipeDevice(QObject *parent = nullptr); 0093 ~QPipeDevice() override; 0094 0095 /** 0096 The Type of the pipe device (that is, read or write) 0097 */ 0098 Type type() const; 0099 0100 /** 0101 Test whether this object corresponds to a valid pipe 0102 */ 0103 bool isValid() const; 0104 0105 /** 0106 The low level identification for this pipe. 0107 0108 On Windows, this is a HANDLE. On Unix, this is a file descriptor (i.e. integer). 0109 0110 Code using this method should be carefully tested for portability. 0111 0112 \sa idAsInt 0113 */ 0114 Q_PIPE_ID id() const; 0115 0116 /** 0117 The low level identification for this pipe, returned as an integer. 0118 0119 Code using this method should be carefully tested for portability. 0120 0121 \sa id(). 0122 */ 0123 int idAsInt() const; 0124 0125 /** 0126 Take over an existing pipe id, closing the old pipe if any. 0127 0128 \param id the identification of the pipe end to take over. 0129 \param t the type of pipe end (read or write). 0130 */ 0131 void take(Q_PIPE_ID id, Type t); 0132 0133 /** 0134 Enable the pipe for reading or writing (depending on Type) 0135 */ 0136 void enable(); 0137 0138 /** 0139 Close the pipe end. 0140 */ 0141 void close(); 0142 0143 /** 0144 Release the pipe end, but do not close it. 0145 */ 0146 void release(); 0147 0148 /** 0149 Set the pipe end to be inheritable 0150 0151 \note On Windows, this operation changes the pipe end id value. 0152 0153 \param enabled whether the pipe is inheritable (true) or not (false) 0154 */ 0155 bool setInheritable(bool enabled); 0156 0157 /** 0158 Obtain the number of bytes available to be read. 0159 */ 0160 int bytesAvailable() const; 0161 0162 /** 0163 Read from the pipe end 0164 0165 \param data where to put the data that has been read 0166 \param maxsize the maximum number of bytes to be read. 0167 0168 \return the actual number of bytes read, 0 on end-of-file, or -1 on error. 0169 */ 0170 int read(char *data, int maxsize); 0171 0172 /** 0173 Write to the pipe end. 0174 0175 \param data the source of the data to be written 0176 \param size the number of bytes in the data to be written 0177 0178 \note the data source must remain valid 0179 0180 \return the number of bytes written, or -1 on error. 0181 */ 0182 int write(const char *data, int size); 0183 0184 /** 0185 The result of a write operation 0186 0187 \param written if not null, this will be set to the number of 0188 bytes written in the last operation. 0189 0190 \return 0 on success (all data written), or -1 on error 0191 */ 0192 int writeResult(int *written) const; 0193 0194 Q_SIGNALS: 0195 /** 0196 Emitted when the pipe end can be read from or written to (depending on its Type). 0197 */ 0198 void notify(); 0199 0200 private: 0201 Q_DISABLE_COPY(QPipeDevice) 0202 0203 class Private; 0204 friend class Private; 0205 Private *d; 0206 }; 0207 0208 /** 0209 \class QPipeEnd qpipe.h QtCrypto 0210 0211 A buffered higher-level pipe end 0212 0213 This is either the read end or write end of a QPipe. 0214 0215 \ingroup UserAPI 0216 */ 0217 class QCA_EXPORT QPipeEnd : public QObject 0218 { 0219 Q_OBJECT 0220 public: 0221 /** 0222 The type of error 0223 */ 0224 enum Error 0225 { 0226 ErrorEOF, ///< End of file error 0227 ErrorBroken ///< Broken pipe error 0228 }; 0229 0230 /** 0231 Standard constructor 0232 0233 \param parent the parent object for this object 0234 */ 0235 QPipeEnd(QObject *parent = nullptr); 0236 0237 ~QPipeEnd() override; 0238 0239 /** 0240 Reset the pipe end to an inactive state 0241 */ 0242 void reset(); 0243 0244 /** 0245 The type of pipe end (either read or write) 0246 */ 0247 QPipeDevice::Type type() const; 0248 0249 /** 0250 Determine whether the pipe end is valid. 0251 0252 \note This does not mean the pipe is ready to be used - you 0253 may need to call enable() first 0254 */ 0255 bool isValid() const; 0256 0257 /** 0258 Pipe identification 0259 */ 0260 Q_PIPE_ID id() const; 0261 0262 /** 0263 Pipe identification 0264 */ 0265 int idAsInt() const; 0266 0267 /** 0268 Take over an existing pipe handle 0269 0270 \param id the pipe handle 0271 \param t the type of the pipe (read or write) 0272 */ 0273 void take(Q_PIPE_ID id, QPipeDevice::Type t); 0274 0275 #ifdef QPIPE_SECURE 0276 /** 0277 Sets whether the pipe uses secure memory for read/write 0278 0279 Enabling this may reduce performance, and it should only be used if 0280 sensitive data is being transmitted (such as a passphrase). 0281 0282 \param secure whether the pipe uses secure memory (true) or not (false). 0283 */ 0284 void setSecurityEnabled(bool secure); 0285 #endif 0286 0287 /** 0288 Enable the endpoint for the pipe 0289 0290 When an endpoint is created, it is not 0291 able to be used until it is enabled. 0292 */ 0293 void enable(); 0294 0295 /** 0296 Close the end of the pipe 0297 0298 \sa closed() 0299 */ 0300 void close(); 0301 0302 /** 0303 Let go of the active pipe handle, but don't close it 0304 0305 Use this before destructing QPipeEnd, if you don't want the pipe 0306 to automatically close. 0307 */ 0308 void release(); 0309 0310 /** 0311 Sets whether the pipe should be inheritable to child processes 0312 0313 Returns true if inheritability was successfully changed, otherwise 0314 false. 0315 0316 \param enabled whether the pipe is inheritable (true) or not (false). 0317 */ 0318 bool setInheritable(bool enabled); 0319 0320 /** 0321 Clear the contents of the pipe, and invalidate the pipe 0322 */ 0323 void finalize(); 0324 0325 /** 0326 Clear the contents of the pipe, and release the pipe 0327 */ 0328 void finalizeAndRelease(); 0329 0330 /** 0331 Determine how many bytes are available to be read. 0332 0333 This only makes sense at the read end of the pipe 0334 0335 \sa readyRead() for a signal that can be used to determine 0336 when there are bytes available to read. 0337 */ 0338 int bytesAvailable() const; 0339 0340 /** 0341 Returns the number of bytes pending to write 0342 0343 This only makes sense at the write end of the pipe 0344 0345 \sa bytesWritten() for a signal that can be used to determine 0346 when bytes have been written 0347 */ 0348 int bytesToWrite() const; 0349 0350 /** 0351 Read bytes from the pipe. 0352 0353 You can only call this on the read end of the pipe 0354 0355 If the pipe is using secure memory, you should use readSecure() 0356 0357 \param bytes the number of bytes to read (-1 for all 0358 content). 0359 */ 0360 QByteArray read(int bytes = -1); 0361 0362 /** 0363 Write bytes to the pipe. 0364 0365 You can only call this on the write end of the pipe. 0366 0367 If the pipe is using secure memory, you should use writeSecure(). 0368 0369 \param a the array to write to the pipe 0370 */ 0371 void write(const QByteArray &a); 0372 0373 #ifdef QPIPE_SECURE 0374 /** 0375 Read bytes from the pipe. 0376 0377 You can only call this on the read end of the pipe 0378 0379 If the pipe is using insecure memory, you should use read() 0380 0381 \param bytes the number of bytes to read (-1 for all 0382 content). 0383 */ 0384 SecureArray readSecure(int bytes = -1); 0385 0386 /** 0387 Write bytes to the pipe. 0388 0389 You can only call this on the write end of the pipe. 0390 0391 If the pipe is using insecure memory, you should use write(). 0392 0393 \param a the array to write to the pipe 0394 */ 0395 void writeSecure(const SecureArray &a); 0396 #endif 0397 0398 /** 0399 Returns any unsent bytes queued for writing 0400 0401 If the pipe is using secure memory, you should use 0402 takeBytesToWriteSecure(). 0403 */ 0404 QByteArray takeBytesToWrite(); 0405 0406 #ifdef QPIPE_SECURE 0407 /** 0408 Returns any unsent bytes queued for writing 0409 0410 If the pipe is using insecure memory, you should use 0411 takeBytesToWrite(). 0412 */ 0413 SecureArray takeBytesToWriteSecure(); 0414 #endif 0415 0416 Q_SIGNALS: 0417 /** 0418 Emitted when there are bytes available to be read 0419 from the read end of the pipe. 0420 0421 \sa bytesAvailable() 0422 */ 0423 void readyRead(); 0424 0425 /** 0426 Emitted when bytes have been written to the 0427 write end of the pipe. 0428 0429 \param bytes the number of bytes written 0430 */ 0431 void bytesWritten(int bytes); 0432 0433 /** 0434 Emitted when this end of the pipe is closed as a result of calling 0435 close() 0436 0437 If this is the write end of the pipe and there is data still 0438 pending to write, this signal will be emitted once all of the data 0439 has been written. 0440 0441 To be notified if the other end of the pipe has been closed, see 0442 error(). 0443 */ 0444 void closed(); 0445 0446 /** 0447 Emitted when the pipe encounters an error trying to read or write, 0448 or if the other end of the pipe has been closed 0449 0450 \param e the reason for error 0451 */ 0452 void error(QCA::QPipeEnd::Error e); 0453 0454 private: 0455 Q_DISABLE_COPY(QPipeEnd) 0456 0457 class Private; 0458 friend class Private; 0459 Private *d; 0460 }; 0461 0462 /** 0463 \class QPipe qpipe.h QtCrypto 0464 0465 A FIFO buffer (named pipe) abstraction 0466 0467 This class creates a full buffer, consisting of two ends 0468 (QPipeEnd). You can obtain each end (after calling create()) using 0469 readEnd() and writeEnd(), however you must call enable() on each end 0470 before using the pipe. 0471 0472 By default, the pipe ends are not inheritable by child processes. On 0473 Windows, the pipe is created with inheritability disabled. On Unix, the 0474 FD_CLOEXEC flag is set on each end's file descriptor. 0475 0476 \ingroup UserAPI 0477 */ 0478 class QCA_EXPORT QPipe 0479 { 0480 public: 0481 /** 0482 Standard constructor 0483 0484 \note You must call create() before using the pipe ends. 0485 0486 \param parent the parent object for this object 0487 */ 0488 QPipe(QObject *parent = nullptr); 0489 0490 ~QPipe(); 0491 0492 /** 0493 Reset the pipe. 0494 0495 At this point, the readEnd() and writeEnd() calls 0496 will no longer be valid. 0497 */ 0498 void reset(); 0499 0500 #ifdef QPIPE_SECURE 0501 /** 0502 Create the pipe 0503 0504 \param secure whether to use secure memory (true) or not (false) 0505 */ 0506 bool create(bool secure = false); 0507 #else 0508 /** 0509 Create the pipe 0510 */ 0511 bool create(); 0512 #endif 0513 0514 /** 0515 The read end of the pipe. 0516 */ 0517 QPipeEnd &readEnd() 0518 { 0519 return i; 0520 } 0521 0522 /** 0523 The write end of the pipe. 0524 */ 0525 QPipeEnd &writeEnd() 0526 { 0527 return o; 0528 } 0529 0530 private: 0531 Q_DISABLE_COPY(QPipe) 0532 0533 QPipeEnd i, o; 0534 }; 0535 0536 } 0537 0538 #endif