Methods
| CreateChannel | (a{sv}: Request) | → | o: Channel, a{sv}: Properties | |
| EnsureChannel | (a{sv}: Request) | → | b: Yours, o: Channel, a{sv}: Properties |
Signals
| NewChannel | (o: Channel, a{sv}: Properties) | |
| ChannelClosed | (o: Removed) |
Properties
| Channels | a(oa{sv}) (Channel_Details_List) | Read only |
Types
| Channel_Details | Struct | (oa{sv}) |
Description
An interface for channel requests and channel lists. Under normal circumstances, applications should deal with this interface via the ChannelDispatcher, but lower-level Telepathy applications (such as the ChannelDispatcher itself) might need to use this interface directly.
This interface is conceptually part of the core Connection interface, but is kept separate so that its properties will normally only need to be retrieved by the ChannelDispatcher, and its signals will normally only wake up the ChannelDispatcher.
Methods
CreateChannel (a{sv}: Request) → o: Channel, a{sv}: Properties
Parameters
- Request — a{sv} (Qualified_Property_Value_Map)
A dictionary containing desirable properties, which MUST include ChannelType. 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).
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.
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
- Channel — o
- Properties — a{sv} (Qualified_Property_Value_Map)
The Channel object, which MUST NOT be signalled with NewChannel until after this method returns.
Rationale:
This allows the requester to alter its handling of NewChannel by knowing whether the channel satisfied a request it made.
Properties of the channel that was produced, equivalent to the properties in Channel_Details. Connection managers MUST NOT include properties here whose values can change, for the same reasons as in Channel_Details.
Request that an entirely new channel is created.
Possible Errors
- Disconnected
- Network Error
- Not Implemented
- Invalid Handle
- Invalid Argument
- Not Capable
- Offline
- Not Available
- a channel matching the request already exists and the protocol requires that only one such channel can exist at a time
- a channel matching the request has already been requested (by a previous call to CreateChannel, EnsureChannel, or similar) and the protocol requires that only one such channel can exist at a time
- Channel.Banned
- Channel.Full
- Channel.Invite Only
- Permission Denied
Rationale:
The requested channel cannot be created, but in principle, a similar request might succeed in future. For instance, this might be because:
EnsureChannel (a{sv}: Request) → b: Yours, o: Channel, a{sv}: Properties
Parameters
- Request — a{sv} (Qualified_Property_Value_Map)
A dictionary containing desirable properties, with the same semantics as the corresponding parameter to CreateChannel.
Returns
- Yours — b
- Channel — o
- Properties — a{sv} (Qualified_Property_Value_Map)
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 CreateChannel returns a channel C, any EnsureChannel calls that also return C MUST return a false value for this argument.
Rationale:
This allows the requester to alter its handling of NewChannel by knowing whether the channel satisfied a request it made.
Properties of the channel that was produced, equivalent to the properties in Channel_Details. Connection managers MUST NOT include properties here whose values can change, for the same reasons as in Channel_Details.
Request that channels are ensured to exist.
Rationale:
The connection manager is in the best position to determine which existing channels could satisfy which requests.
Possible Errors
- Disconnected
- Network Error
- Not Implemented
- Invalid Handle
- Invalid Argument
- Not Capable
- Offline
- Not Available
- Channel.Banned
- Channel.Full
- Channel.Invite Only
- Permission Denied
Rationale:
Signals
NewChannel (o: Channel, a{sv}: Properties)
Parameters
- Channel — o
- Properties — a{sv} (Qualified_Property_Value_Map)
The same properties of the channel that would appear in the Channel_Details struct.
A new channel has been created.
Unlike in some previous Telepathy versions, the connection manager cannot emit a single signal for multiple channels. For example, joining a MUC Tube in XMPP requires joining the corresponding MUC (chatroom). Either the connection manager should announce a new Text channel separately, or not expose the Text channel on the bus until it's actually requested (or an incoming message appears).
Rationale:
Signalling the creation of multiple channels together makes writing simple clients much more complicated, can result in lost messages, and isn't nearly as useful in practice as it sounds.
ChannelClosed (o: Removed)
Parameters
- Removed — o
Properties
Channels — a(oa{sv}) (Channel_Details_List)
Types
Channel_Details — (oa{sv})
- Channel — o
- Properties — a{sv} (Qualified_Property_Value_Map)
- NewChannel or Get("Channels") includes a property P with value V1
- Client creates a proxy object for the channel
- The value of P changes to V2
- Client connects to PChanged signal
- Client should call Get("P") or GetAll here, to avoid the race, but client's author has forgotten to do so
- Proxy object thinks P == V1, but actually P == V2
Properties of the channel.
Connection managers MUST NOT include properties in this mapping if their values can change. Clients MUST ignore properties that appear in this mapping if their values can change.
Rationale:
If properties that could change were included, the following race condition would be likely to exist in some cases:
We've taken the opportunity to make the API encourage the client author to get it right. Where possible, we intend that properties whose value will be used in channel dispatching or other "early" processing will be defined so that they are immutable (can never change).
Each dictionary MUST contain the keys im.telepathy.v1.Channel.ChannelType, im.telepathy.v1.Channel.TargetEntityType, im.telepathy.v1.Channel.TargetHandle, im.telepathy.v1.Channel.TargetID and im.telepathy.v1.Channel.Requested.
Rationale:
We expect these to be crucial to the channel-dispatching process.