This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

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.

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.

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

A struct representing a active session handler. The object path of the session handler, which is on the same bus name as the channel. The media session's type Returns all currently active session handlers on this channel as a list of (session_handler_path, type). Object path of the new Media.SessionHandler object String indicating type of session, eg "rtp" Signal that a session handler object has been created. The client should create a session object and create streams for the streams within. 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. 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. 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. 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.

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

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

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

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

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.

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.

This is necessary to support gatewaying between two Telepathy connections, in which case the available codecs might not be known to the gatewaying process.