| Home · All Classes · All Namespaces · Modules · Functions · Files

Public Slots | Public Member Functions | Static Public Member Functions | Protected Member Functions | List of all members
Tp::Client::ClientObserverInterface Class Reference
Client-side proxies » Client proxies

`#include <TelepathyQt/Client>`

Inheritance diagram for Tp::Client::ClientObserverInterface:
[legend]

## Public Slots

QDBusPendingReply | ObserveChannels (const QDBusObjectPath &account, const QDBusObjectPath &connection, const Tp::ChannelDetailsList &channels, const QDBusObjectPath &dispatchOperation, const Tp::ObjectPathList &requestsSatisfied, const QVariantMap &observerInfo, int timeout=-1)

## Public Member Functions

| ClientObserverInterface (const QString &busName, const QString &objectPath, QObject *parent=0)
| ClientObserverInterface (const QDBusConnection &connection, const QString &busName, const QString &objectPath, QObject *parent=0)
| ClientObserverInterface (Tp::DBusProxy *proxy)
| ClientObserverInterface (const Tp::Client::ClientInterface &mainInterface)
| ClientObserverInterface (const Tp::Client::ClientInterface &mainInterface, QObject *parent)
Tp::PendingVariant * | requestPropertyObserverChannelFilter () const
Tp::PendingVariant * | requestPropertyRecover () const
Tp::PendingVariant * | requestPropertyDelayApprovers () const
Tp::PendingVariantMap * | requestAllProperties () const
Public Member Functions inherited from Tp::AbstractInterface
virtual | ~AbstractInterface ()
bool | isValid () const
QString | invalidationReason () const
QString | invalidationMessage () const
void | setMonitorProperties (bool monitorProperties)
bool | isMonitoringProperties () const
Public Member Functions inherited from QDBusAbstractInterface
virtual | ~QDBusAbstractInterface ()
bool | isValid () const
QDBusConnection | connection () const
QString | service () const
QString | path () const
QString | interface () const
QDBusError | lastError () const
void | setTimeout (int timeout)
int | timeout () const
QDBusMessage | call (const QString &method, const QVariant &arg1, const QVariant &arg2, const QVariant &arg3, const QVariant &arg4, const QVariant &arg5, const QVariant &arg6, const QVariant &arg7, const QVariant &arg8)
QDBusMessage | call (QDBus::CallMode mode, const QString &method, const QVariant &arg1, const QVariant &arg2, const QVariant &arg3, const QVariant &arg4, const QVariant &arg5, const QVariant &arg6, const QVariant &arg7, const QVariant &arg8)
QDBusMessage | callWithArgumentList (QDBus::CallMode mode, const QString &method, const QList< QVariant > &args)
bool | callWithCallback (const QString &method, const QList< QVariant > &args, QObject *receiver, const char *returnMethod, const char *errorMethod)
bool | callWithCallback (const QString &method, const QList< QVariant > &args, QObject *receiver, const char *slot)
QDBusPendingCall | asyncCall (const QString &method, const QVariant &arg1, const QVariant &arg2, const QVariant &arg3, const QVariant &arg4, const QVariant &arg5, const QVariant &arg6, const QVariant &arg7, const QVariant &arg8)
QDBusPendingCall | asyncCallWithArgumentList (const QString &method, const QList< QVariant > &args)
Public Member Functions inherited from QObject
| QObject (QObject *parent)
virtual | ~QObject ()
virtual bool | event (QEvent *e)
virtual bool | eventFilter (QObject *watched, QEvent *event)
virtual const QMetaObject * | metaObject () const
QString | objectName () const
void | setObjectName (const QString &name)
bool | isWidgetType () const
bool | signalsBlocked () const
bool | blockSignals (bool block)
QThread * | thread () const
void | moveToThread (QThread *targetThread)
int | startTimer (int interval)
void | killTimer (int id)
T | findChild (const QString &name) const
QList< T > | findChildren (const QString &name) const
QList< T > | findChildren (const QRegExp &regExp) const
QObject * | child (const char *objName, const char *inheritsClass, bool recursiveSearch) const
const QObjectList & | children () const
void | setParent (QObject *parent)
void | installEventFilter (QObject *filterObj)
void | removeEventFilter (QObject *obj)
bool | connect (const QObject *sender, const char *signal, const char *method, Qt::ConnectionType type) const
bool | disconnect (const char *signal, const QObject *receiver, const char *method)
bool | disconnect (const QObject *receiver, const char *method)
void | dumpObjectTree ()
void | dumpObjectInfo ()
bool | setProperty (const char *name, const QVariant &value)
QVariant | property (const char *name) const
QList< QByteArray > | dynamicPropertyNames () const
void | destroyed (QObject *obj)
QObject * | parent () const
bool | inherits (const char *className) const
void | deleteLater ()
| QObject (QObject *parent, const char *name)
void | insertChild (QObject *object)
void | removeChild (QObject *object)
bool | isA (const char *className) const
const char * | className () const
const char * | name () const
const char * | name (const char *defaultName) const
void | setName (const char *name)

