ConnectionInterfaceRequestsInterface Class Reference
[Connection proxies]

#include <TelepathyQt4/Connection>

Inherits Tp::AbstractInterface.

List of all members.

Public Slots

• QDBusPendingReply
  < QDBusObjectPath, QVariantMap > CreateChannel (const QVariantMap &request)
• QDBusPendingReply< bool,
  QDBusObjectPath, QVariantMap > EnsureChannel (const QVariantMap &request)

Signals

• void NewChannels (const Tp::ChannelDetailsList &channels)
• void ChannelClosed (const QDBusObjectPath &removed)

Public Member Functions

• ConnectionInterfaceRequestsInterface (const QString &busName, const QString &objectPath, QObject *parent=0)
• ConnectionInterfaceRequestsInterface (const QDBusConnection &connection, const QString &busName, const QString &objectPath, QObject *parent=0)
• ConnectionInterfaceRequestsInterface (Tp::DBusProxy *proxy)
• ConnectionInterfaceRequestsInterface (const Tp::Client::ConnectionInterface &mainInterface)
• ConnectionInterfaceRequestsInterface (const Tp::Client::ConnectionInterface &mainInterface, QObject *parent)
• Tp::ChannelDetailsList Channels () const TELEPATHY_GNUC_DEPRECATED
• Tp::RequestableChannelClassList RequestableChannelClasses () 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::ChannelDetailsList Channels
• Tp::RequestableChannelClassList RequestableChannelClasses

---

Detailed Description

Proxy class providing a 1:1 mapping of the D-Bus interface "org.freedesktop.Telepathy.Connection.Interface.Requests."

---

Constructor & Destructor Documentation

ConnectionInterfaceRequestsInterface	(	const QString &	busName,
		const QString &	objectPath,
		QObject *	parent = 0
	)

Creates a ConnectionInterfaceRequestsInterface 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.

ConnectionInterfaceRequestsInterface	(	const QDBusConnection &	connection,
		const QString &	busName,
		const QString &	objectPath,
		QObject *	parent = 0
	)

Creates a ConnectionInterfaceRequestsInterface 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.

ConnectionInterfaceRequestsInterface

(

Tp::DBusProxy *

proxy

)

Creates a ConnectionInterfaceRequestsInterface 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.

ConnectionInterfaceRequestsInterface

(

const Tp::Client::ConnectionInterface &

mainInterface

)

[explicit]

Creates a ConnectionInterfaceRequestsInterface 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.

ConnectionInterfaceRequestsInterface	(	const Tp::Client::ConnectionInterface &	mainInterface,
		QObject *	parent
	)

Creates a ConnectionInterfaceRequestsInterface 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.Connection.Interface.Requests", which this class represents.

Returns:

The D-Bus interface name.

Tp::ChannelDetailsList Channels

(

)

const [inline]

Getter for the remote object property "Channels".

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.

Tp::RequestableChannelClassList RequestableChannelClasses

(

)

const [inline]

Getter for the remote object property "RequestableChannelClasses".

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<QDBusObjectPath, QVariantMap> CreateChannel

(

const QVariantMap &

request

)

[inline, slot]

Begins a call to the D-Bus method "CreateChannel" on the remote object.

Request that an entirely new channel is created.

<tp:rationale>

There is deliberately no flag corresponding to the suppress_handler argument to <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.RequestChannel</tp:dbus-ref>, because passing a FALSE value for that argument is deprecated. Requests made using this interface always behave as though suppress_handler was TRUE. </tp:rationale>

Parameters:

request

A dictionary containing desirable properties, which MUST include <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">ChannelType</tp:dbus-ref>. Some properties are defined such that only an exact match makes sense, and connection managers MUST NOT satisfy a request with a channel where that property does not match; some properties are defined such that the connection manager MAY treat the request as merely a hint, and make a best-effort attempt to satisfy it. This is documented separately for each property.

If this dictionary contains a property whose semantics are not known to the connection manager, this method MUST fail without side-effects (in particular it must not create a new channel).

<tp:rationale>

This is necessary if we want to be able to invent properties in future that, when used in a request, are hard requirements rather than just hints. A connection manager that did not know the semantics of those properties could incorrectly return a new channel that did not satisfy the requirements. </tp:rationale>

The connection manager MUST NOT respond successfully, and SHOULD NOT create a new channel or cause any other side-effects, unless it can create a new channel that satisfies the client's requirements.

Properties that will be set by this argument need not have write access after the channel has been created - indeed, it is expected that most will be read-only.

Returns:

The Channel object, which MUST NOT be signalled with <tp:member-ref>NewChannels</tp:member-ref> until after this method returns.

