/*
 * 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 ChannelDispatchOperationInterface
 * \headerfile TelepathyQt4/channel-dispatch-operation.h <TelepathyQt4/ChannelDispatchOperation>
 * \ingroup clientchanneldispatchoperation
 *
 * Proxy class providing a 1:1 mapping of the D-Bus interface "org.freedesktop.Telepathy.ChannelDispatchOperation."
 */
class TELEPATHY_QT4_EXPORT ChannelDispatchOperationInterface : public Tp::AbstractInterface
{
    Q_OBJECT

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

    /**
     * Creates a ChannelDispatchOperationInterface 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.
     */
    ChannelDispatchOperationInterface(
        const QString& busName,
        const QString& objectPath,
        QObject* parent = 0
    );

    /**
     * Creates a ChannelDispatchOperationInterface 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.
     */
    ChannelDispatchOperationInterface(
        const QDBusConnection& connection,
        const QString& busName,
        const QString& objectPath,
        QObject* parent = 0
    );

    /**
     * Creates a ChannelDispatchOperationInterface 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.
     */
    ChannelDispatchOperationInterface(Tp::DBusProxy *proxy);

    /**
     * Represents property "Interfaces" on the remote object.
     * 
     * A list of the extra interfaces provided by this channel dispatch 
     * operation. This property cannot change.
     */
    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"));
    }

    /**
     * Represents property "Connection" on the remote object.
     * 
     * The Connection with which the Channels are associated. The well-known 
     * bus name to use can be derived from this object path by removing the 
     * leading &apos;/&apos; and replacing all subsequent &apos;/&apos; by 
     * &apos;.&apos;. This property cannot change.
     */
    Q_PROPERTY(QDBusObjectPath Connection READ Connection)

    /**
     * Getter for the remote object property "Connection".
     *
     * 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 QDBusObjectPath Connection() const TELEPATHY_GNUC_DEPRECATED
    {
        return qvariant_cast<QDBusObjectPath>(internalPropGet("Connection"));
    }

    /**
     * Represents property "Account" on the remote object.
     * 
     * The Account with which the Connection and Channels are associated. This 
     * property cannot change.
     */
    Q_PROPERTY(QDBusObjectPath Account READ Account)

    /**
     * Getter for the remote object property "Account".
     *
     * 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 QDBusObjectPath Account() const TELEPATHY_GNUC_DEPRECATED
    {
        return qvariant_cast<QDBusObjectPath>(internalPropGet("Account"));
    }

    /**
     * Represents property "Channels" on the remote object.
     * 
     * The Channels to be dispatched, and their properties. Change 
     * notification is via the ChannelLost signal (channels cannot be added to 
     * this property, only removed).
     */
    Q_PROPERTY(Tp::ChannelDetailsList Channels READ Channels)

    /**
     * Getter for the remote object property "Channels".
     *
     * 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 Tp::ChannelDetailsList Channels() const TELEPATHY_GNUC_DEPRECATED
    {
        return qvariant_cast<Tp::ChannelDetailsList>(internalPropGet("Channels"));
    }

    /**
     * Represents property "PossibleHandlers" on the remote object.
     * 
     * The well known bus names (starting with 
     * org.freedesktop.Telepathy.Client.) of the possible Handlers for these 
     * channels. The channel dispatcher MUST place the most preferred handlers 
     * first, according to some reasonable heuristic. As a result, approvers 
     * SHOULD use the first handler by default. The heuristic used to 
     * prioritize handlers SHOULD give a higher priority to handlers that are 
     * already running. If, for instance, Empathy and Kopete have similar 
     * functionality, and Empathy is running, we should prefer to send 
     * channels to it rather than launching Kopete via service activation.
     */
    Q_PROPERTY(QStringList PossibleHandlers READ PossibleHandlers)

    /**
     * Getter for the remote object property "PossibleHandlers".
     *
     * 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 PossibleHandlers() const TELEPATHY_GNUC_DEPRECATED
    {
        return qvariant_cast<QStringList>(internalPropGet("PossibleHandlers"));
    }

public Q_SLOTS:
    /**
     * Begins a call to the D-Bus method "HandleWith" on the remote object.
     * 
     * <p>Called by an approver to accept a channel bundle and request that
     *   the given handler be used to handle it.</p>
     * 
     * <p>If successful, this method will cause the ChannelDispatchOperation
     *   object to disappear, emitting
     *   <tp:member-ref>Finished</tp:member-ref>.</p>
     * 
     * <p>However, this method may fail because the dispatch has already been
     *   completed and the object has already gone. If this occurs, it
     *   indicates that another approver has asked for the bundle to be
     *   handled by a particular handler. The approver MUST NOT attempt
     *   to interact with the channels further in this case, unless it is
     *   separately invoked as the handler.</p>
     * 
     * <p>Approvers which are also channel handlers SHOULD use
     *   <tp:member-ref>Claim</tp:member-ref> instead
     *   of HandleWith to request that they can handle a channel bundle
     *   themselves.</p>
     * 
     * <p>(FIXME: list some possible errors)</p>
     * 
     * <p>If the channel handler raises an error from <tp:dbus-ref namespace="org.freedesktop.Telepathy.Client.Handler">HandleChannels</tp:dbus-ref>,
     *   this method
     *   MAY respond by raising that same error, even if it is not
     *   specifically documented here.</p>
     *
     * \param handler
     *     
     *     <p>The well-known bus name (starting with
     *       <code>org.freedesktop.Telepathy.Client.</code>) of the channel
     *       handler that should handle the channel, or the empty string
     *       if the client has no preferred channel handler.</p>
     */
    inline QDBusPendingReply<> HandleWith(const QString& handler)
    {
        if (!invalidationReason().isEmpty()) {
            return QDBusPendingReply<>(QDBusMessage::createError(
                invalidationReason(),
                invalidationMessage()
            ));
        }


        QList<QVariant> argumentList;
        argumentList << QVariant::fromValue(handler);
        return asyncCallWithArgumentList(QLatin1String("HandleWith"), argumentList);
    }

    /**
     * Begins a call to the D-Bus method "Claim" on the remote object.
     * 
     * <p>Called by an approver to claim channels for handling
     *   internally. If this method is called successfully, the process
     *   calling this method becomes the handler for the channel, but
     *   <em>does not</em> have the <tp:dbus-ref namespace="org.freedesktop.Telepathy.Client.Handler">HandleChannels</tp:dbus-ref>
     *   method called on it.</p>
     * 
     * <p>Clients that call Claim on channels but do not immediately
     *   close them SHOULD implement the Handler interface and its
     *   <tp:dbus-ref namespace="org.freedesktop.Telepathy.Client.Handler">HandledChannels</tp:dbus-ref>
     *   property.</p>
     * 
     * <p>Approvers wishing to reject channels MUST call this method to
     *   claim ownership of them, and MUST NOT call
     *   <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">Close</tp:dbus-ref>
     *   on the channels unless/until this method returns successfully.</p>
     * 
     * <tp:rationale>
     *   <p>The channel dispatcher can't know how best to close arbitrary
     *     channel types, so it leaves it up to the approver to do so.
     *     For instance, for Text channels it is necessary
     *     to acknowledge any messages that have already been displayed to
     *     the user first - ideally, the approver would display and then
     *     acknowledge the messages - or to call <tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.Interface.Destroyable.Destroy</tp:dbus-ref>
     *     if the destructive behaviour of that method is desired.</p>
     * 
     *   <p>Similarly, an Approver for StreamedMedia channels can close the
     *     channel with a reason (e.g. &quot;busy&quot;) if desired. The channel
     *     dispatcher, which is designed to have no specific knowledge
     *     of particular channel types, can't do that.</p>
     * </tp:rationale>
     * 
     * <p>If successful, this method will cause the ChannelDispatchOperation
     *   object to disappear, emitting
     *   <tp:member-ref>Finished</tp:member-ref>, in the same way as for
     *   <tp:member-ref>HandleWith</tp:member-ref>.</p>
     * 
     * <p>This method may fail because the dispatch operation has already
     *   been completed. Again, see HandleWith for more details. The approver
     *   MUST NOT attempt to interact with the channels further in this
     *   case.</p>
     * 
     * <p>(FIXME: list some other possible errors)</p>
     */
    inline QDBusPendingReply<> Claim()
    {
        if (!invalidationReason().isEmpty()) {
            return QDBusPendingReply<>(QDBusMessage::createError(
                invalidationReason(),
                invalidationMessage()
            ));
        }


        return asyncCall(QLatin1String("Claim"));
    }