## Static Public Member Functions

static QLatin1String | staticInterfaceName ()
Static Public Member Functions inherited from QObject
QString | tr (const char *sourceText, const char *disambiguation, int n)
QString | trUtf8 (const char *sourceText, const char *disambiguation, int n)
bool | connect (const QObject *sender, const char *signal, const QObject *receiver, const char *method, Qt::ConnectionType type)
bool | connect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &method, Qt::ConnectionType type)
bool | disconnect (const QObject *sender, const char *signal, const QObject *receiver, const char *method)
bool | disconnect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &method)

## Protected Member Functions

virtual void | invalidate (Tp::DBusProxy *, const QString &, const QString &)
Protected Member Functions inherited from Tp::AbstractInterface
| AbstractInterface (DBusProxy *proxy, const QLatin1String &interface)
| AbstractInterface (const QString &busName, const QString &path, const QLatin1String &interface, const QDBusConnection &connection, QObject *parent)
PendingVariant * | internalRequestProperty (const QString &name) const
PendingOperation * | internalSetProperty (const QString &name, const QVariant &newValue)
PendingVariantMap * | internalRequestAllProperties () const
Protected Member Functions inherited from QObject
QObject * | sender () const
int | senderSignalIndex () const
int | receivers (const char *signal) const
virtual void | timerEvent (QTimerEvent *event)
virtual void | childEvent (QChildEvent *event)
virtual void | customEvent (QEvent *event)
virtual void | connectNotify (const char *signal)
virtual void | disconnectNotify (const char *signal)
bool | checkConnectArgs (const char *signal, const QObject *object, const char *method)

## Additional Inherited Members

Signals inherited from Tp::AbstractInterface
void | propertiesChanged (const QVariantMap &changedProperties, const QStringList &invalidatedProperties)
Protected Slots inherited from Tp::AbstractInterface
Static Protected Member Functions inherited from QObject
QByteArray | normalizeSignalSlot (const char *signalSlot)
Properties inherited from QObject
| objectName

## Detailed Description

Proxy class providing a 1:1 mapping of the D-Bus interface "org.freedesktop.Telepathy.Client.Observer".

## Constructor & Destructor Documentation

## § ClientObserverInterface() [1/5]

Tp::Client::ClientObserverInterface::ClientObserverInterface | ( | const QString & | busName,
|  | const QString & | objectPath,
|  | QObject * | parent = `0`
| ) |  |

Creates a ClientObserverInterface associated with the given object on the session bus.

Parameters

  busName | Name of the service the object is on.
  objectPath | Path to the object on the service.
  parent | Passed to the parent class constructor.

## § ClientObserverInterface() [2/5]

