/*
 * This file contains D-Bus client proxy classes generated by qt4-client-gen.py.
 *
 * This file can be distributed under the same terms as the specification from
 * which it was generated.
 */

#ifndef IN_TELEPATHY_QT4_HEADER
#error IN_TELEPATHY_QT4_HEADER
#endif

#include <TelepathyQt4/Types>

#include <QtGlobal>

#include <QString>
#include <QObject>
#include <QVariant>

#include <QDBusPendingReply>

#include <TelepathyQt4/AbstractInterface>
#include <TelepathyQt4/DBusProxy>
#include <TelepathyQt4/Global>

// basically the same as GLib's G_GNUC_DEPRECATED
#ifndef TELEPATHY_GNUC_DEPRECATED
#   if defined(Q_CC_GNUC) && __GNUC__ >= 4
#       define TELEPATHY_GNUC_DEPRECATED __attribute__((__deprecated__))
#   else
#       define TELEPATHY_GNUC_DEPRECATED
#   endif
#endif
namespace Tp
{
namespace Client
{

/**
 * \class ChannelDispatcherInterface
 * \headerfile TelepathyQt4/channel-dispatcher.h <TelepathyQt4/ChannelDispatcher>
 * \ingroup clientchanneldispatcher
 *
 * Proxy class providing a 1:1 mapping of the D-Bus interface "org.freedesktop.Telepathy.ChannelDispatcher."
 */
class TELEPATHY_QT4_EXPORT ChannelDispatcherInterface : public Tp::AbstractInterface
{
    Q_OBJECT

public:
    /**
     * Returns the name of the interface "org.freedesktop.Telepathy.ChannelDispatcher", which this class
     * represents.
     *
     * \return The D-Bus interface name.
     */
    static inline const char *staticInterfaceName()
    {
        return "org.freedesktop.Telepathy.ChannelDispatcher";
    }

    /**
     * Creates a ChannelDispatcherInterface associated with the given object on the session bus.
     *
     * \param busName Name of the service the object is on.
     * \param objectPath Path to the object on the service.
     * \param parent Passed to the parent class constructor.
     */
    ChannelDispatcherInterface(
        const QString& busName,
        const QString& objectPath,
        QObject* parent = 0
    );

    /**
     * Creates a ChannelDispatcherInterface associated with the given object on the given bus.
     *
     * \param connection The bus via which the object can be reached.
     * \param busName Name of the service the object is on.
     * \param objectPath Path to the object on the service.
     * \param parent Passed to the parent class constructor.
     */
    ChannelDispatcherInterface(
        const QDBusConnection& connection,
        const QString& busName,
        const QString& objectPath,
        QObject* parent = 0
    );

    /**
     * Creates a ChannelDispatcherInterface associated with the same object as the given proxy.
     *
     * \param proxy The proxy to use. It will also be the QObject::parent()
     *               for this object.
     */
    ChannelDispatcherInterface(Tp::DBusProxy *proxy);

    /**
     * Represents property "Interfaces" on the remote object.
     * 
     * A list of the extra interfaces provided by this channel dispatcher.
     */
    Q_PROPERTY(QStringList Interfaces READ Interfaces)

