From a75a02455db59d6b5a26acf7d9be1d29fb7d8194 Mon Sep 17 00:00:00 2001 From: Brad Hards Date: Tue, 21 Aug 2007 07:35:34 +0000 Subject: [PATCH] Add in the missing API documentation. svn path=/trunk/kdesupport/qca/; revision=702796 --- include/QtCrypto/qca_support.h | 434 ++++++++++++++++++++++++++++----- include/QtCrypto/qpipe.h | 129 ++++++++-- 2 files changed, 493 insertions(+), 70 deletions(-) diff --git a/include/QtCrypto/qca_support.h b/include/QtCrypto/qca_support.h index f48da9d6..5a0b9558 100644 --- a/include/QtCrypto/qca_support.h +++ b/include/QtCrypto/qca_support.h @@ -342,14 +342,35 @@ private: Private *d; }; +/** + \class Synchronizer qca_support.h QtCrypto + + Enable synchronization between two threads. +*/ class QCA_EXPORT Synchronizer : public QObject { Q_OBJECT public: + /** + Standard constructor + + \param parent the parent object to this object + */ Synchronizer(QObject *parent); ~Synchronizer(); + /** + Call to pause execution in this thread. This function + will block until conditionMet() is called. + + \param msecs the time to wait before proceeding. The default + timeout value (-1) indicates to wait indefinitely. + */ bool waitForCondition(int msecs = -1); + + /** + Call to continue execution in the paused thread. + */ void conditionMet(); private: @@ -359,17 +380,54 @@ private: Private *d; }; +/** + \class DirWatch qca_support.h QtCrypto + + Support class to monitor a directory for activity. + + %DirWatch monitors a specified file for any changes. When + the directory changes, the changed() signal is emitted. + + \note QFileSystemWatcher has very similar functionality + to this class. You should evaluate this class and + QFileSystemWatcher to determine which better suits your + application needs. + + \ingroup UserAPI +*/ class QCA_EXPORT DirWatch : public QObject { Q_OBJECT public: + /** + Standard constructor + + \param dir the name of the directory to watch. If not + set in the constructor, you can set it using setDirName() + \param parent the parent object for this object + */ explicit DirWatch(const QString &dir = QString(), QObject *parent = 0); ~DirWatch(); + /** + The name of the directory that is being monitored + */ QString dirName() const; + + /** + Change the directory being monitored + + \param dir the name of the directory to monitor + */ void setDirName(const QString &dir); Q_SIGNALS: + /** + The changed signal is emitted when the directory is + changed (e.g. modified by addition or deletion of a + file within the directory, or the deletion of the + directory) + */ void changed(); private: @@ -388,6 +446,11 @@ private: %FileWatch monitors a specified file for any changes. When the file changes, the changed() signal is emitted. + \note QFileSystemWatcher has very similar functionality + to this class. You should evaluate this class and + QFileSystemWatcher to determine which better suits your + application needs. + \ingroup UserAPI */ class QCA_EXPORT FileWatch : public QObject @@ -435,87 +498,166 @@ class ConsolePrivate; class ConsoleReferencePrivate; class ConsoleReference; -// QCA Console system -// -// QCA provides an API for asynchronous, event-based access to -// the console and stdin/stdout, as these facilities are -// otherwise not portable. The primary use of this system within -// QCA is for passphrase prompting in command-line applications, -// using the tty console type. -// -// How it works: Create a Console object for the type of console -// desired, and then use ConsoleReference to act on the console. -// Only one ConsoleReference may operate on a Console at a time. -// -// A Console object overtakes either the physical console (tty -// type) or stdin/stdout (stdio type). Only one of each type -// may be created at a time. -// -// Whenever code is written that needs a tty or stdio object, the -// code should first call one of the static methods (ttyInstance -// or stdioInstance) to see if a console object for the desired -// type exists already. If the object exists, use it. If it does -// not exist, the rule is that the relevant code should create the -// object, use the object, and then destroy the object when the -// operation is completed. -// -// By following the above rule, you can write code that utilizes -// a console without the application having to create some master -// console object for you. Of course, if the application has -// created a console then it will be used. -// -// Why make a master console object? The primary reason is that it -// is not guaranteed that all I/O will survive creation and -// destruction of a console object. If you are using the stdio -// type, then you probably want a long-lived console object. It -// is possible to capture unprocessed I/O by calling -// bytesLeftToRead or bytesLeftToWrite. However, it is not -// expected that general console-needing code will call these -// functions when utilizing a temporary console. Thus, an -// application developer would need to create his own console -// object, invoke the console-needing code, and then do his own -// extraction of the unprocessed I/O if necessary. Another reason -// to extract unprocessed I/O is if you need to switch from -// QCA::Console back to standard functions (e.g. fgets). -// +/** + \class Console qca_support.h QtCrypto + + %QCA %Console system + + %QCA provides an API for asynchronous, event-based access to + the console and stdin/stdout, as these facilities are + otherwise not portable. The primary use of this system within + %QCA is for passphrase prompting in command-line applications, + using the tty console type. + + How it works: Create a %Console object for the type of console + desired, and then use ConsoleReference to act on the console. + Only one ConsoleReference may operate on a %Console at a time. + + A %Console object takes over either the physical console (Console::Tty + type) or stdin/stdout (Console::Stdio type). Only one of each type + may be created at a time. + + Whenever code is written that needs a tty or stdio object, the + code should first call one of the static methods (ttyInstance() + or stdioInstance()) to see if a console object for the desired + type exists already. If the object exists, use it. If it does + not exist, the rule is that the relevant code should create the + object, use the object, and then destroy the object when the + operation is completed. + + By following the above rule, you can write code that utilizes + a console without the application having to create some master + console object for you. Of course, if the application has + created a console then it will be used. + + The reason why there is a master console object is that it + is not guaranteed that all I/O will survive creation and + destruction of a console object. If you are using the Stdio + Type, then you probably want a long-lived console object. It + is possible to capture unprocessed I/O by calling + bytesLeftToRead or bytesLeftToWrite. However, it is not + expected that general console-needing code will call these + functions when utilizing a temporary console. Thus, an + application developer would need to create his own console + object, invoke the console-needing code, and then do his own + extraction of the unprocessed I/O if necessary. Another reason + to extract unprocessed I/O is if you need to switch from + %Console back to standard functions (e.g. fgets() ). + + \ingroup UserAPI +*/ class QCA_EXPORT Console : public QObject { Q_OBJECT public: + /** + The type of console object + */ enum Type { - Tty, // physical console - Stdio // stdin/stdout + Tty, ///< physical console + Stdio ///< stdin/stdout }; - + /** + The type of I/O to use with the console object. + */ enum ChannelMode { - Read, // stdin - ReadWrite // stdin + stdout + Read, ///< Read only (equivalent to stdin) + ReadWrite ///< Read/write (equivalent to stdin and stdout) }; + /** + The nature of the console operation + */ enum TerminalMode { - Default, // use default terminal settings - Interactive // char-by-char input, no echo + Default, ///< use default terminal settings + Interactive ///< char-by-char input, no echo }; + /** + Standard constructor + + Note that library code should not create a new Console object + without checking whether there is already a Console object of + the required Type. See the main documentation for Console for the + rationale for this. + + \param type the Type of Console object to create + \param cmode the ChannelMode (I/O type) to use + \param tmode the TerminalMode to use + \param parent the parent object for this object + + \sa ttyInstance() and stdioInstance for static methods that allow + you to test whether there is already a Console object of the + required Type, and if there is, obtain a reference to that object. + */ Console(Type type, ChannelMode cmode, TerminalMode tmode, QObject *parent = 0); ~Console(); + /** + The Type of this Console object + */ Type type() const; + + /** + The ChannelMode of this Console object + */ ChannelMode channelMode() const; + + /** + The TerminalMode of this Console object + */ TerminalMode terminalMode() const; + /** + Test whether standard input is redirected. + + \sa type() and channelMode() + */ static bool isStdinRedirected(); + + /** + Test whether standard output is redirected. + + \sa type() and channelMode() + */ static bool isStdoutRedirected(); + /** + The current terminal-type console object + + \return null if there is no current Console + of this type, otherwise the Console to use + */ static Console *ttyInstance(); + + /** + The current stdio-type console object + + \return null if there is no current Console + of this type, otherwise the Console to use + */ static Console *stdioInstance(); - // call release() to get access to unempty buffers + /** + Release the Console + + This allows access to buffers containing any remaining data + */ void release(); + + /** + Obtain remaining data from the Console, awaiting + a read operation + */ QByteArray bytesLeftToRead(); + + /** + Obtain remaining data from the Console, awaiting + a write operation + */ QByteArray bytesLeftToWrite(); private: @@ -527,44 +669,155 @@ private: friend class ConsoleReference; }; -// note: only one ConsoleReference object can be active at a time +/** + \class ConsoleReference qca_support.h QtCrypto + + Manager for a Console + + \note Only one %ConsoleReference object can be active at a time + + \ingroup UserAPI +*/ class QCA_EXPORT ConsoleReference : public QObject { Q_OBJECT public: + /** + The security setting to use for the Console being managed. + */ enum SecurityMode { SecurityDisabled, SecurityEnabled }; + /** + Standard constructor + + \param parent the parent object for this object + */ ConsoleReference(QObject *parent = 0); ~ConsoleReference(); + /** + Set the Console object to be managed, and start processing. + + You typically want to use Console::ttyInstance() or + Console::stdioInstance() to obtain the required Console + reference. + + \param console reference to the Console to be managed + \param mode the SecurityMode to use for this Console. + + \sa QCA::Console for more information on how to handle the + console aspects of your application or library code. + */ bool start(Console *console, SecurityMode mode = SecurityDisabled); + + /** + Stop processing, and release the Console + */ void stop(); + /** + The Console object managed by this object + + \sa start() to set the Console to be managed + */ Console *console() const; + + /** + The security mode setting for the Console object + managed by this object. + + \sa start() to set the SecurityMode + */ SecurityMode securityMode() const; - // normal i/o + /** + Read data from the Console. + + \param bytes the number of bytes to read. The default + is to read all available bytes + + \sa readSecure() for a method suitable for reading + sensitive data. + */ QByteArray read(int bytes = -1); + + /** + Write data to the Console. + + \param a the array of data to write to the Console + + \sa writeSecure() for a method suitable for writing + sensitive data. + */ void write(const QByteArray &a); - // secure i/o + /** + Read secure data from the Console + + \param bytes the number of bytes to read. The default + is to read all available bytes + + \sa read() which is suitable for non-sensitive data + */ SecureArray readSecure(int bytes = -1); + + /** + Write secure data to the Console + + \param a the array of data to write to the Console + + \sa write() wich is suitable for non-sensitive data + */ void writeSecure(const SecureArray &a); - // close write channel (only if writing enabled) + /** + Close the write channel + + You only need to call this if writing is enabled + on the Console being managed. + */ void closeOutput(); + /** + The number of bytes available to read from the + Console being managed. + */ int bytesAvailable() const; + + /** + The number of bytes remaining to be written + to the Console being managed + */ int bytesToWrite() const; Q_SIGNALS: + /** + Emitted when there are bytes available to read from + the Console being managed + */ void readyRead(); + + /** + Emitted when bytes are written to the Console + + \param bytes the number of bytes that were written + + \sa bytesAvailable() + */ void bytesWritten(int bytes); + + /** + Emitted when the console input is closed + */ void inputClosed(); + + /** + Emitted when the console output is closed + */ void outputClosed(); private: @@ -576,21 +829,92 @@ private: friend class Console; }; +/** + \class ConsolePrompt qca_support.h QtCrypto + + Console prompt handler. + + This class provides a convenient way to get user input in a secure way, +as shown below: +\code +QCA::ConsolePrompt prompt; +prompt.getHidden("Passphrase"); +prompt.waitForFinished(); +QCA:SecureArray pass = prompt.result(); +\endcode + + \note It is not necessary to use waitForFinished(), because you can + just connect the finished() signal to a suitable method, however + command line (console) applications often require waitForFinished(). + + \ingroup UserAPI +*/ class QCA_EXPORT ConsolePrompt : public QObject { Q_OBJECT public: + /** + Standard constructor + + \param parent the parent object for this object + */ ConsolePrompt(QObject *parent = 0); ~ConsolePrompt(); + /** + Allow the user to enter data without it being echo'd to + the terminal. This is particularly useful for entry + of passwords, passphrases and PINs. + + \param promptStr the prompt to display to the user + + \sa result() for how to get the input back. + */ void getHidden(const QString &promptStr); + + /** + Obtain one character from the user + + \sa resultChar() for how to get the input back. + */ void getChar(); + + /** + Block waiting for user input. + + You may wish to use the finished() signal to + avoid blocking. + */ void waitForFinished(); + /** + Obtain the result of the user input. + + This method is usually called to obtain data + from the user that was requested by the getHidden() + call. + */ SecureArray result() const; + + /** + Obtain the result of the user input. + + This method is usually called to obtain data + from the user that was requested by the getChar() + call. + */ QChar resultChar() const; signals: + /** + Emitted when the user input activity has been + completed. + + This corresponds to the provision of a string + for getHidden() or a single character for getChar(). + + \sa waitForFinished + */ void finished(); private: diff --git a/include/QtCrypto/qpipe.h b/include/QtCrypto/qpipe.h index 3f558379..43182245 100644 --- a/include/QtCrypto/qpipe.h +++ b/include/QtCrypto/qpipe.h @@ -60,7 +60,17 @@ typedef int Q_PIPE_ID; namespace QCA { -// unbuffered direct pipe + +/** + \class QPipeDevice qpipe.h QtCrypto + + Unbuffered direct pipe. + + This class is not usually required except for very low level operations. + You should use QPipe and QPipeEnd for most applications. + + \ingroup UserAPI +*/ class QCA_EXPORT QPipeDevice : public QObject { Q_OBJECT @@ -74,27 +84,116 @@ public: Write ///< The pipe end can be written to }; + /** + Standard constructor + + \param parent the parent object to this object + */ QPipeDevice(QObject *parent = 0); ~QPipeDevice(); - Type type() const; // Read or Write - bool isValid() const; // indicates if a pipe is held - Q_PIPE_ID id() const; // pipe id (Win=HANDLE, Unix=int) - int idAsInt() const; // pipe id turned into an integer + /** + The Type of the pipe device (that is, read or write) + */ + Type type() const; - void take(Q_PIPE_ID id, Type t); // take over the pipe id, close the old - void enable(); // enables usage (read/write) of the pipe - void close(); // close the pipe - void release(); // let go of the pipe but don't close - bool setInheritable(bool enabled); // note: on windows, this operation changes the id + /** + Test whether this object corresponds to a valid pipe + */ + bool isValid() const; - int bytesAvailable() const; // bytes available to read - int read(char *data, int maxsize); // return number read, 0 = EOF, -1 = error - int write(const char *data, int size); // return number taken, ptr must stay valid. -1 on error - int writeResult(int *written) const; // 0 = success (wrote all), -1 = error (see written) + /** + The low level identification for this pipe. + + On Windows, this is a HANDLE. On Unix, this is a file descriptor (i.e. integer). + + Code using this method should be carefully tested for portability. + + \sa idAsInt + */ + Q_PIPE_ID id() const; + + /** + The low level identification for this pipe, returned as an integer. + + Code using this method should be carefully tested for portability. + + \sa id(). + */ + int idAsInt() const; + + /** + Take over an existing pipe id, closing the old pipe if any. + + \param id the identification of the pipe end to take over. + \param t the type of pipe end (read or write). + */ + void take(Q_PIPE_ID id, Type t); + + /** + Enable the pipe for reading or writing (depending on Type) + */ + void enable(); + + /** + Close the pipe end. + */ + void close(); + + /** + Release the pipe end, but do not close it. + */ + void release(); + + /** + Set the pupe end to be inheritable + + \note On Windows, this operation changes the pipe end id value. + */ + bool setInheritable(bool enabled); + + /** + Obtain the number of bytes available to be read. + */ + int bytesAvailable() const; + + /** + Read from the pipe end + + \param data where to put the data that has been read + \param maxsize the maximum number of bytes to be read. + + \return the actual number of bytes read, 0 on end-of-file, or -1 on error. + */ + int read(char *data, int maxsize); + + /** + Write to the pipe end. + + \param data the source of the data to be written + \param size the number of bytes in the data to be written + + \note the data source must remain valid + + \return the number of bytes written, or -1 on error. + */ + int write(const char *data, int size); + + /** + The result of a write operation + + \param written if not null, this will be set to the number of + bytes written in the last operation. + + \return 0 on success (all data written), or -1 on error + */ + int writeResult(int *written) const; Q_SIGNALS: - void notify(); // can read or can write, depending on type + /** + Emitted when the pipe end can be read from or written to (depending on its Type). + */ + void notify(); private: Q_DISABLE_COPY(QPipeDevice)