TelepathyQt4: ClientObserverInterface Class Reference

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

# ClientObserverInterface Class Reference

`#include <TelepathyQt4/Client>`

Inherits Tp::AbstractInterface.

List of all members.

## Public Slots

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

## 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::ChannelClassList ObserverChannelFilter () const TELEPATHY_GNUC_DEPRECATED

## Static Public Member Functions

- static const char * staticInterfaceName ()

## Protected Member Functions

- virtual void invalidate (Tp::DBusProxy *, const QString &, const QString &)

## Properties

- Tp::ChannelClassList ObserverChannelFilter

## Detailed Description

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

## Constructor & Destructor Documentation

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 | ( | 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 | ( | 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 | ( | 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 | ( | 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

static const char* staticInterfaceName | ( |  | ) | `[inline, static]`

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

Returns:
  The D-Bus interface name.

Tp::ChannelClassList ObserverChannelFilter | ( |  | ) | const`[inline]`

Getter for the remote object property "ObserverChannelFilter".

Don't use this: it blocks the main loop.

Returns:
  The value of the property, or a default-constructed value if the property is not readable.

QDBusPendingReply ObserveChannels | ( | const QDBusObjectPath & | account,
|  | const QDBusObjectPath & | connection,
|  | const Tp::ChannelDetailsList & | channels,
|  | const QDBusObjectPath & | dispatchOperation,
|  | const Tp::ObjectPathList & | requestsSatisfied,
|  | const QVariantMap & | observerInfo |
| ) |  |  | `[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 <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">NewChannels</tp:dbus-ref> 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).

<tp:rationale>

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 <tp:dbus-ref namespace="org.freedesktop.Telepathy.Client.Handler">HandleChannels</tp:dbus-ref> channel handler starts up faster and acknowledges messages, logger never sees those messages. </tp:rationale>

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.

<tp:rationale>

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

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 '/' and replacing all subsequent '/' by '.'.
  | 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 <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelDispatchOperation</tp:dbus-ref> for these channels, or the special value '/' if there is no ChannelDispatchOperation (because the channels were requested, not incoming).

If the Observer calls <tp:dbus-ref namespace="org.freedesktop.Telepathy.ChannelDispatchOperation">Claim</tp:dbus-ref> or <tp:dbus-ref namespace="org.freedesktop.Telepathy.ChannelDispatchOperation">HandleWith</tp:dbus-ref> on the dispatch operation, it MUST be careful to avoid deadlock, since these methods cannot return until the Observer has returned from <tp:member-ref>ObserveChannels</tp:member-ref>.

<tp:rationale>

This allows an Observer to <tp:dbus-ref namespace="org.freedesktop.Telepathy.ChannelDispatchOperation">Claim</tp:dbus-ref> a set of channels without having to match up calls to this method with calls to <tp:dbus-ref namespace="org.freedesktop.Telepathy.Client.Approver">AddDispatchOperation</tp:dbus-ref>. </tp:rationale>

Parameters:

  | requestsSatisfied | The requests 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. No keys are currently defined.

If keys are defined for this dictionary, all will be optional; observers MAY safely ignore any entry in this dictionary.

virtual void invalidate | ( | Tp::DBusProxy * | ,
|  | const QString & | ,
|  | const QString & |  |
| ) |  |  | `[protected, virtual]`

## Property Documentation

Tp::ChannelClassList ObserverChannelFilter`[read]`

Represents property "ObserverChannelFilter" on the remote object.

A specification of the channels in which this observer is interested. The <tp:member-ref>ObserveChannels</tp:member-ref> method should be called by the channel dispatcher whenever any of the new channels in a <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">NewChannels</tp:dbus-ref> 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.

<tp:rationale>

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. </tp:rationale>

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.

Integers in the .client file are encoded in ASCII decimal, booleans are encoded as "true" or "false", and strings are encoded in the usual way for desktop files (including the C-style backslash escapes documented in the Desktop Entry specification).

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.Type 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.Type s=org.freedesktop.Telepathy.Channel.Type.Text
     org.freedesktop.Telepathy.Channel.TargetHandleType u=2
     org.freedesktop.Telepathy.Channel.Requested b=true