Interface Channel.Interface.MediaSignalling

Interface Index (Compact) | Summary | Description | Methods | Signals | Telepathy Properties | Handler Capability Tokens | Types

Methods

GetSessionHandlers () → a(os): Session_Handlers

Signals

NewSessionHandler (o: Session_Handler, s: Session_Type)

Telepathy Properties

nat-traversal s
stun-server s
stun-port q
gtalk-p2p-relay-token s

Handler Capability Tokens

org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/gtalk-p2p
org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/ice-udp
org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/wlm-8.5
org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/wlm-2009
org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/video/h264 (etc.)

Types

Media_Session_Type Simple Type s
Media_Session_Handler_Info Struct (os)
Objects implementing this interface must also implement:

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

(Permalink)

GetSessionHandlers () → a(os): Session_Handlers

Returns

Returns all currently active session handlers on this channel as a list of (session_handler_path, type).

Signals

(Permalink)

NewSessionHandler (o: Session_Handler, s: Session_Type)

Parameters

Signal that a session handler object has been created. The client should create a session object and create streams for the streams within.

Telepathy Properties

Accessed using the org.freedesktop.Telepathy.Properties interface.
(Permalink)

nat-traversal — s

Deprecated since 0.17.22. Use the NATTraversal property on the Media.StreamHandler, if available; use this as a fallback.
A string indicating the NAT traversal techniques employed by the streams within this channel if they do not have a NATTraversal property. The possible values are the same as for the NATTraversal property on the streams.
(Permalink)

stun-server — s

Deprecated since 0.17.22. Use the STUNServers property on the Media.StreamHandler, if available; use this as a fallback.
The IP address or hostname of the STUN server to use for NAT traversal if the individual streams do not specify one.
(Permalink)

stun-port — q

Deprecated since 0.17.22. Use the STUNServers property on the Media.StreamHandler, if available; use this as a fallback.
The UDP port number to use on the provided STUN server.
(Permalink)

gtalk-p2p-relay-token — s

Deprecated since 0.17.22. XMPP connection managers supporting the Google Talk relay server SHOULD make the necessary HTTP requests to find a username and password, and use those to populate the RelayInfo property on the Media.StreamHandler.
The authentication token for use with the Google Talk peer-to-peer relay server.

Handler Capability Tokens

Tokens representing capabilities that a Client.Handler can have.
(Permalink)

org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/gtalk-p2p

The client can implement streaming for streams whose NATTraversal property is gtalk-p2p.

(Permalink)

org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/ice-udp

The client can implement streaming for streams whose NATTraversal property is ice-udp.

(Permalink)

org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/wlm-8.5

The client can implement streaming for streams whose NATTraversal property is wlm-8.5.

(Permalink)

org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/wlm-2009

The client can implement streaming for streams whose NATTraversal property is wlm-2009.

(Permalink)

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

Simple Type (Permalink)

Media_Session_Type — s

The type of a media session. Currently, the only supported value is "rtp".
Struct (Permalink)

Media_Session_Handler_Info — (os)

A struct representing a active session handler.
  • Session_Handler — o
    • The object path of the session handler, which is on the same bus name as the channel.
  • Media_Session_Type — s (Media_Session_Type)
    • The media session's type