Methods
| Close | () | → | nothing | |
| GetChannelType | () | → | s: Channel_Type | (deprecated) |
| GetHandle | () | → | u: Target_Handle_Type, u: Target_Handle | (deprecated) |
| GetInterfaces | () | → | as: Interfaces | (deprecated) |
Signals
| Closed | () |
Properties
| ChannelType | s ( DBus_Interface) | Read only | ||
| Interfaces | as ( DBus_Interface_List) | Read only | ||
| TargetHandle | u ( Handle) | Read only | ||
| TargetID | s | Read only | ||
| TargetHandleType | u ( Handle_Type) | Read only | ||
| Requested | b | Read only | ||
| InitiatorHandle | u ( Contact_Handle) | Read only | ||
| InitiatorID | s | Read only |
Description
All communication in the Telepathy framework is carried out via channel objects which are created and managed by connections. This interface must be implemented by all channel objects, along with one single channel type, such as Channel.Type.ContactList which represents a list of people (such as a buddy list) or Channel.Type.Text which represents a channel over which textual messages are sent and received.
Each Channel's object path MUST start with the object path of its associated Connection, followed by '/'. There MAY be any number of additional object-path components, which clients MUST NOT attempt to parse.
Rationale:
Each channel has a number of immutable properties (which cannot vary after the channel has been announced with NewChannels), provided to clients in the ObserveChannels, AddDispatchOperation and HandleChannels methods to permit immediate identification of the channel. This interface contains immutable properties common to all channels. In brief:
- ChannelType specifies the kind of communication carried out on this channel;
- TargetHandleType, TargetHandle and TargetID specify the entity with which this channel communicates, such as the other party in a 1-1 call, or the name of a multi-user chat room;
- InitiatorHandle and InitiatorID specify who created this channel;
- Requested indicates whether the local user requested this channel, or whether it is an incoming call, a text conversation started by a remote contact, a chatroom invitation, etc.
Other optional Interfaces can be implemented to indicate other available functionality, such as Channel.Interface.Group if the channel contains a number of contacts, Channel.Interface.Password to indicate that a channel may have a password set to require entry, and Channel.Interface.ChatState for typing notifications. The interfaces implemented may not vary after the channel has been created. These other interfaces (along with the interface named by ChannelType) may themselves specify immutable properties to be announced up-front along with the properties on this interface.
Some channels are “anonymous”, with
TargetHandleType set to None,
which indicates that the channel is defined by some other properties. For
instance, transient ad-hoc chat rooms may be defined only by their members (as visible
through the Group
interface), and ContactSearch
channels represent a single search attempt for a particular Server.
Specific connection manager implementations may implement channel types and interfaces which are not contained within this specification in order to support further functionality. To aid interoperability between client and connection manager implementations, the interfaces specified here should be used wherever applicable, and new interfaces made protocol-independent wherever possible. Because of the potential for 3rd party interfaces adding methods or signals with conflicting names, the D-Bus interface names should always be used to invoke methods and bind signals.
Methods
Close () → nothing
Possible Errors
- Disconnected
- Network Error
- Not Implemented
- Not Available
Rationale:
GetChannelType () → s: Channel_Type
Returns
- Channel_Type — s (DBus_Interface)
Rationale:
GetHandle () → u: Target_Handle_Type, u: Target_Handle
Returns
- Target_Handle_Type — u (Handle_Type)
- Target_Handle — u (Handle)
Rationale:
GetInterfaces () → as: Interfaces
Returns
- Interfaces — as (DBus_Interface_List)
Rationale:
Signals
Closed ()
Properties
ChannelType — s (DBus_Interface)
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 GetChannelType.
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.
Rationale:
Interfaces — as (DBus_Interface_List)
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 ChannelType is an empty string, clients MUST use the result of calling GetInterfaces 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.
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.
TargetHandle — u (Handle)
The handle (a representation for the identifier) of the contact, chatroom, etc. with which this handle communicates. Its type is given by the TargetHandleType property.
This is fixed for the lifetime of the channel, so channels which could potentially be used to communicate with multiple contacts, and do not have an identity of their own (such as a Handle_Type_Room handle), 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, TargetHandleType MUST be present and not Handle_Type_None, and TargetID MUST NOT be present. Properties from Addressing1 MUST NOT be present.
The channel that satisfies the request MUST either:
- have the specified TargetHandle property; or
- have TargetHandleType = 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)
TargetID — s
The string that would result from inspecting the TargetHandle 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.
Rationale:
If this is present in a channel request, TargetHandleType MUST be present and not Handle_Type_None, and TargetHandle MUST NOT be present. Properties from Addressing1 MUST NOT be present.The request MUST fail with error InvalidHandle, without side-effects, if the requested TargetID would not be accepted by RequestHandles.
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.
Rationale:
TargetHandleType — u (Handle_Type)
The type of TargetHandle.
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, TargetHandle and TargetID MUST be omitted from the request.
Requested — b
True if this channel was created in response to a local request, such as a call to Connection.RequestChannel or Connection.Interface.Requests.CreateChannel.
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 Connection.NewChannel signal with the suppress_handler parameter set to true.
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.
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.
InitiatorHandle — u (Contact_Handle)
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.
Rationale:
For channels requested by the local user, this MUST be the value of Connection.SelfHandle at the time the channel was created (i.e. not a channel-specific handle).
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 Group 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.
InitiatorID — s
The string that would result from inspecting the InitiatorHandle property (i.e. the initiator's identifier in the IM protocol).
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.