Tp::Client::ChannelInterface Class Reference [Channel proxies]

#include <TelepathyQt4/Channel>

Inherits Tp::AbstractInterface.

List of all members.

Public Slots

• QDBusPendingReply Close ()
• QDBusPendingReply< QString > GetChannelType ()
• QDBusPendingReply< uint, uint > GetHandle ()
• QDBusPendingReply< QStringList > GetInterfaces ()

Signals

• void Closed ()

Public Member Functions

• ChannelInterface (const QString &busName, const QString &objectPath, QObject *parent=0)
• ChannelInterface (const QDBusConnection &connection, const QString &busName, const QString &objectPath, QObject *parent=0)
• ChannelInterface (Tp::DBusProxy *proxy)
• TELEPATHY_QT4_DEPRECATED QString ChannelType () const
• Tp::PendingVariant * requestPropertyChannelType () const
• TELEPATHY_QT4_DEPRECATED
  QStringList Interfaces () const
• Tp::PendingVariant * requestPropertyInterfaces () const
• TELEPATHY_QT4_DEPRECATED uint TargetHandle () const
• Tp::PendingVariant * requestPropertyTargetHandle () const
• TELEPATHY_QT4_DEPRECATED QString TargetID () const
• Tp::PendingVariant * requestPropertyTargetID () const
• TELEPATHY_QT4_DEPRECATED uint TargetHandleType () const
• Tp::PendingVariant * requestPropertyTargetHandleType () const
• TELEPATHY_QT4_DEPRECATED bool Requested () const
• Tp::PendingVariant * requestPropertyRequested () const
• TELEPATHY_QT4_DEPRECATED uint InitiatorHandle () const
• Tp::PendingVariant * requestPropertyInitiatorHandle () const
• TELEPATHY_QT4_DEPRECATED QString InitiatorID () const
• Tp::PendingVariant * requestPropertyInitiatorID () const
• Tp::PendingVariantMap * requestAllProperties () const

Static Public Member Functions

• static const char * staticInterfaceName ()

Protected Member Functions

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

Properties

• QString ChannelType
• QStringList Interfaces
• uint TargetHandle
• QString TargetID
• uint TargetHandleType
• bool Requested
• uint InitiatorHandle
• QString InitiatorID

---

Detailed Description

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

---

Constructor & Destructor Documentation

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

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

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

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

Tp::Client::ChannelInterface::ChannelInterface

(

Tp::DBusProxy *

proxy

)

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

---

Member Function Documentation

static const char* Tp::Client::ChannelInterface::staticInterfaceName

(

)

[inline, static]

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

Returns:

The D-Bus interface name.

TELEPATHY_QT4_DEPRECATED QString Tp::Client::ChannelInterface::ChannelType

(

)

const [inline]

Getter for the remote object property "ChannelType".

Don't use this: it blocks the main loop. Use the asynchronous requestPropertyChannelType() instead.

Returns:

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

Tp::PendingVariant* Tp::Client::ChannelInterface::requestPropertyChannelType

(

)

const [inline]

Asynchronous getter for the remote object property "ChannelType" of type QString.

The channel's type. This cannot change once the channel has been created.

For compatibility between older connection managers and newer clients, if this is unavailable or is an empty string, clients MUST use the result of calling <tp:member-ref>GetChannelType</tp:member-ref>.

<tp:rationale> The GetAll method lets clients retrieve all properties in one round-trip, which is desirable. </tp:rationale>

When requesting a channel, the request MUST specify a channel type, and the request MUST fail if the specified channel type cannot be supplied.

<tp:rationale> Common sense. </tp:rationale>

Returns:

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

TELEPATHY_QT4_DEPRECATED QStringList Tp::Client::ChannelInterface::Interfaces

(

)

const [inline]

Getter for the remote object property "Interfaces".

Don't use this: it blocks the main loop. Use the asynchronous requestPropertyInterfaces() instead.