Tp::Client::ClientObserverInterface::ClientObserverInterface | ( | const QDBusConnection & | connection,
|  | const QString & | busName,
|  | const QString & | objectPath,
|  | QObject * | parent = `0`
| ) |  |

Creates a ClientObserverInterface associated with the given object on the given bus.

Parameters

  connection | The bus via which the object can be reached.
  busName | Name of the service the object is on.
  objectPath | Path to the object on the service.
  parent | Passed to the parent class constructor.

## § ClientObserverInterface() [3/5]

Tp::Client::ClientObserverInterface::ClientObserverInterface | ( | Tp::DBusProxy * | proxy | ) |

Creates a ClientObserverInterface associated with the same object as the given proxy.

Parameters

  proxy | The proxy to use. It will also be the QObject::parent() for this object.

## § ClientObserverInterface() [4/5]

Tp::Client::ClientObserverInterface::ClientObserverInterface | ( | const Tp::Client::ClientInterface & | mainInterface | ) |

explicit

Creates a ClientObserverInterface associated with the same object as the given proxy. Additionally, the created proxy will have the same parent as the given proxy.

Parameters

  mainInterface | The proxy to use.

## § ClientObserverInterface() [5/5]

Tp::Client::ClientObserverInterface::ClientObserverInterface | ( | const Tp::Client::ClientInterface & | mainInterface,
|  | QObject * | parent
| ) |  |

Creates a ClientObserverInterface associated with the same object as the given proxy. However, a different parent object can be specified.

Parameters

  mainInterface | The proxy to use.
  parent | Passed to the parent class constructor.

## Member Function Documentation

## § staticInterfaceName()

static QLatin1String Tp::Client::ClientObserverInterface::staticInterfaceName | ( |  | ) |

inline static

Returns the name of the interface "org.freedesktop.Telepathy.Client.Observer", which this class represents.

Returns
  The D-Bus interface name.

## § requestPropertyObserverChannelFilter()

Tp::PendingVariant* Tp::Client::ClientObserverInterface::requestPropertyObserverChannelFilter | ( |  | ) | const

inline

Asynchronous getter for the remote object property `ObserverChannelFilter` of type `Tp::ChannelClassList`.

A specification of the channels in which this observer is interested. The ObserveChannels() method should be called by the channel dispatcher whenever any of the new channels in a ConnectionInterfaceRequestsInterface::NewChannels() signal match this description.

Only certain D-Bus types have useful semantics for matching like this, so only certain types are allowed:

Integers of all sizes, including byte (y, n, q, i, u, x, t)
  Matched by numeric value, regardless of type (e.g. 42 as a 16-bit signed integer 'n' is considered equal to 42 as a 32-bit unsigned integer 'u')
Booleans (b)
  Matched by equality in the obvious way; not considered equal to any other type
Strings (s)
  Matched by equality in the obvious way; not considered equal to any other type
Object paths (o)
  Matched by equality in the obvious way; not considered equal to any other type

This property never changes while the observer process owns its Client bus name. For activatable processes, the filter can change due to an upgrade - the channel dispatcher SHOULD observe changes to .client files using a mechanism like inotify.

Not allowing this property to change is a simplification, particularly for activatable processes (we reject the possibility that a process with a .client file, when activated, has a filter that differs from what its .client file said).

If an Observer wants to add extra channels to its list of interests at runtime, it can register an additional Client bus name (for instance, the org.freedesktop.Telepathy.Client.Empathy process with unique name :1.42 could additionally register org.freedesktop.Telepathy.Client.Empathy._1_42) with additional filters. To remove those filters, it can release the bus name; it could even re-claim the bus name immediately, with different filters.

The same principle is applied to Approvers and Handlers.

For observers that have a .client file, the channel dispatcher may discover this property from keys of the form "`propertyname type`", in groups in the .client file whose name is the name of this interface followed by `.ObserverChannelFilter`, a space and an ASCII decimal number starting from 0.

