Methods
GetSessionHandlers | () | → | a(os): Session_Handlers |
Signals
NewSessionHandler | (o: Session_Handler, s: Session_Type) |
Handler Capability Tokens
Types
Media_Session_Type | Simple Type | s | |
Media_Session_Handler_Info | Struct | (os) |
Description
An interface for signalling a channel containing synchronised media sessions which can contain an arbitrary number of streams. The presence of this interface on a Channel indicates that the connection manager will not carry out the actual streaming for this channel, and that the client handling the channel is responsible for doing so; in most cases we recommend doing this by using the telepathy-farsight library.
Rationale:
Streaming audio and (particularly) video requires a high level of integration with the UI, and having the connection manager act as a proxy would be likely to introduce unacceptable latency. As a result, audio/video streaming is offloaded into the client where possible, as an exception to the general design of Telepathy.
The negotiation interface is based on the API of the Farsight library. This, in turn, is based upon the IETF MMusic ICE drafts, where connections are established by signalling potential connection candidates to the peer until a usable connection is found, and codecs are negotiated with an SDP-style offer and answer. However, the principles should be applicable to other media streaming methods and the API re-used without difficulty.
Note that the naming conventions used in the MediaStreamHandler and MediaSessionHandler interfaces are rather confusing; methods have signal-like names and signals have method-like names, due to the API being based rather too closely on that of Farsight. This is for historical reasons and will be fixed in a future release of the Telepathy specification.
Methods
GetSessionHandlers () → a(os): Session_Handlers
Returns
- Session_Handlers — a(os) (Media_Session_Handler_Info_List)
Signals
NewSessionHandler (o: Session_Handler, s: Session_Type)
Parameters
- Session_Handler — o
- Session_Type — s (Media_Session_Type)
Handler Capability Tokens
org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/gtalk-p2p
The client can implement streaming for streams whose NATTraversal
property is gtalk-p2p
.
org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/ice-udp
The client can implement streaming for streams whose NATTraversal
property is ice-udp
.
org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/wlm-8.5
The client can implement streaming for streams whose NATTraversal
property is wlm-8.5
.
org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/wlm-2009
The client can implement streaming for streams whose NATTraversal
property is wlm-2009
.
org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/video/h264 (etc.)
The client supports media streaming with H264 (etc.).
This handler capability token is a one of a family of similar tokens: for any other audio or video codec whose MIME type is audio/subtype or video/subtype, a handler capability token of this form may exist (the subtype MUST appear in lower case in this context). Clients MAY support more codecs than they explicitly advertise support for; clients SHOULD explicitly advertise support for their preferred codec(s), and for codecs like H264 that are, in practice, significant in codec negotiation.
Rationale:
For instance, the XMPP capability used by the Google Video
Chat web client to determine whether a client is compatible
with it requires support for H264 video, so an XMPP
connection manager that supports this version of Jingle should
not advertise the Google Video Chat capability unless there
is at least one installed client that declares that it supports
video/h264
on StreamedMedia channels.
For example, a client could advertise support for
Speex, Theora and H264 by having three
handler capability tokens,
org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/audio/speex
,
org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/video/theora
and
org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/video/h264
,
in its Capabilities
property.
Clients MAY have media signalling abilities without explicitly supporting any particular codec, and connection managers SHOULD support this usage.
Rationale:
This is necessary to support gatewaying between two Telepathy connections, in which case the available codecs might not be known to the gatewaying process.
Types
Media_Session_Type — s
Media_Session_Handler_Info — (os)
- Session_Handler — o
- Media_Session_Type — s (Media_Session_Type)