Returns:

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

Tp::PendingVariant* Tp::Client::ChannelInterface::requestPropertyInterfaces

(

)

const [inline]

Asynchronous getter for the remote object property "Interfaces" of type QStringList.

Extra interfaces provided by this channel. This SHOULD NOT include the channel type and the Channel interface itself, and cannot change once the channel has been created.

For compatibility between older connection managers and newer clients, if this is unavailable, or if this is an empty list and <tp:member-ref>ChannelType</tp:member-ref> is an empty string, clients MUST use the result of calling <tp:member-ref>GetInterfaces</tp:member-ref> instead. If this is an empty list but ChannelType is non-empty, clients SHOULD NOT call GetInterfaces; this implies that connection managers that implement the ChannelType property MUST also implement the Interfaces property correctly.

<tp:rationale> The GetAll method lets clients retrieve all properties in one round-trip, which is desirable. </tp:rationale>

When requesting a channel with a particular value for this property, the request must fail without side-effects unless the connection manager expects to be able to provide a channel whose interfaces include at least the interfaces requested.

Returns:

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

TELEPATHY_QT4_DEPRECATED uint Tp::Client::ChannelInterface::TargetHandle

(

)

const [inline]

Getter for the remote object property "TargetHandle".

Don't use this: it blocks the main loop. Use the asynchronous requestPropertyTargetHandle() instead.

Returns:

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

Tp::PendingVariant* Tp::Client::ChannelInterface::requestPropertyTargetHandle

(

)

const [inline]

Asynchronous getter for the remote object property "TargetHandle" of type uint.

The handle (a representation for the identifier) of the contact, chatroom, etc. with which this handle communicates. Its type is given by the <tp:member-ref>TargetHandleType</tp:member-ref> property.

This is fixed for the lifetime of the channel, so channels which could potentially be used to communicate with multiple contacts (such as streamed media calls defined by their members, or ad-hoc chatrooms like MSN switchboards) must have TargetHandleType set to Handle_Type_None and TargetHandle set to 0.

Unlike in the telepathy-spec 0.16 API, there is no particular uniqueness guarantee - there can be many channels with the same (channel type, handle type, handle) tuple. This is necessary to support conversation threads in XMPP and SIP, for example.

If this is present in a channel request, it must be nonzero, <tp:member-ref>TargetHandleType</tp:member-ref> MUST be present and not Handle_Type_None, and <tp:member-ref>TargetID</tp:member-ref> MUST NOT be present. Properties from <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface">Addressing.DRAFT</tp:dbus-ref> MUST NOT be present.

The channel that satisfies the request MUST either:

• have the specified TargetHandle property; or
• have <tp:member-ref>TargetHandleType</tp:member-ref> = Handle_Type_None, TargetHandle = 0, and be configured such that it could communicate with the specified handle in some other way (e.g. have the requested contact handle in its Group interface)

Returns:

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

TELEPATHY_QT4_DEPRECATED QString Tp::Client::ChannelInterface::TargetID

(

)

const [inline]

Getter for the remote object property "TargetID".

Don't use this: it blocks the main loop. Use the asynchronous requestPropertyTargetID() instead.

Returns:

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

Tp::PendingVariant* Tp::Client::ChannelInterface::requestPropertyTargetID

(

)

const [inline]

Asynchronous getter for the remote object property "TargetID" of type QString.

The string that would result from inspecting the <tp:member-ref>TargetHandle</tp:member-ref> property (i.e. the identifier in the IM protocol of the contact, room, etc. with which this channel communicates), or the empty string if the TargetHandle is 0.

<tp:rationale>

The presence of this property avoids the following race condition:

• New channel C is signalled with target handle T
• Client calls <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection">InspectHandles</tp:dbus-ref>(CONTACT, [T])
• Channel C closes, removing the last reference to handle T
• <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection">InspectHandles</tp:dbus-ref>(CONTACT, [T]) returns an error

