diff options
Diffstat (limited to 'qt4/spec/Channel_Type_Call.xml')
| -rw-r--r-- | qt4/spec/Channel_Type_Call.xml | 1429 |
1 files changed, 0 insertions, 1429 deletions
diff --git a/qt4/spec/Channel_Type_Call.xml b/qt4/spec/Channel_Type_Call.xml deleted file mode 100644 index 045d41693..000000000 --- a/qt4/spec/Channel_Type_Call.xml +++ /dev/null @@ -1,1429 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Channel_Type_Call" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright>Copyright © 2009-2010 Collabora Limited</tp:copyright> - <tp:copyright>Copyright © 2009-2010 Nokia Corporation</tp:copyright> - <tp:license> - 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. - </tp:license> - <interface name="org.freedesktop.Telepathy.Channel.Type.Call.DRAFT" - tp:causes-havoc="experimental"> - <tp:added version="0.19.0">(draft 1)</tp:added> - - <tp:requires interface="org.freedesktop.Telepathy.Channel"/> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A channel type for making audio and video calls. Call - channels supersede the old <tp:dbus-ref - namespace="ofdT.Channel.Type">StreamedMedia</tp:dbus-ref> - channel type. Call channels are much more flexible than its - predecessor and allow more than two participants.</p> - - <p>Handlers are advised against executing all the media - signalling, codec and candidate negotiation themselves but - instead use a helper library such as <a - href="http://telepathy.freedesktop.org/doc/telepathy-farstream/">telepathy-farstream</a> - which when given a new Call channel will set up the - transports and codecs and create GStreamer pads which - can be added to the handler UI. This is useful as it means - the handler does not have to worry how exactly the - connection between the call participants is being made.</p> - - <p>The <tp:dbus-ref - namespace="ofdT.Channel">TargetHandle</tp:dbus-ref> and - <tp:dbus-ref namespace="ofdT.Channel">TargetID</tp:dbus-ref> - properties in a Call channel refer to the contact that the - user initially called, or which contact initially called the - user. Even in a conference call, where there are multiple - contacts in the call, these properties refer to the - initial contact, who might have left the conference since - then. As a result, handlers should not rely on these - properties.</p> - - <h4>Contents</h4> - - <p><tp:dbus-ref namespace="ofdT.Call">Content.DRAFT</tp:dbus-ref> - objects represent the actual media that forms the Call (for - example an audio content and a video content). Calls always - have one or more Content objects associated with them. As a - result, a new Call channel request MUST have either - <tp:member-ref>InitialAudio</tp:member-ref>=True, or - <tp:member-ref>InitialVideo</tp:member-ref>=True, or both, - as the Requestable Channel Classes will document.</p> - - <p><tp:dbus-ref - namespace="ofdT.Call">Content.DRAFT</tp:dbus-ref> objects have - one or more stream associated with them. More information on - these streams and how to maniuplate them can be found on the - <tp:dbus-ref namespace="ofdT.Call">Content.DRAFT</tp:dbus-ref> - interface page.</p> - - <h4>Outgoing calls</h4> - - <p>To make an audio-only call to a contact <tt>foo@example.com</tt> - handlers should call:</p> - - <blockquote> - <pre> -<tp:dbus-ref namespace="ofdT.Connection.Interface.Requests">CreateChannel</tp:dbus-ref>({ - ...<tp:dbus-ref namespace="ofdT.Channel">ChannelType</tp:dbus-ref>: ...<tp:dbus-ref - namespace="ofdT.Channel.Type">Call.DRAFT</tp:dbus-ref>, - ...<tp:dbus-ref namespace="ofdT.Channel">TargetHandleType</tp:dbus-ref>: Contact, - ...<tp:dbus-ref namespace="ofdT.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="ofdT.Channel">TargetHandle</tp:dbus-ref> may be used - in place of - <tp:dbus-ref namespace="ofdT.Channel">TargetID</tp:dbus-ref> - if the contact's handle is already known. To make an audio - and video call, the handler 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 the call is outgoing).</p> - - <p>After a new Call channel is requested, the - <tp:member-ref>CallState</tp:member-ref> property will be - <tp:type>Call_State</tp:type>_Pending_Initiator. As the local - user is the initiator, the call must be accepted by the handler - by calling the <tp:member-ref>Accept</tp:member-ref> method. - At this point, <tp:member-ref>CallState</tp:member-ref> changes - to <tp:type>Call_State</tp:type>_Pending_Receiver which signifies - that the call is ringing, waiting for the remote contact to - accept the call. All changes to - <tp:member-ref>CallState</tp:member-ref> property are signalled - using the <tp:member-ref>CallStateChanged</tp:member-ref> - signal.</p> - - <p>When the call is accepted by the remote contact, the - <tp:member-ref>CallStateChanged</tp:member-ref> signal fires - again to show that <tp:member-ref>CallState</tp:member-ref> = - <tp:type>Call_State</tp:type>_Accepted.</p> - - <p>At this point <a - href="http://telepathy.freedesktop.org/doc/telepathy-farstream/">telepathy-farstream</a> - will signal that a pad is available for the handler to show - in the user interface.</p> - - <h5>Missed calls</h5> - - <p>If the remote contact does not accept the call in time, then - the call can be terminated by the server. Note that this only - happens in some protocols. Most XMPP clients, for example, do - not do this and rely on the call initiator terminating the call. - A missed call is shown in a Call channel by the - <tp:member-ref>CallState</tp:member-ref> property changing to - <tp:type>Call_State</tp:type>_Ended, and the - <tp:member-ref>CallStateReason</tp:member-ref> property changing - to (remote contact, - <tp:type>Call_State_Change_Reason</tp:type>_No_Answer, "").</p> - - <h5>Rejected calls</h5> - - <p>If the remote contact decides he or she does not feel like - talking to the local user, he or she can reject his or her - incoming call. This will be shown in the Call channel by - <tp:member-ref>CallState</tp:member-ref> changing to - <tp:type>Call_State</tp:type>_Ended and the - <tp:member-ref>CallStateReason</tp:member-ref> property - changing to (remote contact, - <tp:type>Call_State</tp:type>_Change_Reason_User_Requested, - "org.freedesktop.Telepathy.Error.Rejected").</p> - - <h4>Incoming calls</h4> - - <p>When an incoming call occurs, something like the following - <tp:dbus-ref - namespace="ofdT.Connection.Interface.Requests">NewChannels</tp:dbus-ref> - signal will occur:</p> - - <blockquote> - <pre> -<tp:dbus-ref namespace="ofdT.Connection.Interface.Requests">NewChannels</tp:dbus-ref>([ - /org/freedesktop/Telepathy/Connection/foo/bar/foo_40bar_2ecom/CallChannel, - { - ...<tp:dbus-ref namespace="ofdT.Channel">ChannelType</tp:dbus-ref>: ...<tp:dbus-ref - namespace="ofdT.Channel.Type">Call.DRAFT</tp:dbus-ref>, - ...<tp:dbus-ref namespace="ofdT.Channel">TargetHandleType</tp:dbus-ref>: Contact, - ...<tp:dbus-ref namespace="ofdT.Channel">TargetID</tp:dbus-ref>: 'foo@example.com', - ...<tp:dbus-ref namespace="ofdT.Channel">TargetHandle</tp:dbus-ref>: 42, - ...<tp:dbus-ref namespace="ofdT.Channel">Requested</tp:dbus-ref>: False, - ...<tp:member-ref>InitialAudio</tp:member-ref>: True, - ...<tp:member-ref>InitialVideo</tp:member-ref>: True, - ...<tp:member-ref>InitialAudioName</tp:member-ref>: "audio", - ...<tp:member-ref>InitialVideoName</tp:member-ref>: "video", - ...<tp:member-ref>MutableContents</tp:member-ref>: True, - }])</pre></blockquote> - - <p>The <tp:member-ref>InitialAudio</tp:member-ref> and - <tp:member-ref>InitialVideo</tp:member-ref> properties show that - the call has been started with two contents: one for audio - streaming and one for video streaming. The - <tp:member-ref>InitialAudioName</tp:member-ref> and - <tp:member-ref>InitialVideoName</tp:member-ref> properties also - show that the aforementioned audio and video contents have names - "audio" and "video".</p> - - <p>Once the handler has notified the local user that there is an - incoming call waiting for acceptance, the handler should call - <tp:member-ref>SetRinging</tp:member-ref> to let the CM know. - The new channel should also be given to telepathy-farstream to - work out how the two participants will connect together. - telepathy-farstream will call the appropriate methods on the call's - <tp:dbus-ref namespace="ofdT.Call">Content.DRAFT</tp:dbus-ref>s - to negotiate codecs and transports.</p> - - <p>To pick up the call, the handler should call - <tp:member-ref>Accept</tp:member-ref>. The - <tp:member-ref>CallState</tp:member-ref> property changes to - <tp:type>Call_State</tp:type>_Accepted and once media is - being transferred, telepathy-farstream will notify the - handler of a new pad to be shown to the local user in the - UI</p> - - <p>To reject the call, the handler should call the - <tp:member-ref>Hangup</tp:member-ref> method. The - <tp:member-ref>CallState</tp:member-ref> property will change to - <tp:type>Call_State</tp:type>_Ended and the - <tp:member-ref>CallStateReason</tp:member-ref> property will - change to (self handle, - <tp:type>Call_State_Change_Reason</tp:type>_User_Requested, - "org.freedesktop.Telepathy.Error.Rejected").</p> - - <h4>Ongoing calls</h4> - - <h5>Adding and removing contents</h5> - - <p>When a call is open, new contents can be added as long as the - CM supports it. The - <tp:member-ref>MutableContents</tp:member-ref> property will let - the handler know whether further contents can be added or - existing contents removed. An example of this is starting a - voice call between a contact and then adding a video content. - To do this, the should call - <tp:member-ref>AddContent</tp:member-ref> like this:</p> - - <blockquote> - <pre><tp:member-ref>AddContent</tp:member-ref>("video", - <tp:type>Media_Stream_Type</tp:type>_Video)</pre> - </blockquote> - - <p>Assuming no errors, the new video content will be added to - the call. telepathy-farstream will pick up the new content and - perform the transport and codec negotiation automatically. - telpathy-farstream will signal when the video is ready to - show in the handler's user interface.</p> - - <p>A similar method is used for removing contents from a call, - except that the <tp:dbus-ref - namespace="ofdT.Call.Content.DRAFT">Remove</tp:dbus-ref> method - is on the <tp:dbus-ref - namespace="ofdT.Call">Content.DRAFT</tp:dbus-ref> object.</p> - - <h5>Ending the call</h5> - - <p>To end the call, the handler should call the - <tp:member-ref>Hangup</tp:member-ref> method. The - <tp:member-ref>CallState</tp:member-ref> property will change to - <tp:type>Call_State</tp:type>_Ended and - <tp:member-ref>CallStateReason</tp:member-ref> will change - to (self handle, - <tp:type>Call_State_Change_Reason</tp:type>_User_Requested, - "org.freedesktop.Telepathy.Error.Cancelled").</p> - - <p>If the other participant hangs up first then the - <tp:member-ref>CallState</tp:member-ref> property will change to - <tp:type>Call_State</tp:type>_Ended and - <tp:member-ref>CallStateReason</tp:member-ref> will change - to (remote contact, - <tp:type>Call_State_Change_Reason</tp:type>_User_Requested, - "org.freedesktop.Telepathy.Error.Terminated").</p> - - <h4>Multi-party calls</h4> - - [TODO] - - <h4>Call states</h4> - - <p>There are many combinations of the - <tp:member-ref>CallState</tp:member-ref> and - <tp:member-ref>CallStateReason</tp:member-ref> properties which - mean different things. Here is a table to try to make these - meanings clearer:</p> - - <table> - <tr> - <th rowspan="2"><tp:dbus-ref namespace="ofdT.Channel">Requested</tp:dbus-ref></th> - <th rowspan="2"><tp:member-ref>CallState</tp:member-ref></th> - <th colspan="3"><tp:member-ref>CallStateReason</tp:member-ref></th> - <th rowspan="2">Meaning</th> - </tr> - <tr> - <th>Actor</th> - <th>Reason</th> - <th>DBus_Reason</th> - </tr> - <!-- Pending_Initiator --> - <tr> - <td>True</td> - <td><tp:type>Call_State</tp:type>_Pending_Initiator</td> - <td>Self handle</td> - <td><tp:type>Call_State_Change_Reason</tp:type>_User_Requested</td> - <td>""</td> - <td>The outgoing call channel is waiting for the local user to call <tp:member-ref>Accept</tp:member-ref>.</td> - </tr> - <!-- Pending_Receiver --> - <tr> - <td>True</td> - <td><tp:type>Call_State</tp:type>_Pending_Receiver</td> - <td>Self handle</td> - <td><tp:type>Call_State_Change_Reason</tp:type>_User_Requested</td> - <td>""</td> - <td>The outgoing call is waiting for the remote contact to pick up the call.</td> - </tr> - <tr> - <td>False</td> - <td><tp:type>Call_State</tp:type>_Pending_Receiver</td> - <td>0</td> - <td><tp:type>Call_State_Change_Reason</tp:type>_Unknown</td> - <td>""</td> - <td>The incoming call is waiting for the local user to call <tp:member-ref>Accept</tp:member-ref> on the call.</td> - </tr> - <!-- Accepted --> - <tr> - <td>True</td> - <td><tp:type>Call_State</tp:type>_Accepted</td> - <td>Remote contact handle</td> - <td><tp:type>Call_State_Change_Reason</tp:type>_User_Requested</td> - <td>""</td> - <td>The remote contact accepted the outgoing call.</td> - </tr> - <tr> - <td>False</td> - <td><tp:type>Call_State</tp:type>_Accepted</td> - <td>Self handle</td> - <td><tp:type>Call_State_Change_Reason</tp:type>_User_Requested</td> - <td>""</td> - <td>The local user accepted the incoming call.</td> - </tr> - <!-- Ended --> - <tr> - <td>True or False</td> - <td><tp:type>Call_State</tp:type>_Ended</td> - <td>Self handle</td> - <td><tp:type>Call_State_Change_Reason</tp:type>_User_Requested</td> - <td><tp:error-ref>Cancelled</tp:error-ref></td> - <td>The local user hung up the incoming or outgoing call.</td> - </tr> - <tr> - <td>True or False</td> - <td><tp:type>Call_State</tp:type>_Ended</td> - <td>Remote contact handle</td> - <td><tp:type>Call_State_Change_Reason</tp:type>_User_Requested</td> - <td><tp:error-ref>Terminated</tp:error-ref></td> - <td>The remote contact hung up the incoming or outgoing call.</td> - </tr> - <tr> - <td>True</td> - <td><tp:type>Call_State</tp:type>_Ended</td> - <td>Remote contact handle</td> - <td><tp:type>Call_State_Change_Reason</tp:type>_No_Answer</td> - <td>""</td> - <td>The outgoing call was not picked up and the call ended.</td> - </tr> - <tr> - <td>False</td> - <td><tp:type>Call_State</tp:type>_Ended</td> - <td>Remote contact handle</td> - <td><tp:type>Call_State_Change_Reason</tp:type>_User_Requested</td> - <td><tp:error-ref>PickedUpElsewhere</tp:error-ref></td> - <td>The incoming call was ended because it was picked up elsewhere.</td> - </tr> - </table> - - <h4>Requestable channel classes</h4> - - <p>The <tp:dbus-ref - namespace="ofdT.Connection.Interface.Requests">RequestableChannelClasses</tp:dbus-ref> - for <tp:dbus-ref - namespace="ofdT.Channel.Type">Call.DRAFT</tp:dbus-ref> channels - can be:</p> - - <blockquote> - <pre> -[( Fixed = { ...<tp:dbus-ref namespace="ofdT.Channel">ChannelType</tp:dbus-ref>: ...<tp:dbus-ref namespace="ofdT.Channel.Type">Call.DRAFT</tp:dbus-ref>, - ...<tp:dbus-ref namespace="ofdT.Channel">TargetHandleType</tp:dbus-ref>: Contact, - ...<tp:member-ref>InitialVideo</tp:member-ref>: True - }, - Allowed = [ ...<tp:member-ref>InitialVideoName</tp:member-ref>, - ...<tp:member-ref>InitialAudio</tp:member-ref>, - ...<tp:member-ref>InitialAudioName</tp:member-ref> - ] -), -( Fixed = { ...<tp:dbus-ref namespace="ofdT.Channel">ChannelType</tp:dbus-ref>: ...<tp:dbus-ref namespace="ofdT.Channel.Type">Call.DRAFT</tp:dbus-ref>, - ...<tp:dbus-ref namespace="ofdT.Channel">TargetHandleType</tp:dbus-ref>: Contact, - ...<tp:member-ref>InitialAudio</tp:member-ref>: True - }, - Allowed = [ ...<tp:member-ref>InitialAudioName</tp:member-ref>, - ...<tp:member-ref>InitialVideo</tp:member-ref>, - ...<tp:member-ref>InitialVideoName</tp:member-ref> - ] -)]</pre></blockquote> - - <p>Clients aren't allowed to make outgoing calls that have - neither initial audio nor initial video. Clearly, CMs - which don't support video should leave out the first class and - omit <tp:member-ref>InitialVideo</tp:member-ref> from the second - class, and vice versa for CMs without audio support.</p> - - <p>Handlers should not close <tp:dbus-ref - namespace="ofdT.Channel.Type">Call.DRAFT</tp:dbus-ref> channels - without first calling <tp:member-ref>Hangup</tp:member-ref> on - the channel. If a Call handler crashes, the <tp:dbus-ref - namespace="ofdT">ChannelDispatcher</tp:dbus-ref> will call - <tp:dbus-ref namespace="ofdT.Channel">Close</tp:dbus-ref> on the - channel which SHOULD also imply a call to - <tp:member-ref>Hangup</tp:member-ref>(<tp:type>Call_State_Change_Reason</tp:type>_User_Requested, - "org.freedesktop.Telepathy.Error.Terminated", "") before - actually closing the channel.</p> - - </tp:docstring> - - <method name="SetRinging" tp:name-for-bindings="Set_Ringing"> - <tp:changed version="0.21.2">renamed from Ringing</tp:changed> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Indicate that the local user has been alerted about the incoming - call.</p> - - <p>This method is only useful if the - channel's <tp:dbus-ref namespace="ofdT.Channel">Requested</tp:dbus-ref> - property is False, and - the <tp:member-ref>CallState</tp:member-ref> is - <tp:type>Call_State</tp:type>_Pending_Receiver (an incoming - call waiting on the local user to pick up). While this is - the case, this method SHOULD change the - <tp:member-ref>CallFlags</tp:member-ref> to include - <tp:type>Call_Flags</tp:type>_Locally_Ringing, and notify the - remote contact that the local user has been alerted (if the - protocol implements this); repeated calls to this method - SHOULD succeed, but have no further effect.</p> - - <p>In all other states, this method SHOULD fail with the error - NotAvailable.</p> - </tp:docstring> - - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> - <tp:docstring> - The call was <tp:dbus-ref namespace="ofdT.Channel" - >Requested</tp:dbus-ref>, so ringing does not make sense. - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> - <tp:docstring> - The call is no longer in state - <tp:type>Call_State</tp:type>_Pending_Receiver. - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - <method name="Accept" tp:name-for-bindings="Accept"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>For incoming calls in state - <tp:type>Call_State</tp:type>_Pending_Receiver, accept the - incoming call; this changes the - <tp:member-ref>CallState</tp:member-ref> to - <tp:type>Call_State</tp:type>_Accepted.</p> - - <p>For outgoing calls in state - <tp:type>Call_State</tp:type>_Pending_Initiator, actually - call the remote contact; this changes the - <tp:member-ref>CallState</tp:member-ref> to - <tp:type>Call_State</tp:type>_Pending_Receiver.</p> - - <p>Otherwise, this method SHOULD fail with the error NotAvailable.</p> - - <p>This method should be called exactly once per Call, by whatever - client (user interface) is handling the channel.</p> - - <p>When this method is called, for each <tp:dbus-ref - namespace="ofdT.Call" >Content.DRAFT</tp:dbus-ref> whose - <tp:dbus-ref namespace="ofdT.Call.Content.DRAFT" - >Disposition</tp:dbus-ref> is - <tp:type>Call_Content_Disposition</tp:type>_Initial, any - streams where the <tp:dbus-ref - namespace="ofdT.Call.Stream.DRAFT">LocalSendingState</tp:dbus-ref> - is <tp:type>Sending_State</tp:type>_Pending_Send will be - moved to <tp:type>Sending_State</tp:type>_Sending as if - <tp:dbus-ref namespace="ofdT.Call.Stream.DRAFT" - >SetSending</tp:dbus-ref>(True) had been called.</p> - </tp:docstring> - - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> - <tp:docstring> - The call is not in one of the states where this method makes sense. - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - <method name="Hangup" tp:name-for-bindings="Hangup"> - <tp:docstring> - Request that the call is ended. All contents will be removed - from the Call so that the - <tp:member-ref>Contents</tp:member-ref> property will be the - empty list. - </tp:docstring> - - <arg direction="in" name="Reason" - type="u" tp:type="Call_State_Change_Reason"> - <tp:docstring> - A generic hangup reason. - </tp:docstring> - </arg> - - <arg direction="in" name="Detailed_Hangup_Reason" - type="s" tp:type="DBus_Error_Name"> - <tp:docstring> - A more specific reason for the call hangup, if one is available, or - an empty string otherwise. - </tp:docstring> - </arg> - - <arg direction="in" name="Message" type="s"> - <tp:docstring> - A human-readable message to be sent to the remote contact(s). - - <tp:rationale> - XMPP Jingle allows calls to be terminated with a human-readable - message. - </tp:rationale> - </tp:docstring> - </arg> - - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> - <tp:docstring> - The call has already been ended. - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - <method name="AddContent" tp:name-for-bindings="Add_Content"> - <tp:docstring> - Request that a new <tp:dbus-ref - namespace="ofdT.Call">Content.DRAFT</tp:dbus-ref> of type - Content_Type is added to the Call. Handlers should check the - value of the <tp:member-ref>MutableContents</tp:member-ref> - property before trying to add another content as it might not - be allowed. - </tp:docstring> - <arg direction="in" name="Content_Name" type="s"> - <tp:docstring> - <p>The suggested name of the content to add.</p> - - <tp:rationale> - The content name property should be meaningful, so should - be given a name which is significant to the user. The name - could be a localized "audio", "video" or perhaps include - some string identifying the source, such as a webcam - identifier. - </tp:rationale> - - <p>If there is already a content with the same name as this - property then a sensible suffix should be added. For example, - if this argument is "audio" but a content of the same name - already exists, a sensible suffix such as " (1)" is appended - to name the new content "audio (1)". A further content with the - name "audio" would then be named "audio (2)".</p> - - </tp:docstring> - </arg> - <arg direction="in" name="Content_Type" type="u" - tp:type="Media_Stream_Type"> - <tp:docstring> - The media stream type of the content to be added to the - call. - </tp:docstring> - </arg> - <arg direction="out" name="Content" type="o"> - <tp:docstring> - Path to the newly-created <tp:dbus-ref - namespace="org.freedesktop.Telepathy" - >Call.Content.DRAFT</tp:dbus-ref> object. - </tp:docstring> - </arg> - - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> - <tp:docstring> - The media stream type given is invalid. - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> - <tp:docstring> - The media stream type requested is not implemented by the - CM. - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.NotCapable"> - <tp:docstring> - The content type requested cannot be added to this - call. Examples of why this might be the case include - because a second video stream cannot be added, or a - content cannot be added when the content set isn't - mutable. - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - <signal name="ContentAdded" - tp:name-for-bindings="Content_Added"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Emitted when a new <tp:dbus-ref namespace="ofdT.Call" - >Content.DRAFT</tp:dbus-ref> is added to the call.</p> - </tp:docstring> - <arg name="Content" type="o"> - <tp:docstring> - Path to the newly-created <tp:dbus-ref namespace="ofdT.Call" - >Content.DRAFT</tp:dbus-ref> object. - </tp:docstring> - </arg> - </signal> - - <signal name="ContentRemoved" tp:name-for-bindings="Content_Removed"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Emitted when a <tp:dbus-ref namespace="ofdT.Call" - >Content.DRAFT</tp:dbus-ref> is removed from the call.</p> - </tp:docstring> - <arg name="Content" type="o"> - <tp:docstring> - The <tp:dbus-ref namespace="ofdT.Call" - >Content.DRAFT</tp:dbus-ref> which was removed. - </tp:docstring> - </arg> - </signal> - - <property name="Contents" type="ao" access="read" - tp:name-for-bindings="Contents"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The list of <tp:dbus-ref - namespace="ofdT.Call">Content.DRAFT</tp:dbus-ref> objects that - are part of this call. Change notification is via the - <tp:member-ref>ContentAdded</tp:member-ref> and - <tp:member-ref>ContentRemoved</tp:member-ref> signals. - </p> - </tp:docstring> - </property> - - <tp:enum type="u" name="Call_State"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The state of a call, as a whole.</p> - - <p>The allowed transitions are:</p> - - <ul> - <li>Pending_Initiator → Pending_Receiver (for outgoing calls, - when <tp:member-ref>Accept</tp:member-ref> is called)</li> - <li>Pending_Receiver → Accepted (for incoming calls, when - <tp:member-ref>Accept</tp:member-ref> is called; for outgoing - calls to a contact, when the remote contact accepts the call; - for joining a conference call, when the local user successfully - joins the conference)</li> - <li>Accepted → Pending_Receiver (when transferred to another - contact)</li> - <li>any state → Ended (when the call is terminated normally, or - when an error occurs)</li> - </ul> - - <p>Clients MAY consider unknown values from this enum to be an - error - additional values will not be defined after the Call - specification is declared to be stable.</p> - </tp:docstring> - - <tp:enumvalue suffix="Unknown" value = "0"> - <tp:docstring> - The call state is not known. This call state MUST NOT appear as a - value of the <tp:member-ref>CallState</tp:member-ref> property, but - MAY be used by client code to represent calls whose state is as yet - unknown. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Pending_Initiator" value = "1"> - <tp:docstring> - The initiator of the call hasn't accepted the call yet. This state - only makes sense for outgoing calls, where it means that the local - user has not yet sent any signalling messages to the remote user(s), - and will not do so until <tp:member-ref>Accept</tp:member-ref> is - called. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Pending_Receiver" value = "2"> - <tp:docstring> - The receiver (the contact being called) hasn't accepted the call yet. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Accepted" value = "3"> - <tp:docstring> - The contact being called has accepted the call. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Ended" value = "4"> - <tp:docstring> - The call has ended, either via normal termination or an error. - </tp:docstring> - </tp:enumvalue> - </tp:enum> - - <tp:flags name="Call_Flags" value-prefix="Call_Flag" type="u"> - <tp:docstring> - A set of flags representing the status of the call as a whole, - providing more specific information than the - <tp:member-ref>CallState</tp:member-ref>. Many of these flags only make - sense in a particular state. - </tp:docstring> - - <tp:flag suffix="Locally_Ringing" value="1"> - <tp:docstring> - The local contact has been alerted about the call but has not - responded; if possible, the remote contact(s) have been informed of - this fact. This flag only makes sense on incoming calls in - state <tp:type>Call_State</tp:type>_Pending_Receiver. It SHOULD - be set when <tp:member-ref>SetRinging</tp:member-ref> is - called successfully, and unset when the state changes. - </tp:docstring> - </tp:flag> - - <tp:flag suffix="Queued" value="2"> - <tp:docstring> - The contact is temporarily unavailable, and the call has been placed - in a queue (e.g. 182 Queued in SIP, or call-waiting in telephony). - This flag only makes sense on outgoing 1-1 calls in - state <tp:type>Call_State</tp:type>_Pending_Receiver. It SHOULD be - set or unset according to informational messages from other - contacts. - </tp:docstring> - </tp:flag> - - <tp:flag suffix="Locally_Held" value="4"> - <tp:docstring> - The call has been put on hold by the local user, e.g. using - the <tp:dbus-ref namespace="ofdT.Channel.Interface" - >Hold</tp:dbus-ref> interface. This flag SHOULD only be set - if there is at least one Content, and all Contents are - locally held; it makes sense on calls in state - <tp:type>Call_State</tp:type>_Pending_Receiver - or <tp:type>Call_State</tp:type>_Accepted. - - <tp:rationale> - Otherwise, in transient situations where some but not all contents - are on hold, UIs would falsely indicate that the call as a whole - is on hold, which could lead to the user saying something they'll - regret, while under the impression that the other contacts can't - hear them! - </tp:rationale> - </tp:docstring> - </tp:flag> - - <tp:flag suffix="Forwarded" value="8"> - <tp:docstring> - The initiator of the call originally called a contact other than the - current recipient of the call, but the call was then forwarded or - diverted. This flag only makes sense on outgoing calls, in state - <tp:type>Call_State</tp:type>_Pending_Receiver or - <tp:type>Call_State</tp:type>_Accepted. It SHOULD be set or unset - according to informational messages from other contacts. - </tp:docstring> - </tp:flag> - - <tp:flag suffix="In_Progress" value="16"> - <tp:docstring> - Progress has been made in placing the outgoing call, but the - contact may not have been made aware of the call yet - (so the Ringing state is not appropriate). This corresponds to SIP's - status code 183 Session Progress, and could be used when the - outgoing call has reached a gateway, for instance. - This flag only makes sense on outgoing calls in state - <tp:type>Call_State</tp:type>_Pending_Receiver, and SHOULD be set - or unset according to informational messages from servers, gateways - and other infrastructure. - </tp:docstring> - </tp:flag> - - <tp:flag suffix="Clearing" value="32"> - <tp:docstring> - This flag only occurs when the CallState is Ended. The call with - this flag set has ended, but not all resources corresponding to the - call have been freed yet. - - Depending on the protocol there might be some audible feedback while - the clearing flag is set. - - <tp:rationale> - In calls following the ITU-T Q.931 standard there is a period of - time between the call ending and the underlying channel being - completely free for re-use. - </tp:rationale> - </tp:docstring> - </tp:flag> - - <tp:flag suffix="Muted" value="64"> - <tp:docstring> - The call has been muted by the local user, e.g. using the - <tp:dbus-ref namespace="ofdT.Call.Content.Interface" - >Mute.DRAFT</tp:dbus-ref> interface. This flag SHOULD only - be set if there is at least one Content, and all Contents - are locally muted; it makes sense on calls in state - <tp:type>Call_State</tp:type>_Pending_Receiver or - <tp:type>Call_State</tp:type>_Accepted. - </tp:docstring> - </tp:flag> - </tp:flags> - - <property name="CallStateDetails" - tp:name-for-bindings="Call_State_Details" type="a{sv}" access="read"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A map used to provide optional extensible details for the - <tp:member-ref>CallState</tp:member-ref>, - <tp:member-ref>CallFlags</tp:member-ref> and/or - <tp:member-ref>CallStateReason</tp:member-ref>.</p> - - <p>Well-known keys and their corresponding value types include:</p> - - <dl> - <dt>hangup-message - s</dt> - <dd>An optional human-readable message sent when the call was ended, - corresponding to the Message argument to the - <tp:member-ref>Hangup</tp:member-ref> method. This is only - applicable when the call state is <tp:type>Call_State</tp:type>_Ended. - <tp:rationale> - XMPP Jingle can send such messages. - </tp:rationale> - </dd> - - <dt>queue-message - s</dt> - <dd>An optional human-readable message sent when the local contact - is being held in a queue. This is only applicable when - <tp:type>Call_Flags</tp:type>_Queued is in the call flags. - <tp:rationale> - SIP 182 notifications can have human-readable messages attached. - </tp:rationale> - </dd> - - <dt>debug-message - s</dt> - <dd>A message giving further details of any error indicated by the - <tp:member-ref>CallStateReason</tp:member-ref>. This will not - normally be localized or suitable for display to users, and is only - applicable when the call state is - <tp:type>Call_State</tp:type>_Ended.</dd> - </dl> - </tp:docstring> - </property> - - <property name="CallState" type="u" access="read" - tp:name-for-bindings="Call_State" tp:type="Call_State"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The current high-level state of this call. The - <tp:member-ref>CallFlags</tp:member-ref> provide additional - information, and the <tp:member-ref>CallStateReason</tp:member-ref> - and <tp:member-ref>CallStateDetails</tp:member-ref> explain the - reason for the current values for those properties.</p> - - <p>Note that when in a conference call, this property is - purely to show your state in joining the call. The receiver - (or remote contact) in this context is the conference server - itself. The property does not change when other call members' - states change.</p> - - <p>Clients MAY consider unknown values in this property to be an - error.</p> - </tp:docstring> - </property> - - <property name="CallFlags" type="u" access="read" - tp:name-for-bindings="Call_Flags" tp:type="Call_Flags"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Flags representing the status of the call as a whole, - providing more specific information than the - <tp:member-ref>CallState</tp:member-ref>.</p> - - <p>Clients are expected to ignore unknown flags in this property, - without error.</p> - - <p>When an ongoing call is active and not on hold or has any - other problems, this property will be 0.</p> - </tp:docstring> - </property> - - <tp:enum name="Call_State_Change_Reason" type="u"> - <tp:docstring> - A simple representation of the reason for a change in the call's - state, which may be used by simple clients, or used as a fallback - when the DBus_Reason member of a <tp:type>Call_State_Reason</tp:type> - struct is not understood. - </tp:docstring> - - <tp:enumvalue suffix="Unknown" value="0"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - We just don't know. Unknown values of this enum SHOULD also be - treated like this. - </tp:docstring> - </tp:enumvalue> - - <tp:enumvalue suffix="User_Requested" value="1"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The change was requested by the contact indicated by the Actor - member of a <tp:type>Call_State_Reason</tp:type> struct.</p> - - <p>If the Actor is the local user, the DBus_Reason SHOULD be the - empty string.</p> - - <p>If the Actor is a remote user, the DBus_Reason SHOULD be the empty - string if the call was terminated normally, but MAY be a non-empty - error name to indicate error-like call termination reasons (call - rejected as busy, kicked from a conference by a moderator, etc.).</p> - </tp:docstring> - </tp:enumvalue> - - <tp:enumvalue suffix="Forwarded" value="2"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The call was forwarded. If known, the handle of the contact - the call was forwarded to will be indicated by the Actor member - of a <tp:type>Call_State_Reason</tp:type> struct.</p> - </tp:docstring> - </tp:enumvalue> - - <tp:enumvalue suffix="No_Answer" value="3"> - <tp:added version="0.21.2"/> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The <tp:member-ref>CallState</tp:member-ref> changed from - <tp:type>Call_State</tp:type>_Pending_Receiver to - <tp:type>Call_State</tp:type>_Ended because the initiator - ended the call before the receiver accepted it. With an - incoming call this state change reason signifies a missed - call.</p> - </tp:docstring> - </tp:enumvalue> - </tp:enum> - - <tp:struct name="Call_State_Reason"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A description of the reason for a change to the - <tp:member-ref>CallState</tp:member-ref> and/or - <tp:member-ref>CallFlags</tp:member-ref>.</p> - </tp:docstring> - - <tp:member type="u" tp:type="Contact_Handle" name="Actor"> - <tp:docstring> - The contact responsible for the change, or 0 if no contact was - responsible. - </tp:docstring> - </tp:member> - - <tp:member type="u" tp:type="Call_State_Change_Reason" name="Reason"> - <tp:docstring> - The reason, chosen from a limited set of possibilities defined by - the Telepathy specification. If - <tp:type>Call_State_Change_Reason</tp:type>_User_Requested then - the Actor member will dictate whether it was the local user or - a remote contact responsible. - </tp:docstring> - </tp:member> - - <tp:member type="s" tp:type="DBus_Error_Name" name="DBus_Reason"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A specific reason for the change, which may be a D-Bus error in - the Telepathy namespace, a D-Bus error in any other namespace - (for implementation-specific errors), or the empty string to - indicate that the state change was not an error.</p> - - <p>This SHOULD be an empty string for changes to any state other - than Ended.</p> - - <p>The errors Cancelled and Terminated SHOULD NOT be used here; - an empty string SHOULD be used instead.</p> - - <tp:rationale> - <p>Those error names are used to indicate normal call - termination by the local user or another user, respectively, - in contexts where a D-Bus error name must appear.</p> - </tp:rationale> - </tp:docstring> - </tp:member> - </tp:struct> - - <property name="CallStateReason" tp:name-for-bindings="Call_State_Reason" - type="(uus)" access="read" tp:type="Call_State_Reason"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The reason for the last change to the - <tp:member-ref>CallState</tp:member-ref> and/or - <tp:member-ref>CallFlags</tp:member-ref>. The - <tp:member-ref>CallStateDetails</tp:member-ref> MAY provide additional - information.</p> - </tp:docstring> - </property> - - <signal name="CallStateChanged" - tp:name-for-bindings="Call_State_Changed"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Emitted when the state of the call as a whole changes.</p> - - <p>This signal is emitted for any change in the properties - corresponding to its arguments, even if the other properties - referenced remain unchanged.</p> - </tp:docstring> - - <arg name="Call_State" type="u" tp:type="Call_State"> - <tp:docstring> - The new value of the <tp:member-ref>CallState</tp:member-ref> - property. - </tp:docstring> - </arg> - - <arg name="Call_Flags" type="u" tp:type="Call_Flags"> - <tp:docstring> - The new value of the <tp:member-ref>CallFlags</tp:member-ref> - property. - </tp:docstring> - </arg> - - <arg name="Call_State_Reason" type="(uus)" tp:type="Call_State_Reason"> - <tp:docstring> - The new value of the <tp:member-ref>CallStateReason</tp:member-ref> - property. - </tp:docstring> - </arg> - - <arg name="Call_State_Details" type="a{sv}"> - <tp:docstring> - The new value of the <tp:member-ref>CallStateDetails</tp:member-ref> - property. - </tp:docstring> - </arg> - </signal> - - <property name="HardwareStreaming" tp:name-for-bindings="Hardware_Streaming" - type="b" access="read" tp:immutable="yes"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>If this property is True, all of the media streaming is done by some - mechanism outside the scope of Telepathy.</p> - - <tp:rationale> - <p>A connection manager might be intended for a specialized hardware - device, which will take care of the audio streaming (e.g. - telepathy-yafono, which uses GSM hardware which does the actual - audio streaming for the call).</p> - </tp:rationale> - - <p>If this is False, the handler is responsible for doing the actual - media streaming for at least some contents itself. Those contents - will have the <tp:dbus-ref namespace="ofdT.Call.Content.Interface" - >Media.DRAFT</tp:dbus-ref> interface, to communicate the necessary - information to a streaming implementation. Connection managers SHOULD - operate like this, if possible.</p> - - <tp:rationale> - <p>Many connection managers (such as telepathy-gabble) only do the - call signalling, and expect the client to do the actual streaming - using something like - <a href="http://farsight.freedesktop.org/">Farsight</a>, to improve - latency and allow better UI integration.</p> - </tp:rationale> - </tp:docstring> - </property> - - <tp:flags type="u" name="Call_Member_Flags" value-prefix="Call_Member_Flag"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A set of flags representing the status of a remote contact in a - call.</p> - - <p>It is protocol- and client-specific whether a particular contact - will ever have a particular flag set on them, and Telepathy clients - SHOULD NOT assume that a flag will ever be set.</p> - - <tp:rationale> - <p>180 Ringing in SIP, and its equivalent in XMPP, are optional - informational messages, and implementations are not required - to send them. The same applies to the messages used to indicate - hold state.</p> - </tp:rationale> - </tp:docstring> - - <tp:flag suffix="Ringing" value = "1"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The remote contact's client has told us that the contact has been - alerted about the call but has not responded.</p> - - <tp:rationale> - <p>This is a flag per member, not a flag for the call as a whole, - because in Muji conference calls, you could invite someone and - have their state be "ringing" for a while.</p> - </tp:rationale> - </tp:docstring> - </tp:flag> - - <tp:flag suffix="Held" value = "2"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The call member has put this call on hold.</p> - - <tp:rationale> - <p>This is a flag per member, not a flag for the call as a whole, - because in conference calls, any member could put the conference - on hold.</p> - </tp:rationale> - </tp:docstring> - </tp:flag> - - <tp:flag suffix="Conference_Host" value="4"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - This contact has merged this call into a conference. Note that GSM - provides a notification when the remote party merges a call into a - conference, but not when it is split out again; thus, this flag can - only indicate that the call has been part of a conference at some - point. If a GSM connection manager receives a notification that a - call has been merged into a conference a second time, it SHOULD - represent this by clearing and immediately re-setting this flag on - the remote contact. - </tp:docstring> - </tp:flag> - </tp:flags> - - <tp:mapping name="Call_Member_Map" array-name="Call_Member_Map_List"> - <tp:docstring>A mapping from handles to their current state in the call. - </tp:docstring> - <tp:member type="u" tp:type="Handle" name="key"/> - <tp:member type="u" tp:type="Call_Member_Flags" name="Flag"/> - </tp:mapping> - - <signal name="CallMembersChanged" - tp:name-for-bindings="Call_Members_Changed"> - <tp:docstring> - Emitted when the <tp:member-ref>CallMembers</tp:member-ref> property - changes in any way, either because contacts have been added to the - call, contacts have been removed from the call, or contacts' flags - have changed. - </tp:docstring> - - <arg name="Flags_Changed" type="a{uu}" tp:type="Call_Member_Map"> - <tp:docstring> - A map from members of the call to their new call member flags, - including at least the members who have been added to - <tp:member-ref>CallMembers</tp:member-ref>, and the members whose - flags have changed. - </tp:docstring> - </arg> - <arg name="Removed" type="au" tp:type="Contact_Handle[]"> - <tp:docstring> - A list of members who have left the call, i.e. keys to be removed - from <tp:member-ref>CallMembers</tp:member-ref>. - </tp:docstring> - </arg> - </signal> - - <property name="CallMembers" tp:name-for-bindings="Call_Members" - type="a{uu}" access="read" tp:type="Call_Member_Map"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A mapping from the remote contacts that are part of this call to flags - describing their status. This mapping never has the local user's handle - as a key.</p> - - <p>When the call ends, this property should be an empty list, - and notified with - <tp:member-ref>CallMembersChanged</tp:member-ref></p> - - <p>If the Call implements - <tp:dbus-ref namespace="ofdT.Channel.Interface" - >Group</tp:dbus-ref> and the Group members are - channel-specific handles, then this call SHOULD also use - channel-specific handles.</p> - - <p>Anonymous members are exposed as channel-specific handles - with no owner.</p> - </tp:docstring> - </property> - - <property name="InitialTransport" tp:name-for-bindings="Initial_Transport" - type="u" tp:type="Stream_Transport_Type" access="read" - tp:requestable="yes" tp:immutable="yes"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>If set on a requested channel, this indicates the transport that - should be used for this call. Where not applicable, this property - is defined to be <tp:type>Stream_Transport_Type</tp:type>_Unknown, - in particular, on CMs with hardware streaming.</p> - - <tp:rationale> - When implementing a voip gateway one wants the outgoing leg of the - gatewayed to have the same transport as the incoming leg. This - property allows the gateway to request a Call with the right - transport from the CM. - </tp:rationale> - </tp:docstring> - </property> - - <property name="InitialAudio" tp:name-for-bindings="Initial_Audio" - type="b" access="read" tp:immutable="yes" tp:requestable="yes"> - <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="ofdT.Channel.Type.Call.DRAFT">AddContent</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="ofdT.Channel.Type.Call.DRAFT" - >Contents</tp:dbus-ref>).</p> - - <p>The name of this new content can be decided by using the - <tp:member-ref>InitialAudioName</tp:member-ref> property.</p> - - <p>Connection managers that support the <tp:dbus-ref - namespace="ofdT.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 = Call - 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="ofdT.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="ofdT.Client.Handler">HandlerChannelFilter</tp:dbus-ref> - properties):</p> - - <ul> - <li>{ ChannelType = Call }</li> - <li>{ ChannelType = Call, InitialAudio = True } - if receiving calls with audio is supported</li> - <li>{ ChannelType = Call, 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:immutable="yes" tp:requestable="yes"> - <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="InitialAudioName" tp:name-for-bindings="Initial_Audio_Name" - type="s" access="read" tp:immutable="yes" tp:requestable="yes"> - <tp:added version="0.21.2"/> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>If <tp:member-ref>InitialAudio</tp:member-ref> is set to - True, then this property will name the intial audio content - with the value of this property.</p> - - <tp:rationale> - <p>Content names are meant to be significant, but if no name - can be given to initial audio content, then its name cannot - be meaningful or even localized.</p> - </tp:rationale> - - <p>If this property is empty or missing from the channel - request and InitialAudio is True, then the CM must come up - with a sensible for the content, such as "audio".</p> - - <p>If the protocol has no concept of stream names then this - property will not show up in the allowed properties list of - the Requestable Channel Classes for call channels.</p> - </tp:docstring> - </property> - - <property name="InitialVideoName" tp:name-for-bindings="Initial_Video_Name" - type="s" access="read" tp:immutable="yes" tp:requestable="yes"> - <tp:added version="0.21.2"/> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The same as - <tp:member-ref>InitialAudioName</tp:member-ref>, but for a - video stream created by setting - <tp:member-ref>InitialVideo</tp:member-ref> to True. This - property is immutable and so cannot change.</p> - </tp:docstring> - </property> - - <property name="MutableContents" tp:name-for-bindings="Mutable_Contents" - type="b" access="read" tp:immutable="yes"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>If True, a stream of a different content type can be added - after the Channel has been requested </p> - - <p>If this property is missing, clients SHOULD assume that it is False, - and thus that the channel's streams cannot be changed once the call - has started.</p> - - <p>If this property isn't present in the "allowed" set in any of the - Call entries contact 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> - </tp:docstring> - </property> - - <tp:hct name="audio"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>This client supports audio calls.</p> - </tp:docstring> - </tp:hct> - - <tp:hct name="video"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>This client supports video calls.</p> - </tp:docstring> - </tp:hct> - - <tp:hct name="gtalk-p2p"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The client can implement streaming for streams whose <tp:dbus-ref - namespace="ofdT.Call.Stream.Interface.Media.DRAFT">Transport</tp:dbus-ref> - property is <tp:type>Stream_Transport_Type</tp:type>_GTalk_P2P.</p> - </tp:docstring> - </tp:hct> - - <tp:hct name="ice"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The client can implement streaming for streams whose <tp:dbus-ref - namespace="ofdT.Call.Stream.Interface.Media.DRAFT">Transport</tp:dbus-ref> - property is <tp:type>Stream_Transport_Type</tp:type>_ICE.</p> - </tp:docstring> - </tp:hct> - - <tp:hct name="wlm-2009"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The client can implement streaming for streams whose <tp:dbus-ref - namespace="ofdT.Call.Stream.Interface.Media.DRAFT">Transport</tp:dbus-ref> - property is <tp:type>Stream_Transport_Type</tp:type>_WLM_2009.</p> - </tp:docstring> - </tp:hct> - - <tp:hct name="shm"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The client can implement streaming for streams whose <tp:dbus-ref - namespace="ofdT.Call.Stream.Interface.Media.DRAFT">Transport</tp:dbus-ref> - property is <tp:type>Stream_Transport_Type</tp:type>_SHM.</p> - </tp:docstring> - </tp:hct> - - <tp:hct name="video/h264" is-family="yes"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The client supports media streaming with H264 (etc.).</p> - - <p>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/<em>subtype</em> or video/<em>subtype</em>, 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.</p> - - <tp:rationale> - <p>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 - <code>video/h264</code> on Call channels.</p> - </tp:rationale> - - <p>For example, a client could advertise support for audio and video - calls using Speex, Theora and H264 by having five handler capability - tokens in its <tp:dbus-ref - namespace="ofdT.Client.Handler">Capabilities</tp:dbus-ref> - property:</p> - - <ul> - <li><code>org.freedesktop.Telepathy.Channel.Type.Call.DRAFT/audio</code></li> - <li><code>org.freedesktop.Telepathy.Channel.Type.Call.DRAFT/audio/speex</code></li> - <li><code>org.freedesktop.Telepathy.Channel.Type.Call.DRAFT/video</code></li> - <li><code>org.freedesktop.Telepathy.Channel.Type.Call.DRAFT/video/theora</code></li> - <li><code>org.freedesktop.Telepathy.Channel.Type.Call.DRAFT/video/h264</code></li> - </ul> - - <p>Clients MAY have media signalling abilities without explicitly - supporting any particular codec, and connection managers SHOULD - support this usage.</p> - - <tp:rationale> - <p>This is necessary to support gatewaying between two Telepathy - connections, in which case the available codecs might not be - known to the gatewaying process.</p> - </tp:rationale> - </tp:docstring> - </tp:hct> - - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> |