/****************************************************************************

**

** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).

** All rights reserved.

** Contact: Nokia Corporation (qt-info@nokia.com)

**

** This file is part of the tools applications of the Qt Toolkit.

**

** $QT_BEGIN_LICENSE:LGPL$

** No Commercial Usage

** This file contains pre-release code and may not be distributed.

** You may use this file in accordance with the terms and conditions

** contained in the Technology Preview License Agreement accompanying

** this package.

**

** GNU Lesser General Public License Usage

** Alternatively, this file may be used under the terms of the GNU Lesser

** General Public License version 2.1 as published by the Free Software

** Foundation and appearing in the file LICENSE.LGPL included in the

** packaging of this file.  Please review the following information to

** ensure the GNU Lesser General Public License version 2.1 requirements

** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

**

** In addition, as a special exception, Nokia gives you certain additional

** rights.  These rights are described in the Nokia Qt LGPL Exception

** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

**

** If you have questions regarding the use of this file, please contact

** Nokia at qt-info@nokia.com.

**

**

**

**

**

**

**

**

** $QT_END_LICENSE$

**

****************************************************************************/

#ifndef TCFTRKENGINE_H

#define TCFTRKENGINE_H

#include "symbianutils_global.h"

#include "tcftrkmessage.h"

#include "callback.h"

#include "json.h"

#include <QtCore/QObject>

#include <QtCore/QSharedPointer>

#include <QtCore/QVector>

#include <QtCore/QVariant>

#include <QtCore/QStringList>

QT_BEGIN_NAMESPACE

class QIODevice;

class QTextStream;

QT_END_NAMESPACE

namespace tcftrk {

struct TcfTrkDevicePrivate;

struct Breakpoint;

/* Command error handling in TCF:

 * 1) 'Severe' errors (JSON format, parameter format): Trk emits a

 *     nonstandard message (\3\2 error paramaters) and closes the connection.

 * 2) Protocol errors: 'N' without error message is returned.

 * 3) Errors in command execution: 'R' with a TCF error hash is returned

 *    (see TcfTrkCommandError). */

/* Error code return in 'R' reply to command

 * (see top of 'Services' documentation). */

struct SYMBIANUTILS_EXPORT TcfTrkCommandError {

    TcfTrkCommandError();

    void clear();

    operator bool() const { return timeMS != 0; }

    QString toString() const;

    void write(QTextStream &str) const;

    bool parse(const QVector<JsonValue> &values);

    quint64 timeMS; // Since 1.1.1970

    int code;

    QByteArray format; // message

    // 'Alternative' meaning, like altOrg="POSIX"/altCode=<some errno>

    QByteArray alternativeOrganization;

    int alternativeCode;

};

/* Answer to a Tcf command passed to the callback. */

struct SYMBIANUTILS_EXPORT TcfTrkCommandResult {

    enum Type {

        SuccessReply,       // 'R' and no error -> all happy.

        CommandErrorReply,  // 'R' with TcfTrkCommandError received

        ProgressReply,      // 'P', progress indicator

        FailReply           // 'N' Protocol NAK, severe error

    };

    explicit TcfTrkCommandResult(Type t = SuccessReply);

    explicit TcfTrkCommandResult(char typeChar, Services service,

                                 const QByteArray &request,

                                 const QVector<JsonValue> &values,

                                 const QVariant &cookie);

    QString toString() const;

    QString errorString() const;

    operator bool() const { return type == SuccessReply || type == ProgressReply; }

    Type type;

    Services service;

    QByteArray request;

    TcfTrkCommandError commandError;

    QVector<JsonValue> values;

    QVariant cookie;

};

typedef trk::Callback<const TcfTrkCommandResult &> TcfTrkCallback;

/* TcfTrkDevice: TCF communication helper using an asynchronous QIODevice

 * implementing the TCF protocol according to:

http://dev.eclipse.org/svnroot/dsdp/org.eclipse.tm.tcf/trunk/docs/TCF%20Specification.html

http://dev.eclipse.org/svnroot/dsdp/org.eclipse.tm.tcf/trunk/docs/TCF%20Services.html

 * Commands can be sent along with callbacks that are passed a

 * TcfTrkCommandResult and an opaque QVariant cookie. In addition, events are emitted.

*/

class SYMBIANUTILS_EXPORT TcfTrkDevice : public QObject

{

    Q_PROPERTY(unsigned verbose READ verbose WRITE setVerbose)

    Q_OBJECT

public:

    enum MessageType { MessageWithReply,

                       MessageWithoutReply, /* Non-standard: "Settings:set" command does not reply */

                       NoopMessage };

    typedef QSharedPointer<QIODevice> IODevicePtr;

    explicit TcfTrkDevice(QObject *parent = 0);

    virtual ~TcfTrkDevice();

    unsigned verbose() const;

    // Mapping of register names for indices

    QVector<QByteArray> registerNames() const;

    void setRegisterNames(const QVector<QByteArray>& n);

    IODevicePtr device() const;

    IODevicePtr takeDevice();

    void setDevice(const IODevicePtr &dp);

    void sendTcfTrkMessage(MessageType mt, Services service,

                           const char *command,

                           const char *commandParameters, int commandParametersLength,

                           const TcfTrkCallback &callBack = TcfTrkCallback(),

                           const QVariant &cookie = QVariant());

