diff options
author | Simon McVittie <simon.mcvittie@collabora.co.uk> | 2010-02-22 17:28:39 +0000 |
---|---|---|
committer | Simon McVittie <simon.mcvittie@collabora.co.uk> | 2010-02-22 17:28:39 +0000 |
commit | 539157b11cfd7dcfe384050ee0f7aa40885efa0e (patch) | |
tree | 9fa278a6570b546f1019551474cc166ee2075ce7 /extensions | |
parent | 67017d09534c017ea549dfecb10047373cef15fb (diff) | |
parent | d2c078940b06befd6f8ccd97892f4ccf9292e8c1 (diff) |
Merge commit 'telepathy-gabble-0.9.5' (+ nano version) into contact-info
Conflicts:
src/connection.c
Edits:
fix tp:name-for-bindings of ContactInfoChanged
fix whitespace in conn-contact-info _insert_edit_info
rewrite vcard_node_changed() for the new data structure
Diffstat (limited to 'extensions')
-rw-r--r-- | extensions/Call_Content.xml | 141 | ||||
-rw-r--r-- | extensions/Call_Content_Codec_Offer.xml | 57 | ||||
-rw-r--r-- | extensions/Call_Content_Interface_Media.xml | 229 | ||||
-rw-r--r-- | extensions/Call_Stream.xml | 165 | ||||
-rw-r--r-- | extensions/Call_Stream_Endpoint.xml | 95 | ||||
-rw-r--r-- | extensions/Call_Stream_Interface_Media.xml | 400 | ||||
-rw-r--r-- | extensions/Channel_Interface_Conference.xml | 400 | ||||
-rw-r--r-- | extensions/Channel_Type_Call.xml | 931 | ||||
-rw-r--r-- | extensions/Connection_Future.xml | 110 | ||||
-rw-r--r-- | extensions/Connection_Interface_Contact_Info.xml | 2 | ||||
-rw-r--r-- | extensions/Connection_Interface_Gabble_Decloak.xml | 113 | ||||
-rw-r--r-- | extensions/Gabble_Plugin_Gateways.xml | 75 | ||||
-rw-r--r-- | extensions/Gabble_Plugin_Test.xml | 27 | ||||
-rw-r--r-- | extensions/Makefile.am | 16 | ||||
-rw-r--r-- | extensions/OLPC_Activity_Properties.xml | 7 | ||||
-rw-r--r-- | extensions/OLPC_Buddy_Info.xml | 21 | ||||
-rw-r--r-- | extensions/OLPC_Channel_Interface_View.xml | 4 | ||||
-rw-r--r-- | extensions/OLPC_Gadget.xml | 4 | ||||
-rw-r--r-- | extensions/all.xml | 81 |
19 files changed, 2859 insertions, 19 deletions
diff --git a/extensions/Call_Content.xml b/extensions/Call_Content.xml new file mode 100644 index 000000000..1d5e891df --- /dev/null +++ b/extensions/Call_Content.xml @@ -0,0 +1,141 @@ +<?xml version="1.0" ?> +<node name="/Call_Content" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright © 2009 Collabora Ltd.</tp:copyright> + <tp:copyright>Copyright © 2009 Nokia Corporation</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.Call.Content.DRAFT" + tp:causes-havoc="experimental"> + <tp:added version="0.19.0">(draft 1)</tp:added> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + This object represents one Content inside a Call. For example in an + audio/video call there would be one audio and one video content. Each + content has one or more <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Call">Stream.DRAFT</tp:dbus-ref> + objects which represent the actual transport to one or more contacts. + + </tp:docstring> + + <property name="Name" tp:name-for-bindings="Name" type="s" access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The name of the content. + [FIXME: rationale?]</p> + </tp:docstring> + </property> + + <property name="Type" tp:name-for-bindings="Type" + type="u" tp:type="Media_Stream_Type" access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The media type of this content</p> + </tp:docstring> + </property> + + <property name="Creator" tp:name-for-bindings="Creator" + type="u" tp:type="Contact_Handle" access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The creator of this content</p> + </tp:docstring> + </property> + + <tp:enum name="Call_Content_Disposition" type="u"> + <tp:docstring> + [FIXME] + </tp:docstring> + + <tp:enumvalue suffix="None" value="0"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + The content has no specific disposition + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Early_Media" value="1"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + [FIXME: what does this mean?] + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Initial" value="2"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The content was initially part of the call. When <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type.Call.DRAFT" + >Accept</tp:dbus-ref> is called on the channel, all streams of + this content where the self-handle's sending state in <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Call.Stream.DRAFT" + >Senders</tp:dbus-ref> is Sending_State_Pending_Send + will be moved to Sending_State_Sending as if <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Call.Stream.DRAFT" + >SetSending</tp:dbus-ref>(TRUE) had been called.</p> + </tp:docstring> + </tp:enumvalue> + </tp:enum> + + <property name="Disposition" tp:name-for-bindings="Disposition" + type="u" tp:type="Call_Content_Disposition" access="read"> + <tp:docstring> + The disposition of this content. This property cannot change. + </tp:docstring> + </property> + + <signal name="StreamAdded" tp:name-for-bindings="Stream_Added"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Emitted when a stream is added to a call</p> + </tp:docstring> + <arg name="Stream" type="o"> + <tp:docstring> + The stream which was added + </tp:docstring> + </arg> + </signal> + + <signal name="StreamRemoved" tp:name-for-bindings="Stream_Removed"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Emitted when a stream is added to a call</p> + </tp:docstring> + <arg name="Stream" type="o"> + <tp:docstring> + The stream which was removed + </tp:docstring> + </arg> + </signal> + + <property name="Streams" tp:name-for-bindings="Streams" + type="ao" access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The list of + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Call">Stream.DRAFT</tp:dbus-ref> + objects that exist in this content.</p> + + <tp:rationale> + <p>In a conference call multiple parties can share one media content + (say, audio), but the streaming of that media can either be shared + or separate. For example, in a multicast conference all contacts + would share one stream, while in a Muji conference there would be + a stream for each participant.</p> + </tp:rationale> + + <p>Change notification is via + <tp:member-ref>StreamAdded</tp:member-ref> and + <tp:member-ref>StreamRemoved</tp:member-ref>.</p> + </tp:docstring> + </property> + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/extensions/Call_Content_Codec_Offer.xml b/extensions/Call_Content_Codec_Offer.xml new file mode 100644 index 000000000..31ff0b3c9 --- /dev/null +++ b/extensions/Call_Content_Codec_Offer.xml @@ -0,0 +1,57 @@ +<?xml version="1.0" ?> +<node name="/Call_Content_Codec_Offer" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright © 2009 Collabora Ltd.</tp:copyright> + <tp:copyright>Copyright © 2009 Nokia Corporation</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.Call.Content.CodecOffer.DRAFT" + tp:causes-havoc="experimental"> + <tp:added version="0.19.0">(draft 1)</tp:added> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + This object represents an offer of a Codec payload mapping. + FIXME add Accept and Reject signals ? + </tp:docstring> + + <method name="Accept" tp:name-for-bindings="Accept"> + <arg name="Codecs" direction="in" + type="a(usuua{ss})" tp:type="Codec[]" /> + <tp:docstring> + Accept the updated Codec mapping and update the local mapping + </tp:docstring> + </method> + + <method name="Reject" tp:name-for-bindings="Reject"> + <tp:docstring> + Reject the proposed update to the codecs + FIXME add error codes and strings here + </tp:docstring> + </method> + + <property name="RemoteContactCodecMap" + tp:name-for-bindings="Remote_Contact_Codec_Map" + type="a{ua(usuua{ss})}" tp:type="Contact_Codec_Map" access="read"> + <tp:docstring> + A map from remote contacts to the lists of codecs they support. + </tp:docstring> + </property> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/extensions/Call_Content_Interface_Media.xml b/extensions/Call_Content_Interface_Media.xml new file mode 100644 index 000000000..2b3eb65d5 --- /dev/null +++ b/extensions/Call_Content_Interface_Media.xml @@ -0,0 +1,229 @@ +<?xml version="1.0" ?> +<node name="/Call_Content_Interface_Media" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright © 2009 Collabora Ltd.</tp:copyright> + <tp:copyright>Copyright © 2009 Nokia Corporation</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.Call.Content.Interface.Media.DRAFT" + tp:causes-havoc="experimental"> + <tp:added version="0.19.0">(draft 1)</tp:added> + <tp:requires interface="org.freedesktop.Telepathy.Call.Content"/> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + Interface to use by a software implementation of media streaming. + + FIXME: How should the streaming implementation know when it is its turn + to set the codecs. + </tp:docstring> + + <tp:struct name="Codec" array-name="Codec_List"> + <tp:docstring> + A description of a codec. + </tp:docstring> + + <tp:member name="Identifier" type="u"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + Numeric identifier for the codec. This will be used as the PT in the + SDP or content description. + </tp:docstring> + </tp:member> + + <tp:member name="Name" type="s"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + The name of the codec. + </tp:docstring> + </tp:member> + + <tp:member name="Clockrate" type="u"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + The clockrate of the codec + </tp:docstring> + </tp:member> + <tp:member name="Channels" type="u"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + Number of channels of the codec if applicable, otherwise 0 + </tp:docstring> + </tp:member> + + <tp:member name="Parameters" type="a{ss}"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + Extra parameters for this codec + </tp:docstring> + </tp:member> + </tp:struct> + + <tp:mapping name="Contact_Codec_Map"> + <tp:docstring> + A map from contacts to the lists of codecs they support. + </tp:docstring> + + <tp:member name="Handle" type="u" tp:type="Contact_Handle"> + <tp:docstring> + A contact + </tp:docstring> + </tp:member> + + <tp:member name="Codecs" type="a(usuua{ss})" tp:type="Codec[]"> + <tp:docstring> + The codecs that the contact supports + </tp:docstring> + </tp:member> + </tp:mapping> + + <tp:struct name="Codec_Offering"> + <tp:docstring> + A codec offer and its corresponding remote contact codec map. + </tp:docstring> + + <tp:member name="Codec_Offer" type="o"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + The object path to the + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Call.Content" + >CodecOffer.DRAFT</tp:dbus-ref> + </tp:docstring> + </tp:member> + + <tp:member name="Remote_Contact_Codec_Map" type="a{ua(usuua{ss})}" + tp:type="Contact_Codec_Map"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + The <tp:dbus-ref namespace="org.freedesktop.Telepathy.Call.Content" + >CodecOffer.DRAFT.RemoteContactCodecMap</tp:dbus-ref> property + of the codec offer. + </tp:docstring> + </tp:member> + </tp:struct> + + <signal name="CodecsChanged" tp:name-for-bindings="Codecs_Changed"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Emitted when the codecs in use change.</p> + + <p>As well as acting as change notification for the + <tp:member-ref>ContactCodecMap</tp:member-ref>, emission of this + signal implies that the <tp:member-ref>CodecOffer</tp:member-ref> + property has changed to <code>('/', {})</code>.</p> + </tp:docstring> + + <arg name="Updated_Codecs" type="a{ua(usuua{ss})}" + tp:type="Contact_Codec_Map"> + <tp:docstring> + A map from contacts to their codecs. Each pair in this map is added + to the <tp:member-ref>ContactCodecMap</tp:member-ref> property, + replacing any previous pair with that key. + </tp:docstring> + </arg> + + <arg name="Removed_Contacts" type="au" tp:type="Contact_Handle[]"> + <tp:docstring> + A list of keys which were removed from the + <tp:member-ref>ContactCodecMap</tp:member-ref>, probably because + those contacts left the call. + </tp:docstring> + </arg> + </signal> + + <method name="SetCodecs" tp:name-for-bindings="Set_Codecs"> + <tp:docstring> + Set or update the local codec mapping. + </tp:docstring> + + <arg name="Codecs" direction="in" + type="a(usuua{ss})" tp:type="Codec[]"> + <tp:docstring> + The codecs now supported by the local user. + </tp:docstring> + </arg> + </method> + + <property name="ContactCodecMap" tp:name-for-bindings="Contact_Codec_Map" + type="a{ua(usuua{ss})}" tp:type="Contact_Codec_Map" access="read"> + <tp:docstring> + <p>A map from contact handles (including the local user's own handle) + to the codecs supported by that contact.</p> + + <p>Change notification is via + <tp:member-ref>CodecsChanged</tp:member-ref>.</p> + </tp:docstring> + </property> + + <signal name="NewCodecOffer" tp:name-for-bindings="New_Codec_Offer"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Emitted when a new <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Call.Content" + >CodecOffer.DRAFT</tp:dbus-ref> appears. The streaming + implementation MUST respond by calling the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Call.Content.CodecOffer.DRAFT" + >Accept</tp:dbus-ref> or <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Call.Content.CodecOffer.DRAFT" + >Reject</tp:dbus-ref> method on the codec offer object.</p> + + <p>Emission of this signal indicates that the + <tp:member-ref>CodecOffer</tp:member-ref> property has changed to + <code>(Offer, Codecs)</code>.</p> + </tp:docstring> + + <arg name="Offer" type="o"> + <tp:docstring> + The object path of the new codec offer. This replaces any previous + codec offer. + </tp:docstring> + </arg> + + <arg name="Codecs" type="a{ua(usuua{ss})}" tp:type="Contact_Codec_Map"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The <tp:dbus-ref namespace="org.freedesktop.Telepathy.Call.Content" + >CodecOffer.DRAFT.RemoteContactCodecMap</tp:dbus-ref> property + of the codec offer.</p> + + <tp:rationale> + <p>Having the RemoteContactCodecMap property here saves a D-Bus + round-trip - it shouldn't be necessary to get the property + from the CodecOffer object, in practice.</p> + </tp:rationale> + </tp:docstring> + </arg> + </signal> + + <property name="CodecOffer" tp:name-for-bindings="Codec_Offer" + type="(oa{ua(usuua{ss})})" tp:type="Codec_Offering" access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The object path to the current + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Call.Content" + >CodecOffer.DRAFT</tp:dbus-ref> object, and its + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Call.Content" + >CodecOffer.DRAFT.RemoteContactCodecMap</tp:dbus-ref> property. + If the object path is "/" then there isn't an outstanding + codec offer, and the mapping MUST be empty.</p> + + <tp:rationale> + <p>Having the RemoteContactCodecMap property here saves a D-Bus + round-trip - it shouldn't be necessary to get the property + from the CodecOffer object, in practice.</p> + </tp:rationale> + + <p>Change notification is via + <tp:member-ref>NewCodecOffer</tp:member-ref> (which replaces the + value of this property with a new codec offer), and + <tp:member-ref>CodecsChanged</tp:member-ref> (which implies that + there is no longer any active codec offer).</p> + </tp:docstring> + </property> + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/extensions/Call_Stream.xml b/extensions/Call_Stream.xml new file mode 100644 index 000000000..302bd5e9b --- /dev/null +++ b/extensions/Call_Stream.xml @@ -0,0 +1,165 @@ +<?xml version="1.0" ?> +<node name="/Call_Stream" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright © 2009 Collabora Ltd.</tp:copyright> + <tp:copyright>Copyright © 2009 Nokia Corporation</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.Call.Stream.DRAFT" + tp:causes-havoc="experimental"> + <tp:added version="0.19.0">(draft 1)</tp:added> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + One stream inside a content + FIXME, direction should be a mapping of contact -> (bool)sending ? + </tp:docstring> + + <method name="SetSending" tp:name-for-bindings="Set_Sending"> + <p>Set the stream to start or stop sending media from the local + user to other contacts.</p> + + <arg name="Send" type="b" direction="in"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If true, the local user's sending state should change + to Sending, if it isn't already.</p> + + <p>If false, the local user's sending state should change to None, + if it isn't already.</p> + </tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + [FIXME: when?] + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <method name="RequestReceiving" tp:name-for-bindings="Request_Receiving"> + <tp:docstring> + Request that a remote contact stops or starts sending on this stream. + </tp:docstring> + + <arg name="Contact" type="u" tp:type="Contact_Handle" direction="in"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Contact from which sending is requested</p> + </tp:docstring> + </arg> + + <arg name="Receive" type="b" direction="in"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If true, request that the given contact starts to send media. + If false, request that the given contact stops sending media.</p> + </tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + [FIXME: when?] + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <signal name="SendersChanged" + tp:name-for-bindings="Senders_Changed"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + Emitted when <tp:member-ref>Senders</tp:member-ref> changes. + </tp:docstring> + + <arg name="Updates" type="a{uu}" tp:type="Contact_Sending_State_Map"> + <tp:docstring> + A mapping from channel-specific handles to their updated sending + state, whose keys include at least the senders who were added, + and the senders whose states changed. + </tp:docstring> + </arg> + <arg name="Removed" type="au" tp:type="Contact_Handle[]"> + <tp:docstring> + The channel-specific handles that were removed from + the keys of the Senders property, as a result of the + contact leaving this stream + </tp:docstring> + </arg> + </signal> + + <tp:enum name="Sending_State" type="u"> + <tp:docstring> + Tristate indicating whether a contact is sending media. + </tp:docstring> + + <tp:enumvalue suffix="None" value="0"> + <tp:docstring> + The contact is not sending media and has not been asked to do so. + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Pending_Send" value="1"> + <tp:docstring> + The contact has been asked to start sending media. + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Sending" value="2"> + <tp:docstring> + The contact is sending media. + </tp:docstring> + </tp:enumvalue> + </tp:enum> + + <tp:mapping name="Contact_Sending_State_Map"> + <tp:docstring> + A map from contacts to their sending state. + </tp:docstring> + <tp:member name="Contact" type="u" tp:type="Contact_Handle"> + </tp:member> + <tp:member name="Sending" type="u" tp:type="Sending_State"> + <tp:docstring> + </tp:docstring> + </tp:member> + </tp:mapping> + + <property name="Senders" tp:name-for-bindings="Senders" + type="a{uu}" access="read" tp:type="Contact_Sending_State_Map"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A map from contacts to their sending state.</p> + + <p>The local user's handle in this map (the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface" + >Group.SelfHandle</tp:dbus-ref> if the channel implements + Group, or the <tp:dbus-ref + namespace="org.freedesktop.Telepathy" + >Connection.SelfHandle</tp:dbus-ref> otherwise) indicates + whether the local user is sending media. Media sent on this stream + should be assumed to be received, directly or indirectly, by every + other contact in the Senders mapping. Sending_State_Pending_Send + indicates that another contact has asked the local user to send + media.</p> + + <p>Other contacts' handles in this map indicate whether they are + sending media to the contacts in this stream. + Sending_State_Pending_Send indicates contacts who are not sending but + have been asked to do so.</p> + </tp:docstring> + </property> + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/extensions/Call_Stream_Endpoint.xml b/extensions/Call_Stream_Endpoint.xml new file mode 100644 index 000000000..fbab2cfa3 --- /dev/null +++ b/extensions/Call_Stream_Endpoint.xml @@ -0,0 +1,95 @@ +<?xml version="1.0" ?> +<node name="/Call_Stream_Endpoint" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright © 2009 Collabora Ltd.</tp:copyright> + <tp:copyright>Copyright © 2009 Nokia Corporation</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.Call.Stream.Endpoint.DRAFT" + tp:causes-havoc="experimental"> + <tp:added version="0.19.0">(draft 1)</tp:added> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + This object represents a set of candidates of one end-point. + </tp:docstring> + + <property name="RemoteCredentials" + tp:name-for-bindings="Remote_Credentials" + type="(ss)" tp:type="Stream_Credentials" access="read"> + </property> + + <signal name="RemoteCredentialsSet" + tp:name-for-bindings="Remote_Credentials_Set"> + <arg name="Username" type="s" /> + <arg name="Password" type="s" /> + </signal> + + <property name="RemoteCandidates" tp:name-for-bindings="Remote_Candidates" + type="a(usqa{sv})" tp:type="Candidate[]" access="read"> + </property> + + <signal name="RemoteCandidatesAdded" + tp:name-for-bindings="Remote_Candidates_Added"> + <arg name="Candidates" + type="a(usqa{sv})" tp:type="Candidate[]"/> + </signal> + + <signal name="CandidateSelected" + tp:name-for-bindings="Candidate_Selected"> + <arg name="Candidate" + type="(usqa{sv})" tp:type="Candidate"/> + </signal> + + <property name="SelectedCandidate" + tp:name-for-bindings="Selected_Candidate" + type="(usqa{sv})" tp:type="Candidate" access="read"> + </property> + + <method name="SetSelectedCandidate" + tp:name-for-bindings="Set_Selected_Candidate"> + <arg name="Candidate" + type="(usqa{sv})" tp:type="Candidate" direction="in"> + <tp:docstring> + </tp:docstring> + </arg> + </method> + + <property name="StreamState" tp:name-for-bindings="Stream_State" + type="u" tp:type="Media_Stream_State" + access="read"> + </property> + + <signal name="StreamStateChanged" + tp:name-for-bindings="Stream_State_Changed"> + <arg name="state" + type="u" tp:type="Media_Stream_State"/> + </signal> + + <method name="SetStreamState" + tp:name-for-bindings="Set_Stream_State"> + <arg name="State" type="u" tp:type="Media_Stream_State" + direction="in" /> + </method> + + <property name="Transport" tp:name-for-bindings="Transport" + type="u" tp:type="Stream_Transport_Type" access="read"> + </property> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/extensions/Call_Stream_Interface_Media.xml b/extensions/Call_Stream_Interface_Media.xml new file mode 100644 index 000000000..ccf903374 --- /dev/null +++ b/extensions/Call_Stream_Interface_Media.xml @@ -0,0 +1,400 @@ +<?xml version="1.0" ?> +<node name="/Call_Stream_Interface_Media" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright © 2009 Collabora Ltd.</tp:copyright> + <tp:copyright>Copyright © 2009 Nokia Corporation</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.Call.Stream.Interface.Media.DRAFT" + tp:causes-havoc="experimental"> + <tp:added version="0.19.0">(draft 1)</tp:added> + <tp:requires interface="org.freedesktop.Telepathy.Call.Stream"/> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + [FIXME] + </tp:docstring> + + <tp:method name="SetCredentials" tp:name-for-bindings="Set_Credentials"> + <tp:docstring> + Used to set the username fragment and password for streams that have + global credentials. + + <tp:rationale> + [FIXME: rationale?] + </tp:rationale> + </tp:docstring> + <arg name="Username" type="s" direction="in"/> + <arg name="Password" type="s" direction="in" /> + </tp:method> + + <tp:mapping name="Candidate_Info"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + Extra information about the candidate. Allowed and mandatory keys + depend on the transport protocol used. The following keys are commenly + used: + <dl> + <dt>Type (u)</dt> + <dd>type of candidate (host, srflx, prflx, relay)</dd> + + <dt>Foundation (s)</dt> + <dd>the foundation of this candiate</dd> + + <dt>Protocol (u) </dt> + <dd>Underlying protocol of the candidate (udp, tcp) </dd> + + <dt>Priority (u) </dt> + <dd>Priority of the candidate </dd> + + <dt>BaseIP (u) </dt> + <dd>Base IP of this candidate </dd> + + <dt>Username (s) </dt> + <dd>Username of this candidate + (only if credentials are per candidate)</dd> + + <dt>Password (s) </dt> + <dd>Password of this candidate + (only if credentials are per candidate)</dd> + + <dt>RawUDPFallback (b) </dt> + <dd>Indicate whether this candidate may be used to provide a UDP + fallback</dd> + </dl> + </tp:docstring> + <tp:member name="Key" type="s"> + <tp:docstring>One of the well-known keys documented here, or an + implementation-specific key</tp:docstring> + </tp:member> + <tp:member name="Value" type="v"> + <tp:docstring>The value corresponding to that key</tp:docstring> + </tp:member> + </tp:mapping> + + <tp:struct name="Candidate" array-name="Candidate_List"> + <tp:docstring>A Stream Candidate</tp:docstring> + + <tp:member name="Component" type="u"> + <tp:docstring>The component number</tp:docstring> + </tp:member> + <tp:member name="IP" type="s"> + <tp:docstring>The IP address to use</tp:docstring> + </tp:member> + <tp:member name="Port" type="q"> + <tp:docstring>The port number to use</tp:docstring> + </tp:member> + <tp:member name="Info" type="a{sv}" tp:type="Candidate_Info"> + <tp:docstring>Additional information about the candidate</tp:docstring> + </tp:member> + </tp:struct> + + <method name="AddCandidates" tp:name-for-bindings="Add_Candidates"> + <tp:docstring> + Add candidates to <tp:member-ref>LocalCandidates</tp:member-ref> + and signal them to the remote contact(s). + </tp:docstring> + + <arg name="candidates" direction="in" + type="a(usqa{sv})" tp:type="Candidate[]"> + <tp:docstring> + Candidates to be appended to + <tp:member-ref>LocalCandidates</tp:member-ref> + </tp:docstring> + </arg> + </method> + + <method name="CandidatesPrepared" + tp:name-for-bindings="Candidates_Prepared"> + <tp:docstring> + This indicates to the CM that the initial batch of candidates has been + added. + + <tp:rationale> + [FIXME: rationale] + </tp:rationale> + </tp:docstring> + </method> + + <tp:enum type="u" name="Stream_Transport_Type"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + A transport that can be used for streaming. + </tp:docstring> + + <tp:enumvalue suffix="Raw_UDP" value="0"> + <tp:docstring> + Raw UDP, with or without STUN. All streaming clients are assumed to + support this transport, so there is no handler capability token for + it in the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type" + >Call.DRAFT</tp:dbus-ref> interface. + [This corresponds to "none" or "stun" in the old Media.StreamHandler + interface.] + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="ICE" value="1"> + <tp:docstring> + Interactive Connectivity Establishment, as defined by the IETF MMUSIC + working group. + [FIXME: do we want this to cover both ICE-UDP and ICE-TCP, or split + them?] + [This corresponds to "ice-udp" in the old Media.StreamHandler + interface.] + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="GTalk_P2P" value="2"> + <tp:docstring> + Google Talk peer-to-peer connectivity establishment, as implemented + by libjingle 0.3. + [This corresponds to "gtalk-p2p" in the old Media.StreamHandler + interface.] + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="WLM_8_5" value="3"> + <tp:docstring> + The transport used by Windows Live Messenger 8.5 or later, which + resembles ICE draft 6. + [This corresponds to "wlm-8.5" in the old Media.StreamHandler + interface.] + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="WLM_2009" value="4"> + <tp:docstring> + The transport used by Windows Live Messenger 2009 or later, which + resembles ICE draft 19. + [This corresponds to "wlm-2009" in the old Media.StreamHandler + interface.] + </tp:docstring> + </tp:enumvalue> + </tp:enum> + + <property name="Transport" tp:name-for-bindings="Transport" + type="u" tp:type="Stream_Transport_Type" access="read"> + <tp:docstring> + The transport for this stream. This property is immutable. + </tp:docstring> + </property> + + <property name="LocalCandidates" tp:name-for-bindings="Local_Candidates" + type="a(usqa{sv})" tp:type="Candidate[]" access="read"> + <tp:docstring> + [FIXME]. Change notification is via + <tp:member-ref>LocalCandidatesAdded</tp:member-ref>. + </tp:docstring> + </property> + + <signal name="LocalCandidatesAdded" + tp:name-for-bindings="Local_Candidates_Added"> + <tp:docstring> + Emitted when local candidates are added to + <tp:member-ref>LocalCandidates</tp:member-ref>. + </tp:docstring> + + <arg name="Candidates" + type="a(usqa{sv})" tp:type="Candidate[]"> + <tp:docstring> + Candidates that have been appended to + <tp:member-ref>LocalCandidates</tp:member-ref> + </tp:docstring> + </arg> + </signal> + + <tp:struct name="Stream_Credentials"> + <tp:docstring>A username/password pair.</tp:docstring> + + <tp:member name="Username" type="s"> + <tp:docstring>The username</tp:docstring> + </tp:member> + + <tp:member name="Password" type="s"> + <tp:docstring>The password</tp:docstring> + </tp:member> + </tp:struct> + + <property name="LocalCredentials" tp:name-for-bindings="Local_Credentials" + type="(ss)" tp:type="Stream_Credentials" access="read"> + <tp:docstring> + [FIXME]. Change notification is via + <tp:member-ref>LocalCredentialsSet</tp:member-ref>. + </tp:docstring> + + </property> + + <signal name="LocalCredentialsSet" + tp:name-for-bindings="Local_Credentials_Set"> + <tp:docstring> + Emitted when the value of + <tp:member-ref>LocalCredentials</tp:member-ref> changes. + </tp:docstring> + + <arg name="Username" type="s" /> + <arg name="Password" type="s" /> + </signal> + + <property name="STUNServers" tp:name-for-bindings="STUN_Servers" + type="a(sq)" tp:type="Socket_Address_IP[]" access="read"> + <tp:docstring> + The IP addresses of possible STUN servers to use for NAT traversal, as + dotted-quad IPv4 address literals or RFC2373 IPv6 address literals. + This property cannot change once the stream has been created, so there + is no change notification. The IP addresses MUST NOT be given as DNS + hostnames. + + <tp:rationale> + High-quality connection managers already need an asynchronous + DNS resolver, so they might as well resolve this name to an IP + to make life easier for streaming implementations. + </tp:rationale> + </tp:docstring> + </property> + + <property name="RelayInfo" type="aa{sv}" access="read" + tp:type="String_Variant_Map[]" tp:name-for-bindings="Relay_Info"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A list of mappings describing TURN or Google relay servers + available for the client to use in its candidate gathering, as + determined from the protocol. Map keys are:</p> + + <dl> + <dt><code>ip</code> - s</dt> + <dd>The IP address of the relay server as a dotted-quad IPv4 + address literal or an RFC2373 IPv6 address literal. This MUST NOT + be a DNS hostname. + + <tp:rationale> + High-quality connection managers already need an asynchronous + DNS resolver, so they might as well resolve this name to an IP + and make life easier for streaming implementations. + </tp:rationale> + </dd> + + <dt><code>type</code> - s</dt> + <dd> + <p>Either <code>udp</code> for UDP (UDP MUST be assumed if this + key is omitted), <code>tcp</code> for TCP, or + <code>tls</code>.</p> + + <p>The precise meaning of this key depends on the + <tp:member-ref>Transport</tp:member-ref> property: if + Transport is ICE, <code>tls</code> means + TLS over TCP as referenced by ICE draft 19, and if + Transport is GTalk_P2P, <code>tls</code> means + a fake SSL session over TCP as implemented by libjingle.</p> + </dd> + + <dt><code>port</code> - q</dt> + <dd>The UDP or TCP port of the relay server as an ASCII unsigned + integer</dd> + + <dt><code>username</code> - s</dt> + <dd>The username to use</dd> + + <dt><code>password</code> - s</dt> + <dd>The password to use</dd> + + <dt><code>component</code> - u</dt> + <dd>The component number to use this relay server for, as an + ASCII unsigned integer; if not included, this relay server + may be used for any or all components. + + <tp:rationale> + In ICE draft 6, as used by Google Talk, credentials are only + valid once, so each component needs relaying separately. + </tp:rationale> + </dd> + </dl> + + <tp:rationale> + <p>An equivalent of the gtalk-p2p-relay-token property on + MediaSignalling channels is not included here. The connection + manager should be responsible for making the necessary HTTP + requests to turn the token into a username and password.</p> + </tp:rationale> + + <p>The type of relay server that this represents depends on + the value of the <tp:member-ref>Transport</tp:member-ref> + property. If Transport is ICE, this is a TURN server; + if Transport is GTalk_P2P, this is a Google relay server; + otherwise, the meaning of RelayInfo is undefined.</p> + + <p>If relaying is not possible for this stream, the list is empty.</p> + </tp:docstring> + </property> + + <signal name="ServerInfoRetrieved" + tp:name-for-bindings="Server_Info_Retrieved"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Signals that the initial information about STUN and Relay servers + has been retrieved, i.e. the + <tp:member-ref>RetrievedServerInfo</tp:member-ref> property is now + true.</p> + </tp:docstring> + </signal> + + <property name="RetrievedServerInfo" type="b" + tp:name-for-bindings="Retrieved_Server_Info" access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>True if the initial information about STUN servers and Relay servers + has been retrieved. Change notification is via the + <tp:member-ref>ServerInfoRetrieved</tp:member-ref> signal.</p> + + <tp:rationale> + <p>Streaming implementations that can't cope with STUN and relay + servers being added later SHOULD wait for this property + to become true before proceeding.</p> + </tp:rationale> + </tp:docstring> + </property> + + <signal name="EndpointsChanged" + tp:name-for-bindings="Endpoints_Changed"> + <tp:docstring> + Emitted when the <tp:member-ref>Endpoints</tp:member-ref> property + changes. + </tp:docstring> + + <arg name="EndpointsAdded" type="ao"> + <tp:docstring> + Endpoints that were added. + </tp:docstring> + </arg> + + <arg name="EndpointsRemoved" type="ao"> + <tp:docstring> + Endpoints that no longer exist. + </tp:docstring> + </arg> + </signal> + + <property name="Endpoints" tp:name-for-bindings="Endpoints" + type="ao" access="read"> + <p> The list of endpoints + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Call.Stream" + >Endpoint.DRAFT</tp:dbus-ref> + that exist for this stream. + </p> + + <p>Change notification is via the + <tp:member-ref>EndpointsChanged</tp:member-ref> signal.</p> + </property> + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/extensions/Channel_Interface_Conference.xml b/extensions/Channel_Interface_Conference.xml new file mode 100644 index 000000000..af3e627b9 --- /dev/null +++ b/extensions/Channel_Interface_Conference.xml @@ -0,0 +1,400 @@ +<?xml version="1.0" ?> +<node name="/Channel_Interface_Conference" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright © 2009 Collabora Limited</tp:copyright> + <tp:copyright>Copyright © 2009 Nokia Corporation</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.Interface.Conference.DRAFT" + tp:causes-havoc="experimental"> + <tp:added version="0.19.0">(draft 1)</tp:added> + <tp:requires interface="org.freedesktop.Telepathy.Channel"/> + <tp:requires + interface="org.freedesktop.Telepathy.Channel.Interface.Group"/> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An interface for multi-user conference channels that can "continue + from" one or more individual channels.</p> + + <tp:rationale> + <p>This interface addresses freedesktop.org <a + href="http://bugs.freedesktop.org/show_bug.cgi?id=24906">bug + #24906</a> (GSM-compatible conference calls) and <a + href="http://bugs.freedesktop.org/show_bug.cgi?id=24939">bug + #24939</a> (upgrading calls and chats to multi-user). + See those bugs for rationale and use cases.</p> + + <p>Examples of usage:</p> + + <p>Active and held GSM calls C1, C2 can be merged into a single + channel Cn with the Conference interface, by calling + <code>CreateChannel({...ChannelType: ...Call, + ...<tp:member-ref>InitialChannels</tp:member-ref>: [C1, C2]})</code> + which returns Cn.</p> + + <p>An XMPP 1-1 conversation C1 can be continued in a newly created + multi-user chatroom Cn by calling + <code>CreateChannel({...ChannelType: ...Text, + ...<tp:member-ref>InitialChannels</tp:member-ref>: [C1]})</code> + which returns Cn.</p> + + <p>An XMPP 1-1 conversation C1 can be continued in a specified + multi-user chatroom by calling + <code>CreateChannel({...ChannelType: ...Text, ...HandleType: ROOM, + ...TargetID: 'telepathy@conf.example.com', + ...<tp:member-ref>InitialChannels</tp:member-ref>: [C1]})</code> + which returns a Conference channel.</p> + + <p>Either of the XMPP cases could work for Call channels, to + upgrade from 1-1 Jingle to multi-user Muji. Any of the XMPP cases + could in principle work for link-local XMPP (XEP-0174).</p> + + <p>The underlying switchboard representing an MSN 1-1 conversation C1 + with a contact X can be moved to a representation as a nameless + chatroom, Cn, to which more contacts can be invited, by calling + <code>CreateChannel({...ChannelType: ...Text, + ...<tp:member-ref>InitialChannels</tp:member-ref>: [C1]})</code> + which returns Cn. C1 SHOULD remain open, with no underlying + switchboard attached. If X establishes a new switchboard with the + local user, C1 SHOULD pick up that switchboard rather than letting + it create a new channel. + <strong>[FIXME: should it?]</strong> + Similarly, if the local user sends a message in C1, then + a new switchboard to X should be created and associated with C1.</p> + + <p>XMPP and MSN do not natively have a concept of merging two or more + channels C1, C2... into one channel, Cn. However, the GSM-style + merging API can be supported on XMPP and MSN, as an API short-cut + for upgrading C1 into a conference Cn (which invites the + TargetHandle of C1 into Cn), then immediately inviting the + TargetHandle of C2, the TargetHandle of C3, etc. into Cn as well.</p> + + <p>With a suitable change of terminology, Skype has behaviour similar + to MSN.</p> + </tp:rationale> + + <p>The <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface" + >Group</tp:dbus-ref> MAY have channel-specific handles for participants; + clients SHOULD support both Conferences that have channel-specific handles, + and those that do not.</p> + + <tp:rationale> + <p>In the GSM case, the Conference's Group interface MAY have + channel-specific handles, to reflect the fact that the identities of + the participants might not be known - it can be possible to know that + there is another participant in the Conference, but not know who + they are. + <strong>[FIXME: fact check from GSM gurus needed]</strong> + </p> + + <p>In the XMPP case, the Conference's Group interface SHOULD have + channel-specific handles, to reflect the fact that the participants + have MUC-specific identities, and the user might also be able to see + their global identities, or not.</p> + + <p>In most other cases, including MSN and link-local XMPP, the + Conference's Group interface SHOULD NOT have channel-specific + handles, since users' identities are always visible.</p> + </tp:rationale> + + <p>Connection managers implementing channels with this interface + MUST NOT allow the object paths of channels that could be merged + into a Conference to be re-used, unless the channel re-using the + object path is equivalent to the channel that previously used it.</p> + + <tp:rationale> + <p>If you upgrade some channels into a conference, and then close + the original channels, <tp:member-ref>InitialChannels</tp:member-ref> + (which is immutable) will contain paths to channels which no longer + exist. This implies that you should not re-use channel object paths, + unless future incarnations of the path are equivalent.</p> + + <p>For instance, on protocols where you can only have + zero or one 1-1 text channels with Emily at one time, it would + be OK to re-use the same object path for every 1-1 text channel + with Emily; but on protocols where this is not true, it would + be misleading.</p> + </tp:rationale> + + </tp:docstring> + + <property name="Channels" tp:name-for-bindings="Channels" + access="read" type="ao"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The individual <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Channel</tp:dbus-ref>s that + are continued by this conference, which have the same <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel" + >ChannelType</tp:dbus-ref> as this one, but with <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel" + >TargetHandleType</tp:dbus-ref> = CONTACT.</p> + + <p>This property MUST NOT be requestable. + <strong>[FIXME: or would it be better for this one, and not IC, to be + requestable?]</strong> + </p> + + <p>Change notification is via the + <tp:member-ref>ChannelMerged</tp:member-ref> and + <tp:member-ref>ChannelRemoved</tp:member-ref> signals.</p> + </tp:docstring> + </property> + + <signal name="ChannelMerged" tp:name-for-bindings="Channel_Merged"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Emitted when a new channel is added to the value of + <tp:member-ref>Channels</tp:member-ref>.</p> + </tp:docstring> + + <arg name="Channel" type="o"> + <tp:docstring>The channel that was added to + <tp:member-ref>Channels</tp:member-ref>.</tp:docstring> + </arg> + </signal> + + <signal name="ChannelRemoved" tp:name-for-bindings="Channel_Removed"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Emitted when a channel is removed from the value of + <tp:member-ref>Channels</tp:member-ref>, either because it closed + or because it was split using the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface" + >Splittable.DRAFT.Split</tp:dbus-ref> method.</p> + + <p><strong>[FIXME: relative ordering of this vs. Closed? Do we + care?]</strong></p> + </tp:docstring> + + <arg name="Channel" type="o"> + <tp:docstring>The channel that was removed from + <tp:member-ref>Channels</tp:member-ref>.</tp:docstring> + </arg> + </signal> + + <property name="InitialChannels" tp:name-for-bindings="Initial_Channels" + access="read" type="ao"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The initial value of <tp:member-ref>Channels</tp:member-ref>.</p> + + <p>This property SHOULD be requestable. Omitting it from a request is + equivalent to providing it with an empty list as value. Requests + where its value has at least two elements SHOULD be expected to + succeed on any implementation of this interface.</p> + + <p>Whether a request with 0 or 1 elements in the list will succeed is + indicated by <tp:member-ref>SupportsNonMerges</tp:member-ref>.</p> + + <tp:rationale> + <p>In GSM, a pair of calls can be merged into a conference. In XMPP + and MSN, you can create a new chatroom, or upgrade one 1-1 channel + into a chatroom; however, on these protocols, it is also possible + to fake GSM-style merging by upgrading the first channel, then + inviting the targets of all the other channels into it.</p> + </tp:rationale> + + <p>If possible, the <tp:member-ref>Channels</tp:member-ref>' states SHOULD + NOT be altered by merging them into a conference. However, depending on + the protocol, the Channels MAY be placed in a "frozen" state by placing + them in this property's value or by calling + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface" + >MergeableConference.DRAFT.Merge</tp:dbus-ref> on them. + <strong>[FIXME: there's nothing in RequestableChannelClasses yet + to say what will happen, see #24906 comment 6]</strong></p> + + <tp:rationale> + <p>In Jingle, nothing special will happen to merged calls. UIs MAY + automatically place calls on hold before merging them, if that is + the desired behaviour; this SHOULD always work. Not doing + an implicit hold/unhold seems to preserve least-astonishment.</p> + + <p><strong>[FIXME: check whether ring supports faking Hold on both + channels, as it probably should: see #24906 comment 6]</strong> + </p> + + <p>In GSM, the calls that are merged go into a state similar to + Hold, but they cannot be unheld, only split from the conference + call using <tp:dbus-ref namespace="org.freedesktop.Telepathy" + >Channel.Interface.Splittable.DRAFT.Split</tp:dbus-ref>.</p> + </tp:rationale> + + <p>Depending on the protocol, it might be signalled to remote users + that this channel is a continuation of all the requested channels, + or that it is only a continuation of the first channel in the + list.</p> + + <tp:rationale> + <p>In MSN, the conference steals the underlying switchboard (protocol + construct) from one of its component channels, so the conference + appears to remote users to be a continuation of that channel and no + other. The connection manager has to make some arbitrary choice, so + we arbitrarily mandate that it SHOULD choose the first channel in + the list as the one to continue.</p> + </tp:rationale> + + <p>This property is immutable.</p> + </tp:docstring> + </property> + + <property name="InitialInviteeHandles" + tp:name-for-bindings="Initial_Invitee_Handles" + access="read" type="au" tp:type="Contact_Handle[]"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A list of additional contacts invited to this conference when it + was created.</p> + + <p>This property SHOULD be requestable, and appear in the allowed + properties in <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.Requests" + >RequestableChannelClasses</tp:dbus-ref>, in all connection + managers that can implement its semantics (in practice, this is + likely to mean exactly those connection managers where + <tp:member-ref>SupportsNonMerges</tp:member-ref> will be true).</p> + + <p>If included in a request, the given contacts are automatically + invited into the new channel, as if they had been added with + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface" + >Group.AddMembers</tp:dbus-ref>(InitialInviteeHandles, + <tp:member-ref>InvitationMessage</tp:member-ref> immediately after + the channel was created.</p> + + <tp:rationale> + <p>This is a simple convenience API for the common case that a UI + upgrades a 1-1 chat to a multi-user chat solely in order to invite + someone else to participate.</p> + </tp:rationale> + + <p>At most one of InitialInviteeHandles and InitialInviteeIDs may + appear in each request.</p> + + <p>If the local user was not the initiator of this channel, the + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface" + >Group.SelfHandle</tp:dbus-ref> SHOULD appear in the value of this + property, together with any other contacts invited at the same time + (if that information is known).</p> + + <p>This property is immutable.</p> + </tp:docstring> + </property> + + <property name="InitialInviteeIDs" + tp:name-for-bindings="Initial_Invitee_IDs" + access="read" type="as"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A list of additional contacts invited to this conference when it + was created.</p> + + <p>This property SHOULD be requestable, as an alternative to + <tp:member-ref>InitialInviteeHandles</tp:member-ref>. Its semantics + are the same, except that it takes a list of the string + representations of contact handles.</p> + + <p>At most one of InitialInviteeHandles and InitialInviteeIDs may + appear in each request.</p> + + <p>When a channel is created, the values of InitialInviteeHandles and + InitialInviteeIDs MUST correspond to each other.</p> + + <p>This property is immutable.</p> + </tp:docstring> + </property> + + <property name="InvitationMessage" tp:name-for-bindings="Invitation_Message" + access="read" type="s"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The message that was sent to the + <tp:member-ref>InitialInviteeHandles</tp:member-ref> when they were + invited.</p> + + <p>This property SHOULD be requestable, and appear in the allowed + properties in <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.Requests" + >RequestableChannelClasses</tp:dbus-ref>, in protocols where + invitations can have an accompanying text message.</p> + + <tp:rationale> + <p>This allows invitations with a message to be sent when using + <tp:member-ref>InitialInviteeHandles</tp:member-ref> or + <tp:member-ref>InitialInviteeIDs</tp:member-ref>.</p> + </tp:rationale> + + <p>If the local user was not the initiator of this channel, the + message with which they were invited (if any) SHOULD appear in the + value of this property.</p> + + <p>This property is immutable.</p> + </tp:docstring> + </property> + + <property name="SupportsNonMerges" + tp:name-for-bindings="Supports_Non_Merges" + access="read" type="b"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p><strong>[FIXME: needs a better name; or perhaps it could be implied + by InitialInviteeHandles being requestable in XMPP/MSN but not in + GSM?]</strong></p> + + <p>If true, requests with <tp:member-ref>InitialChannels</tp:member-ref> + omitted, empty, or one element long should be expected to succeed.</p> + + <p>This property SHOULD appear in <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.Requests" + >RequestableChannelClasses</tp:dbus-ref> for + conference channels if and only if its value on those channels will + be true.</p> + + <tp:rationale> + <p>Putting this in <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.Requests" + >RequestableChannelClasses</tp:dbus-ref> means clients can find + out whether their request will succeed early enough to do + something about it.</p> + + <p>In XMPP, you can request a channel of type ROOM without + incorporating any 1-1 chats at all - indeed, this is the normal + way to do it - or as a continuation of a single 1-1 chat, and then + invite other people in later.</p> + + <p>The sense of this property is a bit awkward, but it avoids making it + an anti-capability. If the sense were inverted, then its presence in + RequestableChannelClasses would imply that the protocol <em>lacks</em> + a feature; as it stands, it is additive. (Contrast with + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type.StreamedMedia" + >ImmutableStreams</tp:dbus-ref>, which is the wrong way around for + backwards-compatibility reasons.)</p> + </tp:rationale> + + <p>If false, <tp:member-ref>InitialChannels</tp:member-ref> SHOULD be + supplied in all requests for this channel class, and contain at least + two channels. Requests where this requirement is not met SHOULD fail + with NotImplemented. + </p> + + <tp:rationale> + <p>In GSM, you can only make a conference call by merging at least + two channels. + <strong>[FIXME: the CM could conceivably fake it, but that would be + rather nasty]</strong> + </p> + </tp:rationale> + </tp:docstring> + </property> + + </interface> +</node> diff --git a/extensions/Channel_Type_Call.xml b/extensions/Channel_Type_Call.xml new file mode 100644 index 000000000..702eb1759 --- /dev/null +++ b/extensions/Channel_Type_Call.xml @@ -0,0 +1,931 @@ +<?xml version="1.0" ?> +<node name="/Channel_Type_Call" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright © 2009 Collabora Limited</tp:copyright> + <tp:copyright>Copyright © 2009 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.</p> + + <p>A Call channel can have one or more <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Call">Content.DRAFT</tp:dbus-ref> + objects, which represent the actual Media that forms the Call (e.g. an + audio content and a video content).</p> + </tp:docstring> + + <method name="Ringing" tp:name-for-bindings="Ringing"> + <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="org.freedesktop.Telepathy.Channel" + >Requested</tp:dbus-ref> property is false, and the + <tp:member-ref>CallState</tp:member-ref> is + Call_State_Pending_Initiator. While this is the case, + this method SHOULD change the + <tp:member-ref>CallFlags</tp:member-ref> to include + Call_Flag_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="org.freedesktop.Telepathy.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 Call_State_Pending_Initiator. + </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 Call_State_Pending_Receiver, accept the + incoming call; this changes the + <tp:member-ref>CallState</tp:member-ref> to Call_State_Accepted.</p> + + <p>For outgoing calls in state Call_State_Pending_Initiator, actually + call the remote contact; this changes the + <tp:member-ref>CallState</tp:member-ref> to + Call_State_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="org.freedesktop.Telepathy.Call" + >Content.DRAFT</tp:dbus-ref> whose <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Call.Content.DRAFT" + >Disposition</tp:dbus-ref> is Call_Content_Disposition_Initial, + any streams where the self-handle's sending state in <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Call.Stream.DRAFT" + >Senders</tp:dbus-ref> is Sending_State_Pending_Send + will be moved to Sending_State_Sending as if <tp:dbus-ref + namespace="org.freedesktop.Telepathy.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. + </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> + [FIXME] + </tp:docstring> + <arg direction="in" name="Content_Name" type="s"> + <tp:docstring> + The suggested name of the content to add + + <tp:rationale> + [FIXME: rationale] + </tp:rationale> + </tp:docstring> + </arg> + <arg direction="in" name="Content_Type" type="u" + tp:type="Media_Stream_Type"> + <tp:docstring> + The media type of the content to add + </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> + [FIXME: when?] + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + [FIXME: when?] + </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="org.freedesktop.Telepathy.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="org.freedesktop.Telepathy.Call" + >Content.DRAFT</tp:dbus-ref> object. + </tp:docstring> + </arg> + <arg name="Content_Type" type="u" tp:type="Media_Stream_Type"> + <tp:docstring> + The media type of the content which was added + </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="org.freedesktop.Telepathy.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="org.freedesktop.Telepathy.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="org.freedesktop.Telepathy.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 Call_State_Pending_Receiver. It SHOULD be set when + <tp:member-ref>Ringing</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 Call_State_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="org.freedesktop.Telepathy.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 Call_State_Pending_Receiver or + Call_State_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 + Call_State_Pending_Receiver or Call_State_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 + Call_State_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: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 Call_State_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 + Call_Flag_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 Call_State_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>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> + </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: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. + </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: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: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="org.freedesktop.Telepathy.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: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"> + A mapping from the remote contacts that are part of this call to flags + discribing their status. This mapping never has the local user's handle + as a key. + </tp:docstring> + </property> + + <property name="InitialTransport" tp:name-for-bindings="Initial_Transport" + type="s" access="read"> + <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. + <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> + </p> + </tp:docstring> + </property> + + <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.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="org.freedesktop.Telepathy.Channel.Type.Call.DRAFT">Contents</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">Call.DRAFT</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 = 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="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 = 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: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="MutableContents" tp:name-for-bindings="Mutable_Contents" + type="b" access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If <tt>True</tt>, 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> + + <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:handler-capability-token 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="org.freedesktop.Telepathy.Call.Stream.Interface.Media.DRAFT">Transport</tp:dbus-ref> + property is Stream_Transport_Type_GTalk_P2P.</p> + </tp:docstring> + </tp:handler-capability-token> + + <tp:handler-capability-token name="ice"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The client can implement streaming for streams whose <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Call.Stream.Interface.Media.DRAFT">Transport</tp:dbus-ref> + property is Stream_Transport_Type_ICE.</p> + </tp:docstring> + </tp:handler-capability-token> + + <tp:handler-capability-token name="wlm-8.5"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The client can implement streaming for streams whose <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Call.Stream.Interface.Media.DRAFT">Transport</tp:dbus-ref> + property is Stream_Transport_Type_WLM_8_5.</p> + </tp:docstring> + </tp:handler-capability-token> + + <tp:handler-capability-token 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="org.freedesktop.Telepathy.Call.Stream.Interface.Media.DRAFT">Transport</tp:dbus-ref> + property is Stream_Transport_Type_WLM_2009.</p> + </tp:docstring> + </tp:handler-capability-token> + + <tp:handler-capability-token name="video/h264" is-family="yes"> + <tp:docstring> + <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 + Speex, Theora and H264 by having three + handler capability tokens, + <code>org.freedesktop.Telepathy.Channel.Type.Call.DRAFT/audio/speex</code>, + <code>org.freedesktop.Telepathy.Channel.Type.Call.DRAFT/video/theora</code> and + <code>org.freedesktop.Telepathy.Channel.Type.Call.DRAFT/video/h264</code>, + in its <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client.Handler">Capabilities</tp:dbus-ref> + property.</p> + + <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:handler-capability-token> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/extensions/Connection_Future.xml b/extensions/Connection_Future.xml new file mode 100644 index 000000000..110479832 --- /dev/null +++ b/extensions/Connection_Future.xml @@ -0,0 +1,110 @@ +<?xml version="1.0" ?> +<node name="/Connection_FUTURE" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0" + > + <tp:copyright>Copyright © 2009 Collabora Limited</tp:copyright> + <tp:copyright>Copyright © 2009 Nokia Corporation</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.Connection.FUTURE" + tp:causes-havoc='experimental'> + <tp:requires interface="org.freedesktop.Telepathy.Connection"/> + + <method name="EnsureSidecar" tp:name-for-bindings="Ensure_Sidecar"> + <tp:added version="0.19.UNRELEASED"/> + + <arg direction="in" name="Main_Interface" type="s" + tp:type="DBus_Interface"> + <tp:docstring> + The "primary" interface implemented by an object attached + to a connection. For example, a Gabble plugin implementing + fine-grained control of XEP-0016 privacy lists might expose an object + implementing <tt>com.example.PrivacyLists</tt>. + </tp:docstring> + </arg> + + <arg direction="out" name="Path" type="o"> + <tp:docstring>The object path of the sidecar, exported by the same bus + name as the Connection to which it is attached.</tp:docstring> + </arg> + <arg direction="out" name="Properties" type="a{sv}" + tp:type="Qualified_Property_Value_Map"> + <tp:docstring>Immutable properties of the sidecar.</tp:docstring> + </arg> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Request an object with a particular interface providing additional + connection-specific functionality, together with its immutable + properties. These will often be implemented by plug-ins to the + connection managers; for example, support for an XMPP XEP for which + no generic Telepathy interface exists might be implemented by a + Gabble plugin exposing a sidecar with a particular interface.</p> + + <p>This method may be called at any point during the lifetime of a + connection, even before its <tp:type>Connection_Status</tp:type> + changes to Connected. It MAY take a long time to + return—perhaps it needs to wait for a connection to be established + and for all the services supported by the server to be discovered + before determining whether necessary server-side support is + available—so callers SHOULD override the default method timeout (25 + seconds) with a much higher value (perhaps even MAX_INT32, meaning + “no timeout” in recent versions of libdbus).</p> + + <tp:rationale> + <p>There is an implicit assumption that any connection + manager plugin will only want to export one “primary” object per + feature it implements, since there is a one-to-one mapping between + interface and object. This is reasonable since Sidecars are + (intended to be) analogous to extra interfaces on the connection, + providing once-per-connection shared functionality; it also makes + client code straightforward (look up the interface you care about + in a dictionary, build a proxy object from the value). More + “plural” plugins are likely to want to implement new types of + <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Channel</tp:dbus-ref> + instead.</p> + </tp:rationale> + </tp:docstring> + + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + The requested sidecar is not implemented by this connection manager, + or a necessary server-side component does not exist. (FIXME: split + these two errors out? Then again, once we list the guaranteed and + possible sidecars on a Protocol object, clients can tell the + difference themselves, because they shouldn't be calling this in the + first case.) + </tp:docstring> + </tp:error> + + <tp:error name="org.freedesktop.Telepathy.Error.ServiceBusy"> + <tp:docstring> + A server-side component needed by the requested sidecar reported it + is currently too busy, or did not respond for some + implementation-defined time. The caller may wish to try again later. + </tp:docstring> + </tp:error> + + <tp:error name="org.freedesktop.Telepathy.Error.Cancelled"> + <tp:docstring> + The connection was disconnected while the sidecar was being set up. + </tp:docstring> + </tp:error> + </method> + + </interface> +</node> diff --git a/extensions/Connection_Interface_Contact_Info.xml b/extensions/Connection_Interface_Contact_Info.xml index d08545466..2d9d8a234 100644 --- a/extensions/Connection_Interface_Contact_Info.xml +++ b/extensions/Connection_Interface_Contact_Info.xml @@ -162,7 +162,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ name="Contact_Info"/> </tp:mapping> - <signal name="ContactInfoChanged" tp:name-for-bindings="ContactInfoChanged"> + <signal name="ContactInfoChanged" tp:name-for-bindings="Contact_Info_Changed"> <arg name="Contact" type="u" tp:type="Contact_Handle"> <tp:docstring> An integer handle for the contact whose info has changed. diff --git a/extensions/Connection_Interface_Gabble_Decloak.xml b/extensions/Connection_Interface_Gabble_Decloak.xml new file mode 100644 index 000000000..3ad9e4fda --- /dev/null +++ b/extensions/Connection_Interface_Gabble_Decloak.xml @@ -0,0 +1,113 @@ +<?xml version="1.0" ?> +<node name="/Connection_Interface_Gabble_Decloak" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright © 2010 Collabora Ltd.</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.Connection.Interface.Gabble.Decloak" + tp:causes-havoc="experimental"> + <tp:added version="Gabble 0.9.UNRELEASED">(Gabble-specific)</tp:added> + <tp:requires interface="org.freedesktop.Telepathy.Connection"/> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + A simple D-Bus API for <a + href="http://xmpp.org/extensions/xep-0276.html">XEP-0276 Temporary + Presence Sharing</a>. See the XEP for more details. + </tp:docstring> + + <property name="DecloakAutomatically" + tp:name-for-bindings="Decloak_Automatically" + type="b" access="readwrite"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If true, the connection manager will automatically disclose the + local user's capabilities (and hence the fact that they are online, + but no further presence information) on request from any remote XMPP + user.</p> + + <tp:rationale> + <p>This is necessary to allow incoming calls from arbitrary + users.</p> + </tp:rationale> + + <p>This property SHOULD also be available as a connection manager + parameter, with the DBus_Property flag. The default SHOULD be false + since this constitutes a deliberate presence leak.</p> + </tp:docstring> + </property> + + <signal name="DecloakRequested" tp:name-for-bindings="Decloak_Requested"> + <tp:docstring> + Emitted when a remote contact asks for the local user's capabilities + and basic presence to be disclosed. + </tp:docstring> + + <arg name="Contact" type="u" tp:type="Contact_Handle"> + <tp:docstring> + The contact asking for presence disclosure + </tp:docstring> + </arg> + + <arg name="Reason" type="s"> + <tp:docstring> + A code indicating the reason that decloaking is requested, or the + empty string if no reason code was given. As per the proto-XEP, + well-known values are 'media' (remote contact wants to call local + user), 'text' (remote contact wants to establish a text messaging + session, perhaps end-to-end encrypted), and 'file' (remote contact + wants to send the local user a file). + </tp:docstring> + </arg> + + <arg name="Decloaked" type="b"> + <tp:docstring> + If true, the connection manager automatically disclosed the local user's + capabilities and basic presence in response to the request, and this + signal is merely for information. If false, presence was not + automatically disclosed; a user interface MAY respond by calling + <tp:member-ref>SendDirectedPresence</tp:member-ref>. + </tp:docstring> + </arg> + </signal> + + <method name="SendDirectedPresence" + tp:name-for-bindings="Send_Directed_Presence"> + <tp:docstring> + Send directed presence to a contact. This MAY be called at any time, + but will typically be used as a response to + <tp:member-ref>DecloakRequested</tp:member-ref> + </tp:docstring> + + <arg direction="in" name="Contact" type="u" tp:type="Contact_Handle"> + <tp:docstring> + The contact to send directed presence to. + </tp:docstring> + </arg> + + <arg direction="in" name="Full" type="b"> + <tp:docstring> + If true, full presence (status, message, avatar hash etc.) will be + directed to the specified contact. If false, only capabilities and + the fact that the user is online at all will be directed to the + specified contact (the local user will appear to that contact as + being in 'available' status). + </tp:docstring> + </arg> + </method> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/extensions/Gabble_Plugin_Gateways.xml b/extensions/Gabble_Plugin_Gateways.xml new file mode 100644 index 000000000..4f1f50d55 --- /dev/null +++ b/extensions/Gabble_Plugin_Gateways.xml @@ -0,0 +1,75 @@ +<?xml version="1.0" ?> +<node name="/Gabble_Plugin_Gateways" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright © 2010 Collabora Ltd.</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.Gabble.Plugin.Gateways"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A sidecar interface to register with XEP-0100 gateways.</p> + </tp:docstring> + + <method name="Register" tp:name-for-bindings="Register"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Register with a gateway, as per XEP-0100 §4.1. This method + does not allow for all the parameters that gateways can potentially + have, and indeed doesn't even allow the required or allowed + parameters to be discovered, but it should work in practice for + nearly all gateways to other IM protocols.</p> + + <tp:rationale> + <p>Username and password are enough information to sign in to + many IM protocols, and this method has a high "return on + investment" in terms of being easy to implement and easy to + write UI for.</p> + </tp:rationale> + </tp:docstring> + + <arg direction="in" type="s" name="Gateway"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The gateway (XMPP component) with which to register, e.g. + "sip-transport.example.com".</p> + </tp:docstring> + </arg> + + <arg direction="in" type="s" name="Username"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The username with which to register, in whatever format is + required by the specified gateway; for instance, this might be + a number, the username part of a SIP URI, a complete SIP URI, + etc.</p> + </tp:docstring> + </arg> + + <arg direction="in" type="s" name="Password"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The password with which to register.</p> + </tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"/> + <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> + </tp:possible-errors> + </method> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/extensions/Gabble_Plugin_Test.xml b/extensions/Gabble_Plugin_Test.xml new file mode 100644 index 000000000..a9d756981 --- /dev/null +++ b/extensions/Gabble_Plugin_Test.xml @@ -0,0 +1,27 @@ +<?xml version="1.0" ?> +<node name="/Gabble_Plugin_Test" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright © 2009 Collabora Ltd.</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.Gabble.Plugin.Test"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A sidecar interface implemented by a plugin used by the test + suite.</p> + </tp:docstring> + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/extensions/Makefile.am b/extensions/Makefile.am index 3eace1b10..19c0abd8b 100644 --- a/extensions/Makefile.am +++ b/extensions/Makefile.am @@ -2,10 +2,22 @@ tools_dir = $(top_srcdir)/tools EXTRA_DIST = \ all.xml \ + Call_Content_Codec_Offer.xml \ + Call_Content_Interface_Media.xml \ + Call_Content.xml \ + Call_Stream_Endpoint.xml \ + Call_Stream_Interface_Media.xml \ + Call_Stream.xml \ Channel_Bundle.xml \ Channel_Future.xml \ + Channel_Interface_Conference.xml \ + Channel_Type_Call.xml \ + Connection_Future.xml \ Connection_Interface_Contact_Info.xml \ + Connection_Interface_Gabble_Decloak.xml \ Channel_Type_Contact_Search.xml \ + Gabble_Plugin_Gateways.xml \ + Gabble_Plugin_Test.xml \ OLPC_Activity_Properties.xml \ OLPC_Buddy_Info.xml \ OLPC_Gadget.xml \ @@ -48,8 +60,8 @@ XSLTPROCFLAGS = --nonet --novalid _gen/all.xml: all.xml $(wildcard *.xml) Makefile.am @$(mkdir_p) _gen - $(AM_V_GEN)$(XSLTPROC) $(XSLTPROCFLAGS) --xinclude $(tools_dir)/identity.xsl \ - $< > $@ + $(AM_V_GEN)$(PYTHON) $(tools_dir)/xincludator.py \ + $< > $@.tmp && mv $@.tmp $@ extensions.html: _gen/all.xml $(tools_dir)/doc-generator.xsl Makefile.am $(AM_V_GEN)$(XSLTPROC) $(XSLTPROCFLAGS) \ diff --git a/extensions/OLPC_Activity_Properties.xml b/extensions/OLPC_Activity_Properties.xml index 9f1d3d04e..21d6e3327 100644 --- a/extensions/OLPC_Activity_Properties.xml +++ b/extensions/OLPC_Activity_Properties.xml @@ -19,7 +19,7 @@ Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA</p> <interface name="org.laptop.Telepathy.ActivityProperties"> <tp:requires interface="org.freedesktop.Telepathy.Connection"/> - <method name="SetProperties"> + <method name="SetProperties" tp:name-for-bindings="Set_Properties"> <arg direction="in" name="room" type="u"> <tp:docstring> An integer handle representing the room of the activity @@ -41,7 +41,7 @@ Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA</p> </tp:possible-errors> </method> - <method name="GetProperties"> + <method name="GetProperties" tp:name-for-bindings="Get_Properties"> <arg direction="in" name="room" type="u"> <tp:docstring> An integer handle for the activity's room to request his properties for @@ -61,7 +61,8 @@ Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA</p> </tp:possible-errors> </method> - <signal name="ActivityPropertiesChanged"> + <signal name="ActivityPropertiesChanged" + tp:name-for-bindings="Activity_Properties_Changed"> <arg name="room" type="u"> <tp:docstring> An integer handle representing the room of the activity diff --git a/extensions/OLPC_Buddy_Info.xml b/extensions/OLPC_Buddy_Info.xml index 339da95ad..b57d3b2d0 100644 --- a/extensions/OLPC_Buddy_Info.xml +++ b/extensions/OLPC_Buddy_Info.xml @@ -19,7 +19,7 @@ Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA</p> <interface name="org.laptop.Telepathy.BuddyInfo"> <tp:requires interface="org.freedesktop.Telepathy.Connection"/> - <method name="SetProperties"> + <method name="SetProperties" tp:name-for-bindings="Set_Properties"> <arg direction="in" name="properties" type="a{sv}"> <tp:docstring> A dictionary mapping information names to the desired values. @@ -39,7 +39,7 @@ Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA</p> </tp:possible-errors> </method> - <method name="GetProperties"> + <method name="GetProperties" tp:name-for-bindings="Get_Properties"> <arg direction="in" name="contact" type="u"> <tp:docstring> An integer handle for the contact to request his properties for @@ -59,7 +59,7 @@ Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA</p> </tp:possible-errors> </method> - <signal name="PropertiesChanged"> + <signal name="PropertiesChanged" tp:name-for-bindings="Properties_Changed"> <arg name="contact" type="u"> <tp:docstring> An integer handle representing the contact @@ -89,7 +89,7 @@ Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA</p> <tp:member type="u" tp:type="Room_Handle" name="room"/> </tp:struct> - <method name="SetActivities"> + <method name="SetActivities" tp:name-for-bindings="Set_Activities"> <arg direction="in" name="activities" type="a(su)" tp:type="Activity[]"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> An array of structs containing: @@ -108,7 +108,7 @@ Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA</p> </tp:possible-errors> </method> - <method name="GetActivities"> + <method name="GetActivities" tp:name-for-bindings="Get_Activities"> <arg direction="in" name="contact" type="u"> <tp:docstring> An integer handle for the contact whose activities are to be returned @@ -132,7 +132,7 @@ Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA</p> </tp:possible-errors> </method> - <signal name="ActivitiesChanged"> + <signal name="ActivitiesChanged" tp:name-for-bindings="Activities_Changed"> <arg name="contact" type="u"> <tp:docstring> An integer handle representing the contact @@ -153,7 +153,8 @@ Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA</p> </tp:docstring> </signal> - <method name="SetCurrentActivity"> + <method name="SetCurrentActivity" + tp:name-for-bindings="Set_Current_Activity"> <arg direction="in" name="activity" type="s"> <tp:docstring> The identifier of the activity, or the empty string if there is no @@ -175,7 +176,8 @@ Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA</p> </tp:possible-errors> </method> - <method name="GetCurrentActivity"> + <method name="GetCurrentActivity" + tp:name-for-bindings="Get_Current_Activity"> <arg direction="in" name="contact" type="u"> <tp:docstring> An integer handle for the contact whose current activity is to be @@ -201,7 +203,8 @@ Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA</p> </tp:possible-errors> </method> - <signal name="CurrentActivityChanged"> + <signal name="CurrentActivityChanged" + tp:name-for-bindings="Current_Activity_Changed"> <arg name="contact" type="u"> <tp:docstring> An integer handle representing the contact diff --git a/extensions/OLPC_Channel_Interface_View.xml b/extensions/OLPC_Channel_Interface_View.xml index b2588c6b5..0265538d6 100644 --- a/extensions/OLPC_Channel_Interface_View.xml +++ b/extensions/OLPC_Channel_Interface_View.xml @@ -19,7 +19,7 @@ Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA</p> <interface name="org.laptop.Telepathy.Channel.Interface.View"> <tp:requires interface="org.freedesktop.Telepathy.Channel"/> - <signal name="ActivitiesChanged"> + <signal name="ActivitiesChanged" tp:name-for-bindings="Activities_Changed"> <arg name="added" type="a(su)" tp:type="Activity[]"> <tp:docstring> Room handles of the added activities @@ -35,7 +35,7 @@ Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA</p> </tp:docstring> </signal> - <signal name="BuddiesChanged"> + <signal name="BuddiesChanged" tp:name-for-bindings="Buddies_Changed"> <arg name="added" type="au"> <tp:docstring> Handles of the added buddies diff --git a/extensions/OLPC_Gadget.xml b/extensions/OLPC_Gadget.xml index 30ef02d11..8e76fdfea 100644 --- a/extensions/OLPC_Gadget.xml +++ b/extensions/OLPC_Gadget.xml @@ -21,7 +21,7 @@ Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA</p> <tp:requires interface="org.laptop.Telepathy.BuddyInfo"/> <tp:requires interface="org.laptop.Telepathy.ActivityProperties"/> - <method name="Publish"> + <method name="Publish" tp:name-for-bindings="Publish"> <arg direction="in" name="publish" type="b"> <tp:docstring> A boolean indicating if we want to publish your informations to Gadget. @@ -35,7 +35,7 @@ Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA</p> </tp:possible-errors> </method> - <signal name="GadgetDiscovered"> + <signal name="GadgetDiscovered" tp:name-for-bindings="Gadget_Discovered"> <tp:docstring> Signal emitted when CM discovers the Gadget component. </tp:docstring> diff --git a/extensions/all.xml b/extensions/all.xml index a2055df48..81a82206f 100644 --- a/extensions/all.xml +++ b/extensions/all.xml @@ -44,6 +44,20 @@ Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA</p> <xi:include href="Channel_Type_Contact_Search.xml"/> <xi:include href="Connection_Interface_Contact_Info.xml"/> +<xi:include href="Connection_Interface_Gabble_Decloak.xml"/> +<xi:include href="Channel_Interface_Conference.xml"/> +<xi:include href="Connection_Future.xml"/> + +<xi:include href="Gabble_Plugin_Gateways.xml"/> +<xi:include href="Gabble_Plugin_Test.xml"/> + +<xi:include href="Call_Content.xml" /> +<xi:include href="Call_Content_Codec_Offer.xml" /> +<xi:include href="Call_Content_Interface_Media.xml" /> +<xi:include href="Call_Stream.xml" /> +<xi:include href="Call_Stream_Endpoint.xml" /> +<xi:include href="Call_Stream_Interface_Media.xml" /> +<xi:include href="Channel_Type_Call.xml" /> <tp:generic-types> <tp:external-type name="Contact_Handle" type="u" @@ -94,6 +108,73 @@ Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA</p> <tp:external-type name="Requestable_Channel_Class" type="(a{sv}as)" from="Telepathy specification"/> + <tp:external-type name="Connection_Status" type="u" + from="Telepathy specification"/> + + <!-- use types from Channel_Type_Streamed_Media.xml --> + <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> + + <!-- use types from generic-types.xml --> + <tp:struct name="Socket_Address_IP" array-name="Socket_Address_IP_List"> + <tp:docstring>An IP address and port.</tp:docstring> + <tp:member type="s" name="Address"> + <tp:docstring>Either a dotted-quad IPv4 address literal as for + <tp:type>Socket_Address_IPv4</tp:type>, or an RFC2373 IPv6 address + as for <tp:type>Socket_Address_IPv6</tp:type>. + </tp:docstring> + </tp:member> + <tp:member type="q" name="Port"> + <tp:docstring>The TCP or UDP port number.</tp:docstring> + </tp:member> + </tp:struct> + + <tp:struct name="Socket_Address_IPv4"> + <tp:docstring>An IPv4 address and port.</tp:docstring> + <tp:member type="s" name="Address"> + <tp:docstring>A dotted-quad IPv4 address literal: four ASCII decimal + numbers, each between 0 and 255 inclusive, e.g. + "192.168.0.1".</tp:docstring> + </tp:member> + <tp:member type="q" name="Port"> + <tp:docstring>The TCP or UDP port number.</tp:docstring> + </tp:member> + </tp:struct> + + <tp:struct name="Socket_Address_IPv6"> + <tp:docstring>An IPv6 address and port.</tp:docstring> + <tp:member type="s" name="Address"> + <tp:docstring>An IPv6 address literal as specified by RFC2373 + section 2.2, e.g. "2001:DB8::8:800:200C:4171".</tp:docstring> + </tp:member> + <tp:member type="q" name="Port"> + <tp:docstring>The TCP or UDP port number.</tp:docstring> + </tp:member> + </tp:struct> + + <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:simple-type name="Handle" type="u" array-name="Handle_List"> + <tp:docstring>An unsigned 32-bit integer representing a + handle</tp:docstring> + </tp:simple-type> </tp:generic-types> </tp:spec> |