diff options
author | Simon McVittie <simon.mcvittie@collabora.co.uk> | 2009-01-20 11:42:15 +0000 |
---|---|---|
committer | Simon McVittie <simon.mcvittie@collabora.co.uk> | 2009-01-20 11:42:15 +0000 |
commit | 95a87f182343dea698d281cc6e8b07e734e1f9cb (patch) | |
tree | 581c8ef5956d1d5fd86241fa6a2c7ea4d4e40419 /spec | |
parent | a101efff3a1c46981fd3bb2340d9bff6ec464460 (diff) | |
download | telepathy-glib-95a87f182343dea698d281cc6e8b07e734e1f9cb.tar.gz |
Update telepathy-spec to 0.17.18
Diffstat (limited to 'spec')
33 files changed, 1054 insertions, 206 deletions
diff --git a/spec/Account.xml b/spec/Account.xml index cb8032149..991dcbda0 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 5a40f2f5b..7b4a7ad8a 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 2c07305ed..c77873db9 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 ffa01154b..019e8481d 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. diff --git a/spec/Channel_Interface_Media_Signalling.xml b/spec/Channel_Interface_Media_Signalling.xml index acbe74743..05b618b62 100644 --- a/spec/Channel_Interface_Media_Signalling.xml +++ b/spec/Channel_Interface_Media_Signalling.xml @@ -41,7 +41,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). diff --git a/spec/Channel_Interface_Messages.xml b/spec/Channel_Interface_Messages.xml index 107850429..8cdee3c87 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 bfc617abe..720849a86 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 8e1ffab3a..ff249eb16 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 @@ -72,7 +72,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. tp:name-for-bindings="Status"> <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>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 956eee1cf..bf1bd38c2 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 7c324d0f6..0b166bb16 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 a3b98d7e4..34130c255 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 + list. 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 a2432f4be..f5268c851 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.UNRELEASED">(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 d2403bb6a..10ccac606 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 4a43a0074..b64f4a032 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 f4615ab6f..599fe1638 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: diff --git a/spec/Channel_Type_Text.xml b/spec/Channel_Type_Text.xml index f32382d24..5c28dce8f 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 bb55c4893..f6829b5da 100644 --- a/spec/Channel_Type_Tubes.xml +++ b/spec/Channel_Type_Tubes.xml @@ -252,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) @@ -280,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. @@ -289,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: @@ -330,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> @@ -403,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> @@ -600,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> @@ -632,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. diff --git a/spec/Connection.xml b/spec/Connection.xml index 951619683..bc46ecfee 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> @@ -562,7 +566,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 +587,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> diff --git a/spec/Connection_Interface_Aliasing.xml b/spec/Connection_Interface_Aliasing.xml index 652ed01aa..a599436a3 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 27c77b91d..7ef26afd8 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 7d0c14a9f..4e58d02bb 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 13efba666..042b24be4 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 4f8fd42d5..c29f9fe61 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.UNRELEASED">(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 e04ea5f2d..1033e0453 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 000000000..dbd8d830d --- /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.UNRELEASED">(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 cfcb856ca..6d9b24a18 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 f83853419..203421ba6 100644 --- a/spec/Connection_Interface_Requests.xml +++ b/spec/Connection_Interface_Requests.xml @@ -199,6 +199,18 @@ 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.NotAvailable"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The requested channel cannot be created, but in @@ -322,6 +334,18 @@ 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.NotAvailable"> <tp:docstring> The requested channel cannot be created, but in diff --git a/spec/Connection_Manager.xml b/spec/Connection_Manager.xml index eafa6df6e..46b56ac7a 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/Makefile.am b/spec/Makefile.am index fbae130ec..984a52f4a 100644 --- a/spec/Makefile.am +++ b/spec/Makefile.am @@ -39,15 +39,16 @@ EXTRA_DIST = \ Connection_Interface_Aliasing.xml \ Connection_Interface_Avatars.xml \ Connection_Interface_Capabilities.xml \ + Connection_Interface_Contact_Capabilities.xml \ Connection_Interface_Contact_Info.xml \ Connection_Interface_Contacts.xml \ - Connection_Interface_Contact_Capabilities.xml \ Connection_Interface_Forwarding.xml \ - Connection_Interface_Simple_Presence.xml \ + Connection_Interface_Location.xml \ Connection_Interface_Presence.xml \ Connection_Interface_Privacy.xml \ Connection_Interface_Renaming.xml \ Connection_Interface_Requests.xml \ + Connection_Interface_Simple_Presence.xml \ Connection_Manager.xml \ Connection.xml \ errors.xml \ diff --git a/spec/Media_Stream_Handler.xml b/spec/Media_Stream_Handler.xml index 35866a65e..cb7c79326 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 2773d753f..91423c108 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 a1fd74530..cee9b9220 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.18</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"/> @@ -87,8 +89,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/generic-types.xml b/spec/generic-types.xml index 227fde148..fba6a9f44 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 |