    void sendTcfTrkMessage(MessageType mt, Services service, const char *command,

                           const QByteArray &commandParameters,

                           const TcfTrkCallback &callBack = TcfTrkCallback(),

                           const QVariant &cookie = QVariant());

    // Convenience messages: Start a process

    void sendProcessStartCommand(const TcfTrkCallback &callBack,

                                 const QString &binary,

                                 unsigned uid,

                                 QStringList arguments = QStringList(),

                                 QString workingDirectory = QString(),

                                 bool debugControl = true,

                                 const QStringList &additionalLibraries = QStringList(),

                                 const QVariant &cookie = QVariant());

    // Preferred over Processes:Terminate by TCF TRK.

    void sendRunControlTerminateCommand(const TcfTrkCallback &callBack,

                                        const QByteArray &id,

                                        const QVariant &cookie = QVariant());

    void sendProcessTerminateCommand(const TcfTrkCallback &callBack,

                                     const QByteArray &id,

                                     const QVariant &cookie = QVariant());

    // Non-standard: Remove executable from settings.

    // Probably needs to be called after stopping. This command has no response.

    void sendSettingsRemoveExecutableCommand(const QString &binaryIn,

                                             unsigned uid,

                                             const QStringList &additionalLibraries = QStringList(),

                                             const QVariant &cookie = QVariant());

    void sendRunControlSuspendCommand(const TcfTrkCallback &callBack,

                                      const QByteArray &id,

                                      const QVariant &cookie = QVariant());

    // Resume / Step (see RunControlResumeMode).

    void sendRunControlResumeCommand(const TcfTrkCallback &callBack,

                                     const QByteArray &id,

                                     RunControlResumeMode mode,

                                     unsigned count /* = 1, currently ignored. */,

                                     quint64 rangeStart, quint64 rangeEnd,

                                     const QVariant &cookie = QVariant());

    // Convenience to resume a suspended process

    void sendRunControlResumeCommand(const TcfTrkCallback &callBack,

                                     const QByteArray &id,

                                     const QVariant &cookie = QVariant());

    void sendBreakpointsAddCommand(const TcfTrkCallback &callBack,

                                   const Breakpoint &b,

                                   const QVariant &cookie = QVariant());

    void sendBreakpointsRemoveCommand(const TcfTrkCallback &callBack,

                                      const QByteArray &id,

                                      const QVariant &cookie = QVariant());

    void sendBreakpointsRemoveCommand(const TcfTrkCallback &callBack,

                                      const QVector<QByteArray> &id,

                                      const QVariant &cookie = QVariant());

    void sendBreakpointsEnableCommand(const TcfTrkCallback &callBack,

                                      const QByteArray &id,

                                      bool enable,

                                      const QVariant &cookie = QVariant());

    void sendBreakpointsEnableCommand(const TcfTrkCallback &callBack,

                                      const QVector<QByteArray> &id,

                                      bool enable,

                                      const QVariant &cookie = QVariant());

    void sendMemoryGetCommand(const TcfTrkCallback &callBack,

                              const QByteArray &contextId,

                              quint64 start, quint64 size,

                              const QVariant &cookie = QVariant());

    void sendMemorySetCommand(const TcfTrkCallback &callBack,

                              const QByteArray &contextId,

                              quint64 start, const QByteArray& data,

                              const QVariant &cookie = QVariant());

    // Reply is an array of hexvalues

    void sendRegistersGetMCommand(const TcfTrkCallback &callBack,

                                  const QByteArray &contextId,

                                  const QVector<QByteArray> &ids,

                                  const QVariant &cookie = QVariant());

    // Convenience to get a range of register "R0" .. "R<n>".

    // Cookie will be an int containing "start".

    void sendRegistersGetMRangeCommand(const TcfTrkCallback &callBack,

                                 const QByteArray &contextId,

                                  unsigned start, unsigned count);

    // Set register

    void sendRegistersSetCommand(const TcfTrkCallback &callBack,

                                 const QByteArray &contextId,

                                 const QByteArray &ids,

                                 unsigned value,

                                 const QVariant &cookie = QVariant());

    // Set register

    void sendRegistersSetCommand(const TcfTrkCallback &callBack,

                                 const QByteArray &contextId,

                                 unsigned registerNumber,

                                 unsigned value,

                                 const QVariant &cookie = QVariant());

    static QByteArray parseMemoryGet(const TcfTrkCommandResult &r);

signals:

    void genericTcfEvent(int service, const QByteArray &name, const QVector<tcftrk::JsonValue> &value);

    void tcfEvent(const tcftrk::TcfTrkEvent &knownEvent);

    void logMessage(const QString &);

    void error(const QString &);

public slots:

    void setVerbose(unsigned v);

private slots:

    void slotDeviceError();

    void slotDeviceSocketStateChanged();

    void slotDeviceReadyRead();

private:

    bool checkOpen();

    void checkSendQueue();

    void writeMessage(QByteArray data);

    void emitLogMessage(const QString &);

    int parseMessage(const QByteArray &);

    int parseTcfCommandReply(char type, const QVector<QByteArray> &tokens);

    int parseTcfEvent(const QVector<QByteArray> &tokens);

    TcfTrkDevicePrivate *d;

};

} // namespace tcftrk

#endif // TCFTRKENGINE_H