kttsd/kspeak/kspeak.h

   1 /***************************************************** vim:set ts=4 sw=4 sts=4:
   2   kspeak
   3
   4   Command-line utility for sending commands to KTTSD service via D-Bus.
   5   --------------------------------------------------------------------
   6   Copyright:
   7   (C) 2006 by Gary Cramblitt <garycramblitt@comcast.net>
   8   -------------------
   9   Original author: Gary Cramblitt <garycramblitt@comcast.net>
  10
  11   This program is free software; you can redistribute it and/or modify
  12   it under the terms of the GNU General Public License as published by
  13   the Free Software Foundation; either version 2 of the License, or
  14   (at your option) any later version.
  15
  16   This program is distributed in the hope that it will be useful,
  17   but WITHOUT ANY WARRANTY; without even the implied warranty of
  18   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19   GNU General Public License for more details.
  20
  21   You should have received a copy of the GNU General Public License
  22   along with this program; if not, write to the Free Software
  23   Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
  24  ******************************************************************************/
  25
  26 #ifndef KSPEAK_H
  27 #define KSPEAK_H
  28
  29 // Qt includes.
  30 #include <QObject>
  31 #include <QHash>
  32 #include <QThread>
  33 #include <QTimer>
  34
  35 // KDE includes.
  36 #include <kcmdlineargs.h>
  37
  38 // ktts includes.
  39 #include "kspeechinterface.h"
  40
  41 class QString;
  42 class QTextStream;
  43 class QWaitCondition;
  44 class QMutex;
  45
  46 // ====================================================================
  47
  48 /**
  49  * Class StdinReader reads from an input file in a separate thread, emitting
  50  * signal lineReady for each line of input.  This prevents from blocking
  51  * waiting for input.
  52  */
  53 class StdinReader : public QThread
  54 {
  55     Q_OBJECT
  56
  57 public:
  58     StdinReader(const QString& filename, QObject* parent);
  59     ~StdinReader();
  60
  61     /**
  62      * Tell StdinReader to get more input.
  63      */
  64     void requestInput();
  65
  66 Q_SIGNALS:
  67     /**
  68      * Emitted when a line of input from stdin is ready.
  69      * @param line      The line of input.
  70      */
  71     void lineReady(const QString& line);
  72     /**
  73      * Emitted when EOF is encountered on stdin.
  74      */
  75     void endInput();
  76
  77 protected:
  78     void run();
  79
  80 private:
  81     // Input filename.
  82     QString m_inputFilename;
  83     // True to stop reading input.
  84     mutable bool m_quit;
  85     // Mutex and wait condition for controlling input.
  86     QWaitCondition* m_waitForInputRequest;
  87     QMutex* m_mutexForInputRequest;
  88 };
  89
  90 // ====================================================================
  91
  92 class KSpeak : public QObject
  93 {
  94     Q_OBJECT
  95
  96 public:
  97     KSpeak(KCmdLineArgs* args, QObject* parent = 0);
  98     ~KSpeak();
  99
 100     bool echo();
 101     void setEcho(bool on);
 102     bool stopOnError();
 103     void setStopOnError(bool on);
 104     bool showReply();
 105     void setShowReply(bool on);
 106     bool showSignals();
 107     void setShowSignals(bool on);
 108
 109     Q_PROPERTY(bool echo READ echo WRITE setEcho)
 110     Q_PROPERTY(bool stopOnError READ stopOnError WRITE setStopOnError)
 111     Q_PROPERTY(bool showReply READ showReply WRITE setShowReply)
 112     Q_PROPERTY(bool showSignals READ showSignals WRITE setShowSignals)
 113
 114     /**
 115     * See if KTTSD is running, and optional, if not, start it.
 116     * @param autoStart True to start KTTSD if not already running.
 117     */
 118     bool isKttsdRunning(bool autoStart);
 119
 120 protected Q_SLOTS:
 121     Q_SCRIPTABLE void jobStateChanged(const QString &appId, int jobNum, int state);
 122     Q_SCRIPTABLE void marker(const QString& appId, int jobNum, int markerType, const QString& markerData);
 123
 124     /**
 125      * Start processing input from stdin.
 126      */
 127     void startInput();
 128
 129     /**
 130      * Stop processing input and exit application with m_exitCode.
 131      */
 132     void stopInput();
 133
 134     /**
 135      * Process a single command from input stream.
 136      */
 137     void processCommand(const QString& inputLine);
 138
 139     /**
 140      * WAIT for signal timeout.
 141      */
 142     void waitForSignalTimeout();
 143
 144 private:
 145     /**
 146      * Given a signal, checks to see if it matches a pending WAIT command.
 147      * It it does, more input is requested from the StdinReader and the pending
 148      * WAIT is cleared.
 149      * @param signalName    Name of the signal.  "marker" or "jobStateChanged".
 150      * @param appId         AppID from signal.
 151      * @param jobNum        Job Number from signal.
 152      * @param data1         Marker Type or State from signal.
 153      * @param data2         Additional data from signal.
 154      *
 155      */
 156     void checkWaitForSignal(const QString& signalName, const QString& appId, int jobNum, int data1, const QString& data2Str = QString("*"));
 157
 158     /**
 159     * Print an error message and also store the message in $ERROR variable.
 160     * @param msg  The message.
 161     */
 162     void printError(const QString& msg);
 163
 164     /**
 165     * Make a DBus call to KSpeech.
 166     * @param member    Method to call.
 167     * @param args      QStringList of arguments to pass to method.
 168     * @return          Returned D-Bus message.
 169     *
 170     * The arguments are converted to the types required by the parameters of the member.
 171     */
 172     QDBusMessage placeCall(const QString member, QStringList args);
 173
 174     /**
 175     * Prints a member in format user would enter it into kspeak.
 176     * The return types and parameter types are given inside angle brackets.
 177     * @param mm    QMethodMethod to print.
 178     */
 179     void printMethodHelp(const QMetaMethod& mm);
 180
 181     /**
 182     * Prints help.  If no member is specified, lists all members
 183     * that are not signals.  If "signals" is specified, lists
 184     * all the signals.  If a specific member is specified,
 185     * lists that member only.
 186     * @param member    (optional) "signals" or a specific member name.
 187     */
 188     void printHelp(const QString& member = QString());
 189
 190     /**
 191     * Convert a KTTSD job state integer into a display string.
 192     * @param state          KTTSD job state
 193     * @return               Display string for the state.
 194     */
 195     QString stateToStr(int state);
 196
 197     /**
 198     * Split single string into list of arguments.  Arguments are separated by spaces.
 199     * If an argument contains space(s), enclose in quotes.
 200     * @param argsStr   The string to parse.
 201     * @return          List of parsed argument strings.
 202     */
 203     QStringList parseArgs(const QString& argsStr);
 204
 205     /**
 206     * Converts a QByteArray to a displayable string.  If the array contains undisplayable chars,
 207     * it is converted to a hexadecimal representation.  Code copied from kdebug.cpp.
 208     * @param data  The QByteArray.
 209     * @return      Displayable string.
 210     */
 211     QString byteArrayToString(const QByteArray& data);
 212
 213     /**
 214     * Converts job info in a QByteArray (retrieve via getJobInfo from KTTSD) into displayable string.
 215     * @param jobInfo   QByteArray containing serialized job info.
 216     * @return          The displayable string.
 217     */
 218     QString jobInfoToString(QByteArray& jobInfo);
 219
 220     /**
 221     * Convert the arguments of a reply DBusMessage into a QStringList.
 222     * @param reply The QDBusMessage to convert.
 223     * @param cmd   (optional) The D-Bus member that returned the reply.
 224     * @return      List of strings.
 225     *
 226     * If cmd is "getJobInfo", unserializes the job info in the reply.
 227     */
 228     QStringList dbusReplyToStringList(const QDBusMessage& reply, const QString& cmd = QString());
 229
 230     /**
 231     * Convert a reply DBusMessage into a printable string.
 232     * A newline is appended after each returned argument.
 233     * StringLists are printed as "(one,two,three,etc)".
 234     * @param reply     The D-Bus reply message.
 235     * @param cmd       (optional) The D-Bus member that returned the reply.
 236     * @return          The printable string.
 237     *
 238     * If cmd is "getJobInfo", unserializes the job info in the reply.
 239     */
 240     QString dbusReplyToPrintable(const QDBusMessage& reply, const QString& cmd = QString());
 241
 242     // Input filename.
 243     QString m_inputFilename;
 244     // A dictionary of variables.
 245     QHash<QString, QString> m_vars;
 246     // Stdin Reader.
 247     StdinReader* m_stdinReader;
 248     // Output streams.
 249     QTextStream* m_out;
 250     QTextStream* m_stderr;
 251     // True if commands should be echoed to display.
 252     bool m_echo;
 253     // True if received signals are displayed.
 254     bool m_showSignals;
 255     // True if stop on D-Bus error.
 256     bool m_stopOnError;
 257     // True if automatic print of return values.
 258     bool m_showReply;
 259     // The KSpeech D-Bus Interface.
 260     org::kde::KSpeech* m_kspeech;
 261     // Exit code.
 262     int m_exitCode;
 263     // Name of buffer variable currently being filled.
 264     QString m_fillingBuffer;
 265     // Signal and arguments WAITing for.
 266     QStringList m_waitingSignal;
 267     // Timer for WAIT.
 268     QTimer m_waitTimer;
 269 };
 270
 271 #endif  // KSPEAK_H