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, 0 insertions, 853 deletions
diff --git a/qt4/spec/Channel_Type_Streamed_Media.xml b/qt4/spec/Channel_Type_Streamed_Media.xml deleted file mode 100644 index aa2b90345..000000000 --- a/qt4/spec/Channel_Type_Streamed_Media.xml +++ /dev/null @@ -1,853 +0,0 @@ -<?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: --> |