1 | /* |
2 | * qca_support.h - Qt Cryptographic Architecture |
3 | * Copyright (C) 2003-2005 Justin Karneges <justin@affinix.com> |
4 | * Copyright (C) 2004,2005, 2007 Brad Hards <bradh@frogmouth.net> |
5 | * |
6 | * This library is free software; you can redistribute it and/or |
7 | * modify it under the terms of the GNU Lesser General Public |
8 | * License as published by the Free Software Foundation; either |
9 | * version 2.1 of the License, or (at your option) any later version. |
10 | * |
11 | * This library is distributed in the hope that it will be useful, |
12 | * but WITHOUT ANY WARRANTY; without even the implied warranty of |
13 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
14 | * Lesser General Public License for more details. |
15 | * |
16 | * You should have received a copy of the GNU Lesser General Public |
17 | * License along with this library; if not, write to the Free Software |
18 | * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA |
19 | * 02110-1301 USA |
20 | * |
21 | */ |
22 | |
23 | /** |
24 | \file qca_support.h |
25 | |
26 | Header file for "support" classes used in %QCA |
27 | |
28 | The classes in this header do not have any cryptographic |
29 | content - they are used in %QCA, and are included for convenience. |
30 | |
31 | \note You should not use this header directly from an |
32 | application. You should just use <tt> \#include \<QtCrypto> |
33 | </tt> instead. |
34 | */ |
35 | |
36 | #ifndef QCA_SUPPORT_H |
37 | #define QCA_SUPPORT_H |
38 | |
39 | #include "qca_export.h" |
40 | #include "qca_tools.h" |
41 | #include <QByteArray> |
42 | #include <QList> |
43 | #include <QMetaObject> |
44 | #include <QObject> |
45 | #include <QString> |
46 | #include <QStringList> |
47 | #include <QThread> |
48 | #include <QVariant> |
49 | #include <QVariantList> |
50 | |
51 | namespace QCA { |
52 | |
53 | /** |
54 | Convenience method to determine the return type of a method |
55 | |
56 | This function identifies the return type of a specified |
57 | method. This function can be used as shown: |
58 | \code |
59 | class TestClass : public QObject |
60 | { |
61 | Q_OBJECT |
62 | // ... |
63 | public slots: |
64 | QString qstringMethod() { return QString(); }; |
65 | bool boolMethod( const QString & ) { return true; }; |
66 | }; |
67 | |
68 | QByteArray myTypeName; |
69 | |
70 | TestClass testClass; |
71 | QList<QByteArray> argsList; // empty list, since no args |
72 | |
73 | myTypeName = QCA::methodReturnType( testClass.metaObject(), QByteArray( "qstringMethod" ), argsList ); |
74 | // myTypeName is "QString" |
75 | |
76 | myTypeName = QCA::methodReturnType( testClass.metaObject(), QByteArray( "boolMethod" ), argsList ); |
77 | // myTypeName is "", because there is no method called "boolMethod" that has no arguments |
78 | |
79 | argsList << "QString"; // now we have one argument |
80 | myTypeName = QCA::methodReturnType( testClass.metaObject(), QByteArray( "boolMethod" ), argsList ); |
81 | // myTypeName is "bool" |
82 | \endcode |
83 | |
84 | The return type name of a method returning void is an empty string, not "void" |
85 | |
86 | \note This function is not normally required for use with |
87 | %QCA. It is provided for use in your code, if required. |
88 | |
89 | \param obj the QMetaObject for the object |
90 | \param method the name of the method (without the arguments or brackets) |
91 | \param argTypes the list of argument types of the method |
92 | |
93 | \return the name of the type that this method will return with the specified |
94 | argument types. |
95 | |
96 | \sa QMetaType for more information on the Qt meta type system. |
97 | |
98 | \relates SyncThread |
99 | */ |
100 | |
101 | #if QT_VERSION >= QT_VERSION_CHECK(6, 0, 0) |
102 | QCA_EXPORT int methodReturnType(const QMetaObject *obj, const QByteArray &method, const QList<QByteArray> &argTypes); |
103 | #else |
104 | QCA_EXPORT QByteArray methodReturnType(const QMetaObject *obj, |
105 | const QByteArray &method, |
106 | const QList<QByteArray> argTypes); |
107 | #endif |
108 | |
109 | /** |
110 | Convenience method to invoke a method by name, using a variant |
111 | list of arguments. |
112 | |
113 | This function can be used as shown: |
114 | \code |
115 | class TestClass : public QObject |
116 | { |
117 | Q_OBJECT |
118 | // ... |
119 | public slots: |
120 | QString qstringMethod() { return QString( "the result" ); }; |
121 | bool boolMethod( const QString & ) { return true; }; |
122 | }; |
123 | |
124 | TestClass *testClass = new TestClass; |
125 | QVariantList args; |
126 | |
127 | QVariant stringRes; |
128 | // calls testClass->qstringMethod() with no arguments ( since args is an empty list) |
129 | bool ret = QCA::invokeMethodWithVariants( testClass, QByteArray( "qstringMethod" ), args, &stringRes ); |
130 | // ret is true (since call succeeded), stringRes.toString() is a string - "the result" |
131 | |
132 | QVariant boolResult; |
133 | QString someString( "not important" ); |
134 | args << someString; |
135 | // calls testClass->boolMethod( someString ), returning result in boolResult |
136 | ret = QCA::invokeMethodWithVariants( testClass1, QByteArray( "boolMethod" ), args, &boolResult ); |
137 | // ret is true (since call succeeded), boolResult.toBool() is true. |
138 | \endcode |
139 | |
140 | \param obj the object to call the method on |
141 | \param method the name of the method (without the arguments or brackets) |
142 | \param args the list of arguments to use in the method call |
143 | \param ret the return value of the method (unchanged if the call fails) |
144 | \param type the type of connection to use |
145 | |
146 | \return true if the call succeeded, otherwise false |
147 | |
148 | \relates SyncThread |
149 | */ |
150 | QCA_EXPORT bool invokeMethodWithVariants(QObject *obj, |
151 | const QByteArray &method, |
152 | const QVariantList &args, |
153 | QVariant *ret, |
154 | Qt::ConnectionType type = Qt::AutoConnection); |
155 | |
156 | /** |
157 | \class SyncThread qca_support.h QtCrypto |
158 | |
159 | Convenience class to run a thread and interact with it synchronously |
160 | |
161 | SyncThread makes it easy to perform the common practice of starting a |
162 | thread, running some objects in that thread, and then interacting with |
163 | those objects safely. Often, there is no need to directly use threading |
164 | primitives (e.g. QMutex), resulting in very clean multi-threaded code. |
165 | |
166 | \note The following is an excerpt from |
167 | http://delta.affinix.com/2006/11/13/synchronized-threads-part-3/ |
168 | |
169 | ---<br> |
170 | With SyncThread, you can start, stop, and call a method in another thread |
171 | while the main thread sleeps. The only requirement is that the methods be |
172 | declared as slots. |
173 | |
174 | Below is a contrived example, where we have an object in another thread |
175 | that increments a counter over a some interval, using the Qt event loop, |
176 | and provides a method to inspect the value. |
177 | |
178 | First, the Counter object: |
179 | |
180 | \code |
181 | class Counter : public QObject |
182 | { |
183 | Q_OBJECT |
184 | private: |
185 | int x; |
186 | QTimer timer; |
187 | |
188 | public: |
189 | Counter() : timer(this) |
190 | { |
191 | x = 0; |
192 | connect(&timer, &QTimer::timeout, this, &Counter::t_timeout); |
193 | } |
194 | |
195 | public slots: |
196 | void start(int seconds) |
197 | { |
198 | timer.setInterval(seconds * 1000); |
199 | timer.start(); |
200 | } |
201 | |
202 | int value() const |
203 | { |
204 | return x; |
205 | } |
206 | |
207 | private Q_SLOTS: |
208 | void t_timeout() |
209 | { |
210 | ++x; |
211 | } |
212 | }; |
213 | \endcode |
214 | |
215 | Looks like a typical object, no surprises. |
216 | |
217 | Now to wrap Counter with SyncThread. We went over how to do this in the |
218 | first article, and it is very straightforward: |
219 | |
220 | \code |
221 | class CounterThread : public SyncThread |
222 | { |
223 | Q_OBJECT |
224 | public: |
225 | Counter *counter; |
226 | |
227 | CounterThread(QObject *parent) : SyncThread(parent) |
228 | { |
229 | counter = 0; |
230 | } |
231 | |
232 | ~CounterThread() |
233 | { |
234 | // SyncThread will stop the thread on destruct, but since our |
235 | // atStop() function makes references to CounterThread's |
236 | // members, we need to shutdown here, before CounterThread |
237 | // destructs. |
238 | stop(); |
239 | } |
240 | |
241 | protected: |
242 | virtual void atStart() |
243 | { |
244 | counter = new Counter; |
245 | } |
246 | |
247 | virtual void atStop() |
248 | { |
249 | delete counter; |
250 | } |
251 | }; |
252 | \endcode |
253 | |
254 | We can then use it like this: |
255 | |
256 | \code |
257 | CounterThread *thread = new CounterThread; |
258 | |
259 | // after this call, the thread is started and the Counter is ready |
260 | thread->start(); |
261 | |
262 | // let's start the counter with a 1 second interval |
263 | thread->call(thread->counter, "start", QVariantList() << 1); |
264 | ... |
265 | |
266 | // after some time passes, let's check on the value |
267 | int x = thread->call(thread->counter, "value").toInt(); |
268 | |
269 | // we're done with this thing |
270 | delete thread; |
271 | \endcode |
272 | |
273 | Even without the call() function, SyncThread is still very useful |
274 | for preparing objects in another thread, which you can then |
275 | QObject::connect() to and use signals and slots like normal. |
276 | |
277 | \ingroup UserAPI |
278 | */ |
279 | class QCA_EXPORT SyncThread : public QThread |
280 | { |
281 | Q_OBJECT |
282 | public: |
283 | /** |
284 | Standard constructor |
285 | |
286 | \param parent the parent object for this parent. |
287 | */ |
288 | SyncThread(QObject *parent = nullptr); |
289 | |
290 | /** |
291 | Calls stop() and then destructs |
292 | |
293 | \note Subclasses should call stop() in their own destructor |
294 | */ |
295 | ~SyncThread() override; |
296 | |
297 | /** |
298 | Starts the thread, begins the event loop the thread, and then |
299 | calls atStart() in the thread. This function will block until |
300 | atStart() has returned. |
301 | */ |
302 | void start(); |
303 | |
304 | /** |
305 | Stops the event loop of the thread, calls atStop() in the thread, |
306 | and instructs the thread to finish. This function will block |
307 | until the thread has finished. |
308 | */ |
309 | void stop(); |
310 | |
311 | /** |
312 | Calls a slot of an object in the thread. This function will block |
313 | until the slot has returned. |
314 | |
315 | It is possible for the call to fail, for example if the method |
316 | does not exist. |
317 | |
318 | The arguments and return value of the call use QVariant. If the |
319 | method has no return value (returns void), then the returned |
320 | QVariant will be null. |
321 | |
322 | \param obj the object to call the method on |
323 | \param method the name of the method (without the arguments or |
324 | brackets) |
325 | \param args the list of arguments to use in the method call |
326 | \param ok if not 0, true is stored here if the call succeeds, |
327 | otherwise false is stored here. |
328 | */ |
329 | QVariant |
330 | call(QObject *obj, const QByteArray &method, const QVariantList &args = QVariantList(), bool *ok = nullptr); |
331 | |
332 | protected: |
333 | /** |
334 | Reimplement this to perform your initialization |
335 | */ |
336 | virtual void atStart() = 0; |
337 | |
338 | /** |
339 | Reimplement this to perform your deinitialization |
340 | */ |
341 | virtual void atEnd() = 0; |
342 | |
343 | /** |
344 | Starts the event loop and calls atStart and atStop as necessary |
345 | */ |
346 | void run() override; |
347 | |
348 | private: |
349 | Q_DISABLE_COPY(SyncThread) |
350 | |
351 | class Private; |
352 | friend class Private; |
353 | Private *d; |
354 | }; |
355 | |
356 | /** |
357 | \class Synchronizer qca_support.h QtCrypto |
358 | |
359 | Enable synchronization between two threads. |
360 | */ |
361 | class QCA_EXPORT Synchronizer : public QObject |
362 | { |
363 | Q_OBJECT |
364 | public: |
365 | /** |
366 | Standard constructor |
367 | |
368 | \param parent the parent object to this object |
369 | */ |
370 | Synchronizer(QObject *parent); |
371 | ~Synchronizer() override; |
372 | |
373 | /** |
374 | Call to pause execution in this thread. This function |
375 | will block until conditionMet() is called. |
376 | |
377 | \param msecs the time to wait before proceeding. The default |
378 | timeout value (-1) indicates to wait indefinitely. |
379 | */ |
380 | bool waitForCondition(int msecs = -1); |
381 | |
382 | /** |
383 | Call to continue execution in the paused thread. |
384 | */ |
385 | void conditionMet(); |
386 | |
387 | private: |
388 | Q_DISABLE_COPY(Synchronizer) |
389 | |
390 | class Private; |
391 | Private *d; |
392 | }; |
393 | |
394 | /** |
395 | \class DirWatch qca_support.h QtCrypto |
396 | |
397 | Support class to monitor a directory for activity. |
398 | |
399 | %DirWatch monitors a specified file for any changes. When |
400 | the directory changes, the changed() signal is emitted. |
401 | |
402 | \note QFileSystemWatcher has very similar functionality |
403 | to this class. You should evaluate this class and |
404 | QFileSystemWatcher to determine which better suits your |
405 | application needs. |
406 | |
407 | \ingroup UserAPI |
408 | */ |
409 | class QCA_EXPORT DirWatch : public QObject |
410 | { |
411 | Q_OBJECT |
412 | public: |
413 | /** |
414 | Standard constructor |
415 | |
416 | \param dir the name of the directory to watch. If not |
417 | set in the constructor, you can set it using setDirName() |
418 | \param parent the parent object for this object |
419 | */ |
420 | explicit DirWatch(const QString &dir = QString(), QObject *parent = nullptr); |
421 | ~DirWatch() override; |
422 | |
423 | /** |
424 | The name of the directory that is being monitored |
425 | */ |
426 | QString dirName() const; |
427 | |
428 | /** |
429 | Change the directory being monitored |
430 | |
431 | \param dir the name of the directory to monitor |
432 | */ |
433 | void setDirName(const QString &dir); |
434 | |
435 | Q_SIGNALS: |
436 | /** |
437 | The changed signal is emitted when the directory is |
438 | changed (e.g.\ modified by addition or deletion of a |
439 | file within the directory, or the deletion of the |
440 | directory) |
441 | */ |
442 | void changed(); |
443 | |
444 | private: |
445 | Q_DISABLE_COPY(DirWatch) |
446 | |
447 | class Private; |
448 | friend class Private; |
449 | Private *d; |
450 | }; |
451 | |
452 | /** |
453 | \class FileWatch qca_support.h QtCrypto |
454 | |
455 | Support class to monitor a file for activity |
456 | |
457 | %FileWatch monitors a specified file for any changes. When |
458 | the file changes, the changed() signal is emitted. |
459 | |
460 | \note QFileSystemWatcher has very similar functionality |
461 | to this class. You should evaluate this class and |
462 | QFileSystemWatcher to determine which better suits your |
463 | application needs. |
464 | |
465 | \ingroup UserAPI |
466 | */ |
467 | class QCA_EXPORT FileWatch : public QObject |
468 | { |
469 | Q_OBJECT |
470 | public: |
471 | /** |
472 | Standard constructor |
473 | |
474 | \param file the name of the file to watch. If not |
475 | in this object, you can set it using setFileName() |
476 | \param parent the parent object for this object |
477 | */ |
478 | explicit FileWatch(const QString &file = QString(), QObject *parent = nullptr); |
479 | ~FileWatch() override; |
480 | |
481 | /** |
482 | The name of the file that is being monitored |
483 | */ |
484 | QString fileName() const; |
485 | |
486 | /** |
487 | Change the file being monitored |
488 | |
489 | \param file the name of the file to monitor |
490 | */ |
491 | void setFileName(const QString &file); |
492 | |
493 | Q_SIGNALS: |
494 | /** |
495 | The changed signal is emitted when the file is |
496 | changed (e.g. modified, deleted) |
497 | */ |
498 | void changed(); |
499 | |
500 | private: |
501 | Q_DISABLE_COPY(FileWatch) |
502 | |
503 | class Private; |
504 | friend class Private; |
505 | Private *d; |
506 | }; |
507 | |
508 | class ConsolePrivate; |
509 | class ConsoleReferencePrivate; |
510 | class ConsoleReference; |
511 | |
512 | /** |
513 | \class Console qca_support.h QtCrypto |
514 | |
515 | %QCA %Console system |
516 | |
517 | %QCA provides an API for asynchronous, event-based access to |
518 | the console and stdin/stdout, as these facilities are |
519 | otherwise not portable. The primary use of this system within |
520 | %QCA is for passphrase prompting in command-line applications, |
521 | using the tty console type. |
522 | |
523 | How it works: Create a %Console object for the type of console |
524 | desired, and then use ConsoleReference to act on the console. |
525 | Only one ConsoleReference may operate on a %Console at a time. |
526 | |
527 | A %Console object takes over either the physical console (Console::Tty |
528 | type) or stdin/stdout (Console::Stdio type). Only one of each type |
529 | may be created at a time. |
530 | |
531 | Whenever code is written that needs a tty or stdio object, the |
532 | code should first call one of the static methods (ttyInstance() |
533 | or stdioInstance()) to see if a console object for the desired |
534 | type exists already. If the object exists, use it. If it does |
535 | not exist, the rule is that the relevant code should create the |
536 | object, use the object, and then destroy the object when the |
537 | operation is completed. |
538 | |
539 | By following the above rule, you can write code that utilizes |
540 | a console without the application having to create some master |
541 | console object for you. Of course, if the application has |
542 | created a console then it will be used. |
543 | |
544 | The reason why there is a master console object is that it |
545 | is not guaranteed that all I/O will survive creation and |
546 | destruction of a console object. If you are using the Stdio |
547 | Type, then you probably want a long-lived console object. It |
548 | is possible to capture unprocessed I/O by calling |
549 | bytesLeftToRead or bytesLeftToWrite. However, it is not |
550 | expected that general console-needing code will call these |
551 | functions when utilizing a temporary console. Thus, an |
552 | application developer would need to create his own console |
553 | object, invoke the console-needing code, and then do his own |
554 | extraction of the unprocessed I/O if necessary. Another reason |
555 | to extract unprocessed I/O is if you need to switch from |
556 | %Console back to standard functions (e.g. fgets() ). |
557 | |
558 | \ingroup UserAPI |
559 | */ |
560 | class QCA_EXPORT Console : public QObject |
561 | { |
562 | Q_OBJECT |
563 | public: |
564 | /** |
565 | The type of console object |
566 | */ |
567 | enum Type |
568 | { |
569 | Tty, ///< physical console |
570 | Stdio ///< stdin/stdout |
571 | }; |
572 | /** |
573 | The type of I/O to use with the console object. |
574 | */ |
575 | enum ChannelMode |
576 | { |
577 | Read, ///< Read only (equivalent to stdin) |
578 | ReadWrite ///< Read/write (equivalent to stdin and stdout) |
579 | }; |
580 | |
581 | /** |
582 | The nature of the console operation |
583 | */ |
584 | enum TerminalMode |
585 | { |
586 | Default, ///< use default terminal settings |
587 | Interactive ///< char-by-char input, no echo |
588 | }; |
589 | |
590 | /** |
591 | Standard constructor |
592 | |
593 | Note that library code should not create a new Console object |
594 | without checking whether there is already a Console object of |
595 | the required Type. See the main documentation for Console for the |
596 | rationale for this. |
597 | |
598 | \param type the Type of Console object to create |
599 | \param cmode the ChannelMode (I/O type) to use |
600 | \param tmode the TerminalMode to use |
601 | \param parent the parent object for this object |
602 | |
603 | \sa ttyInstance() and stdioInstance for static methods that allow |
604 | you to test whether there is already a Console object of the |
605 | required Type, and if there is, obtain a reference to that object. |
606 | */ |
607 | Console(Type type, ChannelMode cmode, TerminalMode tmode, QObject *parent = nullptr); |
608 | ~Console() override; |
609 | |
610 | /** |
611 | The Type of this Console object |
612 | */ |
613 | Type type() const; |
614 | |
615 | /** |
616 | The ChannelMode of this Console object |
617 | */ |
618 | ChannelMode channelMode() const; |
619 | |
620 | /** |
621 | The TerminalMode of this Console object |
622 | */ |
623 | TerminalMode terminalMode() const; |
624 | |
625 | /** |
626 | Test whether standard input is redirected. |
627 | |
628 | \sa type() and channelMode() |
629 | */ |
630 | static bool isStdinRedirected(); |
631 | |
632 | /** |
633 | Test whether standard output is redirected. |
634 | |
635 | \sa type() and channelMode() |
636 | */ |
637 | static bool isStdoutRedirected(); |
638 | |
639 | /** |
640 | The current terminal-type console object |
641 | |
642 | \return null if there is no current Console |
643 | of this type, otherwise the Console to use |
644 | */ |
645 | static Console *ttyInstance(); |
646 | |
647 | /** |
648 | The current stdio-type console object |
649 | |
650 | \return null if there is no current Console |
651 | of this type, otherwise the Console to use |
652 | */ |
653 | static Console *stdioInstance(); |
654 | |
655 | /** |
656 | Release the Console |
657 | |
658 | This allows access to buffers containing any remaining data |
659 | */ |
660 | void release(); |
661 | |
662 | /** |
663 | Obtain remaining data from the Console, awaiting |
664 | a read operation |
665 | */ |
666 | QByteArray bytesLeftToRead(); |
667 | |
668 | /** |
669 | Obtain remaining data from the Console, awaiting |
670 | a write operation |
671 | */ |
672 | QByteArray bytesLeftToWrite(); |
673 | |
674 | private: |
675 | Q_DISABLE_COPY(Console) |
676 | |
677 | friend class ConsolePrivate; |
678 | ConsolePrivate *d; |
679 | |
680 | friend class ConsoleReference; |
681 | }; |
682 | |
683 | /** |
684 | \class ConsoleReference qca_support.h QtCrypto |
685 | |
686 | Manager for a Console |
687 | |
688 | \note Only one %ConsoleReference object can be active at a time |
689 | |
690 | \ingroup UserAPI |
691 | */ |
692 | class QCA_EXPORT ConsoleReference : public QObject |
693 | { |
694 | Q_OBJECT |
695 | public: |
696 | /** |
697 | The security setting to use for the Console being managed. |
698 | */ |
699 | enum SecurityMode |
700 | { |
701 | SecurityDisabled, |
702 | SecurityEnabled |
703 | }; |
704 | |
705 | /** |
706 | Standard constructor |
707 | |
708 | \param parent the parent object for this object |
709 | */ |
710 | ConsoleReference(QObject *parent = nullptr); |
711 | ~ConsoleReference() override; |
712 | |
713 | /** |
714 | Set the Console object to be managed, and start processing. |
715 | |
716 | You typically want to use Console::ttyInstance() or |
717 | Console::stdioInstance() to obtain the required Console |
718 | reference. |
719 | |
720 | \param console reference to the Console to be managed |
721 | \param mode the SecurityMode to use for this Console. |
722 | |
723 | \sa QCA::Console for more information on how to handle the |
724 | console aspects of your application or library code. |
725 | */ |
726 | bool start(Console *console, SecurityMode mode = SecurityDisabled); |
727 | |
728 | /** |
729 | Stop processing, and release the Console |
730 | */ |
731 | void stop(); |
732 | |
733 | /** |
734 | The Console object managed by this object |
735 | |
736 | \sa start() to set the Console to be managed |
737 | */ |
738 | Console *console() const; |
739 | |
740 | /** |
741 | The security mode setting for the Console object |
742 | managed by this object. |
743 | |
744 | \sa start() to set the SecurityMode |
745 | */ |
746 | SecurityMode securityMode() const; |
747 | |
748 | /** |
749 | Read data from the Console. |
750 | |
751 | \param bytes the number of bytes to read. The default |
752 | is to read all available bytes |
753 | |
754 | \sa readSecure() for a method suitable for reading |
755 | sensitive data. |
756 | */ |
757 | QByteArray read(int bytes = -1); |
758 | |
759 | /** |
760 | Write data to the Console. |
761 | |
762 | \param a the array of data to write to the Console |
763 | |
764 | \sa writeSecure() for a method suitable for writing |
765 | sensitive data. |
766 | */ |
767 | void write(const QByteArray &a); |
768 | |
769 | /** |
770 | Read secure data from the Console |
771 | |
772 | \param bytes the number of bytes to read. The default |
773 | is to read all available bytes |
774 | |
775 | \sa read() which is suitable for non-sensitive data |
776 | */ |
777 | SecureArray readSecure(int bytes = -1); |
778 | |
779 | /** |
780 | Write secure data to the Console |
781 | |
782 | \param a the array of data to write to the Console |
783 | |
784 | \sa write() which is suitable for non-sensitive data |
785 | */ |
786 | void writeSecure(const SecureArray &a); |
787 | |
788 | /** |
789 | Close the write channel |
790 | |
791 | You only need to call this if writing is enabled |
792 | on the Console being managed. |
793 | */ |
794 | void closeOutput(); |
795 | |
796 | /** |
797 | The number of bytes available to read from the |
798 | Console being managed. |
799 | */ |
800 | int bytesAvailable() const; |
801 | |
802 | /** |
803 | The number of bytes remaining to be written |
804 | to the Console being managed |
805 | */ |
806 | int bytesToWrite() const; |
807 | |
808 | Q_SIGNALS: |
809 | /** |
810 | Emitted when there are bytes available to read from |
811 | the Console being managed |
812 | */ |
813 | void readyRead(); |
814 | |
815 | /** |
816 | Emitted when bytes are written to the Console |
817 | |
818 | \param bytes the number of bytes that were written |
819 | |
820 | \sa bytesAvailable() |
821 | */ |
822 | void bytesWritten(int bytes); |
823 | |
824 | /** |
825 | Emitted when the console input is closed |
826 | */ |
827 | void inputClosed(); |
828 | |
829 | /** |
830 | Emitted when the console output is closed |
831 | */ |
832 | void outputClosed(); |
833 | |
834 | private: |
835 | Q_DISABLE_COPY(ConsoleReference) |
836 | |
837 | friend class ConsoleReferencePrivate; |
838 | ConsoleReferencePrivate *d; |
839 | |
840 | friend class Console; |
841 | }; |
842 | |
843 | /** |
844 | \class ConsolePrompt qca_support.h QtCrypto |
845 | |
846 | Console prompt handler. |
847 | |
848 | This class provides a convenient way to get user input in a secure way, |
849 | as shown below: |
850 | \code |
851 | QCA::ConsolePrompt prompt; |
852 | prompt.getHidden("Passphrase"); |
853 | prompt.waitForFinished(); |
854 | QCA:SecureArray pass = prompt.result(); |
855 | \endcode |
856 | |
857 | \note It is not necessary to use waitForFinished(), because you can |
858 | just connect the finished() signal to a suitable method, however |
859 | command line (console) applications often require waitForFinished(). |
860 | |
861 | \ingroup UserAPI |
862 | */ |
863 | class QCA_EXPORT ConsolePrompt : public QObject |
864 | { |
865 | Q_OBJECT |
866 | public: |
867 | /** |
868 | Standard constructor |
869 | |
870 | \param parent the parent object for this object |
871 | */ |
872 | ConsolePrompt(QObject *parent = nullptr); |
873 | ~ConsolePrompt() override; |
874 | |
875 | /** |
876 | Allow the user to enter data without it being echo'd to |
877 | the terminal. This is particularly useful for entry |
878 | of passwords, passphrases and PINs. |
879 | |
880 | \param promptStr the prompt to display to the user |
881 | |
882 | \sa result() for how to get the input back. |
883 | */ |
884 | void getHidden(const QString &promptStr); |
885 | |
886 | /** |
887 | Obtain one character from the user |
888 | |
889 | \sa resultChar() for how to get the input back. |
890 | */ |
891 | void getChar(); |
892 | |
893 | /** |
894 | Block waiting for user input. |
895 | |
896 | You may wish to use the finished() signal to |
897 | avoid blocking. |
898 | */ |
899 | void waitForFinished(); |
900 | |
901 | /** |
902 | Obtain the result of the user input. |
903 | |
904 | This method is usually called to obtain data |
905 | from the user that was requested by the getHidden() |
906 | call. |
907 | */ |
908 | SecureArray result() const; |
909 | |
910 | /** |
911 | Obtain the result of the user input. |
912 | |
913 | This method is usually called to obtain data |
914 | from the user that was requested by the getChar() |
915 | call. |
916 | */ |
917 | QChar resultChar() const; |
918 | |
919 | Q_SIGNALS: |
920 | /** |
921 | Emitted when the user input activity has been |
922 | completed. |
923 | |
924 | This corresponds to the provision of a string |
925 | for getHidden() or a single character for getChar(). |
926 | |
927 | \sa waitForFinished |
928 | */ |
929 | void finished(); |
930 | |
931 | private: |
932 | Q_DISABLE_COPY(ConsolePrompt) |
933 | |
934 | class Private; |
935 | friend class Private; |
936 | Private *d; |
937 | }; |
938 | |
939 | class AbstractLogDevice; |
940 | |
941 | /** |
942 | \class Logger qca_support.h QtCrypto |
943 | |
944 | A simple logging system |
945 | |
946 | This class provides a simple but flexible approach to logging information |
947 | that may be used for debugging or system operation diagnostics. |
948 | |
949 | There is a single %Logger for each application that uses %QCA. You do not |
950 | need to create this %Logger yourself - %QCA automatically creates it on |
951 | startup. You can get access to the %Logger using the global QCA::logger() |
952 | method. |
953 | |
954 | By default the Logger just accepts all messages (binary and text). If you |
955 | want to get access to those messages, you need to subclass |
956 | AbstractLogDevice, and register your subclass (using registerLogDevice()). |
957 | You can then take whatever action is appropriate (e.g. show to the user |
958 | using the GUI, log to a file or send to standard error). |
959 | |
960 | \ingroup UserAPI |
961 | */ |
962 | class QCA_EXPORT Logger : public QObject |
963 | { |
964 | Q_OBJECT |
965 | public: |
966 | /** |
967 | The severity of the message |
968 | |
969 | This information may be used by the log device to determine |
970 | what the appropriate action is. |
971 | */ |
972 | enum Severity |
973 | { |
974 | Quiet = 0, ///< Quiet: turn of logging |
975 | Emergency = 1, ///< Emergency: system is unusable |
976 | Alert = 2, ///< Alert: action must be taken immediately |
977 | Critical = 3, ///< Critical: critical conditions |
978 | Error = 4, ///< Error: error conditions |
979 | Warning = 5, ///< Warning: warning conditions |
980 | Notice = 6, ///< Notice: normal but significant condition |
981 | Information = 7, ///< Informational: informational messages |
982 | Debug = 8 ///< Debug: debug-level messages |
983 | }; |
984 | |
985 | /** |
986 | Get the current logging level |
987 | |
988 | \return Current level |
989 | */ |
990 | inline Severity level() const |
991 | { |
992 | return m_logLevel; |
993 | } |
994 | |
995 | /** |
996 | Set the current logging level |
997 | |
998 | \param level new logging level |
999 | |
1000 | Only severities less or equal than the log level one will be logged |
1001 | */ |
1002 | void setLevel(Severity level); |
1003 | |
1004 | /** |
1005 | Log a message to all available log devices |
1006 | |
1007 | \param message the text to log |
1008 | */ |
1009 | void logTextMessage(const QString &message, Severity = Information); |
1010 | |
1011 | /** |
1012 | Log a binary blob to all available log devices |
1013 | |
1014 | \param blob the information to log |
1015 | |
1016 | \note how this is handled is quite logger specific. For |
1017 | example, it might be logged as a binary, or it might be |
1018 | encoded in some way |
1019 | */ |
1020 | void logBinaryMessage(const QByteArray &blob, Severity = Information); |
1021 | |
1022 | /** |
1023 | Add an AbstractLogDevice subclass to the existing list of loggers |
1024 | |
1025 | \param logger the LogDevice to add |
1026 | */ |
1027 | void registerLogDevice(AbstractLogDevice *logger); |
1028 | |
1029 | /** |
1030 | Remove an AbstractLogDevice subclass from the existing list of loggers |
1031 | |
1032 | \param loggerName the name of the LogDevice to remove |
1033 | |
1034 | \note If there are several log devices with the same name, all will be removed. |
1035 | */ |
1036 | void unregisterLogDevice(const QString &loggerName); |
1037 | |
1038 | /** |
1039 | Get a list of the names of all registered log devices |
1040 | */ |
1041 | QStringList currentLogDevices() const; |
1042 | |
1043 | private: |
1044 | Q_DISABLE_COPY(Logger) |
1045 | |
1046 | friend class Global; |
1047 | |
1048 | /** |
1049 | Create a new message logger |
1050 | */ |
1051 | Logger(); |
1052 | |
1053 | ~Logger() override; |
1054 | |
1055 | QStringList m_loggerNames; |
1056 | QList<AbstractLogDevice *> m_loggers; |
1057 | Severity m_logLevel; |
1058 | }; |
1059 | |
1060 | /** |
1061 | \class AbstractLogDevice qca_support.h QtCrypto |
1062 | |
1063 | An abstract log device |
1064 | |
1065 | \ingroup UserAPI |
1066 | */ |
1067 | class QCA_EXPORT AbstractLogDevice : public QObject |
1068 | { |
1069 | Q_OBJECT |
1070 | public: |
1071 | /** |
1072 | The name of this log device |
1073 | */ |
1074 | QString name() const; |
1075 | |
1076 | /** |
1077 | Log a message |
1078 | |
1079 | The default implementation does nothing - you should |
1080 | override this method in your subclass to do whatever |
1081 | logging is required |
1082 | |
1083 | \param message the message to log |
1084 | \param severity the severity level of the message |
1085 | */ |
1086 | virtual void logTextMessage(const QString &message, Logger::Severity severity); |
1087 | |
1088 | /** |
1089 | Log a binary blob |
1090 | |
1091 | The default implementation does nothing - you should |
1092 | override this method in your subclass to do whatever |
1093 | logging is required |
1094 | |
1095 | \param blob the message (as a byte array) to log |
1096 | \param severity the severity level of the message |
1097 | */ |
1098 | virtual void logBinaryMessage(const QByteArray &blob, Logger::Severity severity); |
1099 | |
1100 | protected: |
1101 | /** |
1102 | Create a new message logger |
1103 | |
1104 | \param name the name of this log device |
1105 | \param parent the parent for this logger |
1106 | */ |
1107 | explicit AbstractLogDevice(const QString &name, QObject *parent = nullptr); |
1108 | |
1109 | ~AbstractLogDevice() override = 0; |
1110 | |
1111 | private: |
1112 | Q_DISABLE_COPY(AbstractLogDevice) |
1113 | |
1114 | class Private; |
1115 | Private *d; |
1116 | |
1117 | QString m_name; |
1118 | }; |
1119 | |
1120 | } |
1121 | |
1122 | #endif |
1123 | |