[Telepathy] tp-qt4 Observer, Approver, Handler high-level API proposal

[Andre Moreira Magalhaes]

Hi all

So here is a proposal for Client Observer, Approver, Handler high-level 
API.

Design:
Clients that intend to be an observer, handler, approver, should inherit 
the corresponding base classes and implement the pure virtual methods.
To make the methods async a handle for each operation (method call) is 
added, and when done with that operation the client should call 
setOperationFinished or setOperationFinishedWithError.
After creating the objects, clients should register them using 
ClientRegister class, that will do the appropriate D-Bus setup, and 
proper direct D-Bus calls to the clients.

Here are the classes sketches, internal implementation is hidden, 
basically ClientRegister is the magic class, that will do all the hard work.

class BaseClient : public QObject
{
    Q_OBJECT

public:
    BaseClient(QObject *parent = 0);
    ~BaseClient();

    QVariantMap filters() const;
    bool setFilters(const QVariantMap &filters);

    // when finished processing an operation (observeChannels, 
handlerChannels,
    // ...), the client should call setOperationFinished/WithError with the
    // given operationHandle.
    // This allows operations to be threated asynchronously
    void setOperationFinished(uint operationHandle);
    void setOperationFinishedWithError(uint operationHandle,
            const QString &errorName, const QString &errorMessage);

Q_SIGNALS:
    void operationFinished(uint operationHandle);
    void operationFinishedWithError(uint operationHandle,
            const QString &errorName, const QString &errorMessage);
};

class BaseObserverClient : public BaseClient
{
public:
    BaseObserver(QObject *parent = 0);
    virtual ~BaseObserver();

    virtual void observeChannels(uint operationHandle,
            const AccountPtr &account,
            const ConnectionPtr &connection,
            const QList<ChannelPtr> &channels,
            const QString &dispatchOperationObjectPath,
            const QVariantMap &observerInfo) = 0;
};

class BaseApproverClient : public BaseClient
{
public:
    BaseApprover(QObject *parent = 0);
    virtual ~BaseApprover();

    virtual void addDispatchOperation(uint operationHandle,
            const QString &dispatchOperationObjectPath,
            const QVariantMap &dispatchOperationProperties) = 0;
};

class BaseHandlerClient : public BaseClient
{
public:
    BaseHandler(QObject *parent = 0);
    virtual ~BaseHandler();

    virtual void handleChannels(uint operationHandle,
            const AccountPtr &account,
            const ConnectionPtr &connection,
            const QList<ChannelPtr> &channels,
            const QStringList &requestsSatisfiedObjectPaths,
            const QDateTime &userActionTime) = 0;
    virtual void addRequest(const QString &requestObjectPath,
            const QVariantMap &requestProperties) = 0;
    virtual void removeFailedRequest(const QString &requestObjectPath,
            const QString &error, const QString &message) = 0;
};

class ClientRegister : public QObject
{
public:
    // clientName is the name to be used
    ClientRegister(const QString &clientName, bool unique = false,
            QObject *parent = 0);
    ~ClientRegister();

    QString clientName() const;

    bool addObserverClient(ObserverClient *client);
    bool addApproverClient(ApproverClient *client);
    bool addHandlerClient(HandlerClient *client);

    bool registerClients();
};


// -------------------- USAGE ----------------------
void MyHandler : public BaseHandlerClient
{
public:
    MyHandler(QObject *parent = 0);
    ~MyHandler();

    void handleChannels(uint operationHandle,
            const AccountPtr &account,
            const ConnectionPtr &connection,
            const QList<ChannelPtr> &channels,
            const QStringList &requestsSatisfiedObjectPaths,
            const QDateTime &userActionTime)
    {
        foreach (const ChannelPtr &channel, channels) {
            MyHandlerUI *handlerUI = lookupHandlerUIByChannel(channel);
            if (!handlerUI) {
                // create handler UI to handle channel
                ...
            }
            handlerUI->show();
        }
        setOperationFinished(operationHandle);
    }

    virtual void addRequest(const QString &requestObjectPath,
            const QVariantMap &requestProperties)
    {
        ...
        setOperationFinished(operationHandle);
    }

    virtual void removeFailedRequest(uint operationHandle,
            const QString &requestObjectPath,
            const QString &error, const QString &message)
    {
        ...
        setOperationFinished(operationHandle);
    }
};

ClientRegister *r = new ClientRegister("myclient");
MyHandler *h = new MyHandler(r);
QVariantMap map;
map.insert("org.freedesktop.Telepathy.Channel.ChannelType",
           "org.freedesktop.Telepathy.Channel.Type.Text");
map.insert("org.freedesktop.Telepathy.Channel.TargetHandleType",
           Telepathy::HandleTypeContact);
h->setFilters(map);
r->addHandlerClient(h);
r->registerClients();

TODO:
- Write wrappers for ChannelRequest.DRAFT and ChannelDispatchOperation.DRAFT

Ideas, suggestions?

BR
Andrunko