    /**
     * Getter for the remote object property "Interfaces".
     *
     * Don't use this: it blocks the main loop.
     *
     * \return The value of the property, or a default-constructed value
     *          if the property is not readable.
     */
    inline QStringList Interfaces() const TELEPATHY_GNUC_DEPRECATED
    {
        return qvariant_cast<QStringList>(internalPropGet("Interfaces"));
    }

public Q_SLOTS:
    /**
     * Begins a call to the D-Bus method "CreateChannel" on the remote object.
     * 
     * <p>Start a request to create a channel. This initially just creates a
     *   <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelRequest</tp:dbus-ref>
     *   object, which can be used to continue the request and track its
     *   success or failure.</p>
     * 
     * <tp:rationale>
     *   <p>The request can take a long time - in the worst case, the
     *     channel dispatcher has to ask the account manager to put the
     *     account online, the account manager has to ask the operating
     *     system to obtain an Internet connection, and the operating
     *     system has to ask the user whether to activate an Internet
     *     connection using an on-demand mechanism like dialup.</p>
     * 
     *   <p>This means that using a single D-Bus method call and response
     *     to represent the whole request will tend to lead to that call
     *     timing out, which is not the behaviour we want.</p>
     * </tp:rationale>
     * 
     * <p>If this method is called for an Account that is disabled, invalid
     *   or otherwise unusable, no error is signalled until
     *   <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelRequest.Proceed</tp:dbus-ref>
     *   is called, at which point
     *   <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelRequest.Failed</tp:dbus-ref>
     *   is emitted with an appropriate error.</p>
     * 
     * <tp:rationale>
     *   <p>This means there's only one code path for errors, apart from
     *     InvalidArgument for &quot;that request makes no sense&quot;.</p>
     * 
     *   <p>It also means that the request will proceed if the account is
     *     enabled after calling CreateChannel, but before calling
     *     Proceed.</p>
     * </tp:rationale>
     *
     * \param account
     *     
     *     The Account for which the new channel is to be created.
     *
     * \param requestedProperties
     *     
     *     <p>A dictionary containing desirable properties. This has the same
     *       semantics as the corresponding parameter to
     *       <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>.
     *     </p>
     *     
     *     <p>Certain properties will not necessarily make sense in this
     *       dictionary: for instance,
     *       <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref>
     *       can only be given if the requester is able to interact with a
     *       <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>
     *       to the desired account.</p>
     *
     * \param userActionTime
     *     
     *     <p>The time at which user action occurred, or 0 if this channel
     *       request is for some reason not involving user action.
     *       The <tp:dbus-ref namespace="org.freedesktop.Telepathy.ChannelRequest">UserActionTime</tp:dbus-ref>
     *       property will be set to this value, and it will eventually be
     *       passed as the <code>User_Action_Time</code> parameter of <tp:dbus-ref namespace="org.freedesktop.Telepathy.Client.Handler">HandleChannels</tp:dbus-ref>.</p>
     *
     * \param preferredHandler
     *     
     *     <p>Either the well-known bus name (starting with
     *       <code>org.freedesktop.Telepathy.Client.</code>)
     *       of the preferred handler for this
     *       channel, or an empty string to indicate that any handler would be
     *       acceptable. The channel dispatcher SHOULD dispatch as many as
     *       possible of the resulting channels (ideally, all of them)
     *       to that handler, and SHOULD remember the preferred handler
     *       so it can try to dispatch subsequent channels in the same bundle
     *       to the same handler.</p>
     *     
     *     <tp:rationale>
     *       <p>This must be the well-known bus name, not the unique name,
     *         to ensure that all handlers do indeed have the Client API,
     *         and the Client object on the handler can be located easily.</p>
     *     
     *       <p>This is partly so the channel dispatcher can call
     *         <tp:dbus-ref namespace="org.freedesktop.Telepathy.Client.Handler">HandleChannels</tp:dbus-ref>
     *         on it, and partly so the channel dispatcher
     *         can recover state if it crashes and is restarted.</p>
     *     </tp:rationale>
     *     
     *     <p>If this is a well-known bus name and the handler has the
     *       Requests interface, the channel dispatcher SHOULD
     *       call <tp:dbus-ref namespace="org.freedesktop.Telepathy.Client.Interface.Requests">AddRequest</tp:dbus-ref>
     *       on that Handler after this method has returned.</p>
     *     
     *     <tp:rationale>
     *       <p>This ordering allows a Handler which calls CreateChannel with
     *         itself as the preferred handler to associate the call to
     *         AddRequest with that call.</p>
     *     </tp:rationale>
     *     
     *     <p>This is copied to the ChannelRequest that is returned,
     *       as the <tp:dbus-ref namespace="org.freedesktop.Telepathy.ChannelRequest">PreferredHandler</tp:dbus-ref>
     *       property.</p>
     *
     * \return
     *     
     *     A ChannelRequest object.
     */
    inline QDBusPendingReply<QDBusObjectPath> CreateChannel(const QDBusObjectPath& account, const QVariantMap& requestedProperties, qlonglong userActionTime, const QString& preferredHandler)
    {
        if (!invalidationReason().isEmpty()) {
            return QDBusPendingReply<QDBusObjectPath>(QDBusMessage::createError(
                invalidationReason(),
                invalidationMessage()
            ));
        }


        QList<QVariant> argumentList;
        argumentList << QVariant::fromValue(account) << QVariant::fromValue(requestedProperties) << QVariant::fromValue(userActionTime) << QVariant::fromValue(preferredHandler);
        return asyncCallWithArgumentList(QLatin1String("CreateChannel"), argumentList);
    }