</tp:rationale>

If this is present in a channel request, <tp:member-ref>TargetHandleType</tp:member-ref> MUST be present and not Handle_Type_None, and <tp:member-ref>TargetHandle</tp:member-ref> MUST NOT be present. Properties from <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface">Addressing.DRAFT</tp:dbus-ref> MUST NOT be present.The request MUST fail with error InvalidHandle, without side-effects, if the requested TargetID would not be accepted by <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection">RequestHandles</tp:dbus-ref>.

The returned channel must be related to the handle corresponding to the given identifier, in the same way as if TargetHandle had been part of the request instead.

<tp:rationale>

Requesting channels with a string identifier saves a round-trip (the call to RequestHandles). It also allows the channel dispatcher to accept a channel request for an account that is not yet connected (and thus has no valid handles), bring the account online, and pass on the same parameters to the new connection's CreateChannel method. </tp:rationale>

Returns:

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

TELEPATHY_QT4_DEPRECATED uint Tp::Client::ChannelInterface::TargetHandleType

(

)

const [inline]

Getter for the remote object property "TargetHandleType".

Don't use this: it blocks the main loop. Use the asynchronous requestPropertyTargetHandleType() instead.

Returns:

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

Tp::PendingVariant* Tp::Client::ChannelInterface::requestPropertyTargetHandleType

(

)

const [inline]

Asynchronous getter for the remote object property "TargetHandleType" of type uint.

The type of <tp:member-ref>TargetHandle</tp:member-ref>.

If this is omitted from a channel request, connection managers SHOULD treat this as equivalent to Handle_Type_None.

If this is omitted or is Handle_Type_None, <tp:member-ref>TargetHandle</tp:member-ref> and <tp:member-ref>TargetID</tp:member-ref> MUST be omitted from the request.

Returns:

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

TELEPATHY_QT4_DEPRECATED bool Tp::Client::ChannelInterface::Requested

(

)

const [inline]

Getter for the remote object property "Requested".

Don't use this: it blocks the main loop. Use the asynchronous requestPropertyRequested() instead.

Returns:

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

Tp::PendingVariant* Tp::Client::ChannelInterface::requestPropertyRequested

(

)

const [inline]

Asynchronous getter for the remote object property "Requested" of type bool.

True if this channel was created in response to a local request, such as a call to <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.RequestChannel</tp:dbus-ref> or <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>.

<tp:rationale>

The idea of this property is to distinguish between "incoming" and "outgoing" channels, in a way that doesn't break down when considering special cases like contact lists that are automatically created on connection to the server, or chatrooms that an IRC proxy/bouncer like irssi-proxy or bip was already in.

The reason we want to make that distinction is that UIs for things that the user explicitly requested should start up automatically, whereas for incoming messages and VoIP calls we should first ask the user whether they want to open the messaging UI or accept the call. </tp:rationale>

If the channel was not explicitly requested (even if it was created as a side-effect of a call to one of those functions, e.g. because joining a Tube in a MUC context on XMPP implies joining that MUC), then this property is false.

For compatibility with older connection managers, clients SHOULD assume that this property is true if they see a channel announced by the <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.NewChannel</tp:dbus-ref> signal with the suppress_handler parameter set to true.

<tp:rationale>

In a correct connection manager, the only way to get such a channel is to request it. </tp:rationale>

Clients MAY additionally assume that this property is false if they see a channel announced by the NewChannel signal with the suppress_handler parameter set to false.

<tp:rationale>

This is more controversial, since it's possible to get that parameter set to false by requesting a channel. However, there's no good reason to do so, and we've deprecated this practice.

In the particular case of the channel dispatcher, the only side-effect of wrongly thinking a channel is unrequested is likely to be that the user has to confirm that they want to use it, so it seems fairly harmless to assume in the channel dispatcher that channels with suppress_handler false are indeed unrequested. </tp:rationale>

