diff options
| author | Simon McVittie <simon.mcvittie@collabora.co.uk> | 2008-02-21 10:11:39 +0000 |
|---|---|---|
| committer | Simon McVittie <simon.mcvittie@collabora.co.uk> | 2008-02-21 10:11:39 +0000 |
| commit | 74cc3e53e312c85c8da1ec951d36930543058eaa (patch) | |
| tree | c5d2e21c90e0a1f8a1d5c9fde0ebfaf8928c6e0e /spec | |
| parent | 6287cdd68ae7de890a475d0359b86618b0a5b252 (diff) | |
Update spec to 0.17.1
Diffstat (limited to 'spec')
26 files changed, 880 insertions, 216 deletions
diff --git a/spec/Channel.xml b/spec/Channel.xml index 43cf590..5e8678c 100644 --- a/spec/Channel.xml +++ b/spec/Channel.xml @@ -52,7 +52,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:docstring> </signal> <method name="GetChannelType"> - <arg direction="out" type="s" tp:type="Interface"> + <arg direction="out" type="s" tp:type="DBus_Interface"> <tp:docstring>The interface name</tp:docstring> </arg> <tp:docstring> @@ -79,7 +79,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:docstring> </method> <method name="GetInterfaces"> - <arg direction="out" type="as" tp:type="Interface[]"> + <arg direction="out" type="as" tp:type="DBus_Interface[]"> <tp:docstring> An array of the D-Bus interface names </tp:docstring> diff --git a/spec/Channel_Handler.xml b/spec/Channel_Handler.xml new file mode 100644 index 0000000..440ec2a --- /dev/null +++ b/spec/Channel_Handler.xml @@ -0,0 +1,62 @@ +<?xml version="1.0" ?> +<node name="/Channel_Handler" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright (C) 2007 Collabora Limited</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.ChannelHandler"> + + <method name="HandleChannel"> + <arg direction="in" type="s" name="Bus_Name" tp:type="DBus_Bus_Name"> + <tp:docstring> + The bus name of the connection and channel + </tp:docstring> + </arg> + <arg direction="in" type="o" name="Connection"> + <tp:docstring> + The object-path of the connection that owns the channel + </tp:docstring> + </arg> + <arg direction="in" type="s" tp:type="DBus_Interface" name="Channel_Type"> + <tp:docstring> + The channel type + </tp:docstring> + </arg> + <arg direction="in" type="o" name="Channel"> + <tp:docstring> + The object-path of the channel + </tp:docstring> + </arg> + <arg direction="in" type="u" tp:type="Handle_Type" name="Handle_Type"> + <tp:docstring>The type of the handle that the channel communicates + with, or 0 if there is no associated handle</tp:docstring> + </arg> + <arg direction="in" type="u" tp:type="Handle" name="Handle"> + <tp:docstring>The handle that the channel communicates with, + or 0 if there is no associated handle</tp:docstring> + </arg> + <tp:docstring> + Called when a channel handler should handle a new channel. + </tp:docstring> + <!-- FIXME: possible errors? --> + </method> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An interface exported by client applications which are able to + handle incoming channels.</p> + </tp:docstring> + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> + diff --git a/spec/Channel_Interface_Call_Merging.xml b/spec/Channel_Interface_Call_Merging.xml new file mode 100644 index 0000000..f34bf99 --- /dev/null +++ b/spec/Channel_Interface_Call_Merging.xml @@ -0,0 +1,79 @@ +<?xml version="1.0" ?> +<node name="/Channel_Interface_Call_Merging" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright> Copyright (C) 2005-2008 Collabora Limited </tp:copyright> + <tp:copyright> Copyright (C) 2005-2008 Nokia Corporation </tp:copyright> + <tp:copyright> Copyright (C) 2006 INdT </tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> +This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2.1 of the License, or (at your option) any later version. + +This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Library General Public License for more details. + +You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + </tp:license> + + <interface name="org.freedesktop.Telepathy.Channel.Interface.CallMerging" + tp:causes-havoc='not yet API-stable'> + <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.StreamedMedia"/> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Interface for streamed media channels that can be merged and split + in the same sort of way as in GSM or PBX telephony.</p> + </tp:docstring> + + <method name="Merge"> + <arg direction="in" type="o" name="Other"> + <tp:docstring> + The other channel to merge into this one + </tp:docstring> + </arg> + <tp:docstring> + Request that the given channel be merged into this one. This means + that the other channel is closed, and all its participants are added + to the channel on which this method was called. + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/> + </tp:possible-errors> + </method> + + <method name="Split"> + <arg direction="in" name="Contact" type="u" tp:type="Contact_Handle"> + <tp:docstring> + The handle of the contact to split off a conversation with, who + must be a member in the channel's Group interface + </tp:docstring> + </arg> + <arg direction="out" name="Channel" type="o"> + <tp:docstring> + The new channel + </tp:docstring> + </arg> + <tp:docstring> + Request that the given contact is removed from this channel, and + a new channel is created to communicate with them privately instead. + This is the inverse of Merge. + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/> + </tp:possible-errors> + </method> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Channel_Interface_Group.xml b/spec/Channel_Interface_Group.xml index ff3798e..940269a 100644 --- a/spec/Channel_Interface_Group.xml +++ b/spec/Channel_Interface_Group.xml @@ -20,6 +20,19 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:license> <interface name="org.freedesktop.Telepathy.Channel.Interface.Group"> <tp:requires interface="org.freedesktop.Telepathy.Channel"/> + + <tp:struct name="Local_Pending_Info" array-name="Local_Pending_Info_List"> + <tp:docstring>A struct (handle to be added, handle of contact + requesting the change, reason code, optional message) + representing a contact whose attempt to join a group is to be confirmed + by the local user, as returned by GetLocalPendingMembersWithInfo + on the Group interface.</tp:docstring> + <tp:member type="u" tp:type="Contact_Handle" name="To_Be_Added"/> + <tp:member type="u" tp:type="Contact_Handle" name="Actor"/> + <tp:member type="u" tp:type="Channel_Group_Change_Reason" name="Reason"/> + <tp:member type="s" name="Message"/> + </tp:struct> + <method name="AddMembers"> <arg direction="in" name="contacts" type="au" tp:type="Contact_Handle[]"> <tp:docstring> @@ -34,11 +47,14 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Invite all the given contacts into the channel, or accept requests for channel membership for contacts on the pending local list.</p> - + <p>A message may be provided along with the request, which will be sent to the server if supported. See the CHANNEL_GROUP_FLAG_MESSAGE_ADD and CHANNEL_GROUP_FLAG_MESSAGE_ACCEPT flags to see in which cases this message should be provided.</p> + + <p>Attempting to add contacts who are already members is allowed; + connection managers must silently accept this, without error.</p> </tp:docstring> <tp:possible-errors> <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> @@ -233,7 +249,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ requesting channel membership and awaiting local approval with AddMembers. </tp:docstring> - <arg direction="out" type="a(uuus)"> + <arg direction="out" type="a(uuus)" tp:type="Local_Pending_Info[]"> <tp:docstring> An array of structs containing: <ul> diff --git a/spec/Channel_Interface_Hold.xml b/spec/Channel_Interface_Hold.xml index c17d84c..91e72ff 100644 --- a/spec/Channel_Interface_Hold.xml +++ b/spec/Channel_Interface_Hold.xml @@ -1,7 +1,7 @@ <?xml version="1.0" ?> <node name="/Channel_Interface_Hold" 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) 2005-2008 Collabora Limited </tp:copyright> + <tp:copyright> Copyright (C) 2005-2008 Nokia Corporation </tp:copyright> <tp:copyright> Copyright (C) 2006 INdT </tp:copyright> <tp:license xmlns="http://www.w3.org/1999/xhtml"> This library is free software; you can redistribute it and/or @@ -18,106 +18,107 @@ You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. </tp:license> - <tp:enum name="Channel_Hold_State" type="u"> - <tp:enumvalue suffix="None" value="0"> - <tp:docstring> - Neither the local user and the remote member are on hold, and media - is being sent bidirectionally. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Send_Only" value="1"> - <tp:docstring> - The local user has put the remote member on hold, so is sending - media but has arranged not to receive any media streams. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Recv_Only" value="2"> - <tp:docstring> - The user has been put on hold by the remote member, so is receiving - media but has arranged not to send any media streams. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Both" value="3"> + + <interface name="org.freedesktop.Telepathy.Channel.Interface.Hold" + tp:causes-havoc='not yet API-stable'> + <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.StreamedMedia"/> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Interface for channels where you or other members may put + the channel on hold. This only makes sense for channels where + you are streaming media to or from the members.</p> + + <p>If you are placed on hold, this indicates that some or all members + of the channel will no longer be receiving media streams from you. + If the channel has the MediaSignalling interface, client applications + should stop sending media to all members of the channel.</p> + + <p>Depending on the protocol, it might not be possible to tell that + you're on hold, in which case the connection manager should always + indicate that you're not on hold unless it finds out otherwise.</p> + + <p>If you place a channel on hold, this indicates that you do not wish + to be sent media streams by any of its members and will be ignoring + any media streams you continue to receive. It also requests that the + connection manager free up any resources that are only needed for + an actively used channel (e.g. in a GSM or PBX call, it will be + necessary to place an active call on hold before you can start + another call).</p> + </tp:docstring> + + <tp:enum name="Channel_Hold_State" type="u"> <tp:docstring> - Both the local user and the remote member have agreed not to send - any media streams to each other. + The possible hold states of a call. </tp:docstring> - </tp:enumvalue> - </tp:enum> - <interface name="org.freedesktop.Telepathy.Channel.Interface.Hold"> - <tp:requires interface="org.freedesktop.Telepathy.Channel"/> - <method name="GetHoldState"> - <arg direction="in" name="member" type="u" tp:type="Contact_Handle"> + <tp:enumvalue suffix="None" value="0"> <tp:docstring> - The contact handle for a member of the channel + Neither the local user nor a remote member have placed the call on + hold. </tp:docstring> - </arg> + </tp:enumvalue> + <tp:enumvalue suffix="Local" value="1"> + <tp:docstring> + The local user has put the call on hold. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Remote" value="2"> + <tp:docstring> + The call has been put on hold by a remote member. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Both" value="3"> + <tp:docstring> + The local user and a remote member have both placed the call + on hold. + </tp:docstring> + </tp:enumvalue> + </tp:enum> + + <method name="GetHoldState"> <arg direction="out" type="u" tp:type="Channel_Hold_State"> <tp:docstring> - The member's current hold state as one of the values of - ChannelHoldState + The channel's current hold state </tp:docstring> </arg> <tp:docstring> - Given a member of the channel, return their current hold state. + Return the channel's current hold state. </tp:docstring> - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> - </tp:possible-errors> </method> + <signal name="HoldStateChanged"> - <arg name="member" type="u" tp:type="Contact_Handle"> - <tp:docstring> - The integer handle of a member of the channel - </tp:docstring> - </arg> <arg name="state" type="u" tp:type="Channel_Hold_State"> <tp:docstring> An integer representing the new hold state </tp:docstring> </arg> <tp:docstring> - Emitted to indicate that the hold state (as defined in GetHoldState - above) has changed for a member of this channel. This may occur as - a consequence of you requesting a change with RequestHold, or the - state changing as a result of a request from the remote member - or another process. + Emitted to indicate that the hold state has changed for this channel. + This may occur as a consequence of you requesting a change with + RequestHold, or the state changing as a result of a request from a + remote member or another process. </tp:docstring> </signal> + <method name="RequestHold"> - <arg direction="in" name="member" type="u" tp:type="Contact_Handle"> - <tp:docstring> - The contact handle for a member of the channel - </tp:docstring> - </arg> <arg direction="in" name="hold" type="b"> <tp:docstring> - A boolean indicating whether or not the user should be on hold + A boolean indicating whether or not the channel should be on hold </tp:docstring> </arg> <tp:docstring> - Request that a certain member be put on hold (be instructed not to send + Request that the channel be put on hold (be instructed not to send any media streams to you) or be taken off hold. Success is indicated - by the HoldStateChanged signal being emitted. + by the HoldStateChanged signal being emitted and by a successful + return from this method. </tp:docstring> <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.NotAvailable"/> </tp:possible-errors> </method> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>THIS INTERFACE IS DEPRECATED AND SHOULD NOT BE USED. Hold functionality - should be added to the StreamedMedia channel in due course.</p> - <p>Interface for channels where members may put you on hold, or you may put - members on hold. This usually only makes sense for channels where you are - streaming media to or from the members. Hold is defined as requesting - that you are not sent any media streams by another, so these states - indicate whether or not you are sending and receiving media streams - to each member of the channel.</p> - </tp:docstring> </interface> </node> <!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Channel_Interface_Transfer.xml b/spec/Channel_Interface_Transfer.xml index 94257a9..5165c9a 100644 --- a/spec/Channel_Interface_Transfer.xml +++ b/spec/Channel_Interface_Transfer.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.Channel.Interface.Transfer"> + <interface name="org.freedesktop.Telepathy.Channel.Interface.Transfer" + tp:causes-havoc='not well-tested'> <tp:requires interface="org.freedesktop.Telepathy.Channel"/> <method name="Transfer"> <arg direction="in" name="member" type="u" tp:type="Contact_Handle"> diff --git a/spec/Channel_Type_Contact_Search.xml b/spec/Channel_Type_Contact_Search.xml index 19e8aa0..f3c7fd6 100644 --- a/spec/Channel_Type_Contact_Search.xml +++ b/spec/Channel_Type_Contact_Search.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.Channel.Type.ContactSearch"> + <interface name="org.freedesktop.Telepathy.Channel.Type.ContactSearch" + tp:causes-havoc='not well-tested'> <tp:requires interface="org.freedesktop.Telepathy.Channel"/> <method name="GetSearchKeys"> <arg direction="out" type="s"> diff --git a/spec/Channel_Type_Room_List.xml b/spec/Channel_Type_Room_List.xml index fdaf7ac..5b2de13 100644 --- a/spec/Channel_Type_Room_List.xml +++ b/spec/Channel_Type_Room_List.xml @@ -20,6 +20,13 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:license> <interface name="org.freedesktop.Telepathy.Channel.Type.RoomList"> <tp:requires interface="org.freedesktop.Telepathy.Channel"/> + + <tp:struct name="Room_Info" array-name="Room_Info_List"> + <tp:member type="u" tp:type="Room_Handle" name="Handle"/> + <tp:member type="s" tp:type="DBus_Interface" name="Channel_Type"/> + <tp:member type="a{sv}" tp:type="String_Variant_Map" name="Info"/> + </tp:struct> + <method name="GetListingRooms"> <arg direction="out" type="b"> <tp:docstring> @@ -32,7 +39,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:docstring> </method> <signal name="GotRooms"> - <arg name="rooms" type="a(usa{sv})"> + <arg name="rooms" type="a(usa{sv})" tp:type="Room_Info[]"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> An array of structs containing: <ul> diff --git a/spec/Channel_Type_Streamed_Media.xml b/spec/Channel_Type_Streamed_Media.xml index b244433..d24f37f 100644 --- a/spec/Channel_Type_Streamed_Media.xml +++ b/spec/Channel_Type_Streamed_Media.xml @@ -71,7 +71,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:flag> </tp:flags> <method name="ListStreams"> - <arg direction="out" type="a(uuuuuu)"> + <arg direction="out" type="a(uuuuuu)" tp:type="Media_Stream_Info[]"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> An array of structs containing: <ul> @@ -153,7 +153,7 @@ 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)"> + <arg direction="out" type="a(uuuuuu)" tp:type="Media_Stream_Info[]"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> An array of structs (in the same order as the given stream types) containing: @@ -334,6 +334,17 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:docstring> </tp:flag> </tp:flags> + + <tp:struct name="Media_Stream_Info" array-name="Media_Stream_Info_List"> + <tp:member type="u" name="Identifier"/> + <tp:member type="u" tp:type="Contact_Handle" name="Contact"/> + <tp:member type="u" tp:type="Media_Stream_Type" name="Type"/> + <tp:member type="u" tp:type="Media_Stream_State" name="State"/> + <tp:member type="u" tp:type="Media_Stream_Direction" name="Direction"/> + <tp:member type="u" tp:type="Media_Stream_Pending_Send" + name="Pending_Send_Flags"/> + </tp:struct> + </interface> </node> <!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Channel_Type_Text.xml b/spec/Channel_Type_Text.xml index 7216d78..b2e0c65 100644 --- a/spec/Channel_Type_Text.xml +++ b/spec/Channel_Type_Text.xml @@ -20,6 +20,22 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:license> <interface name="org.freedesktop.Telepathy.Channel.Type.Text"> <tp:requires interface="org.freedesktop.Telepathy.Channel"/> + + <tp:struct name="Pending_Text_Message" array-name="Pending_Text_Message_List"> + <tp:docstring>A struct (message ID, timestamp in seconds since + 1970-01-01 00:00 UTC, sender's handle, message type, flags, text) + representing a pending text message, as returned by ListPendingMessages + on the Text channel type. The arguments of the Received signal + also match this struct's signature.</tp:docstring> + <tp:member type="u" name="Message_ID"/> + <tp:member type="u" name="Unix_Timestamp"/> + <tp:member type="u" tp:type="Contact_Handle" name="Sender"/> + <tp:member type="u" tp:type="Channel_Text_Message_Type" + name="Message_Type"/> + <tp:member type="u" tp:type="Channel_Text_Message_Flags" name="Flags"/> + <tp:member type="s" name="Text"/> + </tp:struct> + <method name="AcknowledgePendingMessages"> <arg direction="in" name="ids" type="au"> <tp:docstring> @@ -53,7 +69,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ If true, remove all messages from the queue </tp:docstring> </arg> - <arg direction="out" type="a(uuuuus)"> + <arg direction="out" type="a(uuuuus)" tp:type="Pending_Text_Message[]"> <tp:docstring> An array of structs representing the pending queue. Each contains: <ul> @@ -84,7 +100,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ A numeric identifier for acknowledging the message </tp:docstring> </arg> - <arg name="timestamp" type="u" tp:type="Timestamp"> + <arg name="timestamp" type="u" tp:type="Unix_Timestamp"> <tp:docstring> A Unix timestamp indicating when the message was received </tp:docstring> @@ -180,7 +196,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ One of the values of ChannelTextSendError </tp:docstring> </arg> - <arg name="timestamp" type="u" tp:type="Timestamp"> + <arg name="timestamp" type="u" tp:type="Unix_Timestamp"> <tp:docstring> The Unix timestamp indicating when the message was sent </tp:docstring> @@ -201,7 +217,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:docstring> </signal> <signal name="Sent"> - <arg name="timestamp" type="u" tp:type="Timestamp"> + <arg name="timestamp" type="u" tp:type="Unix_Timestamp"> <tp:docstring> Unix timestamp indicating when the message was sent </tp:docstring> @@ -322,7 +338,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ if it isn't known. </tp:docstring> </tp:property> - <tp:property name="subject-timestamp" type="u" tp:type="Timestamp"> + <tp:property name="subject-timestamp" type="u" tp:type="Unix_Timestamp"> <tp:docstring> A unix timestamp indicating when the subject was last modified. </tp:docstring> diff --git a/spec/Channel_Type_Tubes.xml b/spec/Channel_Type_Tubes.xml index efdb702..c0be619 100644 --- a/spec/Channel_Type_Tubes.xml +++ b/spec/Channel_Type_Tubes.xml @@ -18,7 +18,7 @@ You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. </tp:license> - <interface name="org.freedesktop.Telepathy.Channel.Type.Tubes" tp:name-const="CHANNEL_TYPE_TUBES"> + <interface name="org.freedesktop.Telepathy.Channel.Type.Tubes"> <tp:requires interface="org.freedesktop.Telepathy.Channel"/> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>A "tube" is a mechanism for arbitrary data transfer. Two types of @@ -37,7 +37,83 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. Socket_Address_Type and the v is dependent on the type of address.</p> </tp:docstring> - <tp:enum name="Tube_Type"> + <tp:simple-type name="Tube_ID" type="u"> + <tp:docstring>An identifier for a tube. These are local to a Tubes + channel, and may not be assumed to be the same as the other + participants' idea of the tube identifier.</tp:docstring> + </tp:simple-type> + + <tp:struct name="Tube_Info" array-name="Tube_Info_List"> + <tp:docstring>A struct (tube ID, initiator handle, tube type, + service name, parameters, state) representing a tube, as returned + by ListTubes on the Tubes channel type.</tp:docstring> + <tp:member type="u" name="Tube_ID"/> + <tp:member type="u" tp:type="Contact_Handle" name="Initiator"/> + <tp:member type="u" tp:type="Tube_Type" name="Type"/> + <tp:member type="s" name="Service"/> + <tp:member type="a{sv}" tp:type="String_Variant_Map" name="Parameters"/> + <tp:member type="u" tp:type="Tube_State" name="State"/> + </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:struct> + + <tp:struct name="Socket_Address_IPv4"> + <tp:docstring>An IPv4 address and port.</tp:docstring> + <tp:member type="s" name="Address"> + <tp:docstring>A dotted-quad IPv4 address literal: four ASCII decimal + numbers, each between 0 and 255 inclusive, e.g. + "192.168.0.1".</tp:docstring> + </tp:member> + <tp:member type="q" name="Port"> + <tp:docstring>The TCP or UDP port number.</tp:docstring> + </tp:member> + </tp:struct> + + <tp:struct name="Socket_Address_IPv6"> + <tp:docstring>An IPv6 address and port.</tp:docstring> + <tp:member type="s" name="Address"> + <tp:docstring>An IPv6 address literal as specified by RFC2373 + section 2.2, e.g. "2001:DB8::8:800:200C:4171".</tp:docstring> + </tp:member> + <tp:member type="q" name="Port"> + <tp:docstring>The TCP or UDP port number.</tp:docstring> + </tp:member> + </tp:struct> + + <tp:struct name="Socket_Netmask_IPv4"> + <tp:docstring>An IPv4 network or subnet.</tp:docstring> + <tp:member type="s" name="Address"> + <tp:docstring>A dotted-quad IPv4 address literal: four ASCII decimal + numbers, each between 0 and 255 inclusive, e.g. + "192.168.0.1".</tp:docstring> + </tp:member> + <tp:member type="y" name="Prefix_Length"> + <tp:docstring>The number of leading bits of the address that must + match, for this netmask to be considered to match an + address.</tp:docstring> + </tp:member> + </tp:struct> + + <tp:struct name="Socket_Netmask_IPv6"> + <tp:docstring>An IPv6 network or subnet.</tp:docstring> + <tp:member type="s" name="Address"> + <tp:docstring>An IPv6 address literal as specified by RFC2373 + section 2.2, e.g. "2001:DB8::8:800:200C:4171".</tp:docstring> + </tp:member> + <tp:member type="y" name="Prefix_Length"> + <tp:docstring>The number of leading bits of the address that must + match, for this netmask to be considered to match an + address.</tp:docstring> + </tp:member> + </tp:struct> + + <tp:enum name="Tube_Type" type="u"> <tp:enumvalue suffix="DBus" value="0"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>An ordered reliable transport, for transporting D-Bus @@ -86,7 +162,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. </tp:enumvalue> </tp:enum> - <tp:enum name="Tube_State"> + <tp:enum name="Tube_State" type="u"> <tp:enumvalue suffix="Local_Pending" value="0"> <tp:docstring> The tube is waiting to be accepted/closed locally. @@ -104,7 +180,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. </tp:enumvalue> </tp:enum> - <tp:enum name="Socket_Address_Type"> + <tp:enum name="Socket_Address_Type" type="u"> <tp:enumvalue suffix="Unix" value="0"> <tp:docstring> A Unix socket. The variant contains a byte-array, signature 'ay', @@ -122,7 +198,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <tp:enumvalue suffix="IPv4" value="2"> <tp:docstring> - An IPv4 socket. The variant contains a struct with signature (sq) + An IPv4 socket. The variant contains a Socket_Address_IPv4, + i.e. a structure with signature (sq) in which the string is an IPv4 dotted-quad address literal (and must not be a DNS name), while the 16-bit unsigned integer is the port number. @@ -131,7 +208,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <tp:enumvalue suffix="IPv6" value="3"> <tp:docstring> - An IPv6 socket. The variant contains a struct with signature (sq) + An IPv6 socket. The variant contains a Socket_Address_IPv6, + i.e. a structure with signature (sq) in which the string is an IPv6 address literal as specified in RFC2373 (and must not be a DNS name), while the 16-bit unsigned integer is the port number. @@ -140,7 +218,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. </tp:enum> - <tp:enum name="Socket_Access_Control"> + <tp:enum name="Socket_Access_Control" type="u"> <tp:enumvalue suffix="Localhost" value="0"> <tp:docstring> The IP or Unix socket can be accessed by any local user (e.g. @@ -152,16 +230,18 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <tp:enumvalue suffix="Port" value="1"> <tp:docstring> May only be used on IP sockets. The associated variant must contain - a struct with signature (sq) containing the string form of an - IP address of the appropriate version, and a port number. - The socket can only be accessed if the connecting process has that - address and port number; all other connections will be rejected. + a struct Socket_Address_IPv4 (or Socket_Address_IPv6) + containing the string form of an IP address of the appropriate + version, and a port number. The socket can only be accessed if the + connecting process has that address and port number; all other + connections will be rejected. </tp:docstring> </tp:enumvalue> <tp:enumvalue suffix="Netmask" value="2"> <tp:docstring> May only be used on IP sockets. The associated variant must contain - a struct with signature (sy) containing the string form of an + a struct Socket_Netmask_IPv4 (or Socket_Netmask_IPv6) with + signature (sy), containing the string form of an IP address of the appropriate version, and a prefix length "n". The socket can only be accessed if the first n bits of the connecting address match the first n bits of the given address. @@ -185,10 +265,18 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. </tp:enumvalue> </tp:enum> + <tp:mapping name="Supported_Socket_Map"> + <tp:docstring>The supported socket address and access-control types + for tubes. See GetAvailableStreamTubeTypes.</tp:docstring> + <tp:member name="Address_Type" type="u" tp:type="Socket_Address_Type"/> + <tp:member name="Access_Control" type="au" + tp:type="Socket_Access_Control[]"/> + </tp:mapping> + <method name="GetAvailableStreamTubeTypes"> <tp:docstring>List the available address types and access-control types for stream tubes.</tp:docstring> - <arg direction="out" type="a{uau}"> + <arg direction="out" type="a{uau}" tp:type="Supported_Socket_Map"> <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) @@ -224,7 +312,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. </method> <method name="ListTubes"> - <arg direction="out" type="a(uuusa{sv}u)"> + <arg direction="out" type="a(uuusa{sv}u)" tp:type="Tube_Info[]"> <tp:docstring> Return an array of tuples, each representing a tube, with the following members: @@ -253,7 +341,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. com.example.ServiceName. </tp:docstring> </arg> - <arg direction="in" name="parameters" type="a{sv}"> + <arg direction="in" name="parameters" type="a{sv}" + tp:type="String_Variant_Map"> <tp:docstring> A dictionary of properties for the new tube; the allowable keys, types and values are defined by the service. Connection managers @@ -296,7 +385,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. "rsync" or "daap". </tp:docstring> </arg> - <arg direction="in" name="parameters" type="a{sv}"> + <arg direction="in" name="parameters" type="a{sv}" + tp:type="String_Variant_Map"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>A dictionary of properties for the new tube; the allowable keys, types and values are defined by the service. Connection managers @@ -357,7 +447,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <tp:docstring> Emitted when a tube is created. </tp:docstring> - <arg name="id" type="u"> + <arg name="id" type="u" tp:type="Tube_ID"> <tp:docstring> The ID of the new tube. </tp:docstring> @@ -377,7 +467,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. A string representing the service that will be used over the tube. </tp:docstring> </arg> - <arg name="parameters" type="a{sv}"> + <arg name="parameters" type="a{sv}" tp:type="String_Variant_Map"> <tp:docstring> The new tube's properties. </tp:docstring> @@ -396,7 +486,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. the "local pending" state until the TubeStateChanged signal is emitted. </tp:docstring> - <arg direction="in" name="id" type="u"> + <arg direction="in" name="id" type="u" tp:type="Tube_ID"> <tp:docstring> The ID of the tube to accept. </tp:docstring> @@ -424,7 +514,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. the "local pending" state until the TubeStateChanged signal is emitted. </tp:docstring> - <arg direction="in" name="id" type="u"> + <arg direction="in" name="id" type="u" tp:type="Tube_ID"> <tp:docstring> The ID of the tube to accept. </tp:docstring> @@ -473,7 +563,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <tp:docstring> Emitted when the state of a tube changes. </tp:docstring> - <arg name="id" type="u"> + <arg name="id" type="u" tp:type="Tube_ID"> <tp:docstring> The ID of the tube that changed state. </tp:docstring> @@ -489,7 +579,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <tp:docstring> Close a tube. </tp:docstring> - <arg direction="in" name="id" type="u"> + <arg direction="in" name="id" type="u" tp:type="Tube_ID"> <tp:docstring> The ID of the tube to close. </tp:docstring> @@ -504,7 +594,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. Emitted when a tube has been closed. The ID of a closed tube is no longer valid. The ID may later be reused for a new tube. </tp:docstring> - <arg name="id" type="u"> + <arg name="id" type="u" tp:type="Tube_ID"> <tp:docstring> The ID of the tube that was closed. </tp:docstring> @@ -516,7 +606,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. For a D-Bus tube, return a string describing the address of the private bus. </tp:docstring> - <arg direction="in" name="id" type="u"> + <arg direction="in" name="id" type="u" tp:type="Tube_ID"> <tp:docstring> The ID of the tube to get an address for. </tp:docstring> @@ -545,12 +635,12 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. 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="in" name="id" type="u"> + <arg direction="in" name="id" type="u" tp:type="Tube_ID"> <tp:docstring> The ID of the tube to get names for. </tp:docstring> </arg> - <arg direction="out" type="a(us)"> + <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. @@ -575,12 +665,12 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. Emitted on a multi-user (i.e. Handle_Type_Room) D-Bus tube when a participant opens or closes the tube. </tp:docstring> - <arg name="id" type="u"> + <arg name="id" type="u" tp:type="Tube_ID"> <tp:docstring> The ID of the tube whose names have changed. </tp:docstring> </arg> - <arg name="added" type="a(us)"> + <arg name="added" type="a(us)" tp:type="DBus_Tube_Member[]"> <tp:docstring> Array of handles and D-Bus names of new participants. </tp:docstring> @@ -597,7 +687,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. For a stream tube, obtain the address of the socket used to communicate over this tube. </tp:docstring> - <arg direction="in" name="id" type="u"> + <arg direction="in" name="id" type="u" tp:type="Tube_ID"> <tp:docstring> The ID of the stream tube to get the socket for. </tp:docstring> @@ -633,7 +723,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. Emitted on a stream tube when a participant opens a new connection to its socket. </tp:docstring> - <arg name="id" type="u"> + <arg name="id" type="u" tp:type="Tube_ID"> <tp:docstring> The ID of the tube </tp:docstring> diff --git a/spec/Connection.xml b/spec/Connection.xml index a7ed81e..d703ec3 100644 --- a/spec/Connection.xml +++ b/spec/Connection.xml @@ -21,6 +21,27 @@ 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"> + + <tp:struct name="Channel_Info" array-name="Channel_Info_List"> + <tp:docstring>A struct representing a channel, as returned by + ListChannels on the Connection interface.</tp:docstring> + <tp:member type="o" name="Channel"> + <tp:docstring>The object path of the channel, which is on the + same bus name as the connection</tp:docstring> + </tp:member> + <tp:member type="s" tp:type="DBus_Interface" name="Channel_Type"> + <tp:docstring>The channel's type</tp:docstring> + </tp:member> + <tp:member type="u" tp:type="Handle_Type" name="Handle_Type"> + <tp:docstring>The type of the handle that the channel communicates + with, or 0 if there is no associated handle</tp:docstring> + </tp:member> + <tp:member type="u" tp:type="Handle" name="Handle"> + <tp:docstring>The handle that the channel communicates with, + or 0 if there is no associated handle</tp:docstring> + </tp:member> + </tp:struct> + <method name="Connect"> <tp:docstring> Request that the connection be established. This will be done @@ -41,7 +62,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:docstring> </method> <method name="GetInterfaces"> - <arg direction="out" type="as" tp:type="Interface[]"> + <arg direction="out" type="as" tp:type="DBus_Interface[]"> <tp:docstring> An array of D-Bus interface names </tp:docstring> @@ -92,7 +113,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <method name="HoldHandles"> <arg direction="in" name="handle_type" type="u" tp:type="Handle_Type"> <tp:docstring> - An integer handle type (as defined in HandleType) + The type of handle to be held </tp:docstring> </arg> <arg direction="in" name="handles" type="au" tp:type="Handle[]"> @@ -130,7 +151,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <method name="InspectHandles"> <arg direction="in" name="handle_type" type="u" tp:type="Handle_Type"> <tp:docstring> - An integer handle type (as defined in HandleType) + The type of handle to be inspected </tp:docstring> </arg> <arg direction="in" name="handles" type="au" tp:type="Handle[]"> @@ -158,15 +179,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:possible-errors> </method> <method name="ListChannels"> - <arg direction="out" type="a(osuu)"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>An array of structs containing:</p> - <ul> - <li>a D-Bus object path for the channel object on this service</li> - <li>a D-Bus interface name representing the channel type</li> - <li>an integer representing the handle type this channel communicates with, or zero</li> - <li>an integer handle representing the contact, room or list this channel communicates with, or zero</li> - </ul> + <arg direction="out" type="a(osuu)" tp:type="Channel_Info[]"> + <tp:docstring> + An array of structs representing channels. </tp:docstring> </arg> <tp:docstring> @@ -182,7 +197,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ A D-Bus object path for the channel object on this service </tp:docstring> </arg> - <arg name="channel_type" type="s" tp:type="Interface"> + <arg name="channel_type" type="s" tp:type="DBus_Interface"> <tp:docstring> A D-Bus interface name representing the channel type </tp:docstring> @@ -240,7 +255,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:possible-errors> </method> <method name="RequestChannel"> - <arg direction="in" name="type" type="s" tp:type="Interface"> + <arg direction="in" name="type" type="s" tp:type="DBus_Interface"> <tp:docstring> A D-Bus interface name representing base channel type </tp:docstring> @@ -352,7 +367,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <method name="RequestHandles"> <arg direction="in" name="handle_type" type="u" tp:type="Handle_Type"> <tp:docstring> - An integer handle type (as defined in HandleType) + The type of handle required </tp:docstring> </arg> <arg direction="in" name="names" type="as"> diff --git a/spec/Connection_Interface_Aliasing.xml b/spec/Connection_Interface_Aliasing.xml index 99dd10a..900a8b2 100644 --- a/spec/Connection_Interface_Aliasing.xml +++ b/spec/Connection_Interface_Aliasing.xml @@ -20,8 +20,24 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:license> <interface name="org.freedesktop.Telepathy.Connection.Interface.Aliasing"> <tp:requires interface="org.freedesktop.Telepathy.Connection"/> + + <tp:mapping name="Alias_Map" array-name=""> + <tp:docstring>A dictionary whose keys are contact handles and whose + values are aliases.</tp:docstring> + <tp:member type="u" tp:type="Contact_Handle" name="Handle"/> + <tp:member type="s" name="Alias"/> + </tp:mapping> + + <tp:struct name="Alias_Pair" array-name="Alias_Pair_List"> + <tp:docstring>A pair (contact handle, alias) as seen in the AliasesChanged + signal.</tp:docstring> + <tp:member type="u" tp:type="Contact_Handle" name="Handle"/> + <tp:member type="s" name="Alias"/> + </tp:struct> + <signal name="AliasesChanged"> - <arg name="aliases" type="a(us)"> + <arg name="aliases" type="a(us)" tp:type="Alias_Pair[]"> + <!-- FIXME: if we break API, this could be an Alias_Map, a{us} --> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> An array containing structs of: <ul> @@ -88,7 +104,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:possible-errors> </method> <method name="SetAliases"> - <arg direction="in" name="aliases" type="a{us}"> + <arg direction="in" name="aliases" type="a{us}" tp:type="Alias_Map"> <tp:docstring> A dictionary mapping integer handles of contacts to strings of the new alias to set. diff --git a/spec/Connection_Interface_Avatars.xml b/spec/Connection_Interface_Avatars.xml index fafa68b..33f6f68 100644 --- a/spec/Connection_Interface_Avatars.xml +++ b/spec/Connection_Interface_Avatars.xml @@ -20,6 +20,14 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:license> <interface name="org.freedesktop.Telepathy.Connection.Interface.Avatars"> <tp:requires interface="org.freedesktop.Telepathy.Connection"/> + + <tp:mapping name="Avatar_Token_Map" array-name=""> + <tp:docstring>A dictionary whose keys are contact handles and whose + values are avatar tokens.</tp:docstring> + <tp:member type="u" tp:type="Contact_Handle" name="Handle"/> + <tp:member type="s" name="Token"/> + </tp:mapping> + <signal name="AvatarUpdated"> <arg name="contact" type="u" tp:type="Contact_Handle"> <tp:docstring> @@ -137,7 +145,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}"> + <arg direction="out" type="a{us}" tp:type="Avatar_Token_Map"> <tp:docstring> A dictionary of handles mapped to avatar tokens, containing only the known avatar tokens. @@ -146,8 +154,11 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <tp:docstring> Get the unique tokens for the given contacts' avatars. These tokens can be persisted across connections, and should be used by the client - to check whether the avatars have been updated. A empty token means - that no avatar is set for the given contact. + to check whether the avatars have been updated. A CM must always have + the tokens for the self handle if one is set (even if it is set to no + avatar). Otherwise, only tokens that are already known or that can be + discovered without retrieving the complete avatar are returned. An + empty token means the given contact has no avatar. </tp:docstring> <tp:possible-errors> <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> @@ -258,9 +269,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ a changed token implies the contact's avatar has changed, but the strings should otherwise be considered opaque by clients.</p> - <p>A client should use GetAvatarTokens to request the tokens for the avatars - of all the contacts it is interested in when it connects. The avatars can - then be retreived using RequestAvatar for the corresponding contact. + <p>A client should use GetKnownAvatarTokens to request the tokens for the + avatars of all the contacts it is interested in when it connects. The + avatars can then be requested using RequestAvatars for the contacts. Clients should bind to the AvatarChanged signal and request a new copy of the avatar when a contacts' avatar token changes. Clients should cache the token and data of each contact's avatar between connections, to avoid diff --git a/spec/Connection_Interface_Capabilities.xml b/spec/Connection_Interface_Capabilities.xml index 36153b0..874f07c 100644 --- a/spec/Connection_Interface_Capabilities.xml +++ b/spec/Connection_Interface_Capabilities.xml @@ -20,8 +20,43 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:license> <interface name="org.freedesktop.Telepathy.Connection.Interface.Capabilities"> <tp:requires interface="org.freedesktop.Telepathy.Connection"/> + + <tp:struct name="Capability_Pair" array-name="Capability_Pair_List"> + <tp:docstring>A pair (channel type, type-specific flags) as passed to + AdvertiseCapabilities on the Capabilities interface.</tp:docstring> + <tp:member type="s" tp:type="DBus_Interface" name="Channel_Type"/> + <tp:member type="u" name="Type_Specific_Flags"/> + </tp:struct> + + <tp:struct name="Contact_Capability" array-name="Contact_Capability_List"> + <tp:docstring>A struct (contact handle, channel type, generic flags, + type-specific flags) representing a capability posessed by a contact, + as returned by GetCapabilities on the Capabilities + interface.</tp:docstring> + <tp:member type="u" tp:type="Contact_Handle" name="Handle"/> + <tp:member type="s" tp:type="DBus_Interface" name="Channel_Type"/> + <tp:member type="u" tp:type="Connection_Capability_Flags" + name="Generic_Flags"/> + <tp:member type="u" name="Type_Specific_Flags"/> + </tp:struct> + + <tp:struct name="Capability_Change" array-name="Capability_Change_List"> + <tp:docstring>A struct (contact handle, channel type, old generic flags, + new generic flags, old type-specific flags, new type-specific flags) + representing a change to one of a contact's capabilities, as seen in the + CapabilitiesChanged signal on the Capabilities interface.</tp:docstring> + <tp:member type="u" tp:type="Contact_Handle" name="Handle"/> + <tp:member type="s" tp:type="DBus_Interface" name="Channel_Type"/> + <tp:member type="u" tp:type="Connection_Capability_Flags" + name="Old_Generic_Flags"/> + <tp:member type="u" tp:type="Connection_Capability_Flags" + name="New_Generic_Flags"/> + <tp:member type="u" name="Old_Type_Specific_Flags"/> + <tp:member type="u" name="New_Type_Specific_Flags"/> + </tp:struct> + <method name="AdvertiseCapabilities"> - <arg direction="in" name="add" type="a(su)"> + <arg direction="in" name="add" type="a(su)" tp:type="Capability_Pair[]"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> An array of structures containing: <ul> @@ -30,12 +65,12 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </ul> </tp:docstring> </arg> - <arg direction="in" name="remove" type="as" tp:type="Interface[]"> + <arg direction="in" name="remove" type="as" tp:type="DBus_Interface[]"> <tp:docstring> An array of D-Bus interface names of channel types to remove </tp:docstring> </arg> - <arg direction="out" type="a(su)"> + <arg direction="out" type="a(su)" tp:type="Capability_Pair[]"> <tp:docstring> An array of structures describing the current capabilities containing: <ul> @@ -69,7 +104,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:possible-errors> </method> <signal name="CapabilitiesChanged"> - <arg name="caps" type="a(usuuuu)"> + <arg name="caps" type="a(usuuuu)" tp:type="Capability_Change[]"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> An array of structures containing: <ul> @@ -93,7 +128,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ An array of contact handles for this connection, or zero to query capabilities available on the connection itself </tp:docstring> </arg> - <arg direction="out" type="a(usuu)"> + <arg direction="out" type="a(usuu)" tp:type="Contact_Capability[]"> <tp:docstring> An array of structures containing: <ul> diff --git a/spec/Connection_Interface_Contact_Info.xml b/spec/Connection_Interface_Contact_Info.xml index 3582da3..22cd507 100644 --- a/spec/Connection_Interface_Contact_Info.xml +++ b/spec/Connection_Interface_Contact_Info.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.ContactInfo"> + <interface name="org.freedesktop.Telepathy.Connection.Interface.ContactInfo" + tp:causes-havoc='obsolete'> <tp:requires interface="org.freedesktop.Telepathy.Connection"/> <signal name="GotContactInfo"> <arg name="contact" type="u" tp:type="Contact_Handle"> diff --git a/spec/Connection_Interface_Forwarding.xml b/spec/Connection_Interface_Forwarding.xml index 119c9be..6322fbc 100644 --- a/spec/Connection_Interface_Forwarding.xml +++ b/spec/Connection_Interface_Forwarding.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.Forwarding"> + <interface name="org.freedesktop.Telepathy.Connection.Interface.Forwarding" + tp:causes-havoc='not well-tested'> <tp:requires interface="org.freedesktop.Telepathy.Connection"/> <signal name="ForwardingChanged"> <arg name="forward_to" type="u" tp:type="Contact_Handle"> diff --git a/spec/Connection_Interface_Presence.xml b/spec/Connection_Interface_Presence.xml index e43c727..37653ee 100644 --- a/spec/Connection_Interface_Presence.xml +++ b/spec/Connection_Interface_Presence.xml @@ -26,13 +26,50 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:license> <interface name="org.freedesktop.Telepathy.Connection.Interface.Presence"> <tp:requires interface="org.freedesktop.Telepathy.Connection"/> + + <!-- We hope to simplify these eventually --> + <tp:mapping name="Multiple_Status_Map"> + <tp:docstring>Mapping used in Last_Activity_And_Statuses and passed to + SetStatus, representing a collection of statuses. Use of this mapping + with more than one member is deprecated.</tp:docstring> + <tp:member type="s" name="Status"/> + <tp:member type="a{sv}" tp:type="String_Variant_Map" name="Parameters"/> + </tp:mapping> + <tp:struct name="Last_Activity_And_Statuses" array-name=""> + <tp:docstring>Structure representing a contact's presence, containing + a last-activity time (deprecated) and a Multiple_Status_Map. + </tp:docstring> + <tp:member type="u" tp:type="Unix_Timestamp" name="Last_Activity"/> + <tp:member type="a{sa{sv}}" tp:type="Multiple_Status_Map" + name="Statuses"/> + </tp:struct> + <tp:mapping name="Contact_Presences"> + <tp:docstring>Mapping returned by GetPresence and signalled by + PresenceUpdate, where the keys are contacts and the values represent + their presences.</tp:docstring> + <tp:member type="u" tp:type="Contact_Handle" name="Contact"/> + <tp:member type="(ua{sa{sv}})" tp:type="Last_Activity_And_Statuses" + name="Presence"/> + </tp:mapping> + <tp:struct name="Status_Spec" array-name=""> + <tp:member type="u" tp:type="Connection_Presence_Type" name="Type"/> + <tp:member type="b" name="May_Set_On_Self"/> + <tp:member type="b" name="Exclusive"/> + <tp:member type="a{ss}" tp:type="String_String_Map" + name="Parameter_Types"/> + </tp:struct> + <tp:mapping name="Status_Spec_Map"> + <tp:member type="s" name="Identifier"/> + <tp:member type="(ubba{ss})" tp:type="Status_Spec" name="Spec"/> + </tp:mapping> + <method name="AddStatus"> <arg direction="in" name="status" type="s"> <tp:docstring> The string identifier of the desired status </tp:docstring> </arg> - <arg direction="in" name="parms" type="a{sv}"> + <arg direction="in" name="parms" type="a{sv}" tp:type="String_Variant_Map"> <tp:docstring> A dictionary of optional parameter names mapped to their variant-boxed values </tp:docstring> @@ -69,7 +106,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ An array of the contacts whose presence should be obtained </tp:docstring> </arg> - <arg direction="out" name="presence" type="a{u(ua{sa{sv}})}"> + <arg direction="out" name="presence" type="a{u(ua{sa{sv}})}" + tp:type="Contact_Presences"> <tp:docstring> Presence information in the same format as for the PresenceUpdate signal @@ -89,7 +127,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:possible-errors> </method> <method name="GetStatuses"> - <arg direction="out" type="a{s(ubba{ss})}"> + <arg direction="out" type="a{s(ubba{ss})}" tp:type="Status_Spec_Map"> <tp:docstring> A dictionary of string identifiers mapped to a struct for each status, containing: <ul> @@ -111,7 +149,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:possible-errors> </method> <signal name="PresenceUpdate"> - <arg name="presence" type="a{u(ua{sa{sv}})}"> + <arg name="presence" type="a{u(ua{sa{sv}})}" tp:type="Contact_Presences"> <tp:docstring> A dictionary of contact handles mapped to a struct containing a UNIX timestamp of the last activity time (in UTC), and @@ -174,7 +212,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:possible-errors> </method> <method name="SetLastActivityTime"> - <arg direction="in" name="time" type="u" tp:type="Timestamp"> + <arg direction="in" name="time" type="u" tp:type="Unix_Timestamp"> <tp:docstring> A UNIX timestamp of the user's last activity time (in UTC) </tp:docstring> @@ -194,7 +232,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:possible-errors> </method> <method name="SetStatus"> - <arg direction="in" name="statuses" type="a{sa{sv}}"> + <arg direction="in" name="statuses" type="a{sa{sv}}" tp:type="Multiple_Status_Map"> <tp:docstring> A dictionary mapping status identifiers to dictionaries, which map optional parameter names to their variant-boxed values @@ -307,6 +345,11 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ Hidden (invisible) </tp:docstring> </tp:enumvalue> + <tp:enumvalue suffix="Busy" value="6"> + <tp:docstring> + Busy, Do Not Disturb. + </tp:docstring> + </tp:enumvalue> </tp:enum> </interface> </node> diff --git a/spec/Connection_Interface_Privacy.xml b/spec/Connection_Interface_Privacy.xml index 5cb81a0..4ada369 100644 --- a/spec/Connection_Interface_Privacy.xml +++ b/spec/Connection_Interface_Privacy.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.Privacy"> + <interface name="org.freedesktop.Telepathy.Connection.Interface.Privacy" + tp:causes-havoc='not well-tested'> <tp:requires interface="org.freedesktop.Telepathy.Connection"/> <method name="GetPrivacyMode"> <arg direction="out" type="s"> diff --git a/spec/Connection_Interface_Renaming.xml b/spec/Connection_Interface_Renaming.xml index f1c5497..2c4e272 100644 --- a/spec/Connection_Interface_Renaming.xml +++ b/spec/Connection_Interface_Renaming.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.Renaming"> + <interface name="org.freedesktop.Telepathy.Connection.Interface.Renaming" + tp:causes-havoc='not well-tested'> <tp:requires interface="org.freedesktop.Telepathy.Connection"/> <signal name="Renamed"> <arg name="original" type="u" tp:type="Contact_Handle"> diff --git a/spec/Connection_Manager.xml b/spec/Connection_Manager.xml index 5d5e6cb..5d3aef3 100644 --- a/spec/Connection_Manager.xml +++ b/spec/Connection_Manager.xml @@ -19,6 +19,56 @@ 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.ConnectionManager"> + + <tp:simple-type name="Protocol" type="s"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An instant messaging protocol. It must consist only of ASCII + letters, digits and hyphen/minus signs (U+002D "-"), and must start + with a letter. Where possible, this SHOULD be + chosen from the following well-known values:</p> + + <ul> + <li>aim - AOL Instant Messenger (OSCAR or TOC)</li> + <li>gadugadu - Gadu-Gadu</li> + <li>groupwise - Novell Groupwise</li> + <li>icq - ICQ (OSCAR)</li> + <li>irc - Internet Relay Chat (RFC 1459, 2810-2813)</li> + <li>jabber - XMPP (RFC 3920, 3921) or Jabber</li> + <li>local-xmpp - Link-local XMPP (XEP-0174) (Bonjour, Salut)</li> + <li>msn - MSNP (Windows Live Messenger)</li> + <li>myspace - MySpaceIM</li> + <li>napster - Napster</li> + <li>qq - Tencent QQ</li> + <li>sametime - IBM Lotus Sametime</li> + <li>silc - SILC</li> + <li>sip - Session Initiation Protocol (SIP)</li> + <li>trepia - Trepia</li> + <li>yahoo - YMSG (Yahoo! Messenger)</li> + <li>zephyr - Zephyr</li> + </ul> + </tp:docstring> + </tp:simple-type> + + <tp:struct name="Param_Spec" array-name="Param_Spec_List"> + <tp:docstring>A struct representing an allowed parameter, as returned + by GetParameters on the ConnectionManager interface.</tp:docstring> + <tp:member type="s" name="Name"> + <tp:docstring>A string parameter name</tp:docstring> + </tp:member> + <tp:member type="u" tp:type="Conn_Mgr_Param_Flags" name="Flags"> + <tp:docstring>A bitwise OR of the parameter flags</tp:docstring> + </tp:member> + <tp:member type="s" tp:type="DBus_Signature" name="Signature"> + <tp:docstring>A string containing the D-Bus type signature + for this parameter</tp:docstring> + </tp:member> + <tp:member type="v" name="Default_Value"> + <tp:docstring>The default value (if the Has_Default flag is not + present, there is no default and this takes some dummy value, + which SHOULD be of the appropriate D-Bus type)</tp:docstring> + </tp:member> + </tp:struct> + <tp:flags name="Conn_Mgr_Param_Flags" value-prefix="Conn_Mgr_Param_Flag" type="u"> <tp:flag suffix="Required" value="1"> <tp:docstring> @@ -40,21 +90,14 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:flag> </tp:flags> <method name="GetParameters"> - <arg direction="in" name="proto" type="s"> + <arg direction="in" name="proto" type="s" tp:type="Protocol"> <tp:docstring> The required protocol name </tp:docstring> </arg> - <arg direction="out" type="a(susv)"> + <arg direction="out" type="a(susv)" tp:type="Param_Spec[]"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - An array of structs containing: - <ul> - <li>a string parameter name</li> - <li>a bitwise OR of the parameter flags (as defined above)</li> - <li>a string D-Bus type signature</li> - <li>a variant boxed default value (if the HAS_DEFAULT flag is not - present, there is no default and this takes some dummy value)</li> - </ul> + An array of structs representing possible parameters. </tp:docstring> </arg> <tp:docstring> @@ -70,7 +113,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:possible-errors> </method> <method name="ListProtocols"> - <arg direction="out" type="as"> + <arg direction="out" type="as" tp:type="Protocol[]"> <tp:docstring> A array of string protocol identifiers supported by this manager </tp:docstring> @@ -79,26 +122,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ Get a list of protocol identifiers that are implemented by this connection manager. The following well-known values should be used when applicable: - <ul> - <li>aim - AOL Instant Messenger</li> - <li>gadugadu - Gadu-Gadu</li> - <li>groupwise - Novell Groupwise</li> - <li>icq - ICQ</li> - <li>irc - Internet Relay Chat</li> - <li>jabber - Jabber (XMPP)</li> - <li>local-xmpp - Link-local XMPP (XEP-0174, Bonjour, Salut)</li> - <li>msn - MSN Messenger</li> - <li>napster - Napster</li> - <li>silc - SILC</li> - <li>sip - Session Initiation Protocol (SIP)</li> - <li>trepia - Trepia</li> - <li>yahoo - Yahoo! Messenger</li> - <li>zephyr - Zephyr</li> - </ul> </tp:docstring> </method> <signal name="NewConnection"> - <arg name="bus_name" type="s"> + <arg name="bus_name" type="s" tp:type="DBus_Bus_Name"> <tp:docstring> The D-Bus service where the connection object can be found </tp:docstring> @@ -108,7 +135,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ The object path of the Connection object on this service </tp:docstring> </arg> - <arg name="proto" type="s"> + <arg name="proto" type="s" tp:type="Protocol"> <tp:docstring> The identifier for the protocol this connection uses </tp:docstring> @@ -118,12 +145,13 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:docstring> </signal> <method name="RequestConnection"> - <arg direction="in" name="proto" type="s"> + <arg direction="in" name="proto" type="s" tp:type="Protocol"> <tp:docstring> The protocol identifier </tp:docstring> </arg> - <arg direction="in" name="parameters" type="a{sv}"> + <arg direction="in" name="parameters" type="a{sv}" + tp:type="String_Variant_Map"> <tp:docstring> A dictionary mapping parameter name to the variant boxed value </tp:docstring> @@ -142,22 +170,36 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <p>Request a Connection object representing a given account on a given protocol with the given parameters. The method returns the bus name and the object path where the new Connection object can be found, which - should have the status of CONNECTION_STATUS_DISCONNECTED, to allow + should have the status of Connection_Status_Disconnected, to allow signal handlers to be attached before connecting is started with the Connect method.</p> <p>In order to allow Connection objects to be discovered by new clients, - the object path and bus name must be of the form:</p> - <pre>/org/freedesktop/Telepathy/Connection/manager/proto/account</pre> - <p>And:</p> - <pre>org.freedesktop.Telepathy.Connection.manager.proto.account</pre> - <p>Where manager and proto are the identifiers for this manager and this - protocol, and account is a series of elements formed such that any - valid distinct connection instance on this protocol has a distinct - name. This might be formed by including the server name followed by the - user name, or on protocols where connecting multiple times is - permissable, a per-connection identifier is also necessary to ensure - uniqueness.</p> + the object path and well-known bus name must be of the form + <code>/org/freedesktop/Telepathy/Connection/cmname/proto/account</code> + and + <code>org.freedesktop.Telepathy.Connection.cmname.proto.account</code> + where:</p> + + <ul> + <li><em>cmname</em> is the same connection manager name that appears + in the connection manager's object path and well-known bus name</li> + <li><em>proto</em> is the protocol name as seen in + ListProtocols, but with "-" replaced with "_" to get a valid + object path/bus name</li> + <li><em>account</em> SHOULD be a series of elements formed such that + any valid distinct connection instance on this protocol has a + distinct name; this might be formed by including the server name + followed by the user name (escaped via some suitable mechanism like + telepathy-glib's tp_escape_as_identifier() function to preserve + uniqueness), or on protocols where connecting multiple times + is permissable, a per-connection identifier might be necessary to + ensure uniqueness</li> + </ul> + + <p>Clients MUST NOT attempt to parse the <em>account</em> part of the + bus name. Connection managers MAY use any unique string for this + part.</p> <p>The parameters which must and may be provided in the parameters dictionary can be discovered with the GetParameters method. These @@ -226,16 +268,90 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </method> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>A D-Bus service which allows connections to be created. The manager - processes are intended to be started by D-Bus service activation. The - names of these services, the protocols they support, and the parameters - understood by that protocol are intended to be discovered by reading files - on disk which are provided along with the connection manager. These are - documented elsewhere.</p> - - <p>Once a connection manager service has been activated, the object - path of the manager object implementing this interface is always - /org/freedesktop/Telepathy/ConnectionManager/name - Where name is the identifier for the connection manager.</p> + processes are intended to be started by D-Bus service activation.</p> + + <p>For service discovery, each Telepathy connection manager must have + a <em>connection manager name</em>, which is a non-empty string of + ASCII letters, digits and underscores, starting with a letter. This + is typically the name of the executable with any "telepathy-" prefix + removed.</p> + + <p>The connection manager must then provide a well-known bus name of + <code>org.freedesktop.Telepathy.ConnectionManager.<em>cmname</em></code> + where <em>cmname</em> is its connection manager name. If it makes sense + to start the connection manager using D-Bus service activation, it + must register that well-known name for service activation by installing + a .service file.</p> + + <p>Clients can list the running connection managers by calling the + ListNames method on the D-Bus daemon's org.freedesktop.DBus interface + and looking for names matching the above pattern; they can list the + activatable connection managers by calling ListActivatableNames, and + they should usually combine the two lists to get a complete list of + running or activatable connection managers.</p> + + <p>When the connection manager is running, it must have an object + implementing the ConnectionManager interface at the object path + <code>/org/freedesktop/Telepathy/ConnectionManager/<em>cmname</em></code>. + </p> + + <p>Connection managers' capabilities can be determined dynamically by + calling their ListProtocols method, then for each protocol of interest, + calling GetParameters to discover the required and optional parameters. + However, since it is inefficient to activate all possible connection + managers on the system just to find out what they can do, there + is a standard mechanism to store static information about CMs in + ".manager files".</p> + + <p>To look up a connection manager's supported protocols, clients + should search the data directories specified by + <a href="http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html">the + freedesktop.org XDG Base Directory Specification</a> ($XDG_DATA_HOME, + defaulting to $HOME/.local/share if unset, followed by + colon-separated paths from $XDG_DATA_DIRS, defaulting to + /usr/local/share:/usr/share if unset) for the first file named + <code>telepathy/managers/<em>cmname</em>.manager</code> that can be + read without error. This file has the same syntax as a + <a href="http://standards.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html">freedesktop.org Desktop Entry file</a>.</p> + + <p>For each protocol name <em>proto</em> that would be returned by + ListProtocols, the .manager file contains a group + headed <code>[Protocol <em>proto</em>]</code>. For each parameter + <em>p</em> that would be returned by GetParameters(<em>proto</em>), the + .manager file contains a key <code>param-<em>p</em></code> with a value + consisting of a D-Bus signature (a single complete type), optionally + followed by a space and a space-separated list of flags. The supported + flags are <code>required</code>, corresponding to + Conn_Mgr_Param_Flag_Required, and <code>register</code>, corresponding + to Conn_Mgr_Param_Flag_Register. + </p> + + <p>The group may also contain a key <code>default-<em>p</em></code> + whose value is a string form of the default value for the parameter. + If this key exists, it sets the default, and also sets the flag + Conn_Mgr_Param_Flag_Has_Default. The default value is formatted + according to the D-Bus signature as follows:</p> + + <dl> + <dt>s (string)</dt> + <dd>The UTF-8 string</dd> + <dt>o (object path)</dt> + <dd>The object path as an ASCII string</dd> + <dt>b (boolean)</dt> + <dd>"true" (case-insensitively) or "1" means True, "false" + (case-insensitively) or "0" means False</dd> + <dt>q, u, t (16-, 32-, 64-bit unsigned integer)</dt> + <dd>ASCII decimal integer</dd> + <dt>n, i, x (16-, 32-, 64-bit signed integer)</dt> + <dd>ASCII decimal integer, optionally prefixed with "-"</dd> + <dt>d (double-precision floating point)</dt> + <dd>ASCII decimal number</dd> + </dl> + + <p>Currently, no other D-Bus signatures are allowed to have default values, + but clients parsing the .manager file MUST ignore defaults + that they cannot parse, and treat them as if the + <code>default-<em>p</em></code> key was not present at all.</p> <p>It is not required that a connection manager be able to support multiple protocols, or even multiple connections. When a connection is made, a diff --git a/spec/Media_Session_Handler.xml b/spec/Media_Session_Handler.xml index 5401f57..b4e9ffb 100644 --- a/spec/Media_Session_Handler.xml +++ b/spec/Media_Session_Handler.xml @@ -62,7 +62,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <method name="Ready"> <tp:docstring> Inform the connection manager that a client is ready to handle - this session handler. + this session handler (i.e. that it has connected to the + NewStreamHandler signal and done any other necessary setup). </tp:docstring> </method> <tp:docstring> diff --git a/spec/Media_Stream_Handler.xml b/spec/Media_Stream_Handler.xml index df5a067..92be1f2 100644 --- a/spec/Media_Stream_Handler.xml +++ b/spec/Media_Stream_Handler.xml @@ -19,13 +19,47 @@ 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.Media.StreamHandler"> + + <tp:struct name="Media_Stream_Handler_Candidate" + array-name="Media_Stream_Handler_Candidate_List"> + <tp:member type="s" name="Name"/> + <tp:member type="a(usuussduss)" name="Transports" + tp:type="Media_Stream_Handler_Transport[]"/> + </tp:struct> + + <tp:struct name="Media_Stream_Handler_Transport" + array-name="Media_Stream_Handler_Transport_List"> + <tp:member type="u" name="Component_Number"/> + <tp:member type="s" name="IP_Address"/> + <tp:member type="u" name="Port"/> + <tp:member type="u" tp:type="Media_Stream_Base_Proto" name="Protocol"/> + <tp:member type="s" name="Subtype"/> + <tp:member type="s" name="Profile"/> + <tp:member type="d" name="Preference_Value"/> + <tp:member type="u" tp:type="Media_Stream_Transport_Type" + name="Transport_Type"/> + <tp:member type="s" name="Username"/> + <tp:member type="s" name="Password"/> + </tp:struct> + + <tp:struct name="Media_Stream_Handler_Codec" + array-name="Media_Stream_Handler_Codec_List"> + <tp:member type="u" name="Codec_ID"/> + <tp:member type="s" name="Name"/> + <tp:member type="u" tp:type="Media_Stream_Type" name="Media_Type"/> + <tp:member type="u" name="Clock_Rate"/> + <tp:member type="u" name="Number_Of_Channels"/> + <tp:member type="a{ss}" name="Parameters" tp:type="String_String_Map"/> + </tp:struct> + <signal name="AddRemoteCandidate"> <arg name="candidate_id" type="s"> <tp:docstring> String identifier for this candidate </tp:docstring> </arg> - <arg name="transports" type="a(usuussduss)"> + <arg name="transports" type="a(usuussduss)" + tp:type="Media_Stream_Handler_Transport[]"> <tp:docstring> Array of transports for this candidate with fields, as defined in NewNativeCandidate @@ -105,7 +139,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ String identifier for this candidate </tp:docstring> </arg> - <arg direction="in" name="transports" type="a(usuussduss)"> + <arg direction="in" name="transports" type="a(usuussduss)" + tp:type="Media_Stream_Handler_Transport[]"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> Array of transports for this candidate, with fields: <ul> @@ -191,7 +226,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:docstring> </signal> <signal name="SetRemoteCandidateList"> - <arg name="remote_candidates" type="a(sa(usuussduss))"> + <arg name="remote_candidates" type="a(sa(usuussduss))" + tp:type="Media_Stream_Handler_Candidate[]"> <tp:docstring> A list of candidate id and a list of transports as defined in NewNativeCandidate @@ -203,7 +239,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:docstring> </signal> <signal name="SetRemoteCodecs"> - <arg name="codecs" type="a(usuuua{ss})"> + <arg name="codecs" type="a(usuuua{ss})" + tp:type="Media_Stream_Handler_Codec[]"> <tp:docstring>As for SupportedCodecs</tp:docstring> </arg> <tp:docstring> @@ -250,7 +287,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:docstring> </method> <method name="SupportedCodecs"> - <arg direction="in" name="codecs" type="a(usuuua{ss})"> + <arg direction="in" name="codecs" type="a(usuuua{ss})" + tp:type="Media_Stream_Handler_Codec[]"> <tp:docstring> List of codec info structures, each containing: <ul> diff --git a/spec/Properties_Interface.xml b/spec/Properties_Interface.xml index ffe49c4..a028913 100644 --- a/spec/Properties_Interface.xml +++ b/spec/Properties_Interface.xml @@ -19,6 +19,35 @@ 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.Properties"> + + <tp:struct name="Property_Spec" array-name="Property_Spec_List"> + <tp:docstring>A struct (property ID, property name, D-Bus signature, + flags) representing a property, as returned by ListProperties on the + Properties interface.</tp:docstring> + <tp:member type="u" name="Property_ID"/> + <tp:member type="s" name="name"/> + <tp:member type="s" tp:type="DBus_Signature" name="signature"/> + <tp:member type="u" tp:type="Property_Flags" name="Flags"/> + </tp:struct> + + <tp:struct name="Property_Flags_Change" + array-name="Property_Flags_Change_List"> + <tp:docstring>A struct (property ID, flags) representing a change to + a property's flags, as seen in the PropertyFlagsChanged signal on + the Properties interface.</tp:docstring> + <tp:member type="u" name="Property_ID"/> + <tp:member type="u" name="New_Flags"/> + </tp:struct> + + <tp:struct name="Property_Value" array-name="Property_Value_List"> + <tp:docstring>A struct (property ID, value) representing a + property's value, as seen in the PropertiesChanged signal on + the Properties interface, returned by the GetProperties method + and passed to the SetProperties method.</tp:docstring> + <tp:member type="u" name="Property_ID"/> + <tp:member type="v" name="Value"/> + </tp:struct> + <method name="GetProperties"> <tp:docstring> Returns an array of (identifier, value) pairs containing the current @@ -27,7 +56,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <arg direction="in" name="properties" type="au"> <tp:docstring>An array of property identifiers</tp:docstring> </arg> - <arg direction="out" type="a(uv)"> + <arg direction="out" type="a(uv)" tp:type="Property_Value[]"> <!-- 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> @@ -55,7 +84,7 @@ 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)"> + <arg direction="out" type="a(ussu)" tp:type="Property_Spec[]"> <!-- XXX: if we're ever breaking API compatibility, make this a{u(ssu)} ? --> <tp:docstring> @@ -73,7 +102,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <tp:docstring> Emitted when the value of readable properties has changed. </tp:docstring> - <arg name="properties" type="a(uv)"> + <arg name="properties" type="a(uv)" tp:type="Property_Value[]"> <!-- 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 +119,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <tp:docstring> Emitted when the flags of some room properties have changed. </tp:docstring> - <arg name="properties" type="a(uu)"> + <arg name="properties" type="a(uu)" tp:type="Property_Flags_Change[]"> <!-- XXX: if we're ever breaking API compatibility, make this a{uu} --> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>An array of structs containing:</p> @@ -116,7 +145,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ are invalid, InvalidArgument will be returned.</p> </tp:docstring> - <arg direction="in" name="properties" type="a(uv)"> + <arg direction="in" name="properties" type="a(uv)" + tp:type="Property_Value[]"> <!-- XXX: if we're ever breaking API compatibility, make this a{uv} --> <tp:docstring> A dictionary mapping integer identifiers to boxed values diff --git a/spec/all.xml b/spec/all.xml index 67ebcac..1fb517c 100644 --- a/spec/all.xml +++ b/spec/all.xml @@ -3,10 +3,10 @@ xmlns:xi="http://www.w3.org/2001/XInclude"> <tp:title>Telepathy D-Bus Interface Specification</tp:title> -<tp:version>0.16.0</tp:version> +<tp:version>0.17.1</tp:version> -<tp:copyright>Copyright (C) 2005, 2006, 2007 Collabora Limited</tp:copyright> -<tp:copyright>Copyright (C) 2005, 2006, 2007 Nokia Corporation</tp:copyright> +<tp:copyright>Copyright (C) 2005-2008 Collabora Limited</tp:copyright> +<tp:copyright>Copyright (C) 2005-2008 Nokia Corporation</tp:copyright> <tp:copyright>Copyright (C) 2006 INdT</tp:copyright> <tp:license xmlns="http://www.w3.org/1999/xhtml"> @@ -44,6 +44,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <xi:include href="Channel_Type_Text.xml"/> <xi:include href="Channel_Type_Tubes.xml"/> +<xi:include href="Channel_Interface_Call_Merging.xml"/> <xi:include href="Channel_Interface_Chat_State.xml"/> <xi:include href="Channel_Interface_DTMF.xml"/> <xi:include href="Channel_Interface_Group.xml"/> @@ -57,7 +58,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <xi:include href="Properties_Interface.xml"/> +<xi:include href="Channel_Handler.xml"/> + <xi:include href="errors.xml"/> +<xi:include href="generic-types.xml"/> <xi:include href="extensions.xml"> <xi:fallback> diff --git a/spec/generic-types.xml b/spec/generic-types.xml new file mode 100644 index 0000000..f134d7c --- /dev/null +++ b/spec/generic-types.xml @@ -0,0 +1,67 @@ +<tp:generic-types + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + + <tp:simple-type name="Unix_Timestamp" type="u"> + <tp:docstring>An unsigned 32-bit integer representing time since 1970</tp:docstring> + </tp:simple-type> + + <tp:simple-type name="Handle" type="u"> + <tp:docstring>An unsigned 32-bit integer representing a handle</tp:docstring> + </tp:simple-type> + + <tp:simple-type name="Contact_Handle" type="u"> + <tp:docstring>An unsigned 32-bit integer representing a handle of type + Handle_Type_Contact</tp:docstring> + </tp:simple-type> + + <tp:simple-type name="Room_Handle" type="u"> + <tp:docstring>An unsigned 32-bit integer representing a handle of type + Handle_Type_Room</tp:docstring> + </tp:simple-type> + + <tp:simple-type name="List_Handle" type="u"> + <tp:docstring>An unsigned 32-bit integer representing a handle of type + Handle_Type_List</tp:docstring> + </tp:simple-type> + + <tp:simple-type name="Group_Handle" type="u"> + <tp:docstring>An unsigned 32-bit integer representing a handle of type + Handle_Type_Group</tp:docstring> + </tp:simple-type> + + <tp:simple-type name="DBus_Bus_Name" type="s"> + <tp:docstring>A string representing a D-Bus bus name - either a well-known + name like "org.freedesktop.Telepathy.MissionControl" or a unique name + like ":1.123"</tp:docstring> + </tp:simple-type> + + <tp:simple-type name="DBus_Unique_Name" type="s"> + <tp:docstring>A string representing a D-Bus unique name, such as + ":1.123"</tp:docstring> + </tp:simple-type> + + <tp:simple-type name="DBus_Interface" type="s"> + <tp:docstring>A string representing a D-Bus interface</tp:docstring> + </tp:simple-type> + + <tp:simple-type name="DBus_Signature" type="s"> + <tp:docstring>A string representing a D-Bus signature + (the 'g' type isn't used because of poor interoperability, particularly + with dbus-glib)</tp:docstring> + </tp:simple-type> + + <tp:mapping name="String_Variant_Map"> + <tp:docstring>A mapping from strings to variants representing extra + key-value pairs.</tp:docstring> + <tp:member type="s" name="Key"/> + <tp:member type="v" name="Value"/> + </tp:mapping> + + <tp:mapping name="String_String_Map"> + <tp:docstring>A mapping from strings to strings representing extra + key-value pairs.</tp:docstring> + <tp:member type="s" name="Key"/> + <tp:member type="s" name="Value"/> + </tp:mapping> + +</tp:generic-types> |