[Telepathy] tp-qt4 Requesting channels using ChannelDispatcher high-level API proposal

[Andre Moreira Magalhaes]

Hi,

We now come to a point where we are going to start implementing support for
requesting channels using ChannelDispatcher on tp-qt4, so here is a proposal
API I would like to discuss with you before starting implementing this.

For those not familiar with ChannelDispatcher please refer to
http://telepathy.freedesktop.org/spec.html#org.freedesktop.Telepathy.ChannelDispatcher

Aditional methods that will be added to Account:

class Account : public ...
{
    ...

public:
    ...

    // one to one chat
    bool canEnsureTextChannel();
    ChannelRequestPtr ensureTextChat(
            const QString &contactIdentifier,
            QDateTime userActionTime = QDateTime::currentDateTime(),
            const QString &preferredHandler = QString());
    ChannelRequestPtr ensureTextChat(
            const ContactPtr &contact,
            QDateTime userActionTime = QDateTime::currentDateTime(),
            const QString &preferredHandler = QString());

    // group chat
    bool canEnsureGroupTextChat();
    ChannelRequestPtr ensureGroupTextChat(
            const QStringList &contactsIdentifiers,
            QDateTime userActionTime = QDateTime::currentDateTime(),
            const QString &preferredHandler = QString());
    ChannelRequestPtr ensureGroupTextChat(
            const QList<ContactPtr> &contacts,
            QDateTime userActionTime = QDateTime::currentDateTime(),
            const QString &preferredHandler = QString());

    // room chat (irc, ...)
    bool canEnsureRoomTextChat();
    ChannelRequest *ensureRoomTextChat(
            const QString &roomName,
            QDateTime userActionTime = QDateTime::currentDateTime(),
            const QString &preferredHandler = QString());

    // media call
    bool canEnsureMediaCall();
    ChannelRequestPtr ensureMediaCall(
            const QString &contactIdentifier,
            QDateTime userActionTime = QDateTime::currentDateTime(),
            const QString &preferredHandler = QString());
    ChannelRequestPtr ensureMediaCall(
            const ContactPtr &contact,
            QDateTime userActionTime = QDateTime::currentDateTime(),
            const QString &preferredHandler = QString());

    // file transfer
    bool canCreateFileTransfer();
    ChannelRequestPtr createFileTransfer(
            const QString &contactIdentifier,
            QDateTime userActionTime = QDateTime::currentDateTime(),
            const QString &preferredHandler = QString());
    ChannelRequestPtr createFileTransfer(
            const ContactPtr &contact,
            QDateTime userActionTime = QDateTime::currentDateTime(),
            const QString &preferredHandler = QString());

    // advanced
    ChannelRequestPtr createChannel(
            const QVariantMap &requestedProperties,
            QDateTime userActionTime = QDateTime::currentDateTime(),
            const QString &preferredHandler = QString());
    ChannelRequestPtr ensureChannel(
            const QVariantMap &requestedProperties,
            QDateTime userActionTime = QDateTime::currentDateTime(),
            const QString &preferredHandler = QString());

    ...
};

Now aditional contact methods, some would require ContactCapabilities 
support.

class Contact : public ...
{
public:

    ...
    
    // one to one chat
    bool canEnsureTextChannel();
    ChannelRequestPtr ensureTextChat(
            QDateTime userActionTime = QDateTime::currentDateTime(),
            const QString &preferredHandler = QString());

    // media call
    bool canEnsureMediaCall();
    ChannelRequestPtr ensureMediaCall(
            QDateTime userActionTime = QDateTime::currentDateTime(),
            const QString &preferredHandler = QString());

    // file transfer
    bool canCreateFileTransfer();
    ChannelRequestPtr createFileTransfer(
            QDateTime userActionTime = QDateTime::currentDateTime(),
            const QString &preferredHandler = QString());

    ...
};

* Note that Contact object would have to have access to the Contact 
Account object,
which is not always possible (e.g: not using AccountManager), so the Contact
methods would only work when an Account is being used.
* Should we support Tubes, FileTransfer here, as the support for them is 
not complete yet?

Ideas, suggestions are welcome
BR
Andrunko