    /**
     * Begins a call to the D-Bus method "EnsureChannel" on the remote object.
     * 
     * <p>Start a request to ensure that a channel exists, creating it if
     *   necessary.  This initially just creates a <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelRequest</tp:dbus-ref>
     *   object, which can be used to continue the request and track its
     *   success or failure.</p>
     * 
     * <p>If this method is called for an Account that is disabled, invalid
     *   or otherwise unusable, no error is signalled until
     *   <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelRequest.Proceed</tp:dbus-ref>
     *   is called, at which point
     *   <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelRequest.Failed</tp:dbus-ref>
     *   is emitted with an appropriate error.</p>
     * 
     * <tp:rationale>
     *   <p>The rationale is as for <tp:dbus-ref namespace="org.freedesktop.Telepathy.ChannelDispatcher">CreateChannel</tp:dbus-ref>.</p>
     * </tp:rationale>
     *
     * \param account
     *     
     *     The Account for which the new channel is to be created.
     *
     * \param requestedProperties
     *     
     *     <p>A dictionary containing desirable properties. This has the same
     *       semantics as the corresponding parameter to
     *       <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.EnsureChannel</tp:dbus-ref>.
     *     </p>
     *     
     *     <p>Certain properties will not necessarily make sense in this
     *       dictionary: for instance,
     *       <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref>
     *       can only be given if the requester is able to interact with a
     *       <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>
     *       to the desired account.</p>
     *
     * \param userActionTime
     *     
     *     <p>The time at which user action occurred, or 0 if this channel
     *       request is for some reason not involving user action.</p>
     *     
     *     <p>This parameter is used in the same way as the corresponding
     *       parameter to <tp:member-ref>CreateChannel</tp:member-ref>.</p>
     *
     * \param preferredHandler
     *     
     *     <p>Either the well-known bus name (starting with
     *       <code>org.freedesktop.Telepathy.Client.</code>)
     *       of the preferred handler for this
     *       channel, or an empty string to indicate that any handler would be
     *       acceptable. The behaviour and rationale are the same as for the
     *       corresponding parameter to
     *       <tp:member-ref>CreateChannel</tp:member-ref>, except as noted
     *       here.</p>
     *     
     *     <p>If any new channels are created in response to this
     *       request, the channel dispatcher SHOULD dispatch as many as
     *       possible of the resulting channels (ideally, all of them)
     *       to that handler, and SHOULD remember the preferred handler
     *       so it can try to dispatch subsequent channels in the same bundle
     *       to the same handler. If the requested channel already exists (that
     *       is, <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.EnsureChannel</tp:dbus-ref>
     *       returns <code>Yours=False</code>) then the channel dispatcher
     *       SHOULD re-dispatch the channel to its existing handler, and MUST
     *       NOT dispatch it to this client (unless it is the existing handler);
     *       the request is still deemed to have succeeded in this case.</p>
     *     
     *     <tp:rationale>
     *       <p>An address book application, for example, might call <tp:dbus-ref namespace="org.freedesktop.Telepathy.ChannelDispatcher">EnsureChannel</tp:dbus-ref>
     *         to ensure that a text channel with a particular contact is
     *         displayed to the user; it does not care whether a new channel was
     *         made. An IM client might call <tp:dbus-ref namespace="org.freedesktop.Telepathy.ChannelDispatcher">EnsureChannel</tp:dbus-ref>
     *         in response to the user double-clicking an entry in the contact
     *         list, with itself as the <code>Preferred_Handler</code>; if the
     *         user already has a conversation with that contact in another
     *         application, they would expect the existing window to be
     *         presented, rather than their double-click leading to an error
     *         message.  So the request should succeed, even if its
     *         <code>Preferred_Handler</code> is not used.</p>
     *     </tp:rationale>
     *
     * \return
     *     
     *     A ChannelRequest object.
     */
    inline QDBusPendingReply<QDBusObjectPath> EnsureChannel(const QDBusObjectPath& account, const QVariantMap& requestedProperties, qlonglong userActionTime, const QString& preferredHandler)
    {
        if (!invalidationReason().isEmpty()) {
            return QDBusPendingReply<QDBusObjectPath>(QDBusMessage::createError(
                invalidationReason(),
                invalidationMessage()
            ));
        }


        QList<QVariant> argumentList;
        argumentList << QVariant::fromValue(account) << QVariant::fromValue(requestedProperties) << QVariant::fromValue(userActionTime) << QVariant::fromValue(preferredHandler);
        return asyncCallWithArgumentList(QLatin1String("EnsureChannel"), argumentList);
    }

protected:
    virtual void invalidate(Tp::DBusProxy *, const QString &, const QString &);
};
}
}
