diff options
| author | Simon McVittie <simon.mcvittie@collabora.co.uk> | 2009-02-10 12:25:37 +0000 |
|---|---|---|
| committer | Simon McVittie <simon.mcvittie@collabora.co.uk> | 2009-02-10 12:25:37 +0000 |
| commit | ff0d897da941d48d8e9bbe8e8098a4e669da873e (patch) | |
| tree | 3dbced9667a089de6c070ed77b992702fce3eeba /spec | |
| parent | 36ee092d3a8fe1d1dbaf364e00f1892cd0781604 (diff) | |
Update to spec 0.17.19 and enable File Transfer code generation
This changes the ABI of Tubes channels' auto-generated code. Better
now than later...
Diffstat (limited to 'spec')
35 files changed, 2075 insertions, 288 deletions
diff --git a/spec/Account.xml b/spec/Account.xml index cb803214..991dcbda 100644 --- a/spec/Account.xml +++ b/spec/Account.xml @@ -369,10 +369,14 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <property name="Connection" tp:name-for-bindings="Connection" type="o" access="read"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - Either the object path of the <tp:dbus-ref + <p>Either the object path of the <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref> to this account, or the special value <code>'/'</code> if there is no - connection. + connection.</p> + + <p>If this object path is not '/', the Connection's well-known bus + name can be derived from this object path by removing the first '/' + and replacing subsequent '/' characters with '.'.</p> <tp:rationale> Object paths aren't nullable, so we can't use an empty string. @@ -465,7 +469,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. result of <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection">GetSelfHandle</tp:dbus-ref> for an active connection).</p> - + <p>It is unspecified whether this user ID is globally unique.</p> <tp:rationale> diff --git a/spec/Channel.xml b/spec/Channel.xml index 5a40f2f5..7b4a7ad8 100644 --- a/spec/Channel.xml +++ b/spec/Channel.xml @@ -220,7 +220,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <method name="GetChannelType" tp:name-for-bindings="Get_Channel_Type"> <tp:deprecated version="0.17.7">Use the ChannelType property if possible.</tp:deprecated> - <arg direction="out" type="s" tp:type="DBus_Interface"> + <arg direction="out" type="s" tp:type="DBus_Interface" + name="Channel_Type"> <tp:docstring>The interface name</tp:docstring> </arg> <tp:docstring> @@ -238,12 +239,13 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <method name="GetHandle" tp:name-for-bindings="Get_Handle"> <tp:deprecated version="0.17.7">Use the TargetHandleType and TargetHandle properties if possible.</tp:deprecated> - <arg direction="out" type="u" tp:type="Handle_Type"> + <arg direction="out" type="u" tp:type="Handle_Type" + name="Target_Handle_Type"> <tp:docstring> The same as TargetHandleType. </tp:docstring> </arg> - <arg direction="out" type="u" tp:type="Handle"> + <arg direction="out" type="u" tp:type="Handle" name="Target_Handle"> <tp:docstring> The same as TargetHandle. </tp:docstring> @@ -266,7 +268,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <method name="GetInterfaces" tp:name-for-bindings="Get_Interfaces"> <tp:deprecated version="0.17.7">Use the Interfaces property if possible.</tp:deprecated> - <arg direction="out" type="as" tp:type="DBus_Interface[]"> + <arg direction="out" type="as" tp:type="DBus_Interface[]" + name="Interfaces"> <tp:docstring> An array of the D-Bus interface names </tp:docstring> diff --git a/spec/Channel_Dispatcher.xml b/spec/Channel_Dispatcher.xml index 2c07305e..c77873db 100644 --- a/spec/Channel_Dispatcher.xml +++ b/spec/Channel_Dispatcher.xml @@ -160,7 +160,7 @@ </tp:docstring> </arg> - <arg direction="in" name="User_Action_Time" type="t" + <arg direction="in" name="User_Action_Time" type="x" tp:type="Unix_Timestamp64"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The time at which user action occurred, or 0 if this channel @@ -280,7 +280,7 @@ </tp:docstring> </arg> - <arg direction="in" name="User_Action_Time" type="t" + <arg direction="in" name="User_Action_Time" type="x" tp:type="Unix_Timestamp64"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The time at which user action occurred, or 0 if this channel diff --git a/spec/Channel_Interface_Group.xml b/spec/Channel_Interface_Group.xml index ffa01154..490258fc 100644 --- a/spec/Channel_Interface_Group.xml +++ b/spec/Channel_Interface_Group.xml @@ -91,17 +91,20 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ this method and GetLocalPendingMembersWithInfo if necessary. </tp:deprecated> - <arg direction="out" type="au" tp:type="Contact_Handle[]"> + <arg direction="out" type="au" tp:type="Contact_Handle[]" + name="Members"> <tp:docstring> array of handles of current members </tp:docstring> </arg> - <arg direction="out" type="au" tp:type="Contact_Handle[]"> + <arg direction="out" type="au" tp:type="Contact_Handle[]" + name="Local_Pending"> <tp:docstring> array of handles of local pending members </tp:docstring> </arg> - <arg direction="out" type="au" tp:type="Contact_Handle[]"> + <arg direction="out" type="au" tp:type="Contact_Handle[]" + name="Remote_Pending"> <tp:docstring> array of handles of remote pending members </tp:docstring> @@ -254,7 +257,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </property> <method name="GetGroupFlags" tp:name-for-bindings="Get_Group_Flags"> - <arg direction="out" type="u" tp:type="Channel_Group_Flags"> + <arg direction="out" type="u" tp:type="Channel_Group_Flags" + name="Group_Flags"> <tp:docstring> The value of the GroupFlags property </tp:docstring> @@ -340,7 +344,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ A list of integer handles representing members of the channel </tp:docstring> </arg> - <arg direction="out" type="au" tp:type="Contact_Handle[]"> + <arg direction="out" type="au" tp:type="Contact_Handle[]" name="Owners"> <tp:docstring> An array of integer handles representing the owner handles of the given room members, in the same order, or 0 if the @@ -379,7 +383,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <method name="GetLocalPendingMembers" tp:name-for-bindings="Get_Local_Pending_Members"> - <arg direction="out" type="au" tp:type="Contact_Handle[]"/> + <arg direction="out" type="au" tp:type="Contact_Handle[]" + name="Handles"/> <tp:docstring> Returns the To_Be_Added handle (only) for each structure in the <tp:member-ref>LocalPendingMembers</tp:member-ref> property. @@ -400,7 +405,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:docstring> <tp:deprecated version="0.17.6">Use the LocalPendingMembers property, if Channel_Group_Flag_Properties is present.</tp:deprecated> - <arg direction="out" type="a(uuus)" tp:type="Local_Pending_Info[]"> + <arg direction="out" type="a(uuus)" tp:type="Local_Pending_Info[]" + name="Info"> <tp:docstring> An array of structs containing: <ul> @@ -452,7 +458,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </property> <method name="GetMembers" tp:name-for-bindings="Get_Members"> - <arg direction="out" type="au" tp:type="Contact_Handle[]"/> + <arg direction="out" type="au" tp:type="Contact_Handle[]" + name="Handles"/> <tp:docstring> Returns the <tp:member-ref>Members</tp:member-ref> property. </tp:docstring> @@ -476,7 +483,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <method name="GetRemotePendingMembers" tp:name-for-bindings="Get_Remote_Pending_Members"> - <arg direction="out" type="au" tp:type="Contact_Handle[]"/> + <arg direction="out" type="au" tp:type="Contact_Handle[]" + name="Handles"/> <tp:docstring> Returns an array of handles representing contacts who have been invited to the channel and are awaiting remote approval. @@ -524,7 +532,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </property> <method name="GetSelfHandle" tp:name-for-bindings="Get_Self_Handle"> - <arg direction="out" type="u" tp:type="Contact_Handle"/> + <arg direction="out" type="u" tp:type="Contact_Handle" + name="Self_Handle"/> <tp:docstring> Returns the value of the <tp:member-ref>SelfHandle</tp:member-ref> property. @@ -563,29 +572,81 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:docstring> </tp:enumvalue> <tp:enumvalue suffix="Offline" value="1"> - <tp:docstring> - The change is due to a user going offline. Also used when - user is already offline, but this wasn't known previously. + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The change is due to a user going offline. Also used when + user is already offline, but this wasn't known previously.</p> + + <p>If a one-to-one <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type">StreamedMedia</tp:dbus-ref> + call fails because the contact being called is offline, the + connection manager SHOULD indicate this by removing both the + <tp:member-ref>SelfHandle</tp:member-ref> and the other contact's + handle from the Group interface with reason Offline.</p> + + <tp:rationale> + For 1-1 calls, the call terminates as a result of removing the + remote contact, so the SelfHandle should be removed at the same + time as the remote contact and for the same reason. + </tp:rationale> + + <p>If a handle is removed from a group for this reason, the + equivalent D-Bus error is + <code>org.freedesktop.Telepathy.Error.Offline</code>.</p> </tp:docstring> </tp:enumvalue> <tp:enumvalue suffix="Kicked" value="2"> - <tp:docstring> - The change is due to a kick operation. + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The change is due to a kick operation.</p> + + <p>If the <tp:member-ref>SelfHandle</tp:member-ref> is removed + from a group for this reason, the equivalent D-Bus error is + <code>org.freedesktop.Telepathy.Error.Channel.Kicked</code>. + </p> </tp:docstring> </tp:enumvalue> <tp:enumvalue suffix="Busy" value="3"> - <tp:docstring> - The change is due to a busy indication. + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The change is due to a busy indication.</p> + + <p>If a one-to-one <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type">StreamedMedia</tp:dbus-ref> + call fails because the contact being called is busy, the + connection manager SHOULD indicate this by removing both the + <tp:member-ref>SelfHandle</tp:member-ref> and the other contact's + handle from the Group interface with reason Busy.</p> + + <tp:rationale> + For 1-1 calls, the call terminates as a result of removing the + remote contact, so the SelfHandle should be removed at the same + time as the remote contact and for the same reason. + </tp:rationale> + + <p>If the <tp:member-ref>SelfHandle</tp:member-ref> is removed + from a group for this reason, the equivalent D-Bus error is + <code>org.freedesktop.Telepathy.Error.Busy</code>. + </p> </tp:docstring> </tp:enumvalue> <tp:enumvalue suffix="Invited" value="4"> <tp:docstring> - The change is due to an invitation. + The change is due to an invitation. This reason SHOULD only be used + when contacts are added to the remote-pending set (to indicate that + the contact has been invited) or to the members (to indicate that + the contact has accepted the invitation). + + <tp:rationale> + Otherwise, what would it mean? + </tp:rationale> </tp:docstring> </tp:enumvalue> <tp:enumvalue suffix="Banned" value="5"> - <tp:docstring> - The change is due to a kick+ban operation. + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The change is due to a kick+ban operation.</p> + + <p>If the <tp:member-ref>SelfHandle</tp:member-ref> is removed + from a group for this reason, the equivalent D-Bus error is + <code>org.freedesktop.Telepathy.Error.Channel.Banned</code>. + </p> </tp:docstring> </tp:enumvalue> <tp:enumvalue suffix="Error" value="6"> @@ -594,18 +655,53 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:docstring> </tp:enumvalue> <tp:enumvalue suffix="Invalid_Contact" value="7"> - <tp:docstring> - The change is because the requested contact does not exist. + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The change is because the requested contact does not exist.</p> + + <p>For instance, if the user invites a nonexistent contact to a + chatroom or attempts to call a nonexistent contact, this could + be indicated by the CM adding that contact's handle to + remote-pending for reason None or Invited, then removing it for + reason Invalid_Contact. In the case of a 1-1 StreamedMedia + call, the CM SHOULD remove the self handle from the Group + in the same signal.</p> + + <tp:rationale> + For 1-1 calls, the call terminates as a result of removing the + remote contact, so the SelfHandle should be removed at the same + time as the remote contact and for the same reason. + </tp:rationale> + + <p>If a contact is removed from a group for this reason, the + equivalent D-Bus error is + <code>org.freedesktop.Telepathy.Error.DoesNotExist</code>. + </p> </tp:docstring> </tp:enumvalue> <tp:enumvalue suffix="No_Answer" value="8"> - <tp:docstring> - The change is because the requested contact did not respond. + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The change is because the requested contact did not respond.</p> + + <p>If a one-to-one <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type">StreamedMedia</tp:dbus-ref> + call fails because the contact being called did not respond, the + connection manager SHOULD indicate this by removing both the + <tp:member-ref>SelfHandle</tp:member-ref> and the other contact's + handle from the Group interface with reason No_Answer.</p> + + <tp:rationale> + Documenting existing practice. + </tp:rationale> + + <p>If a contact is removed from a group for this reason, the + equivalent D-Bus error is + <code>org.freedesktop.Telepathy.Error.NoAnswer</code>. + </p> </tp:docstring> </tp:enumvalue> <tp:enumvalue suffix="Renamed" value="9"> - <tp:docstring> - The change is because a contact's unique identifier changed. + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The change is because a contact's unique identifier changed. There must be exactly one handle in the removed set and exactly one handle in one of the added sets. The <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface.Renaming">Renamed</tp:dbus-ref> @@ -613,13 +709,18 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface">Renaming</tp:dbus-ref> interface will have been emitted for the same handles, - shortly before this <tp:member-ref>MembersChanged</tp:member-ref> signal is emitted. + shortly before this <tp:member-ref>MembersChanged</tp:member-ref> signal is emitted.</p> </tp:docstring> </tp:enumvalue> <tp:enumvalue suffix="Permission_Denied" value="10"> - <tp:docstring> - The change is because there was no permission to contact the - requested handle. + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The change is because there was no permission to contact the + requested handle.</p> + + <p>If a contact is removed from a group for this reason, the + equivalent D-Bus error is + <code>org.freedesktop.Telepathy.Error.PermissionDenied</code>. + </p> </tp:docstring> </tp:enumvalue> <tp:enumvalue suffix="Separated" value="11"> @@ -648,6 +749,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ the group with reason Separated. Application protocols in Tubes should be prepared to cope with this situation. </p> + + <p>The <tp:member-ref>SelfHandle</tp:member-ref> SHOULD NOT be + removed from channels with this reason.</p> </tp:docstring> </tp:enumvalue> </tp:enum> @@ -928,6 +1032,14 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ should be emitted when information is retrieved from the server, or changes occur.</p> + <p>If the <tp:member-ref>MembersChanged</tp:member-ref> or + <tp:member-ref>MembersChangedDetailed</tp:member-ref> signal indicates + that the <tp:member-ref>SelfHandle</tp:member-ref> has been removed from + the channel, and the channel subsequently emits <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">Closed</tp:dbus-ref>, + clients SHOULD consider the details given in the MembersChanged or + MembersChangedDetailed signal to be the reason why the channel closed.</p> + <p>Addition of members to the channel may be requested by using <tp:member-ref>AddMembers</tp:member-ref>. If remote acknowledgement is required, use of the AddMembers method will cause diff --git a/spec/Channel_Interface_Media_Signalling.xml b/spec/Channel_Interface_Media_Signalling.xml index acbe7474..82493316 100644 --- a/spec/Channel_Interface_Media_Signalling.xml +++ b/spec/Channel_Interface_Media_Signalling.xml @@ -22,6 +22,41 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <tp:requires interface="org.freedesktop.Telepathy.Channel"/> <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.StreamedMedia"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An interface for signalling a channel containing synchronised media + sessions which can contain an arbitrary number of streams. The + presence of this interface on a Channel indicates that the connection + manager will not carry out the actual streaming for this channel, + and that the client handling the channel is responsible for doing + so; in most cases we recommend doing this by using the + telepathy-farsight library.</p> + + <tp:rationale> + <p>Streaming audio and (particularly) video requires a high level of + integration with the UI, and having the connection manager act as + a proxy would be likely to introduce unacceptable latency. As a + result, audio/video streaming is offloaded into the client + where possible, as an exception to the general design of + Telepathy.</p> + </tp:rationale> + + <p>The negotiation interface is based on the API of the + <a href="http://farsight.freedesktop.org/">Farsight</a> library. + This, in turn, is based upon the IETF MMusic ICE drafts, where + connections are established by signalling potential connection + candidates to the peer until a usable connection is found, and + codecs are negotiated with an SDP-style offer and answer. However, + the principles should be applicable to other media streaming methods + and the API re-used without difficulty.</p> + + <p>Note that the naming conventions used in the MediaStreamHandler + and MediaSessionHandler interfaces are rather confusing; methods + have signal-like names and signals have method-like names, due to + the API being based rather too closely on that of Farsight. This + is for historical reasons and will be fixed in a future release + of the Telepathy specification.</p> + </tp:docstring> + <tp:simple-type name="Media_Session_Type" type="s"> <tp:docstring>The type of a media session. Currently, the only supported value is "rtp".</tp:docstring> @@ -41,7 +76,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <method name="GetSessionHandlers" tp:name-for-bindings="Get_Session_Handlers"> - <arg direction="out" type="a(os)" tp:type="Media_Session_Handler_Info[]"/> + <arg direction="out" type="a(os)" tp:type="Media_Session_Handler_Info[]" + name="Session_Handlers"/> <tp:docstring> Returns all currently active session handlers on this channel as a list of (session_handler_path, type). @@ -104,17 +140,6 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:docstring> </tp:property> - <tp:docstring> - An interface for signalling a channel containing synchronised media - sessions which can contain an arbitrary number of streams. The negotiation - interface is based closely around the API of the Farsight library - (http://farsight.sourceforge.net/). This in turn is based upon the IETF - MMusic ICE drafts where connections are established by signalling potential - connection candidates to the peer until a usable connection is found, and - codecs are negotiated with an SDP-style offer and answer. However, the - principles should be applicable to other media streaming methods and the - API re-used without difficulty. - </tp:docstring> </interface> </node> <!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Channel_Interface_Media_Signalling_Future.xml b/spec/Channel_Interface_Media_Signalling_Future.xml new file mode 100644 index 00000000..e1d2d25f --- /dev/null +++ b/spec/Channel_Interface_Media_Signalling_Future.xml @@ -0,0 +1,189 @@ +<?xml version="1.0" ?> +<node name="/Channel_Interface_Media_Signalling_Future" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright> Copyright (C) 2009 Collabora Limited </tp:copyright> + <tp:copyright> Copyright (C) 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.MediaSignalling.FUTURE"> + <tp:requires interface="org.freedesktop.Telepathy.Channel"/> + <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.StreamedMedia"/> + <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.MediaSignalling"/> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>This interface contains functionality which we intend to incorporate + into the <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Channel.Interface.MediaSignalling</tp:dbus-ref> + interface in future. It should be considered to be conceptually part + of the core MediaSignalling interface, but without API or ABI + guarantees.</p> + + <tp:rationale> + <p>The rationale is the same as for <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Channel.FUTURE</tp:dbus-ref>.</p> + </tp:rationale> + </tp:docstring> + + <property name="ICETransportAvailable" + tp:name-for-bindings="ICE_Transport_Available" + type="b" access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>True if this channel supports the use of the ICE-UDP transport + (<a href="http://xmpp.org/extensions/xep-0176.html">XEP-0176</a>, + <a href="http://tools.ietf.org/html/draft-ietf-mmusic-ice">ICE RFC + draft)</a>. Various other transports have boolean properties + that work in the same way as this one, so this description covers + all such transports.</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> + + <p>Connection managers capable of signalling streamed media calls to + contacts SHOULD include the properties representing all supported + transports in the allowed properties list of the channel class + in <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">RequestableChannelClasses</tp:dbus-ref> + that advertises support for streamed media channels.</p> + + <p>Similarly, connection managers that support the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface">ContactCapabilities.DRAFT</tp:dbus-ref> + interface SHOULD include all supported transports in the allowed + properties list of the channel class that advertises a contact's + ability to receive streamed media calls.</p> + + <p>Clients that are able to receive calls with particular NAT + traversal mechanisms MAY include the following filters if + calling <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities.DRAFT">SetSelfCapabilities</tp:dbus-ref> + (clients of a <tp:dbus-ref + namespace="org.freedesktop.Telepathy">ChannelDispatcher.DRAFT</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.DRAFT">HandlerChannelFilter</tp:dbus-ref> + properties):</p> + + <ul> + <li>{ ChannelType = StreamedMedia, ICETransportAvailable = true } + if the ICE transport is supported</li> + <li>{ ChannelType = StreamedMedia, RawUDPTransportAvailable = true } + if the raw UDP transport is supported</li> + <li>... and so on, one filter per available transport.</li> + </ul> + + <p>Connection managers MAY use this information to adjust the + transports for which they advertise support to other contacts. + If a client has indicated support for any particular transports, + the connection manager SHOULD advertise support for + each transport that is supported by any client, and also + supported by the CM itself.</p> + + <tp:rationale> + <p>This minimizes the possibility that a call will be started that + cannot in fact succeed, because the intersection of the contacts' + available transports is empty.</p> + </tp:rationale> + + <p>If no client has mentioned any of the transports known to the + connection manager in a call to SetSelfCapabilities, the connection + manager SHOULD advertise support for every transport that it can + signal.</p> + + <tp:rationale> + <p>This simplifies implementation on integrated platforms like Maemo, + where it can be assumed that client libraries will support all the + "standard" transports known to any connection manager, and + lowers the "barrier to entry" for new Telepathy clients.</p> + </tp:rationale> + + <p>Clients making outgoing calls for which the same client that made + the request will handle the streaming MAY indicate their ability or + inability to handle particular transports by including + <code>ICETransportAvailable = true</code>, + <code>RawUDPTransportAvailable = false</code>, etc. + in the request properties parameter of their call to <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">EnsureChannel</tp:dbus-ref> + or similar functions. When they do so, the connection manager + SHOULD attempt to use a transport that the client has indicated + it is able to handle; if this is not possible, the connection + manager SHOULD raise an error instead of creating a channel.</p> + + <tp:rationale> + <p>This enables such clients to restrict the CM to the subset of + transports supported by that particular client.</p> + </tp:rationale> + + <p>Clients making outgoing calls for which they will not themselves + handle the streaming (e.g. an address book starting a call which + will be streamed by a separate call UI) SHOULD NOT include those + properties in the request.</p> + + <tp:rationale> + <p>In general, such a client can't know the capabilities of the + streaming implementation, or even which streaming implementation + will be used.</p> + </tp:rationale> + + <p>In the absence of any indication of supported transports from the + client, the connection manager SHOULD assume that the transports + indicated by calling SetSelfCapabilities are available. If + no transports were indicated as supported by calling + SetSelfCapabilities either, it SHOULD assume that any transport + that it can signal will be acceptable.</p> + + <p>If this property, or any of the similar transport availability + properties, 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> + </tp:docstring> + </property> + + <property name="RawUDPTransportAvailable" + tp:name-for-bindings="Raw_UDP_Transport_Available" + type="b" access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The same as <tp:member-ref>ICETransportAvailable</tp:member-ref>, + but for raw UDP streaming as described by <a + href="http://xmpp.org/extensions/xep-0177.html">XEP-0177</a>.</p> + </tp:docstring> + </property> + + <property name="GoogleP2PTransportAvailable" + tp:name-for-bindings="Google_P2P_Transport_Available" + type="b" access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The same as <tp:member-ref>ICETransportAvailable</tp:member-ref>, + but for the variant of ICE used by the Google Talk peer-to-peer + connectivity establishment mechanism (as implemented in libjingle + 0.3).</p> + </tp:docstring> + </property> + + <property name="MSNTransportAvailable" + tp:name-for-bindings="MSN_Transport_Available" + type="b" access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The same as <tp:member-ref>ICETransportAvailable</tp:member-ref>, + but for the variant of ICE used by MSN.</p> + </tp:docstring> + </property> + + </interface> +</node> diff --git a/spec/Channel_Interface_Messages.xml b/spec/Channel_Interface_Messages.xml index 10785042..8cdee3c8 100644 --- a/spec/Channel_Interface_Messages.xml +++ b/spec/Channel_Interface_Messages.xml @@ -252,13 +252,13 @@ USA.</p> the mid: and cid: URI schemes. If omitted, there is no suitable token.</dd> - <dt>message-sent (t - <tp:type>Unix_Timestamp64</tp:type>)</dt> + <dt>message-sent (x - <tp:type>Unix_Timestamp64</tp:type>)</dt> <dd>The time the message was sent (if unavailable, the time it arrived at a central server MAY be used). Omitted if no reasonable approximation is available; SHOULD always be present on outgoing messages.</dd> - <dt>message-received (t - <tp:type>Unix_Timestamp64</tp:type>)</dt> + <dt>message-received (x - <tp:type>Unix_Timestamp64</tp:type>)</dt> <dd>The time the message was received locally. SHOULD always be present.</dd> @@ -797,7 +797,8 @@ USA.</p> </tp:docstring> </arg> - <arg direction="out" type="s" tp:type="Sent_Message_Token"> + <arg direction="out" type="s" tp:type="Sent_Message_Token" + name="Token"> <tp:docstring> An opaque token used to match any incoming delivery or failure reports against this message, or an empty string if the message diff --git a/spec/Channel_Interface_Password.xml b/spec/Channel_Interface_Password.xml index bfc617ab..720849a8 100644 --- a/spec/Channel_Interface_Password.xml +++ b/spec/Channel_Interface_Password.xml @@ -31,7 +31,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. </tp:flag> </tp:flags> <method name="GetPasswordFlags" tp:name-for-bindings="Get_Password_Flags"> - <arg direction="out" type="u" tp:type="Channel_Password_Flags"> + <arg direction="out" type="u" tp:type="Channel_Password_Flags" + name="Password_Flags"> <tp:docstring> An integer with the logical OR of all the flags set (values of ChannelPasswordFlags) @@ -71,7 +72,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. The password </tp:docstring> </arg> - <arg direction="out" type="b"> + <arg direction="out" type="b" name="Correct"> A boolean indicating whether or not the password was correct </arg> <tp:docstring> diff --git a/spec/Channel_Interface_Tube.xml b/spec/Channel_Interface_Tube.xml index 8e1ffab3..b2d0f318 100644 --- a/spec/Channel_Interface_Tube.xml +++ b/spec/Channel_Interface_Tube.xml @@ -58,7 +58,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. SRV (RFC 2782) Service Types http://www.dns-sd.org/ServiceTypes.html</a>): <code>{'u': 'username', 'p': 'password', 'path': 'path'}</code></p> - <p>When requesting a channel with + <p>When requesting a channel with <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>, this property MAY be included in the request. If it is not included in the request, the connection manager MUST consider the property to be @@ -68,11 +68,11 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. </tp:docstring> </property> - <property name="Status" type="u" tp:type="Tube_Channel_State" access="read" - tp:name-for-bindings="Status"> + <property name="State" type="u" tp:type="Tube_Channel_State" access="read" + tp:name-for-bindings="State"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Status of the tube in this channel.</p> - <p>When requesting a channel with + <p>State of the tube in this channel.</p> + <p>When requesting a channel with <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>, this property MUST NOT be included in the request.</p> </tp:docstring> diff --git a/spec/Channel_Request.xml b/spec/Channel_Request.xml index 956eee1c..bf1bd38c 100644 --- a/spec/Channel_Request.xml +++ b/spec/Channel_Request.xml @@ -49,7 +49,7 @@ </property> <property name="UserActionTime" tp:name-for-bindings="User_Action_Time" - type="t" tp:type="Unix_Timestamp64" access="read"> + type="x" tp:type="Unix_Timestamp64" access="read"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The time at which user action occurred, or 0 if this channel request is for some reason not involving user action.</p> diff --git a/spec/Channel_Type_Contact_Search.xml b/spec/Channel_Type_Contact_Search.xml index 7c324d0f..0b166bb1 100644 --- a/spec/Channel_Type_Contact_Search.xml +++ b/spec/Channel_Type_Contact_Search.xml @@ -21,7 +21,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <interface name="org.freedesktop.Telepathy.Channel.Type.ContactSearch" tp:causes-havoc='not well-tested'> <tp:requires interface="org.freedesktop.Telepathy.Channel"/> - + <tp:struct name="Search_Key_Info"> <tp:docstring>A struct representing details on search strings.</tp:docstring> <tp:member type="b" name="Is_Mandatory"> @@ -49,7 +49,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </arg> <arg direction="out" type="a{s(bg)}" tp:type="Search_Key_Info_Map"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - A dictionary mapping string search key names to its search details. + A dictionary mapping string search key names to its search details. </tp:docstring> </arg> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> diff --git a/spec/Channel_Type_DBus_Tube.xml b/spec/Channel_Type_DBus_Tube.xml index a3b98d7e..2671a17a 100644 --- a/spec/Channel_Type_DBus_Tube.xml +++ b/spec/Channel_Type_DBus_Tube.xml @@ -58,6 +58,12 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <tp:docstring> Offers a D-Bus tube providing the service specified. </tp:docstring> + <arg direction="out" name="address" type="s"> + <tp:docstring> + The string describing the address of the private bus. The client + SHOULD not attempt to connect to the address until the tube is open. + </tp:docstring> + </arg> <tp:possible-errors> <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> @@ -66,11 +72,6 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. capabilities. </tp:docstring> </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> - <tp:docstring> - The connection manager doesn't support D-Bus tubes. - </tp:docstring> - </tp:error> </tp:possible-errors> </method> @@ -87,71 +88,15 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. SHOULD not attempt to connect to the address until the tube is open. </tp:docstring> </arg> - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> - <tp:docstring> - The given tube ID is invalid or does not refer to a D-Bus - tube. - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - <method name="GetDBusTubeAddress" - tp:name-for-bindings="Get_DBus_Tube_Address"> - <tp:docstring> - Return a string describing the address of the private bus. - </tp:docstring> - <arg direction="out" type="s"> - <tp:docstring> - The bus address. - </tp:docstring> - </arg> - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> - <tp:docstring> - The tube is not a D-Bus tube. - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> - <tp:docstring> - This tube is not in the "open" state. - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - <method name="GetDBusNames" tp:name-for-bindings="Get_DBus_Names"> - <tp:docstring> - For a multi-user (i.e. Handle_Type_Room) D-Bus tube, obtain a mapping - between contact handles and their unique bus names on this tube. - </tp:docstring> - <arg direction="out" type="a(us)" tp:type="DBus_Tube_Member[]"> - <tp:docstring> - An array of structures, each containing a contact handle and a D-Bus - bus name. - </tp:docstring> - </arg> - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> - <tp:docstring> - The tube is not a multi-user D-Bus tube. - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> - <tp:docstring> - This tube is not in the "open" state. - </tp:docstring> - </tp:error> - </tp:possible-errors> </method> <signal name="DBusNamesChanged" tp:name-for-bindings="DBus_Names_Changed"> <tp:docstring> Emitted on a multi-user (i.e. Handle_Type_Room) D-Bus tube when a - participant opens or closes the tube. + participant opens or closes the tube. This provides change + notification for the <tp:member-ref>DBusNames</tp:member-ref> property. </tp:docstring> - <arg name="added" type="a(us)" tp:type="DBus_Tube_Member[]"> + <arg name="added" type="a{us}" tp:type="DBus_Tube_Participants"> <tp:docstring> Array of handles and D-Bus names of new participants. </tp:docstring> @@ -171,12 +116,39 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. com.example.ServiceName.</p> <p>When the tube is offered, the service name is transmitted to the other end.</p> - <p>When requesting a channel with + <p>When requesting a channel with <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>, this property MUST be included in the request.</p> </tp:docstring> </property> + <property name="DBusNames" tp:name-for-bindings="DBus_Names" + access="read" type="a{us}" tp:type="DBus_Tube_Participants"> + <tp:docstring> + For a multi-user (i.e. Handle_Type_Room) D-Bus tube, a mapping + between contact handles and their unique bus names on this tube. + For a peer-to-peer (i.e. Handle_Type_Contact) D-Bus tube, the empty + dictionary. Change notification is via + <tp:member-ref>DBusNamesChanged</tp:member-ref>. + </tp:docstring> + </property> + + <tp:mapping name="DBus_Tube_Participants"> + <tp:docstring>Represents the participants in a multi-user D-Bus tube, as + used by the <tp:member-ref>DBusNames</tp:member-ref> property and the + <tp:member-ref>DBusNamesChanged</tp:member-ref> signal.</tp:docstring> + <tp:member type="u" tp:type="Contact_Handle" name="Handle"> + <tp:docstring> + The handle of a participant in this D-Bus tube. + </tp:docstring> + </tp:member> + <tp:member type="s" tp:type="DBus_Unique_Name" name="Unique_Name"> + <tp:docstring> + That participant's unique name. + </tp:docstring> + </tp:member> + </tp:mapping> + </interface> </node> diff --git a/spec/Channel_Type_File_Transfer.xml b/spec/Channel_Type_File_Transfer.xml index a2432f4b..c88834c1 100644 --- a/spec/Channel_Type_File_Transfer.xml +++ b/spec/Channel_Type_File_Transfer.xml @@ -18,9 +18,9 @@ Library General Public License for more details.</p> License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> </tp:license> - <interface name="org.freedesktop.Telepathy.Channel.Type.FileTransfer.DRAFT" - tp:causes-havoc="experimental"> + <interface name="org.freedesktop.Telepathy.Channel.Type.FileTransfer"> <tp:requires interface="org.freedesktop.Telepathy.Channel"/> + <tp:added version="0.17.18">(as stable API)</tp:added> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>A channel type for transferring files. The transmission of data between contacts is achieved by reading from @@ -178,7 +178,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:docstring> </property> - <property name="Date" type="t" access="read" + <property name="Date" type="x" access="read" tp:type="Unix_Timestamp64" tp:name-for-bindings="Date"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The last modification time of the file being transferred. This diff --git a/spec/Channel_Type_Room_List.xml b/spec/Channel_Type_Room_List.xml index d2403bb6..10ccac60 100644 --- a/spec/Channel_Type_Room_List.xml +++ b/spec/Channel_Type_Room_List.xml @@ -40,7 +40,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </property> <method name="GetListingRooms" tp:name-for-bindings="Get_Listing_Rooms"> - <arg direction="out" type="b"> + <arg direction="out" type="b" name="In_Progress"> <tp:docstring> A boolean indicating if room listing is in progress </tp:docstring> diff --git a/spec/Channel_Type_Stream_Tube.xml b/spec/Channel_Type_Stream_Tube.xml index 4a43a007..b64f4a03 100644 --- a/spec/Channel_Type_Stream_Tube.xml +++ b/spec/Channel_Type_Stream_Tube.xml @@ -154,7 +154,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. "rsync" or "daap".</p> <p>When the tube is offered, the service name is transmitted to the other end.</p> - <p>When requesting a channel with + <p>When requesting a channel with <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>, this property MUST be included in the request.</p> </tp:docstring> @@ -185,7 +185,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <p>Connection Managers MUST support at least IPv4 with the localhost access control.</p> - <p>When requesting a channel with + <p>When requesting a channel with <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>, this property MUST NOT be included in the request.</p> diff --git a/spec/Channel_Type_Streamed_Media.xml b/spec/Channel_Type_Streamed_Media.xml index f4615ab6..b89065b4 100644 --- a/spec/Channel_Type_Streamed_Media.xml +++ b/spec/Channel_Type_Streamed_Media.xml @@ -89,7 +89,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <tp:simple-type name="Stream_ID" type="u"/> <method name="ListStreams" tp:name-for-bindings="List_Streams"> - <arg direction="out" type="a(uuuuuu)" tp:type="Media_Stream_Info[]"> + <arg direction="out" type="a(uuuuuu)" tp:type="Media_Stream_Info[]" + name="Streams"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> An array of structs containing: <ul> @@ -180,7 +181,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ An array of stream types (values of MediaStreamType) </tp:docstring> </arg> - <arg direction="out" type="a(uuuuuu)" tp:type="Media_Stream_Info[]"> + <arg direction="out" type="a(uuuuuu)" tp:type="Media_Stream_Info[]" + name="Streams"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> An array of structs (in the same order as the given stream types) containing: @@ -206,6 +208,12 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ will be emitted with the MEDIA_STREAM_PENDING_REMOTE_SEND flag set, and the signal emitted again with the flag cleared when the remote end has replied.</p> + + <p>If streams of the requested types have already been requested + via this method or <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type.StreamedMedia">FUTURE.InitialAudio</tp:dbus-ref>/<tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type.StreamedMedia">FUTURE.InitialVideo</tp:dbus-ref>, + this method SHOULD return successfully.</p> </tp:docstring> <tp:changed version="0.17.2"> <p>It is valid to use a handle which is neither @@ -371,7 +379,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <p>In the past, several other patterns have been used to place outgoing calls; see - <tt>http://telepathy.freedesktop.org/wiki/Requesting%20StreamedMedia%20channels</tt> + <a href="http://telepathy.freedesktop.org/wiki/Requesting%20StreamedMedia%20channels">'Requesting StreamedMedia Channels' on the Telepathy wiki</a> for the details.</p> <p>In general this should be used in conjunction with the <tp:dbus-ref @@ -389,7 +397,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ The channel-type-specific capability flags used for Channel.Type.StreamedMedia in the <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Capabilities</tp:dbus-ref> - interface. + interface. See the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type.StreamedMedia">FUTURE.InitialAudio</tp:dbus-ref> + property for details of the mechanisms that will replace this. </tp:docstring> <tp:flag suffix="Audio" value="1"> <tp:docstring> diff --git a/spec/Channel_Type_Streamed_Media_Future.xml b/spec/Channel_Type_Streamed_Media_Future.xml new file mode 100644 index 00000000..2421ed68 --- /dev/null +++ b/spec/Channel_Type_Streamed_Media_Future.xml @@ -0,0 +1,166 @@ +<?xml version="1.0" ?> +<node name="/Channel_Type_Streamed_Media_Future" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright> Copyright (C) 2009 Collabora Limited </tp:copyright> + <tp:copyright> Copyright (C) 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.Type.StreamedMedia.FUTURE"> + <tp:requires interface="org.freedesktop.Telepathy.Channel"/> + <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.StreamedMedia"/> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>This interface contains functionality which we intend to incorporate + into the <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Channel.Type.StreamedMedia</tp:dbus-ref> + interface in future. It should be considered to be conceptually part + of the core StreamedMedia interface, but without API or ABI + guarantees.</p> + + <tp:rationale> + <p>The rationale is the same as for <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Channel.FUTURE</tp:dbus-ref>.</p> + </tp:rationale> + </tp:docstring> + + <property name="InitialAudio" tp:name-for-bindings="Initial_Audio" + type="b" access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If set to true in a channel request that will create a new channel, + the connection manager should immediately attempt to establish an + audio stream to the remote contact, making it unnecessary for the + client to call <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type.StreamedMedia">RequestStreams</tp:dbus-ref>.</p> + + <p>If this property, or InitialVideo, is passed to EnsureChannel + (as opposed to CreateChannel), the connection manager SHOULD ignore + these properties when checking whether it can return an existing + channel as suitable; these properties only become significant when + the connection manager has decided to create a new channel.</p> + + <p>If true on a requested channel, this indicates that the audio + stream has already been requested and the client does not need to + call RequestStreams, although it MAY still do so.</p> + + <p>If true on an unrequested (incoming) channel, this indicates that + the remote contact initially requested an audio stream; this does + not imply that that audio stream is still active (as indicated by + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type.StreamedMedia">ListStreams</tp:dbus-ref>).</p> + + <p>This property is immutable (cannot change), and therefore SHOULD + appear wherever immutable properties are reported, e.g. <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">NewChannels</tp:dbus-ref> + signals.</p> + + <tp:rationale><p>This reduces D-Bus round trips.</p></tp:rationale> + + <p>Connection managers capable of signalling audio calls to contacts + SHOULD include a channel class in <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">RequestableChannelClasses</tp:dbus-ref> + with <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">ChannelType</tp:dbus-ref> + = <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type">StreamedMedia</tp:dbus-ref> + and <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref> + = Contact in the fixed properties dictionary, and InitialAudio + (and also InitialVideo, if applicable) in the allowed properties + list. Clients wishing to discover whether a connection manager + can signal audio and/or video calls SHOULD use this information.</p> + + <tp:rationale> + <p>Not all protocols support signalling video calls, and it would be + possible (although unlikely) to have a protocol where only video, + and not audio, could be signalled.</p> + </tp:rationale> + + <p>Connection managers that support the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface">ContactCapabilities.DRAFT</tp:dbus-ref> + interface SHOULD represent the capabilities of receiving audio + and/or video calls by including a channel class in + a contact's capabilities with ChannelType = StreamedMedia + in the fixed properties dictionary, and InitialAudio and/or + InitialVideo in the allowed properties list. Clients wishing to + discover whether a particular contact is likely to be able to + receive audio and/or video calls SHOULD use this information.</p> + + <tp:rationale> + <p>Not all clients support video calls, and it would also be + possible (although unlikely) to have a client which could only + stream video, not audio.</p> + </tp:rationale> + + <p>Clients that are willing to receive audio and/or video calls + SHOULD include the following filters if calling <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities.DRAFT">SetSelfCapabilities</tp:dbus-ref> + (clients of a <tp:dbus-ref + namespace="org.freedesktop.Telepathy">ChannelDispatcher.DRAFT</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.DRAFT">HandlerChannelFilter</tp:dbus-ref> + properties):</p> + + <ul> + <li>{ ChannelType = StreamedMedia }</li> + <li>{ ChannelType = StreamedMedia, InitialAudio = true } + if receiving audio-only or audio+video calls is supported</li> + <li>{ ChannelType = StreamedMedia, InitialVideo = true } + if receiving video-only or audio+video calls 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> + + <p>If { ChannelType = StreamedMedia } is passed to + SetSelfCapabilities, but no more specific channel class for + audio or video has been passed to that method (in the presence + of a ChannelDispatcher, this would mean that there is at least one + client with that channel class in its HandlerChannelFilter, but + no installed client has the more specific channel classes in its + HandlerChannelFilter), then the connection manager SHOULD advertise + support for every content type (audio or video) that it + supports.</p> + + <tp:rationale> + <p>This lowers the "barrier to entry" by allowing a simple client + to say merely that it supports streamed media at all.</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> + + </interface> +</node> diff --git a/spec/Channel_Type_Text.xml b/spec/Channel_Type_Text.xml index f32382d2..5c28dce8 100644 --- a/spec/Channel_Type_Text.xml +++ b/spec/Channel_Type_Text.xml @@ -67,7 +67,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </method> <method name="GetMessageTypes" tp:name-for-bindings="Get_Message_Types"> - <arg direction="out" type="au" tp:type="Channel_Text_Message_Type[]"> + <arg direction="out" type="au" tp:type="Channel_Text_Message_Type[]" + name="Available_Types"> <tp:docstring> An array of integer message types (ChannelTextMessageType) </tp:docstring> @@ -92,7 +93,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ acknowledge messages after they have actually stored them, which is impossible if this flag is true.</tp:deprecated> </arg> - <arg direction="out" type="a(uuuuus)" tp:type="Pending_Text_Message[]"> + <arg direction="out" type="a(uuuuus)" tp:type="Pending_Text_Message[]" + name="Pending_Messages"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> An array of structs representing the pending queue. Each contains: <ul> diff --git a/spec/Channel_Type_Tubes.xml b/spec/Channel_Type_Tubes.xml index f28f9b6b..f6829b5d 100644 --- a/spec/Channel_Type_Tubes.xml +++ b/spec/Channel_Type_Tubes.xml @@ -56,11 +56,19 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. </tp:struct> <tp:struct name="DBus_Tube_Member" array-name="DBus_Tube_Member_List"> - <tp:docstring>A struct (handle, unique name) representing a participant - in a D-Bus tube, as returned by GetDBusNames on the Tubes channel - type, and as seen in the DBusNamesChanged signal.</tp:docstring> - <tp:member type="u" tp:type="Contact_Handle" name="Handle"/> - <tp:member type="s" tp:type="DBus_Unique_Name" name="Unique_Name"/> + <tp:docstring>Represents a participant in a multi-user D-Bus tube, as + returned by <tp:member-ref>GetDBusNames</tp:member-ref> and seen in the + <tp:member-ref>DBusNamesChanged</tp:member-ref> signal.</tp:docstring> + <tp:member type="u" tp:type="Contact_Handle" name="Handle"> + <tp:docstring> + The handle of a participant in this D-Bus tube. + </tp:docstring> + </tp:member> + <tp:member type="s" tp:type="DBus_Unique_Name" name="Unique_Name"> + <tp:docstring> + That participant's unique name. + </tp:docstring> + </tp:member> </tp:struct> <tp:struct name="Socket_Address_IPv4"> @@ -244,7 +252,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. tp:name-for-bindings="Get_Available_Stream_Tube_Types"> <tp:docstring>List the available address types and access-control types for stream tubes.</tp:docstring> - <arg direction="out" type="a{uau}" tp:type="Supported_Socket_Map"> + <arg direction="out" type="a{uau}" tp:type="Supported_Socket_Map" + name="Available_Stream_Tube_Types"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>A mapping from address types (members of Socket_Address_Type) to arrays of access-control type (members of Socket_Access_Control) @@ -272,7 +281,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <method name="GetAvailableTubeTypes" tp:name-for-bindings="Get_Available_Tube_Types"> - <arg direction="out" type="au" tp:type="Tube_Type[]"> + <arg direction="out" type="au" tp:type="Tube_Type[]" + name="Available_Tube_Types"> <tp:docstring> An array of the available tube types, as defined by the Tube_Type enum. @@ -281,7 +291,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. </method> <method name="ListTubes" tp:name-for-bindings="List_Tubes"> - <arg direction="out" type="a(uuusa{sv}u)" tp:type="Tube_Info[]"> + <arg direction="out" type="a(uuusa{sv}u)" tp:type="Tube_Info[]" + name="Tubes"> <tp:docstring> Return an array of tuples, each representing a tube, with the following members: @@ -298,7 +309,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. </arg> </method> - <method name="OfferDBusTube" tp:name-for-bindings="Offer_DBus_Tube"> + <!-- this tp:name-for-bindings is ugly, but compatible with + the code generation in telepathy-glib versions that did not use + tp:name-for-bindings --> + <method name="OfferDBusTube" tp:name-for-bindings="Offer_D_Bus_Tube"> <tp:docstring> Offers a D-Bus tube providing the service specified. </tp:docstring> @@ -319,7 +333,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. D-Bus type, or a byte array 'ay'. </tp:docstring> </arg> - <arg direction="out" type="u" tp:type="Tube_ID"> + <arg direction="out" type="u" tp:type="Tube_ID" name="Tube_ID"> <tp:docstring> The ID of the new tube. </tp:docstring> @@ -392,7 +406,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. specified in the documentation for the Socket_Access_Control enum. </tp:docstring> </arg> - <arg direction="out" type="u" tp:type="Tube_ID"> + <arg direction="out" type="u" tp:type="Tube_ID" name="Tube_ID"> <tp:docstring> The ID of the new tube. </tp:docstring> @@ -450,7 +464,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. </arg> </signal> - <method name="AcceptDBusTube" tp:name-for-bindings="Accept_DBus_Tube"> + <!-- this tp:name-for-bindings is ugly, but compatible with + the code generation in telepathy-glib versions that did not use + tp:name-for-bindings --> + <method name="AcceptDBusTube" tp:name-for-bindings="Accept_D_Bus_Tube"> <tp:docstring> Accept a D-Bus tube that's in the "local pending" state. The connection manager will attempt to open the tube. The tube remains in @@ -572,8 +589,11 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. </arg> </signal> + <!-- this tp:name-for-bindings is ugly, but compatible with + the code generation in telepathy-glib versions that did not use + tp:name-for-bindings --> <method name="GetDBusTubeAddress" - tp:name-for-bindings="Get_DBus_Tube_Address"> + tp:name-for-bindings="Get_D_Bus_Tube_Address"> <tp:docstring> For a D-Bus tube, return a string describing the address of the private bus. @@ -583,7 +603,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. The ID of the tube to get an address for. </tp:docstring> </arg> - <arg direction="out" type="s"> + <arg direction="out" type="s" name="Address"> <tp:docstring> The bus address. </tp:docstring> @@ -602,7 +622,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. </tp:possible-errors> </method> - <method name="GetDBusNames" tp:name-for-bindings="Get_DBus_Names"> + <!-- this tp:name-for-bindings is ugly, but compatible with + the code generation in telepathy-glib versions that did not use + tp:name-for-bindings --> + <method name="GetDBusNames" tp:name-for-bindings="Get_D_Bus_Names"> <tp:docstring> For a multi-user (i.e. Handle_Type_Room) D-Bus tube, obtain a mapping between contact handles and their unique bus names on this tube. @@ -612,7 +635,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. The ID of the tube to get names for. </tp:docstring> </arg> - <arg direction="out" type="a(us)" tp:type="DBus_Tube_Member[]"> + <arg direction="out" type="a(us)" tp:type="DBus_Tube_Member[]" + name="DBus_Names"> <tp:docstring> An array of structures, each containing a contact handle and a D-Bus bus name. @@ -632,7 +656,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. </tp:possible-errors> </method> - <signal name="DBusNamesChanged" tp:name-for-bindings="DBus_Names_Changed"> + <!-- this tp:name-for-bindings is ugly, but compatible with + the code generation in telepathy-glib versions that did not use + tp:name-for-bindings --> + <signal name="DBusNamesChanged" tp:name-for-bindings="D_Bus_Names_Changed"> <tp:docstring> Emitted on a multi-user (i.e. Handle_Type_Room) D-Bus tube when a participant opens or closes the tube. diff --git a/spec/Connection.xml b/spec/Connection.xml index 95161968..97a3c4c7 100644 --- a/spec/Connection.xml +++ b/spec/Connection.xml @@ -67,7 +67,8 @@ USA.</p> </method> <method name="GetInterfaces" tp:name-for-bindings="Get_Interfaces"> - <arg direction="out" type="as" tp:type="DBus_Interface[]"> + <arg direction="out" type="as" tp:type="DBus_Interface[]" + name="Interfaces"> <tp:docstring> An array of D-Bus interface names </tp:docstring> @@ -110,7 +111,7 @@ USA.</p> </method> <method name="GetProtocol" tp:name-for-bindings="Get_Protocol"> - <arg direction="out" type="s" tp:type="Protocol"> + <arg direction="out" type="s" tp:type="Protocol" name="Protocol"> <tp:docstring> A string identifier for the protocol </tp:docstring> @@ -157,7 +158,8 @@ USA.</p> </property> <method name="GetSelfHandle" tp:name-for-bindings="Get_Self_Handle"> - <arg direction="out" type="u" tp:type="Contact_Handle"> + <arg direction="out" type="u" tp:type="Contact_Handle" + name="Self_Handle"> <tp:docstring> The value of the <tp:member-ref>SelfHandle</tp:member-ref> property </tp:docstring> @@ -177,7 +179,8 @@ USA.</p> </method> <method name="GetStatus" tp:name-for-bindings="Get_Status"> - <arg direction="out" type="u" tp:type="Connection_Status"> + <arg direction="out" type="u" tp:type="Connection_Status" + name="Status"> <tp:docstring> An integer representing the current status </tp:docstring> @@ -246,7 +249,7 @@ USA.</p> </tp:docstring> </arg> - <arg direction="out" type="as"> + <arg direction="out" type="as" name="Identifiers"> <tp:docstring> An array of handle names in the same order as the given numbers </tp:docstring> @@ -269,7 +272,8 @@ USA.</p> </method> <method name="ListChannels" tp:name-for-bindings="List_Channels"> - <arg direction="out" type="a(osuu)" tp:type="Channel_Info[]"> + <arg direction="out" type="a(osuu)" tp:type="Channel_Info[]" + name="Channel_Info"> <tp:docstring> An array of structs representing channels. </tp:docstring> @@ -429,7 +433,7 @@ USA.</p> </tp:docstring> </arg> - <arg direction="out" type="o"> + <arg direction="out" type="o" name="Object_Path"> <tp:docstring> The D-Bus object path for the channel created or retrieved </tp:docstring> @@ -488,6 +492,12 @@ USA.</p> The requested channel type cannot be created with the given handle </tp:docstring> </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotCapable"> + <tp:docstring> + The requested channel cannot be created because contact doesn't + have the required capabilities. + </tp:docstring> + </tp:error> <tp:error name="org.freedesktop.Telepathy.Error.Channel.Banned"/> <tp:error name="org.freedesktop.Telepathy.Error.Channel.Full"/> <tp:error name="org.freedesktop.Telepathy.Error.Channel.InviteOnly"/> @@ -562,7 +572,8 @@ USA.</p> </tp:docstring> </arg> - <arg direction="out" type="au" tp:type="Handle[]"> + <arg direction="out" type="au" tp:type="Handle[]" + name="Handles"> <tp:docstring> An array of integer handle numbers in the same order as the given strings </tp:docstring> @@ -582,21 +593,27 @@ USA.</p> <tp:possible-errors> <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> - <tp:docstring> - The handle type is invalid - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"> <tp:docstring> - The given name is not a valid entity of the given type + The given name does not identify a valid entity of the given type. + + <tp:rationale> + For instance, an XMPP connection would raise this error for + identifiers with type Handle_Type_Room that do not contain + exactly one '@' character, that contain spaces, and so on. + </tp:rationale> </tp:docstring> </tp:error> <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> <tp:docstring> - The given handle type is valid, but not implemented on this - connection. For instance, a CM for a protocol that doesn't have - chat rooms would not implement room handles. + The given handle type is not valid, or is not implemented on this + connection. + + <tp:rationale> + For instance, a connection to a protocol that doesn't have + chat rooms would raise this error for room handles, and all CMs + would raise this error for Handle_Type_None. + </tp:rationale> </tp:docstring> </tp:error> </tp:possible-errors> @@ -622,83 +639,275 @@ USA.</p> </tp:docstring> </tp:enumvalue> </tp:enum> + <tp:enum name="Connection_Status_Reason" type="u"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A reason why the status of the connection changed. Apart from + Requested, the values of this enumeration only make sense as + reasons why the status changed to Disconnected.</p> + </tp:docstring> + <tp:enumvalue suffix="None_Specified" value="0"> - <tp:docstring> - There is no reason set for this state change. + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>There is no reason set for this state change. Unknown status + reasons SHOULD be treated like this reason.</p> + + <p>When disconnected for this reason, the equivalent D-Bus error is + <code>org.freedesktop.Telepathy.Error.Disconnected</code>.</p> </tp:docstring> </tp:enumvalue> + <tp:enumvalue suffix="Requested" value="1"> - <tp:docstring> - The change is in response to a user request. + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The change is in response to a user request. Changes to the + Connecting or Connected status SHOULD always indicate this reason; + changes to the Disconnected status SHOULD indicate this reason + if and only if the disconnection was requested by the user.</p> + + <p>When disconnected for this reason, the equivalent D-Bus error is + <code>org.freedesktop.Telepathy.Error.Cancelled</code>.</p> </tp:docstring> </tp:enumvalue> + <tp:enumvalue suffix="Network_Error" value="2"> - <tp:docstring> - There was an error sending or receiving on the network socket. + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>There was an error sending or receiving on the network socket.</p> + + <p>When disconnected for this reason, the equivalent D-Bus error is + <code>org.freedesktop.Telepathy.Error.NetworkError</code>.</p> </tp:docstring> </tp:enumvalue> + <tp:enumvalue suffix="Authentication_Failed" value="3"> - <tp:docstring> - The username or password was invalid. + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The username or password was invalid.</p> + + <p>When disconnected for this reason, the equivalent D-Bus error is + <code>org.freedesktop.Telepathy.Error.AuthenticationFailed</code>. + </p> </tp:docstring> </tp:enumvalue> + <tp:enumvalue suffix="Encryption_Error" value="4"> - <tp:docstring> - There was an error negotiating SSL on this connection, or + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>There was an error negotiating SSL on this connection, or encryption was unavailable and require-encryption was set when the - connection was created. + connection was created.</p> + + <p>When disconnected for this reason, the equivalent D-Bus error is + <code>org.freedesktop.Telepathy.Error.EncryptionNotAvailable</code> + if encryption was not available at all, or + <code>org.freedesktop.Telepathy.Error.EncryptionError</code> + if encryption failed.</p> </tp:docstring> </tp:enumvalue> + <tp:enumvalue suffix="Name_In_Use" value="5"> - <tp:docstring> - Someone is already connected to the server using the name - you are trying to connect with. + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>In general, this reason indicates that the requested account + name or other identification could not be used due to conflict + with another connection. It can be divided into three cases:</p> + + <ul> + <li>If the status change is from Connecting to Disconnected + and the 'register' parameter to RequestConnection was present + and true, the requested account could not be created on the + server because it already exists.</li> + + <li>If the status change is from Connecting to Disconnected + but the 'register' parameter is absent or false, the connection + manager could not connect to the specified account because + a connection to that account already exists. + + <tp:rationale> + In some protocols, like XMPP (when connecting with the same + JID and resource as an existing connection), the existing + connection "wins" and the new one fails to connect. + </tp:rationale> + </li> + + <li>If the status change is from Connected to Disconnected, + the existing connection was automatically disconnected because + a new connection to the same account (perhaps from a different + client or location) was established. + + <tp:rationale> + In some protocols, like MSNP (when connecting twice with the + same Passport), the new connection "wins" and the + existing one is automatically disconnected. + </tp:rationale> + </li> + </ul> + + <p>When disconnected for this reason, the equivalent D-Bus error is + <code>org.freedesktop.Telepathy.Error.NotYours</code>. + </p> + + <tp:rationale> + These three errors are distinct but very similar, and can be + distinguished by other factors. + </tp:rationale> </tp:docstring> </tp:enumvalue> + <tp:enumvalue suffix="Cert_Not_Provided" value="6"> - <tp:docstring> - The server did not provide a SSL certificate. + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The server did not provide a SSL certificate.</p> + + <p>When disconnected for this reason, the equivalent D-Bus error is + <code>org.freedesktop.Telepathy.Error.Cert.NotProvided</code>. + </p> </tp:docstring> </tp:enumvalue> + <tp:enumvalue suffix="Cert_Untrusted" value="7"> - <tp:docstring> - The server's SSL certificate could not be trusted. + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The server's SSL certificate is signed by an untrusted certifying + authority. This error SHOULD NOT be used to represent a self-signed + certificate: use the more specific Cert_Self_Signed reason for + that.</p> + + <p>When disconnected for this reason, the equivalent D-Bus error is + <code>org.freedesktop.Telepathy.Error.Cert.Untrusted</code>. + </p> </tp:docstring> </tp:enumvalue> + <tp:enumvalue suffix="Cert_Expired" value="8"> - <tp:docstring> - The server's SSL certificate has expired. + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The server's SSL certificate has expired.</p> + + <p>When disconnected for this reason, the equivalent D-Bus error is + <code>org.freedesktop.Telepathy.Error.Cert.Expired</code>. + </p> </tp:docstring> </tp:enumvalue> + <tp:enumvalue suffix="Cert_Not_Activated" value="9"> - <tp:docstring> - The server's SSL certificate is not yet valid. + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The server's SSL certificate is not yet valid.</p> + + <p>When disconnected for this reason, the equivalent D-Bus error is + <code>org.freedesktop.Telepathy.Error.Cert.NotActivated</code>. + </p> </tp:docstring> </tp:enumvalue> + <tp:enumvalue suffix="Cert_Hostname_Mismatch" value="10"> - <tp:docstring> - The server's SSL certificate did not match its hostname. + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The server's SSL certificate did not match its hostname.</p> + + <p>When disconnected for this reason, the equivalent D-Bus error is + <code>org.freedesktop.Telepathy.Error.Cert.HostnameMismatch</code>. + </p> </tp:docstring> </tp:enumvalue> + <tp:enumvalue suffix="Cert_Fingerprint_Mismatch" value="11"> - <tp:docstring> - The server's SSL certificate does not have the expected - fingerprint. + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The server's SSL certificate does not have the expected + fingerprint.</p> + + <p>When disconnected for this reason, the equivalent D-Bus error is + <code>org.freedesktop.Telepathy.Error.Cert.FingerprintMismatch</code>. + </p> </tp:docstring> </tp:enumvalue> + <tp:enumvalue suffix="Cert_Self_Signed" value="12"> - <tp:docstring> - The server's SSL certificate is self-signed. + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The server's SSL certificate is self-signed.</p> + + <p>When disconnected for this reason, the equivalent D-Bus error is + <code>org.freedesktop.Telepathy.Error.Cert.HostnameMismatch</code>. + </p> </tp:docstring> </tp:enumvalue> + <tp:enumvalue suffix="Cert_Other_Error" value="13"> - <tp:docstring> - There was some other error validating the server's SSL certificate. + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>There was some other error validating the server's SSL + certificate.</p> + + <p>When disconnected for this reason, the equivalent D-Bus error is + <code>org.freedesktop.Telepathy.Error.Cert.Invalid</code>. + </p> </tp:docstring> </tp:enumvalue> </tp:enum> + <signal name="ConnectionError" tp:name-for-bindings="Connection_Error"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Emitted when an error occurs that renders this connection unusable. + </p> + + <p>Whenever this signal is emitted, it MUST immediately be followed by + a <tp:member-ref>StatusChanged</tp:member-ref> signal with status + Connection_Status_Reason_Disconnected and an appropriate reason + code.</p> + + <p>Connection managers SHOULD emit this signal on disconnection, but + need not do so. Clients MUST support connection managers that emit + StatusChanged(Disconnected, ...) without first emitting + ConnectionError.</p> + + <tp:rationale> + <p>This signal provides additional information about the reason + for disconnection. The reason for connection is always + straightforward - it was requested - so it does not need further + explanation. However, on errors, it can be useful to provide + additional information.</p> + + <p>The <tp:type>Connection_Status_Reason</tp:type> is not given + here, since it will be signalled in + <tp:member-ref>StatusChanged</tp:member-ref>. A reasonable client + implementation would be to store the information given by this + signal until StatusChanged is received, at which point the + information given by this signal can be used to supplement the + StatusChanged signal.</p> + </tp:rationale> + </tp:docstring> + + <arg name="Error" type="s" tp:type="DBus_Error_Name"> + <tp:docstring> + The name of a D-Bus error describing the error that occurred, + which may correspond to a + <tp:type>Connection_Status_Reason</tp:type> or be a + protocol-specific or connection-manager-specific error in a + suitable namespace. + + <tp:rationale> + For instance, a SIP connection manager could signal + "402 Payment Required" as an error in a + connection-manager-specific namespace, or a link-local + XMPP implementation that used Avahi could provide the error + given to it by the avahi-daemon. + </tp:rationale> + </tp:docstring> + </arg> + + <arg name="Details" type="a{sv}" tp:type="String_Variant_Map"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Additional information about the error, which may include + the following well-known keys:</p> + + <dl> + <dt>debug-message (s)</dt> + <dd>Debugging information on the change, corresponding to the + message part of a D-Bus error message, which SHOULD NOT be + displayed to users under normal circumstances</dd> + </dl> + + <tp:rationale> + <p>This argument allows for future extensions. For instance, + if indicating DNS lookup failure, we could define a key + that indicates the hostname that could not be found.</p> + </tp:rationale> + </tp:docstring> + </arg> + + </signal> + <signal name="StatusChanged" tp:name-for-bindings="Status_Changed"> <arg name="Status" type="u" tp:type="Connection_Status"> <tp:docstring> diff --git a/spec/Connection_Interface_Aliasing.xml b/spec/Connection_Interface_Aliasing.xml index 652ed01a..a599436a 100644 --- a/spec/Connection_Interface_Aliasing.xml +++ b/spec/Connection_Interface_Aliasing.xml @@ -71,7 +71,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:flag> </tp:flags> <method name="GetAliasFlags" tp:name-for-bindings="Get_Alias_Flags"> - <arg direction="out" type="u" tp:type="Connection_Alias_Flags"> + <arg direction="out" type="u" tp:type="Connection_Alias_Flags" + name="Alias_Flags"> <tp:docstring> An integer with a bitwise OR of flags from ConnectionAliasFlags </tp:docstring> @@ -90,7 +91,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ An array of handles representing contacts </tp:docstring> </arg> - <arg direction="out" type="as"> + <arg direction="out" type="as" name="Aliases"> <tp:docstring> A list of aliases in the same order as the contact handles </tp:docstring> @@ -111,7 +112,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ An array of handles representing contacts </tp:docstring> </arg> - <arg direction="out" type="a{us}" tp:type="Alias_Map"> + <arg direction="out" type="a{us}" tp:type="Alias_Map" name="Aliases"> <tp:docstring> A dictionary mapping contact handles to aliases </tp:docstring> diff --git a/spec/Connection_Interface_Avatars.xml b/spec/Connection_Interface_Avatars.xml index 27c77b91..7ef26afd 100644 --- a/spec/Connection_Interface_Avatars.xml +++ b/spec/Connection_Interface_Avatars.xml @@ -126,32 +126,32 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <method name="GetAvatarRequirements" tp:name-for-bindings="Get_Avatar_Requirements"> - <arg direction="out" type="as"> + <arg direction="out" type="as" name="MIME_Types"> <tp:docstring> An array of supported MIME types (eg image/jpeg) </tp:docstring> </arg> - <arg direction="out" type="q"> + <arg direction="out" type="q" name="Min_Width"> <tp:docstring> The minimum image width in pixels </tp:docstring> </arg> - <arg direction="out" type="q"> + <arg direction="out" type="q" name="Min_Height"> <tp:docstring> The minimum image height in pixels </tp:docstring> </arg> - <arg direction="out" type="q"> + <arg direction="out" type="q" name="Max_Width"> <tp:docstring> The maximum image width in pixels, or 0 if there is no limit </tp:docstring> </arg> - <arg direction="out" type="q"> + <arg direction="out" type="q" name="Max_Height"> <tp:docstring> The maximum image height in pixels, or 0 if there is no limit </tp:docstring> </arg> - <arg direction="out" type="u"> + <arg direction="out" type="u" name="Max_Bytes"> <tp:docstring> The maximum image size in bytes, or 0 if there is no limit </tp:docstring> @@ -233,12 +233,12 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ An integer handle for the contact to request the avatar for </tp:docstring> </arg> - <arg direction="out" type="ay"> + <arg direction="out" type="ay" name="Data"> <tp:docstring> An array of bytes containing the image data </tp:docstring> </arg> - <arg direction="out" type="s"> + <arg direction="out" type="s" name="MIME_Type"> <tp:docstring> A string containing the image MIME type (eg image/jpeg), or empty if unknown diff --git a/spec/Connection_Interface_Capabilities.xml b/spec/Connection_Interface_Capabilities.xml index 7d0c14a9..4e58d02b 100644 --- a/spec/Connection_Interface_Capabilities.xml +++ b/spec/Connection_Interface_Capabilities.xml @@ -130,7 +130,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ An array of D-Bus interface names of channel types to remove </tp:docstring> </arg> - <arg direction="out" type="a(su)" tp:type="Capability_Pair[]"> + <arg direction="out" type="a(su)" tp:type="Capability_Pair[]" + name="Self_Capabilities"> <tp:docstring> An array of structures describing the current capabilities containing: <ul> @@ -203,7 +204,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ list.</p> </tp:docstring> </arg> - <arg direction="out" type="a(usuu)" tp:type="Contact_Capability[]"> + <arg direction="out" type="a(usuu)" tp:type="Contact_Capability[]" + name="Contact_Capabilities"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> An array of structures containing: <ul> diff --git a/spec/Connection_Interface_Contact_Capabilities.xml b/spec/Connection_Interface_Contact_Capabilities.xml index 13efba66..042b24be 100644 --- a/spec/Connection_Interface_Contact_Capabilities.xml +++ b/spec/Connection_Interface_Contact_Capabilities.xml @@ -18,7 +18,8 @@ Lesser General Public License for more details.</p> 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.ContactCapabilities.DRAFT"> + <interface name="org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities.DRAFT" + tp:causes-havoc="experimental"> <tp:requires interface="org.freedesktop.Telepathy.Connection"/> <tp:added version="0.17.16">(as a draft)</tp:added> @@ -100,7 +101,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ Now there is a fix, so we don't use the workaround anymore. --> <arg direction="out" type="a{ua(a{sv}as)}" - tp:type="Contact_Capabilities_Map"> + tp:type="Contact_Capabilities_Map" name="Contact_Capabilities"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> An array of structures containing: <ul> @@ -139,7 +140,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <p>The underlying protocol can get several contacts' capabilities at the same time.</p> </tp:rationale> - + </tp:docstring> </signal> diff --git a/spec/Connection_Interface_Contact_Info.xml b/spec/Connection_Interface_Contact_Info.xml index 4f8fd42d..e7b033bf 100644 --- a/spec/Connection_Interface_Contact_Info.xml +++ b/spec/Connection_Interface_Contact_Info.xml @@ -1,8 +1,7 @@ <?xml version="1.0" ?> <node name="/Connection_Interface_Contact_Info" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright> Copyright (C) 2005, 2006 Collabora Limited </tp:copyright> - <tp:copyright> Copyright (C) 2005, 2006 Nokia Corporation </tp:copyright> - <tp:copyright> Copyright (C) 2006 INdT </tp:copyright> + <tp:copyright> Copyright (C) 2008 Collabora Limited </tp:copyright> + <tp:copyright> Copyright (C) 2008 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 @@ -18,66 +17,359 @@ Lesser General Public License for more details.</p> 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.ContactInfo" - tp:causes-havoc='obsolete'> + <interface name="org.freedesktop.Telepathy.Connection.Interface.ContactInfo.DRAFT" + tp:causes-havoc="experimental"> + <tp:added version="0.17.18">(as a draft)</tp:added> <tp:requires interface="org.freedesktop.Telepathy.Connection"/> - <signal name="GotContactInfo" tp:name-for-bindings="Got_Contact_Info"> + + <tp:struct name="Contact_Info_Field" array-name="Contact_Info_Field_List"> + <tp:member type="s" name="Field_Name"> + <tp:docstring> + The name of the field; this is the lowercased name of a vCard field. + For example, a field representing a contact's address would be named + "adr". + </tp:docstring> + </tp:member> + <tp:member type="as" name="Parameters"> + <tp:docstring> + A list of (lowercased) vCard type parameters applicable to this field. + For example, a contact's preferred home address would have parameters + 'home' and 'pref'. + + <tp:rationale> + This is a list of strings rather than a bitwise OR of enum members + because vCard type parameters are essentially arbitrary strings. + </tp:rationale> + </tp:docstring> + </tp:member> + <tp:member type="as" name="Field_Value"> + <tp:docstring> + For unstructured vCard fields (such as 'fn', a formatted name + field), a single-element array containing the field's value; for + structured fields (such as 'adr', an address field), an array + corresponding to the semicolon-separated elements of the field (with + empty strings for empty elements). A vCard field with multiple + comma-separated values should be represented by several + <tp:type>Contact_Info_Field</tp:type>s. Characters which are + required to be escaped in vCard values, such as semi-colons, should + not be escaped in this list. + + <tp:rationale> + An earlier draft of this interface split structured vCard fields + into multiple Telepathy-level fields; for example, 'n' became + 'family-name', 'given-name', etc. But under this representation, + omitting empty components leads to difficulty identifying where one + name ends and another begins. Consider the fields ['given-name', + 'honorific-suffixes', 'family-name', 'honorific-prefixes']: does + this represent two 'n' fields, or one with incorrect component + ordering? + </tp:rationale> + </tp:docstring> + </tp:member> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Represents one piece of information about a contact, as modelled by + a single vCard field. Of the fields defined in RFC 2426, common + examples include:</p> + + <dl> + <dt>fn</dt> + <dd>The contact's full name, formatted to their liking</dd> + + <dt>n</dt> + <dd>The contact's full name, divided into five parts: family name, + given name, additional names, honorific prefixes, and honorific + suffixes</dd> + + <dt>org</dt> + <dd>The contact's organisation, divided into the organization's name + possibly followed by one or more organizational unit names.</dd> + + <dt>adr</dt> + <dd>A street address for the contact, divided into seven components: + post office box, extended address, street address, locality (e.g., + city), region (e.g., state or province), the postal code, and the + country name.</dd> + + <dt>tel</dt> + <dd>A telephone number for the contact.</dd> + + <dt>email</dt> + <dd>An email address for the contact.</dd> + </dl> + + <p>For example, the following vCard:</p> + + <pre> + BEGIN:vCard + VERSION:3.0 + FN:Wee Ninja + N:Ninja;Wee;;;-san + ORG:Collabora, Ltd.;Human Resources\; Company Policy Enforcement + ADR;TYPE=WORK,POSTAL,PARCEL:;;11 Kings Parade;Cambridge;Cambridgeshire + ;CB2 1SJ;UK + TEL;TYPE=VOICE,WORK:+44 1223 362967, +44 7700 900753 + EMAIL;TYPE=INTERNET,PREF:wee.ninja@collabora.co.uk + EMAIL;TYPE=INTERNET:wee.ninja@example.com + URL:http://www.thinkgeek.com/geektoys/plush/8823/ + END:vCard</pre> + + <p>would be represented by (in Python-like syntax):</p> + + <pre> +[ + ('fn', [], ['Wee Ninja']), + ('n', [], ['Ninja', 'Wee', '', '', '-san']), + ('org', [], ['Collabora, Ltd.', 'Human Resources; Company Policy Enforcement']), + ('adr', ['work','postal','parcel'], ['','','11 Kings Parade','Cambridge', + 'Cambridgeshire','CB2 1SJ','UK']), + ('tel', ['voice','work'], ['+44 1223 362967']), + ('tel', ['voice','work'], ['+44 7700 900753']), + ('email', ['internet','pref'], ['wee.ninja@collabora.co.uk']), + ('email', ['internet'], ['wee.ninja@example.com']), + ('url', [], ['http://www.thinkgeek.com/geektoys/plush/8823/']), +]</pre> + </tp:docstring> + </tp:struct> + + <tp:mapping name="Contact_Info_Map" array-name=""> + <tp:docstring>A dictionary whose keys are contact handles and whose + values are contact information..</tp:docstring> + <tp:member type="u" tp:type="Contact_Handle" name="Handle"/> + <tp:member type="a(sasas)" tp:type="Contact_Info_Field[]" + name="Contact_Info"/> + </tp:mapping> + + <signal name="ContactInfoChanged" tp:name-for-bindings="ContactInfoChanged"> <arg name="Contact" type="u" tp:type="Contact_Handle"> <tp:docstring> - An integer handle of the contact ID on the server + An integer handle for the contact whose info has changed. </tp:docstring> </arg> - <arg name="VCard" type="s"> - <tp:docstring> - The XML string containing their vcard information + <arg name="ContactInfo" type="a(sasas)" tp:type="Contact_Info_Field[]"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + An array of fields representing information about this contact. </tp:docstring> </arg> <tp:docstring> - Emitted when information has been received from the server with - the details of a particular contact. + Emitted when a contact's information has changed or been received for + the first time on this connection. </tp:docstring> </signal> + + <method name="GetContactInfo" + tp:name-for-bindings="Get_Contact_Info"> + <arg direction="in" name="Contacts" type="au" tp:type="Contact_Handle[]"> + <tp:docstring> + An array of handles representing contacts. + </tp:docstring> + </arg> + <arg direction="out" name="ContactInfo" type="a{ua(sasas)}" + tp:type="Contact_Info_Map"> + <tp:docstring> + A dictionary mapping contact handles to information, whose keys are + the subset of the requested list of handles for which information was + cached. + </tp:docstring> + </arg> + <tp:docstring> + Request information on several contacts at once. This SHOULD only + return cached information, omitting handles for which no information is + cached from the returned map. For contacts without cached information, + the information SHOULD be requested from the network, with the result + signalled later by <tp:member-ref>ContactInfoChanged</tp:member-ref>. + </tp:docstring> + </method> + <method name="RequestContactInfo" tp:name-for-bindings="Request_Contact_Info"> <arg direction="in" name="Contact" type="u" tp:type="Contact_Handle"> <tp:docstring> - An integer handle for the contact to request info for + An integer handle for a contact. </tp:docstring> </arg> + <arg direction="out" name="Contact_Info" type="a(sasas)" + tp:type="Contact_Info_Field[]"> + <tp:docstring> + Information about that contact. + </tp:docstring> + </arg> + <tp:docstring> + Retrieve information for a contact, requesting it from the network if + it is not cached locally. + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + The contact's information could not be retrieved. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <method name="SetContactInfo" tp:name-for-bindings="Set_Contact_Info"> <tp:docstring> - Request information for a given contact. The function will return - after a GotContactInfo signal has been emitted for the contact, or - an error returned. + Set new contact information for this connection, replacing existing + information. This method is only suppported if + <tp:member-ref>ContactInfoFlags</tp:member-ref> contains + <code>Can_Set</code>, and may only be passed fields conforming to + <tp:member-ref>SupportedFields</tp:member-ref>. </tp:docstring> + <arg direction="in" name="ContactInfo" type="a(sasas)" + tp:type="Contact_Info_Field[]"> + <tp:docstring> + The new information to be set. + </tp:docstring> + </arg> <tp:possible-errors> <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + Setting your own information is not supported on this protocol. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring> + The supplied fields do not match the restrictions specified by + <tp:member-ref>SupportedFields</tp:member-ref>. + </tp:docstring> + </tp:error> </tp:possible-errors> </method> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>THIS INTERFACE IS DEPRECATED AND SHOULD NOT BE USED. A new version - will be proposed in the 0.13 specification branch.</p> + <tp:enum name="Contact_Info_Flag" value-prefix="Contact_Info_Flag" + type="u"> + <tp:docstring> + Flags defining the behaviour of contact information on this protocol. + Some protocols provide no information on contacts without an explicit + request; others always push information to the connection manager as + and when it changes. + </tp:docstring> + + <tp:enumvalue suffix="Can_Set" value="1"> + <tp:docstring> + Indicates that <tp:member-ref>SetContactInfo</tp:member-ref> is + supported on this connection. + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Push" value="2"> + <tp:docstring> + Indicates that the protocol pushes all contacts' information to the + connection manager without prompting. If set, + <tp:member-ref>RequestContactInfo</tp:member-ref> will not cause a + network roundtrip and + <tp:member-ref>ContactInfoChanged</tp:member-ref> will be emitted + whenever contacts' information changes. + </tp:docstring> + </tp:enumvalue> + </tp:enum> + + <property name="ContactInfoFlags" type="u" access="read" + tp:type="Contact_Info_Flag" tp:name-for-bindings="Contact_Info_Flags"> + <tp:docstring> + An integer representing the bitwise-OR of flags on this channel. This + property should be constant over the lifetime of a connection. + </tp:docstring> + </property> + + <tp:struct name="Field_Spec" array-name="Field_Specs"> + <tp:docstring>A struct describing a vCard field, with parameters, that + may be passed to <tp:member-ref>SetContactInfo</tp:member-ref> on this + Connection.</tp:docstring> + + <tp:member type="s" name="Name"> + <tp:docstring>A vCard field name, such as 'tel'.</tp:docstring> + </tp:member> + + <tp:member type="as" name="Parameters"> + <tp:docstring>The set of vCard type parameters which may be set on this + field. If this list is empty and the + Contact_Info_Field_Flag_Parameters_Mandatory + flag is unset, any vCard type parameters may be used.</tp:docstring> + </tp:member> + + <tp:member type="u" name="Flags" tp:type="Contact_Info_Field_Flags"> + <tp:docstring>Flags describing the behaviour of this + field.</tp:docstring> + </tp:member> + + <tp:member type="u" name="Max"> + <tp:docstring>Maximum number of instances of this field which may be + set. MAXUINT32 is used to indicate that there is no + limit.</tp:docstring> + </tp:member> + </tp:struct> + + <property name="SupportedFields" type="a(sasuu)" tp:type="Field_Spec[]" + access="read" tp:name-for-bindings="Supported_Fields"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A list of field specifications describing the kinds of fields which may + be passed to <tp:member-ref>SetContactInfo</tp:member-ref>. The empty + list indicates that arbitrary vCard fields are permitted. This + property SHOULD be the empty list, and be ignored by clients, if + <tp:member-ref>ContactInfoFlags</tp:member-ref> does not contain the + Can_Set <tp:type>Contact_Info_Flag</tp:type>.</p> + + <p>For example, an implementation of XEP-0054, which defines a mapping + of vCards to XML for use over XMPP, would set this property to the + empty list. A protocol whose notion of contact information is one + each of personal phone number, mobile phone number, location, email + address and date of birth, with no attributes allowed on each piece + of information, would set this property to (in Python-like + syntax):</p> + + <pre> +[ + ('tel', ['home'], Parameters_Mandatory, 1), + ('tel', ['cell'], Parameters_Mandatory, 1), + ('adr', [], Parameters_Mandatory, 1), + ('bday', [], Parameters_Mandatory, 1), + ('email', ['internet'], Parameters_Mandatory, 1), +]</pre> + + <p>A protocol which allows users to specify up to four phone numbers, + which may be labelled as personal and/or mobile, would set this + property to <code>[ ('tel', ['home', 'cell'], 0, 4), ]</code>.</p> + + <tp:rationale> + <p>Studying existing IM protocols shows that in practice protocols + allow either a very restricted set of fields (such as MSN, which + seems to correspond roughly to the largest example above) or + something mapping 1-1 to vCard (such as XMPP).</p> + </tp:rationale> + </tp:docstring> + </property> + + <tp:flags name="Contact_Info_Field_Flags" + value-prefix="Contact_Info_Field_Flag" type="u"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + Flags describing the behaviour of a vCard field. + </tp:docstring> + <tp:flag suffix="Parameters_Mandatory" value="1"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If present, exactly the parameters indicated must be set on this + field; in the case of an empty list of parameters, this implies that + parameters may not be used.</p> + + <p>If absent, and the list of allowed parameters is non-empty, + any (possibly empty) subset of that list may be + used.</p> + + <p>If absent, and the list of allowed parameters is empty, + any parameters may be used.</p> + </tp:docstring> + </tp:flag> + </tp:flags> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>An interface for requesting information about a contact on a given - connection. Information is returned as a vCard represented as an XML - string, in the format defined by JEP-0054: vcard-temp specifiation - from the Jabber Software Foundation (this is derived from the - aborted IETF draft draft-dawson-vcard-xml-dtd-01).</p> - - <p>Implementations using PHOTO or SOUND elements should use the URI encoding - where possible, and not provide base64 encoded data to avoid unnecessary - bus traffic. Clients should not implement support for these encoded forms. - A separate interface will be provided for transferring user avatars.</p> - - <p>The following extended element names are also added to represent - information from other systems which are not based around vCards:</p> - <dl> - <dt>USERNAME</dt><dd>the username of the contact on their local system (used on IRC for example)</dd> - <dt>HOSTNAME</dt><dd>the fully qualified hostname, or IPv4 or IPv6 address of the contact in dotted quad or colon-separated form</dd> - </dl> + connection. Information is represented as a list of + <tp:type>Contact_Info_Field</tp:type>s forming a + structured representation of a vCard (as defined by RFC 2426), using + field names and semantics defined therein.</p> </tp:docstring> </interface> </node> diff --git a/spec/Connection_Interface_Contacts.xml b/spec/Connection_Interface_Contacts.xml index e04ea5f2..1033e045 100644 --- a/spec/Connection_Interface_Contacts.xml +++ b/spec/Connection_Interface_Contacts.xml @@ -75,6 +75,7 @@ first member). Omitted from the result if the contact's capabilities are not known; present in the result as an empty array if the contact is known to have no capabilities at all.</dd> + <dt>org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities.DRAFT/caps (type a{ua(a{sv}as)}, <tp:type>Contact_Capabilities_Map</tp:type>)</dt> @@ -83,6 +84,14 @@ Omitted from the result if the contact's capabilities are not known; present in the result as an empty array if the contact is known to have no capabilities at all.</dd> + + <dt>org.freedesktop.Telepathy.Connection.Interface.Location.DRAFT/location + (type a{sv}, <tp:type>Location</tp:type>)</dt> + <dd>The same struct used by + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface.Location.DRAFT">GetLocations</tp:dbus-ref> + Omitted from the result if the contact's location + is not known.</dd> + </dl> </tp:docstring> diff --git a/spec/Connection_Interface_Location.xml b/spec/Connection_Interface_Location.xml new file mode 100644 index 00000000..8821ec01 --- /dev/null +++ b/spec/Connection_Interface_Location.xml @@ -0,0 +1,394 @@ +<?xml version="1.0" ?> +<node name="/Connection_Interface_Location" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright (C) 2008 Collabora Ltd.</tp:copyright> + <tp:copyright>Copyright (C) 2008 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.Interface.Location.DRAFT" + tp:causes-havoc='experimental'> + <tp:added version="0.17.18">(as a draft)</tp:added> + <tp:requires interface="org.freedesktop.Telepathy.Connection"/> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An interface on connections to support protocols which allow users to + publish their current geographical location, and subscribe to the + current location of their contacts.</p> + + <p>This interface is geared strongly towards automatic propagation and + use of this information, so focuses on latitude, longitude and + altitude which can be determined by GPS, although provision is also + included for an optional human-readable description of locations. All + co-ordinate information is required to be relative to the WGS84 + datum.</p> + + <p>The information published through this interface is intended to have + the same scope as presence information, so will normally be made + available to those individuals on the user's "publish" contact list. + Even so, user interfaces should not automatically publish location + information without the consent of the user, and it is recommended + that an option is made available to reduce the accuracy of the + reported information to allow the user to maintain their privacy.</p> + + <p>Location information is represented using the terminology of XMPP's + <a href="http://www.xmpp.org/extensions/xep-0080.html">XEP-0080</a> + or the XEP-0080-derived + <a href="http://geoclue.freedesktop.org/">Geoclue</a> API where + possible.</p> + </tp:docstring> + + <tp:enum name="Location_Accuracy_Level" type="i"> + <tp:docstring> + A location accuracy level. This should be kept in sync with + GeoclueAccuracyLevel in the Geoclue project. + </tp:docstring> + + <tp:enumvalue suffix="None" value="0"> + <tp:docstring> + The accuracy is unspecified. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Country" value="1"> + <tp:docstring> + The location indicates the contact's country. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Region" value="2"> + <tp:docstring> + The location indicates the contact's region within a country. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Locality" value="3"> + <tp:docstring> + The location indicates the contact's locality within a region + (e.g. the correct city). + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Postal_Code" value="4"> + <tp:docstring> + The location indicates the correct postal code. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Street" value="5"> + <tp:docstring> + The location indicates the correct street. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Detailed" value="6"> + <tp:docstring> + The location's accuracy is given by the error, horizontal-error-m + and/or vertical-error-m keys. + </tp:docstring> + </tp:enumvalue> + </tp:enum> + + <tp:mapping name="Location"> + <tp:docstring> + A user's location, represented as an extensible mapping. + </tp:docstring> + + <tp:member name="Key" type="s"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + + <p>Civic addresses are represented by the following well-known + keys (all of which have string values), which should be kept in + sync with those used in XEP-0080 and in the Geoclue project:</p> + + <ul> + <li>countrycode - s: an ISO-3166-1 alpha-2 (two-letter) country + code, e.g. "us", "gb", "fr"</li> + <li>country - s: a country name in unspecified locale, e.g. + "USA"</li> + <li>region - s: an administrative region of the nation, such as a + state or province</li> + <li>locality - s: a locality within the administrative region, such + as a town or city</li> + <li>area - s: a named area such as a campus or neighborhood</li> + <li>postalcode - s: a code used for postal delivery</li> + <li>street - s: a thoroughfare within the locality, or a crossing of + two thoroughfares</li> + </ul> + + <p>The following address keys are defined in XEP-0080 but not by + Geoclue, and are also allowed:</p> + + <ul> + <li>building - s: a specific building on a street or in an area</li> + <li>floor - s: a particular floor in a building</li> + <li>room - s: a particular room in a building</li> + <li>text - s: any more specific information, e.g. + "Northwest corner of the lobby"</li> + <li>description - s: A natural-language name for or description of + the location, e.g. "Bill's house"</li> + <li>uri - s: a URI representing the location or pointing to more + information about it</li> + </ul> + + <p>Positions are represented by the following well-known keys:</p> + + <ul> + <li>lat - d: latitude in decimal degrees north, -90 to +90, + relative to the WGS-84 datum + <tp:rationale> + This is from XEP-0080; the XEP allows use of a different + datum, but recommends this one. We enforce sanity by requiring + a consistent datum: a minimal compliant implementation of this + specification in terms of XEP-0080 would simply ignore the + <lat> and <lon> elements if <datum> exists + and has a value other than WGS-84, while an advanced + implementation might correct for the different datum. + </tp:rationale> + </li> + <li>lon - d: Longitude in decimal degrees east, -180 to +180, + relative to the WGS-84 datum + <tp:rationale> + Same rationale as 'lat' + </tp:rationale> + </li> + <li>alt - d: altitude in metres above sea level (negative + if below sea level) + <tp:rationale> + This is from XEP-0080 + </tp:rationale> + </li> + <li>accuracy-level - i (<tp:type>Location_Accuracy_Level</tp:type>): + an indication of accuracy, which SHOULD be omitted if it would be + Location_Accuracy_Level_None or + Location_Accuracy_Level_Detailed + <tp:rationale> + This is a struct field in GeoClue; the name is new in this + specification, and was chosen in an attempt to avoid clashing + with any future XEP-0080 terminology. + </tp:rationale> + </li> + <li>error - d: horizontal position error in arc-minutes (1/60 + degree) if known + <tp:rationale> + This is from XEP-0080 + </tp:rationale> + </li> + <li>vertical-error-m - d: vertical position error in metres if + known + <tp:rationale> + This exists as a struct field in GeoClue; the name is new + in this specification. + </tp:rationale> + </li> + <li>horizontal-error-m - d: horizontal position error in metres if + known + <tp:rationale> + This exists as a struct field in GeoClue; the name is new + in this specification. + </tp:rationale> + </li> + </ul> + + <p>Velocities are represented by the following well-known keys:</p> + + <ul> + <li>speed - d: speed in metres per second + <tp:rationale> + This is from XEP-0080 + </tp:rationale> + </li> + <li>bearing - d: direction of movement in decimal degrees, + where North is 0 and East is 90 + <tp:rationale> + This is from XEP-0080, and is equivalent to the struct field + called "direction" in GeoClue + </tp:rationale> + </li> + <li>climb - d: rate of change of 'alt' in metres per second + <tp:rationale> + This is a struct field in GeoClue; the name is new to this + specification, but seems uncontroversial + </tp:rationale> + </li> + </ul> + + <p>Other well-known keys:</p> + + <ul> + <li>timestamp - x (<tp:type>Unix_Timestamp64</tp:type>): the time + that the contact was at this location, in seconds since + 1970-01-01T00:00:00Z (i.e. the beginning of 1970 in UTC) + <tp:rationale> + XEP-0080 uses an ISO 8601 string for this, but a number of + seconds since the epoch is probably easier to work with. + </tp:rationale> + </li> + </ul> + </tp:docstring> + </tp:member> + + <tp:member name="Value" type="v"> + <tp:docstring> + The value corresponding to the well-known key. + </tp:docstring> + </tp:member> + </tp:mapping> + + <tp:mapping name="Contact_Locations" type="a{ua{sv}}"> + <tp:docstring> + A map from contacts to their locations. + </tp:docstring> + <tp:member name="Contact" type="u" tp:type="Contact_Handle"> + <tp:docstring>A contact</tp:docstring> + </tp:member> + <tp:member name="Location" type="a{sv}" tp:type="Location"> + <tp:docstring>The contact's location, which MAY be empty to indicate + that the contact's location is unknown</tp:docstring> + </tp:member> + </tp:mapping> + + <method name="GetLocations" tp:name-for-bindings="Get_Locations"> + <tp:docstring> + Return the current locations of the given contacts, if they are + already known. If any of the given contacts' locations are not known, + request their current locations, but return immediately without waiting + for a reply; if a reply with a non-empty location is later received + for those contacts, the <tp:member-ref>LocationUpdated</tp:member-ref> + signal will be emitted for them. + + <tp:rationale> + This method is appropriate for "lazy" location finding, for instance + displaying the location (if available) of everyone in your contact + list. + </tp:rationale> + </tp:docstring> + + <arg direction="in" name="Contacts" type="au" tp:type="Contact_Handle[]"> + <tp:docstring> + The contacts whose locations should be returned or signalled. + </tp:docstring> + </arg> + + <arg direction="out" name="Locations" type="a{ua{sv}}" + tp:type="Contact_Locations"> + <tp:docstring> + The contacts' locations, if already known. Contacts whose locations + are not already known are omitted from the mapping; contacts known + to have no location information appear in the mapping with an empty + Location dictionary. + </tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> + </tp:possible-errors> + </method> + + <method name="RequestLocation" tp:name-for-bindings="Request_Location"> + <tp:docstring> + Return the current location of the given contact. If necessary, make + a request to the server for up-to-date information, and wait for a + reply. + + <tp:rationale> + This method is appropriate for use in a "Contact Information..." + dialog; it can be used to show progress information (while waiting + for the method to return), and can distinguish between various error + conditions. + </tp:rationale> + </tp:docstring> + + <arg direction="in" name="Contact" type="u" tp:type="Contact_Handle"> + <tp:docstring> + The contact whose location should be returned. + </tp:docstring> + </arg> + + <arg direction="out" name="Location" type="a{sv}" tp:type="Location"> + <tp:docstring> + The contact's location. It MAY be empty, indicating that no location + information was found. + </tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> + <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"> + <tp:docstring> + The requested contact does not allow the local user to see their + location information. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <signal name="LocationUpdated" tp:name-for-bindings="Location_Updated"> + <tp:docstring> + Emitted when a contact's location changes or becomes known. + </tp:docstring> + + <arg name="Contact" type="u" tp:type="Contact_Handle"> + <tp:docstring> + The contact + </tp:docstring> + </arg> + <arg name="Location" type="a{sv}" tp:type="Location"> + <tp:docstring> + The contact's location, or empty to indicate that nothing is known + about the contact's location. + </tp:docstring> + </arg> + </signal> + + <method name="SetLocation" tp:name-for-bindings="Set_Location"> + <tp:docstring> + Set the local user's own location. + </tp:docstring> + + <arg direction="in" name="Location" type="a{sv}"> + <tp:docstring> + The location to advertise. If the user wants to obscure their + exact location by reducing the precision or accuracy, clients + MUST do this themselves, rather than relying on the connection + manager to do so. Clients that interact with more than one + connection SHOULD advertise the same reduced-accuracy location + to all of them, so that contacts cannot obtain an undesirably + accurate location by assuming that random errors have been added + and averaging the locations advertised on multiple connections. + </tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"/> + <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> + </tp:possible-errors> + </method> + + <property name="LocationAccessControlTypes" type="au" access="read" + tp:type="Rich_Presence_Access_Control_Type[]" tp:name-for-bindings="Location_Access_Control_Types"> + <tp:docstring>The types of access control that are supported by this + connection.</tp:docstring> + </property> + + <property name="LocationAccessControl" type="(uv)" access="readwrite" + tp:type="Rich_Presence_Access_Control" tp:name-for-bindings="Location_Access_Control"> + <tp:docstring>The current access control mechanism and settings + for this connection. Before publishing location for the first time, + if this has not been set by a client, implementations SHOULD + set it to be as restrictive as possible (an empty whitelist, if + supported).</tp:docstring> + </property> + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Connection_Interface_Presence.xml b/spec/Connection_Interface_Presence.xml index cfcb856c..6d9b24a1 100644 --- a/spec/Connection_Interface_Presence.xml +++ b/spec/Connection_Interface_Presence.xml @@ -131,7 +131,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:possible-errors> </method> <method name="GetStatuses" tp:name-for-bindings="Get_Statuses"> - <arg direction="out" type="a{s(ubba{ss})}" tp:type="Status_Spec_Map"> + <arg direction="out" type="a{s(ubba{ss})}" tp:type="Status_Spec_Map" + name="Available_Statuses"> <tp:docstring> A dictionary of string identifiers mapped to a struct for each status, containing: <ul> @@ -160,7 +161,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ A dictionary of contact handles mapped to a struct containing a UNIX timestamp of the last activity time (in UTC), and a dictionary mapping the contact's current status identifiers to - a dictionary of optional parameter names mapped to their + a dictionary of optional parameter names mapped to their variant-boxed values </tp:docstring> </arg> @@ -396,6 +397,67 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:docstring> </tp:enumvalue> </tp:enum> + + <tp:enum name="Rich_Presence_Access_Control_Type" type="u"> + <tp:docstring> + A type of access control for Rich_Presence_Access_Control. + For most types, the exact access control is given by an associated + variant. + + <tp:rationale> + These are the access control types from XMPP publish/subscribe + (XEP-0060). + </tp:rationale> + </tp:docstring> + + <tp:enumvalue suffix="Whitelist" value="0"> + <tp:docstring> + The associated variant is a list of contacts (signature 'au', + Contact_Handle[]) who can see the extended presence information. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Publish_List" value="1"> + <tp:docstring> + All contacts in the user's 'publish' contact list can see the + extended presence information. The associated variant is ignored. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Group" value="2"> + <tp:docstring> + The associated variant is a handle of type Group (signature 'u', + Group_Handle) representing a group of contacts who can see the + extended presence information. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Open" value="3"> + <tp:docstring> + Anyone with access to the service can see the extended presence + information. + </tp:docstring> + </tp:enumvalue> + </tp:enum> + + <tp:struct name="Rich_Presence_Access_Control"> + <tp:docstring> + An access control mode for extended presence items like geolocation. + This type isn't actually used by the core Presence interface, but + it's included here so it can be referenced by other specifications. + </tp:docstring> + + <tp:member name="Type" type="u" tp:type="Rich_Presence_Access_Control_Type"> + <tp:docstring> + The type of access control to apply. + </tp:docstring> + </tp:member> + <tp:member name="Detail" type="v"> + <tp:docstring> + Any additional information required by the Type. The required + type and semantics are defined for each + Rich_Presence_Access_Control_Type. + </tp:docstring> + </tp:member> + </tp:struct> + </interface> </node> <!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Connection_Interface_Requests.xml b/spec/Connection_Interface_Requests.xml index f8385341..3e472621 100644 --- a/spec/Connection_Interface_Requests.xml +++ b/spec/Connection_Interface_Requests.xml @@ -199,6 +199,24 @@ namespace="org.freedesktop.Telepathy">Channel.TargetID</tp:dbus-ref>). </tp:docstring> </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring> + The request matched the fixed properties of a + <tp:type>Requestable_Channel_Class</tp:type> in + <tp:member-ref>RequestableChannelClasses</tp:member-ref>, but the + allowed arguments did not make sense; for example, a <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type">RoomList</tp:dbus-ref> + was requested, but the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type.RoomList">Server</tp:dbus-ref> + property provided was not a valid DNS name. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotCapable"> + <tp:docstring> + The requested channel cannot be created because the requested + contact is using a client that lacks a particular feature. + </tp:docstring> + </tp:error> <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The requested channel cannot be created, but in @@ -206,8 +224,6 @@ For instance, this might be because:</p> <ul> - <li>the requested contact is using a client - that lacks a particular feature</li> <li>a channel matching the request already exists and the protocol requires that only one such channel can exist at a time</li> @@ -322,12 +338,28 @@ namespace="org.freedesktop.Telepathy">Channel.TargetID</tp:dbus-ref>). </tp:docstring> </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring> + The request matched the fixed properties of a + <tp:type>Requestable_Channel_Class</tp:type> in + <tp:member-ref>RequestableChannelClasses</tp:member-ref>, but the + allowed arguments did not make sense; for example, a <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type">RoomList</tp:dbus-ref> + was requested, but the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type.RoomList">Server</tp:dbus-ref> + property provided was not a valid DNS name. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotCapable"> + <tp:docstring> + The requested channel cannot be created because the requested + contact is using a client that lacks a particular feature. + </tp:docstring> + </tp:error> <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> <tp:docstring> The requested channel cannot be created, but in - principle, a similar request might succeed in future. For instance, - this might be because the requested contact is using a client - that lacks a particular feature. + principle, a similar request might succeed in future. </tp:docstring> </tp:error> <tp:error name="org.freedesktop.Telepathy.Error.Channel.Banned"/> diff --git a/spec/Connection_Manager.xml b/spec/Connection_Manager.xml index eafa6df6..46b56ac7 100644 --- a/spec/Connection_Manager.xml +++ b/spec/Connection_Manager.xml @@ -158,7 +158,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ The required protocol name </tp:docstring> </arg> - <arg direction="out" type="a(susv)" tp:type="Param_Spec[]"> + <arg direction="out" type="a(susv)" tp:type="Param_Spec[]" + name="Parameters"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> An array of structs representing possible parameters. </tp:docstring> @@ -178,7 +179,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </method> <method name="ListProtocols" tp:name-for-bindings="List_Protocols"> - <arg direction="out" type="as" tp:type="Protocol[]"> + <arg direction="out" type="as" tp:type="Protocol[]" name="Protocols"> <tp:docstring> A array of string protocol identifiers supported by this manager </tp:docstring> @@ -226,12 +227,12 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ and the above well-known list. </tp:docstring> </arg> - <arg direction="out" type="s" tp:type="DBus_Bus_Name"> + <arg direction="out" type="s" tp:type="DBus_Bus_Name" name="Bus_Name"> <tp:docstring> A D-Bus service name where the new Connection object can be found </tp:docstring> </arg> - <arg direction="out" type="o"> + <arg direction="out" type="o" name="Object_Path"> <tp:docstring> The D-Bus object path to the Connection on this service </tp:docstring> diff --git a/spec/Media_Stream_Handler.xml b/spec/Media_Stream_Handler.xml index 35866a65..cb7c7932 100644 --- a/spec/Media_Stream_Handler.xml +++ b/spec/Media_Stream_Handler.xml @@ -98,7 +98,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <method name="CodecChoice" tp:name-for-bindings="Codec_Choice"> <arg direction="in" name="Codec_ID" type="u"/> <tp:docstring> - Inform the connection manager of the current codec choice. + Inform the connection manager of codec used to receive data. </tp:docstring> </method> <method name="Error" tp:name-for-bindings="Error"> @@ -222,10 +222,21 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ Locally-supported codecs </tp:docstring> </arg> - <tp:docstring> - Used to provide codecs after Ready(), so the media client can go - ready for an incoming call and exchange candidates/codecs before - knowing what local codecs are available. + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Used to provide codecs after Ready(), so the media client can go + ready for an incoming call and exchange candidates/codecs before + knowing what local codecs are available.</p> + + <p>This is useful for gatewaying calls between two connection managers. + Given an incoming call, you need to call + <tp:member-ref>Ready</tp:member-ref> to get the remote codecs before + you can use them as the "local" codecs to place the outgoing call, + and hence receive the outgoing call's remote codecs to use as the + incoming call's "local" codecs.</p> + + <p>In this situation, you would pass an empty list of codecs to the + incoming call's Ready method, then later call SetLocalCodecs on the + incoming call in order to respond to the offer.</p> </tp:docstring> </method> <signal name="RemoveRemoteCandidate" @@ -235,10 +246,19 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ String identifier for remote candidate to drop </tp:docstring> </arg> + <tp:deprecated> + There is no case where you want to release candidates (except + for an ICE reset, and there you'd want to replace then all, + using <tp:member-ref>SetRemoteCandidateList</tp:member-ref>). + </tp:deprecated> <tp:docstring> Signal emitted when the connection manager wishes to inform the client that the remote end has removed a previously usable candidate. + + <tp:rationale> + It seemed like a good idea at the time, but wasn't. + </tp:rationale> </tp:docstring> </signal> <signal name="SetActiveCandidatePair" @@ -275,13 +295,22 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <tp:docstring> Signal emitted when the connection manager wishes to inform the client of the codecs supported by the remote end. + If these codecs are compatible with the remote codecs, then the client + must call <tp:member-ref>SupportedCodecs</tp:member-ref>, + otherwise call <tp:member-ref>Error</tp:member-ref>. </tp:docstring> </signal> <signal name="SetStreamPlaying" tp:name-for-bindings="Set_Stream_Playing"> <arg name="Playing" type="b"/> <tp:docstring> - Signal emitted when the connection manager wishes to set the - stream playing or stopped. + If emitted with argument TRUE, this means that the connection manager + wishes to set the stream playing; this means that the streaming + implementation should expect to receive data. If emitted with argument + FALSE this signal is basically meaningless and should be ignored. + + <tp:rationale> + We're very sorry. + </tp:rationale> </tp:docstring> </signal> <signal name="SetStreamSending" tp:name-for-bindings="Set_Stream_Sending"> @@ -317,6 +346,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ as specified in Channel.Type.StreamedMedia::ListStreams. </tp:docstring> </method> + <method name="SupportedCodecs" tp:name-for-bindings="Supported_Codecs"> <arg direction="in" name="Codecs" type="a(usuuua{ss})" tp:type="Media_Stream_Handler_Codec[]"> @@ -333,6 +363,25 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:docstring> </method> + <method name="CodecsUpdated" tp:name-for-bindings="Codecs_Updated"> + <arg direction="in" name="Codecs" type="a(usuuua{ss})" + tp:type="Media_Stream_Handler_Codec[]"> + <tp:docstring> + Locally supported codecs, which SHOULD be the same as were previously + in effect, but possibly with different parameters. + </tp:docstring> + </arg> + <tp:docstring> + Inform the connection manager that the parameters of the supported + codecs for this session have changed. The connection manager should + send the new parameters to the remote contact. + + <tp:rationale> + This is required for H.264 and Theora, for example. + </tp:rationale> + </tp:docstring> + </method> + <signal name="SetStreamHeld" tp:name-for-bindings="Set_Stream_Held"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Emitted when the connection manager wishes to place the stream on diff --git a/spec/Properties_Interface.xml b/spec/Properties_Interface.xml index 2773d753..91423c10 100644 --- a/spec/Properties_Interface.xml +++ b/spec/Properties_Interface.xml @@ -62,7 +62,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <arg direction="in" name="Properties" type="au" tp:type="Property_ID[]"> <tp:docstring>An array of property identifiers</tp:docstring> </arg> - <arg direction="out" type="a(uv)" tp:type="Property_Value[]"> + <arg direction="out" type="a(uv)" tp:type="Property_Value[]" + name="Values"> <!-- XXX: if we're ever breaking API compatibility, make this a{uv} --> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>An array of structs containing:</p> @@ -90,7 +91,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <tp:docstring> Returns a dictionary of the properties available on this channel. </tp:docstring> - <arg direction="out" type="a(ussu)" tp:type="Property_Spec[]"> + <arg direction="out" type="a(ussu)" tp:type="Property_Spec[]" + name="Available_Properties"> <!-- XXX: if we're ever breaking API compatibility, make this a{u(ssu)} ? --> <tp:docstring> diff --git a/spec/all.xml b/spec/all.xml index a1fd7453..7745d549 100644 --- a/spec/all.xml +++ b/spec/all.xml @@ -3,7 +3,7 @@ xmlns:xi="http://www.w3.org/2001/XInclude"> <tp:title>Telepathy D-Bus Interface Specification</tp:title> -<tp:version>0.17.17</tp:version> +<tp:version>0.17.19</tp:version> <tp:copyright>Copyright (C) 2005-2008 Collabora Limited</tp:copyright> <tp:copyright>Copyright (C) 2005-2008 Nokia Corporation</tp:copyright> @@ -31,11 +31,13 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <xi:include href="Connection_Interface_Avatars.xml"/> <xi:include href="Connection_Interface_Capabilities.xml"/> <xi:include href="Connection_Interface_Contact_Capabilities.xml"/> +<xi:include href="Connection_Interface_Contact_Info.xml"/> <xi:include href="Connection_Interface_Contacts.xml"/> -<xi:include href="Connection_Interface_Simple_Presence.xml"/> +<xi:include href="Connection_Interface_Location.xml"/> <xi:include href="Connection_Interface_Presence.xml"/> <xi:include href="Connection_Interface_Renaming.xml"/> <xi:include href="Connection_Interface_Requests.xml"/> +<xi:include href="Connection_Interface_Simple_Presence.xml"/> <xi:include href="Channel_Bundle.xml"/> @@ -43,6 +45,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <xi:include href="Channel_Future.xml"/> <xi:include href="Channel_Type_Contact_List.xml"/> <xi:include href="Channel_Type_Streamed_Media.xml"/> +<xi:include href="Channel_Type_Streamed_Media_Future.xml"/> <xi:include href="Channel_Type_Room_List.xml"/> <xi:include href="Channel_Type_Text.xml"/> <xi:include href="Channel_Type_Tubes.xml"/> @@ -60,6 +63,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <xi:include href="Channel_Interface_HTML.xml"/> <xi:include href="Channel_Interface_Password.xml"/> <xi:include href="Channel_Interface_Media_Signalling.xml"/> +<xi:include href="Channel_Interface_Media_Signalling_Future.xml"/> <xi:include href="Channel_Interface_Messages.xml"/> <xi:include href="Channel_Interface_Tube.xml"/> @@ -87,8 +91,6 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <xi:include href="errors.xml"/> <xi:include href="generic-types.xml"/> -<!-- Never implemented, is a terrible API -<xi:include href="Connection_Interface_Contact_Info.xml"/> --> <!-- Never implemented, insufficient (needs conditions) <xi:include href="Connection_Interface_Forwarding.xml"/> --> <!-- Never implemented, vague diff --git a/spec/errors.xml b/spec/errors.xml index 679e3f4e..0a2d7d2d 100644 --- a/spec/errors.xml +++ b/spec/errors.xml @@ -35,7 +35,17 @@ <tp:error name="Disconnected"> <tp:docstring> - The connection is not currently connected and cannot be used. + The connection is not currently connected and cannot be used. + This error may also be raised when operations are performed on a + Connection for which + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection">StatusChanged</tp:dbus-ref> + has signalled status Disconnected for reason None. + + <tp:rationale> + The second usage corresponds to None in the + <tp:type>Connection_Status_Reason</tp:type> enum; if a better reason + is available, the corresponding error should be used instead. + </tp:rationale> </tp:docstring> </tp:error> @@ -73,7 +83,216 @@ <tp:error name="Cancelled"> <tp:docstring> Raised by an ongoing request if it is cancelled by user request before - it has completed. + it has completed, or when operations are performed on an object which + the user has asked to close (for instance, a Connection where the user + has called Disconnect, or a Channel where the user has called Close). + + <tp:rationale> + The second form can be used to correspond to the Requested member in + the <tp:type>Connection_Status_Reason</tp:type> enum, or to + to represent the situation where disconnecting a Connection, + closing a Channel, etc. has been requested by the user but this + request has not yet been acted on, for instance because the + service will only act on the request when it has finished processing + an event queue. + </tp:rationale> + </tp:docstring> + </tp:error> + + <tp:error name="Authentication Failed"> + <tp:docstring> + Raised when authentication with a service was unsuccessful. + <tp:rationale> + This corresponds to Authentication_Failed in the + <tp:type>Connection_Status_Reason</tp:type> enum. + </tp:rationale> + </tp:docstring> + </tp:error> + + <tp:error name="Encryption Not Available"> + <tp:docstring> + Raised if a user request insisted that encryption should be used, + but encryption was not actually available. + + <tp:rationale> + This corresponds to part of Encryption_Error in the + <tp:type>Connection_Status_Reason</tp:type> enum. It's been separated + into a distinct error here because the two concepts that were part + of EncryptionError seem to be things that could reasonably appear + differently in the UI. + </tp:rationale> + </tp:docstring> + </tp:error> + + <tp:error name="Encryption Error"> + <tp:docstring> + Raised if encryption appears to be available, but could not actually be + used (for instance if SSL/TLS negotiation fails). + <tp:rationale> + This corresponds to part of Encryption_Error in the + <tp:type>Connection_Status_Reason</tp:type> enum. + </tp:rationale> + </tp:docstring> + </tp:error> + + <tp:error name="Cert.Not Provided"> + <tp:docstring> + Raised if the server did not provide a SSL/TLS certificate. This error + MUST NOT be used to represent the absence of a client certificate + provided by the Telepathy connection manager. + <tp:rationale> + This corresponds to Cert_Not_Provided in the + <tp:type>Connection_Status_Reason</tp:type> enum. That error + explicitly applied only to server SSL certificates, so this one + is similarly limited; having the CM present a client certificate + is a possible future feature, but it should have its own error + handling. + </tp:rationale> + </tp:docstring> + </tp:error> + + <tp:error name="Cert.Untrusted"> + <tp:docstring> + Raised if the server provided a SSL/TLS certificate signed by an + untrusted certifying authority. This error SHOULD NOT be used to + represent a self-signed certificate: see the Self Signed error for that. + <tp:rationale> + This corresponds to Cert_Untrusted in the + <tp:type>Connection_Status_Reason</tp:type> enum, with a clarification + to avoid ambiguity. + </tp:rationale> + </tp:docstring> + </tp:error> + + <tp:error name="Cert.Expired"> + <tp:docstring> + Raised if the server provided an expired SSL/TLS certificate. + <tp:rationale> + This corresponds to Cert_Expired in the + <tp:type>Connection_Status_Reason</tp:type> enum. + </tp:rationale> + </tp:docstring> + </tp:error> + + <tp:error name="Cert.Not Activated"> + <tp:docstring> + Raised if the server provided an SSL/TLS certificate that will become + valid at some point in the future. + <tp:rationale> + This corresponds to Cert_Not_Activated in the + <tp:type>Connection_Status_Reason</tp:type> enum. + </tp:rationale> + </tp:docstring> + </tp:error> + + <tp:error name="Cert.Fingerprint Mismatch"> + <tp:docstring> + Raised if the server provided an SSL/TLS certificate that did not have + the expected fingerprint. + <tp:rationale> + This corresponds to Cert_Fingerprint_Mismatch in the + <tp:type>Connection_Status_Reason</tp:type> enum. + </tp:rationale> + </tp:docstring> + </tp:error> + + <tp:error name="Cert.Hostname Mismatch"> + <tp:docstring> + Raised if the server provided an SSL/TLS certificate that did not match + its hostname. + <tp:rationale> + This corresponds to Cert_Hostname_Mismatch in the + <tp:type>Connection_Status_Reason</tp:type> enum. + </tp:rationale> + </tp:docstring> + </tp:error> + + <tp:error name="Cert.Self Signed"> + <tp:docstring> + Raised if the server provided an SSL/TLS certificate that is self-signed + and untrusted. + <tp:rationale> + This corresponds to Cert_Hostname_Mismatch in the + <tp:type>Connection_Status_Reason</tp:type> enum. + </tp:rationale> + </tp:docstring> + </tp:error> + + <tp:error name="Cert.Invalid"> + <tp:docstring> + Raised if the server provided an SSL/TLS certificate that is + unacceptable in some way that does not have a more specific error. + <tp:rationale> + This corresponds to Cert_Other_Error in the + <tp:type>Connection_Status_Reason</tp:type> enum. + </tp:rationale> + </tp:docstring> + </tp:error> + + <tp:error name="Not Capable"> + <tp:docstring> + Raised when requested functionality is unavailable due to contact + not having required capabilities. + </tp:docstring> + </tp:error> + + <tp:error name="Offline"> + <tp:docstring> + Raised when requested functionality is unavailable because a contact is + offline. + + <tp:rationale> + This corresponds to Offline in the + <tp:type>Channel_Group_Change_Reason</tp:type> enum. + </tp:rationale> + </tp:docstring> + </tp:error> + + <tp:error name="Channel.Kicked"> + <tp:docstring> + Used to represent a user being ejected from a channel by another user, + for instance being kicked from a chatroom. + + <tp:rationale> + This corresponds to Kicked in the + <tp:type>Channel_Group_Change_Reason</tp:type> enum. + </tp:rationale> + </tp:docstring> + </tp:error> + + <tp:error name="Busy"> + <tp:docstring> + Used to represent a user being removed from a channel because of a + "busy" indication. + + <tp:rationale> + This corresponds to Busy in the + <tp:type>Channel_Group_Change_Reason</tp:type> enum. + </tp:rationale> + </tp:docstring> + </tp:error> + + <tp:error name="No Answer"> + <tp:docstring> + Used to represent a user being removed from a channel because they did + not respond, e.g. to a StreamedMedia call. + + <tp:rationale> + This corresponds to No_Answer in the + <tp:type>Channel_Group_Change_Reason</tp:type> enum. + </tp:rationale> + </tp:docstring> + </tp:error> + + <tp:error name="Does Not Exist"> + <tp:docstring> + Raised when the requested user does not, in fact, exist. + + <tp:rationale> + This corresponds to Invalid_Contact in the + <tp:type>Channel_Group_Change_Reason</tp:type> enum, but can also be + used to represent other things not existing (like chatrooms, perhaps). + </tp:rationale> </tp:docstring> </tp:error> diff --git a/spec/generic-types.xml b/spec/generic-types.xml index 227fde14..fba6a9f4 100644 --- a/spec/generic-types.xml +++ b/spec/generic-types.xml @@ -7,10 +7,10 @@ (1970-01-01T00:00:00Z)</tp:docstring> </tp:simple-type> - <tp:simple-type name="Unix_Timestamp64" type="t"> - <tp:docstring>An unsigned 64-bit integer representing time as the number + <tp:simple-type name="Unix_Timestamp64" type="x"> + <tp:docstring>An signed 64-bit integer representing time as the number of seconds elapsed since the Unix epoch - (1970-01-01T00:00:00Z)</tp:docstring> + (1970-01-01T00:00:00Z); negative for times before the epoch</tp:docstring> <tp:rationale>The Text interface is the only user of Unix_Timestamp so far, and we'd like to be Y2038 compatible in future |