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 */ readEnd()517 QPipeEnd &readEnd() 518 { 519 return i; 520 } 521 522 /** 523 The write end of the pipe. 524 */ writeEnd()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