diff options
Diffstat (limited to 'qt4/spec/Channel_Type_Streamed_Media.xml')
| -rw-r--r-- | qt4/spec/Channel_Type_Streamed_Media.xml | 853 |
1 files changed, 853 insertions, 0 deletions
diff --git a/qt4/spec/Channel_Type_Streamed_Media.xml b/qt4/spec/Channel_Type_Streamed_Media.xml new file mode 100644 index 000000000..aa2b90345 --- /dev/null +++ b/qt4/spec/Channel_Type_Streamed_Media.xml @@ -0,0 +1,853 @@ +<?xml version="1.0" ?> +<node name="/Channel_Type_Streamed_Media" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright> Copyright © 2005-2009 Collabora Limited </tp:copyright> + <tp:copyright> Copyright © 2005-2009 Nokia Corporation </tp:copyright> + <tp:copyright> Copyright © 2006 INdT </tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>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.</p> + +<p>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.</p> + +<p>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.</p> + </tp:license> + <interface name="org.freedesktop.Telepathy.Channel.Type.StreamedMedia"> + <tp:requires interface="org.freedesktop.Telepathy.Channel"/> + <tp:requires interface="org.freedesktop.Telepathy.Channel.Interface.Group"/> + + <tp:enum name="Media_Stream_Type" type="u" + array-name="Media_Stream_Type_List"> + <tp:enumvalue suffix="Audio" value="0"> + <tp:docstring>An audio stream</tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Video" value="1"> + <tp:docstring>A video stream</tp:docstring> + </tp:enumvalue> + </tp:enum> + + <tp:enum name="Media_Stream_State" type="u"> + <tp:enumvalue suffix="Disconnected" value="0"> + <tp:docstring>The stream is disconnected.</tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Connecting" value="1"> + <tp:docstring>The stream is trying to connect.</tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Connected" value="2"> + <tp:docstring>The stream is connected.</tp:docstring> + </tp:enumvalue> + </tp:enum> + + <tp:enum name="Media_Stream_Direction" type="u"> + <tp:enumvalue suffix="None" value="0"> + <tp:docstring>Media are not being sent or received</tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Send" value="1"> + <tp:docstring>Media are being sent, but not received</tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Receive" value="2"> + <tp:docstring>Media are being received, but not sent</tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Bidirectional" value="3"> + <tp:docstring>Media are being sent and received</tp:docstring> + </tp:enumvalue> + </tp:enum> + + <tp:flags name="Media_Stream_Pending_Send" value-prefix="Media_Stream_Pending" type="u"> + <tp:flag suffix="Local_Send" value="1"> + <tp:docstring> + The local user has been asked to send media by the remote user. + Call <tp:member-ref>RequestStreamDirection</tp:member-ref> to + indicate whether or not this is acceptable. + </tp:docstring> + </tp:flag> + <tp:flag suffix="Remote_Send" value="2"> + <tp:docstring> + The remote user has been asked to send media by the local user. + The <tp:member-ref>StreamDirectionChanged</tp:member-ref> signal + will be emitted when the remote user accepts or rejects this + change. + </tp:docstring> + </tp:flag> + </tp:flags> + + <tp:struct name="Media_Stream_Info" array-name="Media_Stream_Info_List"> + <tp:member type="u" tp:type="Stream_ID" name="Identifier"/> + <tp:member type="u" tp:type="Contact_Handle" name="Contact"/> + <tp:member type="u" tp:type="Media_Stream_Type" name="Type"/> + <tp:member type="u" tp:type="Media_Stream_State" name="State"/> + <tp:member type="u" tp:type="Media_Stream_Direction" name="Direction"/> + <tp:member type="u" tp:type="Media_Stream_Pending_Send" + name="Pending_Send_Flags"/> + </tp:struct> + + <tp:simple-type name="Stream_ID" type="u" + array-name="Stream_ID_List"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An unsigned integer identifying a stream within a channel.</p> + </tp:docstring> + </tp:simple-type> + + <method name="ListStreams" tp:name-for-bindings="List_Streams"> + <arg direction="out" type="a(uuuuuu)" tp:type="Media_Stream_Info[]" + name="Streams"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + An array of structs containing: + <ul> + <li>the stream identifier</li> + <li>the contact handle who the stream is with (or 0 if the stream + represents more than a single member)</li> + <li>the type of the stream</li> + <li>the current stream state</li> + <li>the current direction of the stream</li> + <li>the current pending send flags</li> + </ul> + </tp:docstring> + </arg> + <tp:docstring> + Returns an array of structs representing the streams currently active + within this channel. Each stream is identified by an unsigned integer + which is unique for each stream within the channel. + </tp:docstring> + </method> + + <method name="RemoveStreams" tp:name-for-bindings="Remove_Streams"> + <arg direction="in" name="Streams" type="au" tp:type="Stream_ID[]"> + <tp:docstring> + An array of stream identifiers (as defined in + <tp:member-ref>ListStreams</tp:member-ref>) + </tp:docstring> + </arg> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Request that the given streams are removed. If all streams are + removed, the channel MAY close.</p> + + <p>Clients SHOULD NOT attempt to terminate calls by removing all the + streams; instead, clients SHOULD terminate calls by removing the + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface">Group.SelfHandle</tp:dbus-ref> + from the channel, using either + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface.Group">RemoveMembers</tp:dbus-ref> + or + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface.Group">RemoveMembersWithReason</tp:dbus-ref>. + </p> + </tp:docstring> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring> + A stream identifier is unknown + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <method name="RequestStreamDirection" + tp:name-for-bindings="Request_Stream_Direction"> + <arg direction="in" name="Stream_ID" type="u"> + <tp:docstring> + The stream identifier (as defined in + <tp:member-ref>ListStreams</tp:member-ref>) + </tp:docstring> + </arg> + <arg direction="in" name="Stream_Direction" type="u" tp:type="Media_Stream_Direction"> + <tp:docstring> + The desired stream direction (a value of MediaStreamDirection) + </tp:docstring> + </arg> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Request a change in the direction of an existing stream. In particular, + this might be useful to stop sending media of a particular type, + or inform the peer that you are no longer using media that is being + sent to you.</p> + + <p>Depending on the protocol, streams which are no longer sending in + either direction should be removed and a + <tp:member-ref>StreamRemoved</tp:member-ref> signal emitted. + Some direction changes can be enforced locally (for example, + BIDIRECTIONAL -> RECEIVE can be achieved by merely stopping sending), + others may not be possible on some protocols, and some need agreement + from the remote end. In this case, the MEDIA_STREAM_PENDING_REMOTE_SEND + flag will be set in the + <tp:member-ref>StreamDirectionChanged</tp:member-ref> signal, and the + signal + emitted again without the flag to indicate the resulting direction when + the remote end has accepted or rejected the change.</p> + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring> + A stream identifier is unknown + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + The requested direction is not available on this stream + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <method name="RequestStreams" tp:name-for-bindings="Request_Streams"> + <arg direction="in" name="Contact_Handle" type="u" tp:type="Contact_Handle"> + <tp:docstring> + A contact handle with whom to establish the streams + </tp:docstring> + </arg> + <arg direction="in" name="Types" type="au" tp:type="Media_Stream_Type[]"> + <tp:docstring> + An array of stream types (values of MediaStreamType) + </tp:docstring> + </arg> + <arg direction="out" type="a(uuuuuu)" tp:type="Media_Stream_Info[]" + name="Streams"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + An array of structs (in the same order as the given stream types) + containing: + <ul> + <li>the stream identifier</li> + <li>the contact handle who the stream is with (or 0 if the stream + represents more than a single member)</li> + <li>the type of the stream</li> + <li>the current stream state</li> + <li>the current direction of the stream</li> + <li>the current pending send flags</li> + </ul> + </tp:docstring> + </arg> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Request that streams be established to exchange the given types of + media with the given member. In general this will try and establish a + bidirectional stream, but on some protocols it may not be possible to + indicate to the peer that you would like to receive media, so a + send-only stream will be created initially. In the cases where the + stream requires remote agreement (eg you wish to receive media from + them), the <tp:member-ref>StreamDirectionChanged</tp:member-ref> signal + will be emitted with the + MEDIA_STREAM_PENDING_REMOTE_SEND flag set, and the signal emitted again + with the flag cleared when the remote end has replied.</p> + + <p>If streams of the requested types already exist, calling this + method results in the creation of additional streams. Accordingly, + clients wishing to have exactly one audio stream or exactly one + video stream SHOULD check for the current streams using + <tp:member-ref>ListStreams</tp:member-ref> before calling this + method.</p> + </tp:docstring> + <tp:changed version="0.17.2"> + <p>It is valid to use a handle which is neither + a current nor pending member in this channel's <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface">Group</tp:dbus-ref> + interface. If + so, that handle will be added to the remote-pending set only when + an attempt has actually been made to contact them. For further + call-state notification, use the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface">CallState</tp:dbus-ref> + interface, if + supported. This usage was not allowed in spec versions below + 0.17.2.</p> + </tp:changed> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring> + A stream type given is invalid. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + A stream type given is not implemented by the connection manager. + Since 0.17.23, connection managers SHOULD raise this error + in preference to InvalidArgument. + <tp:rationale> + Connection managers can't know whether an unknown number + is a valid stream type that was introduced in a later spec + version. + </tp:rationale> + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + That contact's client does not implement one of the given stream + types. For this method, clients SHOULD consider this error and + NotCapable to be equivalent. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotCapable"> + <tp:docstring> + That contact's client does not implement one of the given stream + types. Since 0.17.23, connection managers SHOULD raise + this in preference to NotAvailable. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <signal name="StreamAdded" tp:name-for-bindings="Stream_Added"> + <arg name="Stream_ID" type="u"> + <tp:docstring> + The stream identifier (as defined in + <tp:member-ref>ListStreams</tp:member-ref>) + </tp:docstring> + </arg> + <arg name="Contact_Handle" type="u" tp:type="Contact_Handle"> + <tp:docstring> + The contact handle who the stream is with (or 0 if it + represents more than a single member) + </tp:docstring> + </arg> + <arg name="Stream_Type" type="u" tp:type="Media_Stream_Type"> + <tp:docstring> + The stream type (a value from MediaStreamType) + </tp:docstring> + </arg> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Emitted when a new stream has been added to this channel. + Clients SHOULD assume that the stream's + <tp:type>Media_Stream_State</tp:type> is initially Disconnected.</p> + + <p>If a connection manager needs to represent the addition of a stream + whose state is already Connecting or Connected, it MUST do this + by emitting StreamAdded, closely followed by + <tp:member-ref>StreamStateChanged</tp:member-ref> indicating a + change to the appropriate state.</p> + + <tp:rationale> + <p>Historically, it was not clear from the StreamAdded signal what + the state of the stream was. telepathy-spec 0.17.22 + clarified this.</p> + </tp:rationale> + + <p>Similarly, clients SHOULD assume that the initial + <tp:type>Media_Stream_Direction</tp:type> of a newly added stream + is Receive, and that the initial + <tp:type>Media_Stream_Pending_Send</tp:type> is + Pending_Local_Send.</p> + + <p>If a connection manager needs to represent the addition of a stream + whose direction or pending-send differs from those initial values, + it MUST do so by emitting StreamAdded, closely followed by + <tp:member-ref>StreamDirectionChanged</tp:member-ref> indicating a + change to the appropriate direction and pending-send state.</p> + + <tp:rationale> + <p>StreamAdded doesn't itself indicate the stream's direction; this + is unfortunate, but is preserved for compatibility.</p> + + <p>This is the appropriate direction for streams added by a remote + contact on existing connection managers, and does not violate + user privacy by automatically sending audio or video (audio streams + start off muted, video streams start off not sending). For + streams added by the local user using the client receiving the + signal, the true direction can also be determined from the return + value of the <tp:member-ref>RequestStreams</tp:member-ref> + method.</p> + + <p>Existing clients typically operate by maintaining a separate + idea of the directions that they would like the streams to have, + and enforcing these intended directions by calling + <tp:member-ref>RequestStreamDirection</tp:member-ref> whenever + needed.</p> + </tp:rationale> + </tp:docstring> + </signal> + + <signal name="StreamDirectionChanged" + tp:name-for-bindings="Stream_Direction_Changed"> + <arg name="Stream_ID" type="u"> + <tp:docstring> + The stream identifier (as defined in <tp:member-ref>ListStreams</tp:member-ref>) + </tp:docstring> + </arg> + <arg name="Stream_Direction" type="u" tp:type="Media_Stream_Direction"> + <tp:docstring> + The new stream direction (as defined in ListStreams) + </tp:docstring> + </arg> + <arg name="Pending_Flags" type="u" tp:type="Media_Stream_Pending_Send"> + <tp:docstring> + The new pending send flags (as defined in ListStreams) + </tp:docstring> + </arg> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Emitted when the direction or pending flags of a stream are + changed.</p> + + <p>If the MEDIA_STREAM_PENDING_LOCAL_SEND flag is set, the remote user + has requested that we begin sending on this stream. + <tp:member-ref>RequestStreamDirection</tp:member-ref> + should be called to indicate whether or not this change is + acceptable.</p> + + <tp:rationale> + <p>This allows for a MSN-style user interface, "Fred has asked you + to enable your webcam. (Accept | Reject)", if desired.</p> + </tp:rationale> + </tp:docstring> + </signal> + + <signal name="StreamError" tp:name-for-bindings="Stream_Error"> + <arg name="Stream_ID" type="u"> + <tp:docstring> + The stream identifier (as defined in + <tp:member-ref>ListStreams</tp:member-ref>) + </tp:docstring> + </arg> + <arg name="Error_Code" type="u" tp:type="Media_Stream_Error"> + <tp:docstring> + A stream error number, one of the values of MediaStreamError + </tp:docstring> + </arg> + <arg name="Message" type="s"> + <tp:docstring> + A string describing the error (for debugging purposes only) + </tp:docstring> + </arg> + <tp:docstring> + Emitted when a stream encounters an error. + </tp:docstring> + </signal> + + <signal name="StreamRemoved" tp:name-for-bindings="Stream_Removed"> + <arg name="Stream_ID" type="u"> + <tp:docstring> + stream_id - the stream identifier (as defined in + <tp:member-ref>ListStreams</tp:member-ref>) + </tp:docstring> + </arg> + <tp:docstring> + Emitted when a stream has been removed from this channel. + </tp:docstring> + </signal> + + <signal name="StreamStateChanged" + tp:name-for-bindings="Stream_State_Changed"> + <arg name="Stream_ID" type="u"> + <tp:docstring> + The stream identifier (as defined in + <tp:member-ref>ListStreams</tp:member-ref>) + </tp:docstring> + </arg> + <arg name="Stream_State" type="u" tp:type="Media_Stream_State"> + <tp:docstring> + The new stream state (as defined in ListStreams) + </tp:docstring> + </arg> + <tp:docstring> + Emitted when a member's stream's state changes. + </tp:docstring> + </signal> + + <property name="InitialAudio" tp:name-for-bindings="Initial_Audio" + type="b" access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If set to true in a channel request that will create a new channel, + the connection manager should immediately attempt to establish an + audio stream to the remote contact, making it unnecessary for the + client to call <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type.StreamedMedia">RequestStreams</tp:dbus-ref>.</p> + + <p>If this property, or InitialVideo, is passed to EnsureChannel + (as opposed to CreateChannel), the connection manager SHOULD ignore + these properties when checking whether it can return an existing + channel as suitable; these properties only become significant when + the connection manager has decided to create a new channel.</p> + + <p>If true on a requested channel, this indicates that the audio + stream has already been requested and the client does not need to + call RequestStreams, although it MAY still do so.</p> + + <p>If true on an unrequested (incoming) channel, this indicates that + the remote contact initially requested an audio stream; this does + not imply that that audio stream is still active (as indicated by + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type.StreamedMedia">ListStreams</tp:dbus-ref>).</p> + + <p>This property is immutable (cannot change), and therefore SHOULD + appear wherever immutable properties are reported, e.g. <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">NewChannels</tp:dbus-ref> + signals.</p> + + <tp:rationale><p>This reduces D-Bus round trips.</p></tp:rationale> + + <p>Connection managers capable of signalling audio calls to contacts + SHOULD include a channel class in <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">RequestableChannelClasses</tp:dbus-ref> + with <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">ChannelType</tp:dbus-ref> + = <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type">StreamedMedia</tp:dbus-ref> + and <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref> + = Contact in the fixed properties dictionary, and InitialAudio + (and also InitialVideo, if applicable) in the allowed properties + list. Clients wishing to discover whether a connection manager + can signal audio and/or video calls SHOULD use this information.</p> + + <tp:rationale> + <p>Not all protocols support signalling video calls, and it would be + possible (although unlikely) to have a protocol where only video, + and not audio, could be signalled.</p> + </tp:rationale> + + <p>Connection managers that support the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface">ContactCapabilities</tp:dbus-ref> + interface SHOULD represent the capabilities of receiving audio + and/or video calls by including a channel class in + a contact's capabilities with ChannelType = StreamedMedia + in the fixed properties dictionary, and InitialAudio and/or + InitialVideo in the allowed properties list. Clients wishing to + discover whether a particular contact is likely to be able to + receive audio and/or video calls SHOULD use this information.</p> + + <tp:rationale> + <p>Not all clients support video calls, and it would also be + possible (although unlikely) to have a client which could only + stream video, not audio.</p> + </tp:rationale> + + <p>Clients that are willing to receive audio and/or video calls + SHOULD include the following among their channel classes if + calling <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities">UpdateCapabilities</tp:dbus-ref> + (clients of a <tp:dbus-ref + namespace="org.freedesktop.Telepathy">ChannelDispatcher</tp:dbus-ref> + SHOULD instead arrange for the ChannelDispatcher to do this, + by including the filters in their <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client.Handler">HandlerChannelFilter</tp:dbus-ref> + properties):</p> + + <ul> + <li>{ ChannelType = StreamedMedia }</li> + <li>{ ChannelType = StreamedMedia, InitialAudio = true } + if receiving calls with audio is supported</li> + <li>{ ChannelType = StreamedMedia, InitialVideo = true } + if receiving calls with video is supported</li> + </ul> + + <tp:rationale> + <p>Connection managers for protocols with capability discovery, + like XMPP, need this information to advertise the appropriate + capabilities for their protocol.</p> + </tp:rationale> + </tp:docstring> + </property> + + <property name="InitialVideo" tp:name-for-bindings="Initial_Video" + type="b" access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The same as <tp:member-ref>InitialAudio</tp:member-ref>, but for + a video stream. This property is immutable (cannot change).</p> + + <p>In particular, note that if this property is false, this does not + imply that an active video stream has not been added, only that no + video stream was active at the time the channel appeared.</p> + + <p>This property is the correct way to discover whether connection + managers, contacts etc. support video calls; it appears in + capabilities structures in the same way as InitialAudio.</p> + </tp:docstring> + </property> + + <property name="ImmutableStreams" tp:name-for-bindings="Immutable_Streams" + type="b" access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If <tt>True</tt>, once streams have been requested for this channel + (either by setting <tp:member-ref>InitialAudio</tp:member-ref> or + <tp:member-ref>InitialVideo</tp:member-ref> when the channel is + requested, or by calling + <tp:member-ref>RequestStreams</tp:member-ref> on a channel with no + streams), a stream of a different content type cannot be added; + subsequent calls to <tp:member-ref>RequestStreams</tp:member-ref> + that attempt to do so will fail.</p> + + <p>If this property is missing, clients SHOULD assume that it is false, + and thus that the channel's streams can be changed once the call has + started.</p> + + <p>If this property is present in the "allowed" set in all of the + StreamedMedia entries in a contact's capabilities, then user + interfaces MAY choose to show a separate "call" option for each + class of call.</p> + + <tp:rationale> + <p>For example, once an audio-only Google Talk call has started, + it is not possible to add a video stream; both audio and video + must be requested at the start of the call if video is desired. + User interfaces may use this pseudo-capability as a hint to + display separate "Audio call" and "Video call" buttons, rather + than a single "Call" button with the option to add and remove + video once the call has started for contacts without this flag. + </p> + </tp:rationale> + + <p>This property is immutable, and therefore SHOULD be announced + in <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">NewChannels</tp:dbus-ref>, + etc.</p> + </tp:docstring> + </property> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A channel that can send and receive streamed media such as audio or + video. Provides a number of methods for listing and requesting new + streams, and signals to indicate when streams have been added, removed + and changed status. The state of the call (ringing remotely, ringing + locally, answered, missed, etc.) are represented using the properties + and signals of the Group interface.</p> + + <p>In general this should be used in conjunction with the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface">MediaSignalling</tp:dbus-ref> + interface to exchange connection candidates and codec choices with + whichever component is responsible for the streams. However, in certain + applications where no candidate exchange is necessary (eg the streams + are handled by specialised hardware which is controlled directly by the + connection manager), the signalling interface can be omitted and this + channel type used simply to control the streams.</p> + + <h4>Outgoing calls</h4> + + <p>To make an audio-only call to a contact <tt>foo@example.com</tt>, + clients should call:</p> + + <blockquote> + <pre> +<tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">CreateChannel</tp:dbus-ref>({ + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">ChannelType</tp:dbus-ref>: <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type">StreamedMedia</tp:dbus-ref>, + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref>: Contact, + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref>: 'foo@example.com', + <tp:member-ref>InitialAudio</tp:member-ref>: True, +)</pre></blockquote> + + <p>As always, <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref> + may be used in place of TargetID if the contact's handle is already + known. To make an audio-and-video call, the client should also specify + <tp:member-ref>InitialVideo</tp:member-ref>. The connection manager + SHOULD return a channel whose immutable properties contain the local + user as the <tp:dbus-ref namespace='ofdT.Channel'>InitiatorHandle</tp:dbus-ref>, + the remote contact as the <tp:dbus-ref namespace='ofdT.Channel'>TargetHandle</tp:dbus-ref>, + <tp:dbus-ref namespace='ofdT.Channel'>Requested</tp:dbus-ref> = <code>True</code> + (indicating that the call is outgoing); the <tp:dbus-ref + namespace='ofdT.Channel.Interface'>Group</tp:dbus-ref> interface should + initially have the local user in <tp:dbus-ref + namespace='ofdT.Channel.Interface.Group'>Members</tp:dbus-ref> and the remote + contact in <tp:dbus-ref + namespace='ofdT.Channel.Interface.Group'>RemotePendingMembers</tp:dbus-ref>, to + indicate that we are awaiting their response.</p> + + <p>The contact answering the call is represented by the CM signalling + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface.Group">MembersChanged</tp:dbus-ref>, + moving the remote contact to Members, with the remote contact as the + <var>Actor</var> and <var>Reason</var> <code>None</code>. The contact + rejecting the call is represented by both contacts being removed from + the group, with the remote contact as the <var>Actor</var> and + <var>Reason</var> set appropriately. The local user may hang up at any + time by calling + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface.Group">RemoveMembersWithReason</tp:dbus-ref> + to remove themself, with an appropriate reason; the CM SHOULD relay the + reason to the remote contact, and emit MembersChanged removing both + contacts from the group with the self handle as the <var>Actor</var>.</p> + + <p>(In the past, several other patterns have been used to place outgoing + calls; see + <a href="http://telepathy.freedesktop.org/wiki/Requesting%20StreamedMedia%20channels">'Requesting StreamedMedia Channels' on the Telepathy wiki</a> + for the details.)</p> + + <h4>Incoming calls</h4> + + <p>Incoming calls' immutable properties should contain <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref> + = Contact, both <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref> and + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">InitiatorHandle</tp:dbus-ref> + set to the remote contact, <tp:dbus-ref + namespace='ofdT.Channel'>Requested</tp:dbus-ref> = <code>False</code> + (indicating that this is an incoming call), and appropriate values of + <tp:member-ref>InitialAudio</tp:member-ref> and + <tp:member-ref>InitialVideo</tp:member-ref>; the Group interface should + initially have the local user in <tp:dbus-ref + namespace="ofdT.Channel.Interface.Group">LocalPendingMembers</tp:dbus-ref> + and the remote contact in <tp:dbus-ref + namespace="ofdT.Channel.Interface.Group">Members</tp:dbus-ref>, + indicating that the contact is awaiting our response.</p> + + <p>To accept the call, use <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface.Group">AddMembers</tp:dbus-ref> + to move the local user to the group's members. To reject the call, use + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface.Group">RemoveMembersWithReason</tp:dbus-ref> + to remove the local member from the group, with an appropriate reason. + If the remote user ends the call before it is answered, this is + represented by <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface.Group">MembersChanged</tp:dbus-ref> + removing both parties from the group with the remote contact as the + <var>Actor</var>, and <var>Reason</var> set appropriately.</p> + + <p>Note that the call may end with the self handle as the + <var>Actor</var> without the user having chosen to reject the call, as + indicated by the nature of the <var>Reason</var>. Specifically, some + local component may time out the call (indicating this with reason + <code>No_Answer</code>; for example, the CM may have forwarded the call + to another number, as configured using <tp:dbus-ref + namespace='ofdT.Connection.Interface'>Forwarding.DRAFT</tp:dbus-ref>), + or something may have gone wrong with the call + (indicated by reason <code>Error</code>). Such calls SHOULD be + considered missed, just as if the remote contact had hung up before the + local user answered the call.</p> + + <tp:rationale> + <p>This is a bit awkward, but these are the best ways we can represent + these situations. It's important to document which calls should be + considered missed, to ensure that the user can be notified.</p> + </tp:rationale> + + <p>When the local user accepts an incoming call, the connection manager + SHOULD change the direction of any streams with pending local send + to be sending, without altering whether those streams are + receiving.</p> + + <tp:rationale> + <p>This matches existing practice, and means that a client + can answer incoming calls and get an unmuted microphone/activated + webcam without having to take additional action to accept the + stream directions.</p> + + <p>It does, however, introduce a race condition: a client believing + that it is accepting an audio-only call by calling AddMembers + can inadvertantly accept an audio + video call (and hence activate + sending from a webcam without the user's permission) if a video + stream is added just before AddMembers is processed. This race + should be removed when this specification is revised.</p> + </tp:rationale> + + <h4>During a call</h4> + + <p>If <tp:member-ref>ImmutableStreams</tp:member-ref> is + <code>False</code>, new streams may be requested using + <tp:member-ref>RequestStreams</tp:member-ref> (to add video to an + audio-only call, for instance), and existing streams may be removed using + <tp:member-ref>RemoveStreams</tp:member-ref> (for example, to downgrade + an audio-video call to audio-only). The call may be ended by calling + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface.Group">RemoveMembers</tp:dbus-ref> + or <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface.Group">RemoveMembersWithReason</tp:dbus-ref>; the call ending is signalled by the CM emitting <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface.Group">MembersChanged</tp:dbus-ref>, + removing both parties from the group.</p> + + <h4>Handler filters</h4> + + <p>For historical reasons, handlers must specify more than one filter if + they want to correctly advertise support for audio and/or video calls. If + they can handle channels using the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface">MediaSignalling</tp:dbus-ref> + interface, they should also advertise various + <tp:type>Handler_Capability_Token</tp:type>s to indicate which codecs and + transports they support. See <tp:member-ref>InitialAudio</tp:member-ref> + and <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface">MediaSignalling/video/h264</tp:dbus-ref> + for the gory details. In summary:</p> + + <dl> + <dt>To advertise support for streamed media in general, include the + following filter in <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client.Handler">HandlerChannelFilter</tp:dbus-ref>:</dt> + <dd><pre> +{ '...Channel.ChannelType': '...Channel.Type.StreamedMedia' , + '...Channel.TargetHandleType': Contact, +}</pre></dd> + + <dt>To advertise support for audio calls, also include the following + filter:</dt> + <dd><pre> +{ '...Channel.ChannelType': '...Channel.Type.StreamedMedia' , + '...Channel.TargetHandleType': Contact, + '...Channel.Type.StreamedMedia.InitialAudio': True, +}</pre></dd> + + <dt>To advertise support for video calls, also include the following + filter:</dt> + <dd><pre> +{ '...Channel.ChannelType': '...Channel.Type.StreamedMedia' , + '...Channel.TargetHandleType': Contact, + '...Channel.Type.StreamedMedia.InitialVideo': True, +}</pre></dd> + + <dt>If you use telepathy-farsight, and have H.264 support, you probably + want these <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client.Handler">Capabilities</tp:dbus-ref>:</dt> + <dd><pre> +[ "org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/ice-udp", + "org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/gtalk-p2p", + "org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/video/h264", +]</pre></dd> + </dl> + </tp:docstring> + + <tp:flags name="Channel_Media_Capabilities" value-prefix="Channel_Media_Capability" type="u"> + <tp:docstring> + The channel-type-specific capability flags used for + Channel.Type.StreamedMedia in the <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Connection.Interface.Capabilities</tp:dbus-ref> + interface. See the <tp:member-ref>InitialAudio</tp:member-ref> + property for details of the mechanisms that will replace this. + </tp:docstring> + <tp:flag suffix="Audio" value="1"> + <tp:docstring> + The handle is capable of using audio streams within a media channel. + </tp:docstring> + </tp:flag> + <tp:flag suffix="Video" value="2"> + <tp:docstring> + The handle is capable of using video streams within a media channel. + </tp:docstring> + </tp:flag> + <tp:flag suffix="NAT_Traversal_STUN" value="4"> + <tp:docstring> + The handle is capable of performing STUN to traverse NATs. + </tp:docstring> + </tp:flag> + <tp:flag suffix="NAT_Traversal_GTalk_P2P" value="8"> + <tp:docstring> + The handle is capable of establishing Google Talk peer-to-peer + connections (as implemented in libjingle 0.3) to traverse NATs. + </tp:docstring> + </tp:flag> + <tp:flag suffix="NAT_Traversal_ICE_UDP" value="16"> + <tp:docstring> + The handle is capable of establishing ICE UDP peer-to-peer + connections (as defined by the IETF MMUSIC working group) to traverse + NATs. + </tp:docstring> + </tp:flag> + + <tp:flag suffix="Immutable_Streams" value="32"> + <tp:docstring> + Channels whose target handle is this contact will have + <tp:member-ref>ImmutableStreams</tp:member-ref> = <tt>True</tt>. + </tp:docstring> + </tp:flag> + + </tp:flags> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> |