<tp:rationale>

This allows the requester to alter its handling of NewChannels by knowing whether one of the channels satisfied a request it made. </tp:rationale>

Returns:

Properties of the channel that was produced, equivalent to the properties in <tp:type>Channel_Details</tp:type>. Connection managers MUST NOT include properties here whose values can change, for the same reasons as in <tp:type>Channel_Details</tp:type>.

QDBusPendingReply<bool, QDBusObjectPath, QVariantMap> EnsureChannel

(

const QVariantMap &

request

)

[inline, slot]

Begins a call to the D-Bus method "EnsureChannel" on the remote object.

Request that channels are ensured to exist.

<tp:rationale>

The connection manager is in the best position to determine which existing channels could satisfy which requests. </tp:rationale>

Parameters:

request

A dictionary containing desirable properties, with the same semantics as the corresponding parameter to <tp:member-ref>CreateChannel</tp:member-ref>.

Returns:

If false, the caller of EnsureChannel MUST assume that some other process is handling this channel; if true, the caller of EnsureChannel SHOULD handle it themselves or delegate it to another client.

If the creation of a channel makes several calls to EnsureChannel (and no other requests) successful, exactly one of those calls MUST return a true value for this argument.

If the creation of a channel makes other requests successful, the value returned for this argument MUST be such that exactly one of the clients making requests ends up responsible for the channel. In particular, if <tp:member-ref>CreateChannel</tp:member-ref> returns a channel C, any EnsureChannel calls that also return C MUST return a false value for this argument.

Returns:

The Channel object. If it was created as a result of this method call, it MUST NOT be signalled by NewChannels until after this method returns. This allows the requester to alter its handling of NewChannels by knowing whether one of the channels satisfied a request it made.

Returns:

Properties of the channel that was produced, equivalent to the properties in <tp:type>Channel_Details</tp:type>. Connection managers MUST NOT include properties here whose values can change, for the same reasons as in <tp:type>Channel_Details</tp:type>.

void NewChannels

(

const Tp::ChannelDetailsList &

channels

)

[signal]

Represents the signal "NewChannels" on the remote object.

New channels have been created. The connection manager SHOULD emit a single signal for any group of closely related channels that are created at the same time, so that the channel dispatcher can try to dispatch them to a handler as a unit.

In particular, if additional channels are created as a side-effect of a call to <tp:member-ref>CreateChannel</tp:member-ref>, these channels SHOULD appear in the same NewChannels signal as the channel that satisfies the request.

<tp:rationale>

Joining a MUC Tube in XMPP requires joining the corresponding MUC (chatroom), so a <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type">Text</tp:dbus-ref> channel can be created as a side-effect. </tp:rationale>

Every time NewChannels is emitted, it MUST be followed by a <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.NewChannel</tp:dbus-ref> signal for each channel.

<tp:rationale>

The double signal emission is for the benefit of older Telepathy clients, which won't be listening for NewChannels.

The more informative NewChannels signal comes first so that clients that did not examine the connection to find out whether Requests is supported will see the more informative signal for each channel first, and then ignore the less informative signal because it announces a new channel of which they are already aware. </tp:rationale>

Parameters:

channels

The channels and their details. All channels that are signalled together like this MUST have the same Bundle property, which may either refer to an existing bundle, or establish a new bundle.

void ChannelClosed

(

const QDBusObjectPath &

removed

)

[signal]

Represents the signal "ChannelClosed" on the remote object.

Emitted when a channel is closed and hence disappears from the Channels property. This is redundant with the Closed signal on the channel itself, but it does provide full change notification for the Channels property.

Parameters:

removed

The channel which has been removed from the Channels property

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

---

Property Documentation

Tp::ChannelDetailsList Channels [read]

Represents property "Channels" on the remote object.

A list of all the channels which currently exist on this connection. Change notification is via the NewChannels and ChannelClosed signals.

Tp::RequestableChannelClassList RequestableChannelClasses [read]

Represents property "RequestableChannelClasses" on the remote object.

The classes of channel that are expected to be available on this connection, i.e. those for which <tp:member-ref>CreateChannel</tp:member-ref> can reasonably be expected to succeed. User interfaces can use this information to show or hide UI components.

This property cannot change after the connection has gone to state Connection_Status_Connected, so there is no change notification (if the connection has context-dependent capabilities, it SHOULD advertise support for all classes of channel that it might support during its lifetime). Before this state has been reached, the value of this property is undefined.

<tp:rationale>

This is not on an optional interface, because connection managers can always offer some sort of clue about the channel classes they expect to support (at worst, they can announce support for everything for which they have code). </tp:rationale>