Values in the .client file are encoded in exactly the same way as the `default-p` keys in .manager files, as described in the ConnectionManagerInterface interface (but note that not all types supported in .manager files can appear in .client files).

For instance, a .client file for an observer that is only interested in Text channels, with CONTACT or ROOM handles, that were requested by a local client:

    [org.freedesktop.Telepathy.Client]
    Interfaces=org.freedesktop.Telepathy.Client.Observer;

    [org.freedesktop.Telepathy.Client.Observer.ObserverChannelFilter 0]
    org.freedesktop.Telepathy.Channel.ChannelType s=org.freedesktop.Telepathy.Channel.Type.Text
    org.freedesktop.Telepathy.Channel.TargetHandleType u=1
    org.freedesktop.Telepathy.Channel.Requested b=true

    [org.freedesktop.Telepathy.Client.Observer.ObserverChannelFilter 1]
    org.freedesktop.Telepathy.Channel.ChannelType s=org.freedesktop.Telepathy.Channel.Type.Text
    org.freedesktop.Telepathy.Channel.TargetHandleType u=2
    org.freedesktop.Telepathy.Channel.Requested b=true

Returns
  A pending variant which will emit finished when the property has been retrieved.

## § requestPropertyRecover()

Tp::PendingVariant* Tp::Client::ClientObserverInterface::requestPropertyRecover | ( |  | ) | const

inline

Asynchronous getter for the remote object property `Recover` of type `bool`.

If true, upon the startup of this observer, ClientObserverInterface::ObserveChannels() will be called for every already existing channel matching its ClientObserverInterface::ObserverChannelFilter

When an activatable client having this property disappears from the bus and there are channels matching its ObserverChannelFilter, ObserveChannels will be called immediately to reactivate it again. Such clients should specify this property in their `.client` file as follows:

    [org.freedesktop.Telepathy.Client.Observer]
    Recover=true

This means that if an activatable Observer crashes, it will be restarted as soon as possible; while there is an unavoidable possibility that it will miss some events during this process (particularly ChannelTypeTextInterface messages), this window of event loss is kept to a minimum.

Non-activatable observers can't take advantage of this mechanism, but setting this property on a non-activatable observer does allow it to "catch up" on channels that are currently active at the time that it starts up.

When the ObserveChannels method is called due to observer recovery, the Observer_Info dictionary will contain one extra item mapping the key `"recovering"` to `True`.

Returns
  A pending variant which will emit finished when the property has been retrieved.

## § requestPropertyDelayApprovers()

Tp::PendingVariant* Tp::Client::ClientObserverInterface::requestPropertyDelayApprovers | ( |  | ) | const

inline

Asynchronous getter for the remote object property `DelayApprovers` of type `bool`.

If true, the channel dispatcher will wait for ObserveChannels() to return before calling ClientApproverInterface::AddDispatchOperation() on appropriate Approvers.

This property SHOULD be false unless there is a reason why a channel should not be given to approvers. An example of this is if an Observer is also a Handler and wants to ChannelDispatchOperationInterface::Claim() a channel so that it becomes its handler and doesn't want any approver to be called, this property should be true.

Observers and Approvers should be called at the same time in normal operation (with this property set to false) to improve responsiveness. For example, if an incoming call appears, the approver should get the channel as fast as possible to show a dialog, but if an approver has to make round-trips to set itself up, then the approval of the channel is delayed. As a result, it is recommended for this property to remain false unless absolutely necessary.

For service-activatable clients, this property should be specified in the observer's `.client` file as follows:

If this property is not implemented (telepathy-mission-control 5.7.5 and older), the channel dispatcher SHOULD consider it as being false.

    [org.freedesktop.Telepathy.Client.Observer]
    DelayApprovers=true

Returns
  A pending variant which will emit finished when the property has been retrieved.

## § requestAllProperties()

Tp::PendingVariantMap* Tp::Client::ClientObserverInterface::requestAllProperties | ( |  | ) | const

inline