It does not make sense for this property to be in channel requests—it will always be true for channels returned by CreateChannel, and callers of EnsureChannel cannot control whether an existing channel was originally requested locally—so it MUST NOT be accepted.

Returns:

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

TELEPATHY_QT4_DEPRECATED uint Tp::Client::ChannelInterface::InitiatorHandle

(

)

const [inline]

Getter for the remote object property "InitiatorHandle".

Don't use this: it blocks the main loop. Use the asynchronous requestPropertyInitiatorHandle() instead.

Returns:

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

Tp::PendingVariant* Tp::Client::ChannelInterface::requestPropertyInitiatorHandle

(

)

const [inline]

Asynchronous getter for the remote object property "InitiatorHandle" of type uint.

The contact who initiated the channel; for instance, the contact who invited the local user to a chatroom, or the contact who initiated a call.

This does not necessarily represent the contact who created the underlying protocol-level construct. For instance, if Rob creates a chatroom, Will joins that chatroom, and Will invites Simon to join it, then Simon will see Will as the InitiatorHandle of the channel representing the chatroom.

<tp:rationale>

The room creator is generally a less useful piece of information than the inviter, is less likely to be available at invitation time (i.e. can't necessarily be an immutable property), and is less likely to be available at all. The creator of a chatroom is not currently available via Telepathy; if added in future, it is likely to be made available as a property on the Chatroom interface (bug 23151). </tp:rationale>

For channels requested by the local user, this MUST be the value of <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.SelfHandle</tp:dbus-ref> at the time the channel was created (i.e. not a channel-specific handle).

<tp:rationale>

On some protocols, the SelfHandle may change (as signalled by <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.SelfHandleChanged</tp:dbus-ref>), but this property is immutable. Hence, locally-requested channels' InitiatorHandle and InitiatorID may not match the current SelfHandle; <tp:member-ref>Requested</tp:member-ref> can be used to determine whether the channel was created locally. </tp:rationale>

For channels requested by a remote user, this MUST be their handle. If unavailable or not applicable, this MUST be 0 (for instance, contact lists are not really initiated by anyone in particular, and it's easy to imagine a protocol where chatroom invitations can be anonymous).

For channels with the <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface">Group</tp:dbus-ref> interface, this SHOULD be the same contact who is signalled as the "Actor" causing the self-handle to be placed in the local-pending set.

This SHOULD NOT be a channel-specific handle, if possible.

It does not make sense for this property to be in channel requests - the initiator will always be the local user - so it MUST NOT be accepted.

Returns:

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

TELEPATHY_QT4_DEPRECATED QString Tp::Client::ChannelInterface::InitiatorID

(

)

const [inline]

Getter for the remote object property "InitiatorID".

Don't use this: it blocks the main loop. Use the asynchronous requestPropertyInitiatorID() instead.

Returns:

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

Tp::PendingVariant* Tp::Client::ChannelInterface::requestPropertyInitiatorID

(

)

const [inline]

Asynchronous getter for the remote object property "InitiatorID" of type QString.

The string that would result from inspecting the <tp:member-ref>InitiatorHandle</tp:member-ref> property (i.e. the initiator's identifier in the IM protocol).

<tp:rationale>

The presence of this property avoids the following race condition:

• New StreamedMedia channel C is signalled with initiator handle I
• Client calls <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection">InspectHandles</tp:dbus-ref>(CONTACT, [I])
• Channel C closes, removing the last reference to handle I
• <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection">InspectHandles</tp:dbus-ref>(CONTACT, [I]) returns an error
• Client can indicate that a call was missed, but not who called!

</tp:rationale>

It does not make sense for this property to be in channel requests - the initiator will always be the local user - so it MUST NOT be accepted.

Returns:

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

Tp::PendingVariantMap* Tp::Client::ChannelInterface::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.

QDBusPendingReply Tp::Client::ChannelInterface::Close

(

)

[inline, slot]

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

Request that the channel be closed. This is not the case until the Closed signal has been emitted, and depending on the connection manager this may simply remove you from the channel on the server, rather than causing it to stop existing entirely. Some channels such as contact list channels may not be closed.

QDBusPendingReply<QString> Tp::Client::ChannelInterface::GetChannelType

(

)

[inline, slot]

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

Returns the interface name for the type of this channel. Clients SHOULD use the ChannelType property instead, falling back to this method only if necessary. The GetAll method lets clients retrieve all properties in one round-trip.

Returns:

The interface name

QDBusPendingReply<uint, uint> Tp::Client::ChannelInterface::GetHandle

(

)

[inline, slot]

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

Returns the handle type and number if this channel represents a communication with a particular contact, room or server-stored list, or zero if it is transient and defined only by its contents. Clients SHOULD use the TargetHandle and TargetHandleType properties instead, falling back to this method only if necessary. The GetAll method lets clients retrieve all properties in one round-trip.

Returns:

The same as TargetHandleType.

Returns:

The same as TargetHandle.

QDBusPendingReply<QStringList> Tp::Client::ChannelInterface::GetInterfaces

(

)

[inline, slot]

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

Get the optional interfaces implemented by the channel. Clients SHOULD use the Interfaces property instead, falling back to this method only if necessary. The GetAll method lets clients retrieve all properties in one round-trip.

Returns:

An array of the D-Bus interface names

void Tp::Client::ChannelInterface::Closed

(

)

[signal]

Represents the signal "Closed" on the remote object.

Emitted when the channel has been closed. Method calls on the channel are no longer valid after this signal has been emitted, and the connection manager may then remove the object from the bus at any point.

void Tp::Client::ChannelInterface::invalidate	(	Tp::DBusProxy *	proxy,
		const QString &	error,
		const QString &	message
	)			[protected, virtual]

Reimplemented from Tp::AbstractInterface.

---

Property Documentation

QString Tp::Client::ChannelInterface::ChannelType [read]

Represents property "ChannelType" on the remote object.

The channel's type. This cannot change once the channel has been created.

For compatibility between older connection managers and newer clients, if this is unavailable or is an empty string, clients MUST use the result of calling <tp:member-ref>GetChannelType</tp:member-ref>.

<tp:rationale> The GetAll method lets clients retrieve all properties in one round-trip, which is desirable. </tp:rationale>

When requesting a channel, the request MUST specify a channel type, and the request MUST fail if the specified channel type cannot be supplied.

<tp:rationale> Common sense. </tp:rationale>

QStringList Tp::Client::ChannelInterface::Interfaces [read]

Represents property "Interfaces" on the remote object.

Extra interfaces provided by this channel. This SHOULD NOT include the channel type and the Channel interface itself, and cannot change once the channel has been created.

For compatibility between older connection managers and newer clients, if this is unavailable, or if this is an empty list and <tp:member-ref>ChannelType</tp:member-ref> is an empty string, clients MUST use the result of calling <tp:member-ref>GetInterfaces</tp:member-ref> instead. If this is an empty list but ChannelType is non-empty, clients SHOULD NOT call GetInterfaces; this implies that connection managers that implement the ChannelType property MUST also implement the Interfaces property correctly.

<tp:rationale> The GetAll method lets clients retrieve all properties in one round-trip, which is desirable. </tp:rationale>

When requesting a channel with a particular value for this property, the request must fail without side-effects unless the connection manager expects to be able to provide a channel whose interfaces include at least the interfaces requested.

uint Tp::Client::ChannelInterface::TargetHandle [read]

Represents property "TargetHandle" on the remote object.

The handle (a representation for the identifier) of the contact, chatroom, etc. with which this handle communicates. Its type is given by the <tp:member-ref>TargetHandleType</tp:member-ref> property.

This is fixed for the lifetime of the channel, so channels which could potentially be used to communicate with multiple contacts (such as streamed media calls defined by their members, or ad-hoc chatrooms like MSN switchboards) must have TargetHandleType set to Handle_Type_None and TargetHandle set to 0.

Unlike in the telepathy-spec 0.16 API, there is no particular uniqueness guarantee - there can be many channels with the same (channel type, handle type, handle) tuple. This is necessary to support conversation threads in XMPP and SIP, for example.

If this is present in a channel request, it must be nonzero, <tp:member-ref>TargetHandleType</tp:member-ref> MUST be present and not Handle_Type_None, and <tp:member-ref>TargetID</tp:member-ref> MUST NOT be present. Properties from <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface">Addressing.DRAFT</tp:dbus-ref> MUST NOT be present.

The channel that satisfies the request MUST either:

• have the specified TargetHandle property; or
• have <tp:member-ref>TargetHandleType</tp:member-ref> = Handle_Type_None, TargetHandle = 0, and be configured such that it could communicate with the specified handle in some other way (e.g. have the requested contact handle in its Group interface)

QString Tp::Client::ChannelInterface::TargetID [read]

Represents property "TargetID" on the remote object.

The string that would result from inspecting the <tp:member-ref>TargetHandle</tp:member-ref> property (i.e. the identifier in the IM protocol of the contact, room, etc. with which this channel communicates), or the empty string if the TargetHandle is 0.

<tp:rationale>

The presence of this property avoids the following race condition:

• New channel C is signalled with target handle T
• Client calls <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection">InspectHandles</tp:dbus-ref>(CONTACT, [T])
• Channel C closes, removing the last reference to handle T
• <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection">InspectHandles</tp:dbus-ref>(CONTACT, [T]) returns an error

</tp:rationale>

If this is present in a channel request, <tp:member-ref>TargetHandleType</tp:member-ref> MUST be present and not Handle_Type_None, and <tp:member-ref>TargetHandle</tp:member-ref> MUST NOT be present. Properties from <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface">Addressing.DRAFT</tp:dbus-ref> MUST NOT be present.The request MUST fail with error InvalidHandle, without side-effects, if the requested TargetID would not be accepted by <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection">RequestHandles</tp:dbus-ref>.

The returned channel must be related to the handle corresponding to the given identifier, in the same way as if TargetHandle had been part of the request instead.

<tp:rationale>

Requesting channels with a string identifier saves a round-trip (the call to RequestHandles). It also allows the channel dispatcher to accept a channel request for an account that is not yet connected (and thus has no valid handles), bring the account online, and pass on the same parameters to the new connection's CreateChannel method. </tp:rationale>

uint Tp::Client::ChannelInterface::TargetHandleType [read]

Represents property "TargetHandleType" on the remote object.

The type of <tp:member-ref>TargetHandle</tp:member-ref>.

If this is omitted from a channel request, connection managers SHOULD treat this as equivalent to Handle_Type_None.

If this is omitted or is Handle_Type_None, <tp:member-ref>TargetHandle</tp:member-ref> and <tp:member-ref>TargetID</tp:member-ref> MUST be omitted from the request.

bool Tp::Client::ChannelInterface::Requested [read]

Represents property "Requested" on the remote object.

True if this channel was created in response to a local request, such as a call to <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.RequestChannel</tp:dbus-ref> or <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>.

<tp:rationale>

The idea of this property is to distinguish between "incoming" and "outgoing" channels, in a way that doesn't break down when considering special cases like contact lists that are automatically created on connection to the server, or chatrooms that an IRC proxy/bouncer like irssi-proxy or bip was already in.

The reason we want to make that distinction is that UIs for things that the user explicitly requested should start up automatically, whereas for incoming messages and VoIP calls we should first ask the user whether they want to open the messaging UI or accept the call. </tp:rationale>

If the channel was not explicitly requested (even if it was created as a side-effect of a call to one of those functions, e.g. because joining a Tube in a MUC context on XMPP implies joining that MUC), then this property is false.

For compatibility with older connection managers, clients SHOULD assume that this property is true if they see a channel announced by the <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.NewChannel</tp:dbus-ref> signal with the suppress_handler parameter set to true.

<tp:rationale>

In a correct connection manager, the only way to get such a channel is to request it. </tp:rationale>

Clients MAY additionally assume that this property is false if they see a channel announced by the NewChannel signal with the suppress_handler parameter set to false.

<tp:rationale>

This is more controversial, since it's possible to get that parameter set to false by requesting a channel. However, there's no good reason to do so, and we've deprecated this practice.

In the particular case of the channel dispatcher, the only side-effect of wrongly thinking a channel is unrequested is likely to be that the user has to confirm that they want to use it, so it seems fairly harmless to assume in the channel dispatcher that channels with suppress_handler false are indeed unrequested. </tp:rationale>

It does not make sense for this property to be in channel requests—it will always be true for channels returned by CreateChannel, and callers of EnsureChannel cannot control whether an existing channel was originally requested locally—so it MUST NOT be accepted.

uint Tp::Client::ChannelInterface::InitiatorHandle [read]

Represents property "InitiatorHandle" on the remote object.

The contact who initiated the channel; for instance, the contact who invited the local user to a chatroom, or the contact who initiated a call.

This does not necessarily represent the contact who created the underlying protocol-level construct. For instance, if Rob creates a chatroom, Will joins that chatroom, and Will invites Simon to join it, then Simon will see Will as the InitiatorHandle of the channel representing the chatroom.

<tp:rationale>

The room creator is generally a less useful piece of information than the inviter, is less likely to be available at invitation time (i.e. can't necessarily be an immutable property), and is less likely to be available at all. The creator of a chatroom is not currently available via Telepathy; if added in future, it is likely to be made available as a property on the Chatroom interface (bug 23151). </tp:rationale>

For channels requested by the local user, this MUST be the value of <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.SelfHandle</tp:dbus-ref> at the time the channel was created (i.e. not a channel-specific handle).

<tp:rationale>

On some protocols, the SelfHandle may change (as signalled by <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.SelfHandleChanged</tp:dbus-ref>), but this property is immutable. Hence, locally-requested channels' InitiatorHandle and InitiatorID may not match the current SelfHandle; <tp:member-ref>Requested</tp:member-ref> can be used to determine whether the channel was created locally. </tp:rationale>

For channels requested by a remote user, this MUST be their handle. If unavailable or not applicable, this MUST be 0 (for instance, contact lists are not really initiated by anyone in particular, and it's easy to imagine a protocol where chatroom invitations can be anonymous).

For channels with the <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface">Group</tp:dbus-ref> interface, this SHOULD be the same contact who is signalled as the "Actor" causing the self-handle to be placed in the local-pending set.

This SHOULD NOT be a channel-specific handle, if possible.

It does not make sense for this property to be in channel requests - the initiator will always be the local user - so it MUST NOT be accepted.

QString Tp::Client::ChannelInterface::InitiatorID [read]

Represents property "InitiatorID" on the remote object.

The string that would result from inspecting the <tp:member-ref>InitiatorHandle</tp:member-ref> property (i.e. the initiator's identifier in the IM protocol).

<tp:rationale>

The presence of this property avoids the following race condition:

• New StreamedMedia channel C is signalled with initiator handle I
• Client calls <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection">InspectHandles</tp:dbus-ref>(CONTACT, [I])
• Channel C closes, removing the last reference to handle I
• <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection">InspectHandles</tp:dbus-ref>(CONTACT, [I]) returns an error
• Client can indicate that a call was missed, but not who called!

</tp:rationale>

It does not make sense for this property to be in channel requests - the initiator will always be the local user - so it MUST NOT be accepted.