QCA

qca_support.h
Go to the documentation of this file.
1 /*
2  * qca_support.h - Qt Cryptographic Architecture
3  * Copyright (C) 2003-2005 Justin Karneges <[email protected]>
4  * Copyright (C) 2004,2005, 2007 Brad Hards <[email protected]>
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,
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  */
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  */
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  */
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
ChannelMode
The type of I/O to use with the console object.
Definition: qca_support.h:575
TerminalMode
The nature of the console operation.
Definition: qca_support.h:584
Type
The type of console object.
Definition: qca_support.h:567
Severity
The severity of the message.
Definition: qca_support.h:972
void stop(Ekos::AlignState mode)
virtual void release(quint64 objid)
Q_SCRIPTABLE Q_NOREPLY void start()
QCA - the Qt Cryptographic Architecture.
Definition: qca_basic.h:41
Severity level() const
Get the current logging level.
Definition: qca_support.h:990
@ Read
Read only (equivalent to stdin)
Definition: qca_support.h:577
@ Tty
physical console
Definition: qca_support.h:569
ConnectionType
QCA_EXPORT Logger * logger()
Return a reference to the QCA Logger, which is used for diagnostics and error recording.
@ Default
use default terminal settings
Definition: qca_support.h:586
SecurityMode
The security setting to use for the Console being managed.
Definition: qca_support.h:699
QString message
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Mon May 8 2023 03:50:08 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.