Request all of the DBus properties on the interface.

Returns
  A pending variant map which will emit finished when the properties have been retrieved.

## § ObserveChannels

QDBusPendingReply Tp::Client::ClientObserverInterface::ObserveChannels | ( | const QDBusObjectPath & | account,
|  | const QDBusObjectPath & | connection,
|  | const Tp::ChannelDetailsList & | channels,
|  | const QDBusObjectPath & | dispatchOperation,
|  | const Tp::ObjectPathList & | requestsSatisfied,
|  | const QVariantMap & | observerInfo,
|  | int | timeout = `-1`
| ) |  |

inline slot

Begins a call to the D-Bus method `ObserveChannels` on the remote object.

Called by the channel dispatcher when channels in which the observer has registered an interest are announced in a ConnectionInterfaceRequestsInterface::NewChannels() signal.

If the same NewChannels signal announces some channels that match the filter, and some that do not, then only a subset of the channels (those that do match the filter) are passed to this method.

If the channel dispatcher will split up the channels from a single NewChannels signal and dispatch them separately (for instance because no installed Handler can handle all of them), it will call ObserveChannels several times.

The observer MUST NOT return from this method call until it is ready for a handler for the channel to run (which may change the channel's state).

The channel dispatcher must wait for observers to start up, to avoid the following race: text channel logger (observer) gets ObserveChannels, text channel handler gets ClientHandlerInterface::HandleChannels() channel handler starts up faster and acknowledges messages, logger never sees those messages.

The channel dispatcher SHOULD NOT change its behaviour based on whether this method succeeds or fails: there are no defined D-Bus errors for this method, and if it fails, this only indicates that an Observer is somehow broken.

The expected error response in the channel dispatcher is to log a warning, and otherwise continue as though this method had succeeded.

Note that timeout is ignored as of now. It will be used once http://bugreports.qt.nokia.com/browse/QTBUG-11775 is fixed.

Parameters

  account

      The Account with which the channels are associated. The well-known
      bus name to use is that of the AccountManager.

  connection

      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;.

  channels

      The Channels and their properties. Their well-known bus names are
      all the same as that of the Connection.

  dispatchOperation

  The path to the ChannelDispatchOperationInterface for these channels, or the special value '/' if there is no ChannelDispatchOperation (because the channels were requested, not incoming).

  If the Observer calls ChannelDispatchOperationInterface::Claim() or ChannelDispatchOperationInterface::HandleWith() on the dispatch operation, it MUST be careful to avoid deadlock, since these methods cannot return until the Observer has returned from ObserveChannels() .

  This allows an Observer to ChannelDispatchOperationInterface::Claim() a set of channels without having to match up calls to this method with calls to ClientApproverInterface::AddDispatchOperation() .

  requestsSatisfied

      The ChannelRequests satisfied by these channels. If the same
      process is an Observer and a Handler, it can be useful to be given
      this information as soon as possible (it will also be passed to
      Handler.HandleChannels).

  observerInfo

  Additional information about these channels. Currently defined keys are:
  `recovering` - b
    `True` if ObserveChannels was called for an existing channel (due to the Recover property being `True`); `False` or omitted otherwise.
    This allows observers to distinguish between new channels (the normal case), and existing channels that were given to the observer in order to catch up on previous events (perhaps after a previous instance of the same observer crashed).
  `request-properties` - a{oa{sv}}
    A map from ChannelRequestInterface paths listed in Requests_Satisfied to Qualified_Property_Value_Maps containing namespaced immutable properties of each request.

  All defined keys for this dictionary are optional; observers MAY safely ignore any entry in this dictionary.

  timeout | The timeout in milliseconds.

## § invalidate()

void Tp::Client::ClientObserverInterface::invalidate | ( | Tp::DBusProxy * | proxy,
|  | const QString & | error,
|  | const QString & | message
| ) |  |

protected virtual

Reimplemented from Tp::AbstractInterface.