Q_SIGNALS:
    /**
     * Represents the signal "ChannelLost" on the remote object.
     * 
     * <p>A channel has closed before it could be claimed or handled. If
     *   this is emitted for the last remaining channel in a channel
     *   dispatch operation, it MUST immediately be followed by
     *   <tp:member-ref>Finished</tp:member-ref>.</p>
     * 
     * <p>This signal MUST NOT be emitted until all Approvers that were
     *   invoked have returned (successfully or with an error) from
     *   their <tp:dbus-ref namespace="org.freedesktop.Telepathy.Client.Approver">AddDispatchOperation</tp:dbus-ref>
     *   method.</p>
     * 
     * <tp:rationale>
     *   <p>This means that Approvers can connect to the ChannelLost signal
     *     in a race-free way. Non-approver processes that discover
     *     a channel dispatch operation in some way (such as observers)
     *     will have to follow the usual &quot;connect to signals then recover
     *     state&quot; model - first connect to ChannelLost and
     *     <tp:member-ref>Finished</tp:member-ref>,
     *     then download <tp:member-ref>Channels</tp:member-ref> (and
     *     on error, perhaps assume that the operation has already
     *     Finished).</p>
     * </tp:rationale>
     *
     * \param channel
     *     
     *     The Channel that closed.
     *
     * \param error
     *     
     *     <p>The name of a D-Bus error indicating why the channel closed. If
     *       no better reason can be found,
     *       <code>org.freedesktop.Telepathy.Error.NotAvailable</code> MAY
     *       be used as a fallback; this means that this error SHOULD NOT be
     *       given any more specific meaning.</p>
     *
     * \param message
     *     
     *     A string associated with the D-Bus error.
     */
    void ChannelLost(const QDBusObjectPath& channel, const QString& error, const QString& message);

    /**
     * Represents the signal "Finished" on the remote object.
     * 
     * <p>Emitted when this dispatch operation finishes. The dispatch
     *   operation is no longer present and further methods must not be
     *   called on it.</p>
     * 
     * <p>Approvers that have a user interface SHOULD stop notifying the user
     *   about the channels in response to this signal; they MAY assume that
     *   on errors, they would have received
     *   <tp:member-ref>ChannelLost</tp:member-ref> first.</p>
     * 
     * <p>Its object path SHOULD NOT be reused for a subsequent dispatch
     *   operation; the ChannelDispatcher MUST choose object paths
     *   in a way that avoids immediate re-use.</p>
     * 
     * <tp:rationale>
     *   <p>Otherwise, clients might accidentally call
     *     <tp:member-ref>HandleWith</tp:member-ref> or
     *     <tp:member-ref>Claim</tp:member-ref> on a new dispatch operation
     *     instead of the one they intended to handle.</p>
     * </tp:rationale>
     * 
     * <p>This signal MUST NOT be emitted until all Approvers that were
     *   invoked have returned (successfully or with an error) from
     *   their <tp:dbus-ref namespace="org.freedesktop.Telepathy.Client.Approver">AddDispatchOperation</tp:dbus-ref>
     *   method.</p>
     * 
     * <tp:rationale>
     *   <p>This means that Approvers can connect to the ChannelLost signal
     *     in a race-free way. Non-approver processes that discover
     *     a channel dispatch operation in some way (such as observers)
     *     will have to follow the usual &quot;connect to signals then recover
     *     state&quot; model - first connect to
     *     <tp:member-ref>ChannelLost</tp:member-ref> and
     *     Finished, then download <tp:member-ref>Channels</tp:member-ref>
     *     (and on error, perhaps assume that the operation has already
     *     Finished).</p>
     * </tp:rationale>
     */
    void Finished();

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