diff options
author | Will Thompson <will.thompson@collabora.co.uk> | 2011-11-24 15:15:58 +0000 |
---|---|---|
committer | Will Thompson <will.thompson@collabora.co.uk> | 2011-11-24 15:25:12 +0000 |
commit | f467b8cd4dffca20516be46d6da58f0bb4868df3 (patch) | |
tree | b501e4c1e29b8dc20af34709a0e53cecf4f9cad0 /extensions | |
parent | 6a0ed9a2f9c49d21060dd0053c8b71864ee59e10 (diff) | |
parent | 7fa869b1f319ab42c75d61fdd3b22859f3bb1dfb (diff) |
Merge remote-tracking branch 'andrunko/conn-addressing'
Fixes: <https://bugs.freedesktop.org/show_bug.cgi?id=30296>
Diffstat (limited to 'extensions')
-rw-r--r-- | extensions/Connection_Interface_Addressing.xml | 245 | ||||
-rw-r--r-- | extensions/Makefile.am | 1 | ||||
-rw-r--r-- | extensions/all.xml | 6 |
3 files changed, 252 insertions, 0 deletions
diff --git a/extensions/Connection_Interface_Addressing.xml b/extensions/Connection_Interface_Addressing.xml new file mode 100644 index 000000000..db8155f23 --- /dev/null +++ b/extensions/Connection_Interface_Addressing.xml @@ -0,0 +1,245 @@ +<?xml version="1.0" ?> +<node name="/Connection_Interface_Addressing" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright> Copyright (C) 2010 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.Connection.Interface.Addressing.DRAFT" + tp:causes-havoc="experimental"> + <tp:requires interface="org.freedesktop.Telepathy.Connection"/> + <tp:requires interface="org.freedesktop.Telepathy.Connection.Interface.Contacts"/> + <tp:added version="0.19.12">(as draft)</tp:added> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>This interface deals with the multiple address types that can + refer to the same contact, such as vCard fields and URIs.</p> + + <p>It can be used to retrieve contacts with a specific addresses + through <tp:member-ref>GetContactsByVCardField</tp:member-ref> and + <tp:member-ref>GetContactsByURI</tp:member-ref>, as well as + defining the various addressing methods for a given contact + through this interface's contact attributes.</p> + </tp:docstring> + + <method name="GetContactsByVCardField" + tp:name-for-bindings="Get_Contacts_By_VCard_Field"> + <arg direction="in" name="Field" type="s"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The vCard field of the addresses we are requesting. The + field name SHOULD be in lower case. Supported + fields can be found in + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Protocol.Interface.Addressing">AddressableVCardFields</tp:dbus-ref>.</p> + + <p>The <code>url</code> vCard field MUST NOT appear here; see + <tp:member-ref>GetContactsByURI</tp:member-ref> instead.</p> + + <tp:rationale> + <p>In practice, protocols have a limited set of URI + schemes that make sense to resolve as a contact.</p> + </tp:rationale> + + </tp:docstring> + </arg> + <arg direction="in" name="Addresses" type="as"> + <tp:docstring> + The addresses to get contact handles for. The address types + should match the given vCard field. + </tp:docstring> + </arg> + <arg direction="in" name="Interfaces" type="as" + tp:type="DBus_Interface[]"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A list of strings indicating which D-Bus interfaces the calling + process is interested in. All supported attributes from these + interfaces, whose values can be obtained without additional network + activity, will be in the reply.</p> + + <p>Attributes from this interface and from + <tp:dbus-ref>org.freedesktop.Telepathy.Connection</tp:dbus-ref> + are always returned, and need not be requested + explicitly.</p> + + <p>The behavior of this parameter is similar to the same + parameter in + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface">Contacts.GetContactAttributes</tp:dbus-ref>.</p> + </tp:docstring> + </arg> + + <arg direction="out" type="a{su}" name="Requested" + tp:type="Addressing_Normalization_Map"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A mapping from requested vCard addresses to the corresponding + contact handles.</p> + + <p>Requested addresses that are not valid or understood for this protocol + MUST be omitted from the mapping.</p> + </tp:docstring> + </arg> + + <arg direction="out" type="a{ua{sv}}" name="Attributes" + tp:type="Contact_Attributes_Map"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A dictionary mapping the contact handles to contact attributes. + If any of the requested addresses are in fact invalid, they are + simply omitted from this mapping. If contact attributes are not + immediately known, the behaviour is defined by the interface; + the attribute should either be omitted from the result or + replaced with a default value.</p> + + <p>Requested addresses that are not valid or understood for this protocol + MUST be omitted from the mapping.</p> + + <p>Each contact's attributes will always include at least the + identifier that would be obtained by inspecting the handle + (<code>org.freedesktop.Telepathy.Connection/contact-id</code>). + </p> + </tp:docstring> + </arg> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Request contacts and retrieve their attributes using a given field + in their vCards.</p> + + <p>The connection manager should record that these handles are in + use by the client who invokes this method, and must not + deallocate the handles until the client disconnects from the + bus or calls the + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.ReleaseHandles</tp:dbus-ref> + method.</p> + </tp:docstring> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + </tp:possible-errors> + </method> + + <method name="GetContactsByURI" + tp:name-for-bindings="Get_Contacts_By_URI"> + <arg direction="in" name="URIs" type="as"> + <tp:docstring> + The URI addresses to get contact handles for. Supported + schemes can be found in + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Protocol.Interface.Addressing">AddressableURISchemes</tp:dbus-ref>. + </tp:docstring> + </arg> + <arg direction="in" name="Interfaces" type="as" + tp:type="DBus_Interface[]"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A list of strings indicating which D-Bus interfaces the calling + process is interested in. All supported attributes from these + interfaces, whose values can be obtained without additional network + activity, will be in the reply.</p> + + <p>Attributes from this interface and from + <tp:dbus-ref>org.freedesktop.Telepathy.Connection</tp:dbus-ref> + are always returned, and need not be requested + explicitly.</p> + + <p>The behavior of this parameter is similar to the same + parameter in + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface">Contacts.GetContactAttributes</tp:dbus-ref>.</p> + </tp:docstring> + </arg> + + <arg direction="out" type="a{su}" name="Requested" + tp:type="Addressing_Normalization_Map"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A mapping of requested URIs to the corresponding contact handles.</p> + + <p>Requested URIs that are not valid or understood for this protocol + MUST be omitted from the mapping.</p> + </tp:docstring> + </arg> + + <arg direction="out" type="a{ua{sv}}" name="Attributes" + tp:type="Contact_Attributes_Map"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A dictionary mapping the contact handles to contact attributes. + If any of the requested addresses are in fact invalid, they are + simply omitted from this mapping. If contact attributes are not + immediately known, the behaviour is defined by the interface; + the attribute should either be omitted from the result or + replaced with a default value.</p> + + <p>Requested URIs that are not valid or understood for this protocol + MUST be omitted from the mapping.</p> + + <p>Each contact's attributes will always include at least the + identifier that would be obtained by inspecting the handle + (<code>org.freedesktop.Telepathy.Connection/contact-id</code>). + </p> + </tp:docstring> + </arg> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Request contacts and retrieve their attributes using URI addresses.</p> + + <p>The connection manager should record that these handles are in + use by the client who invokes this method, and must not + deallocate the handles until the client disconnects from the + bus or calls the + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.ReleaseHandles</tp:dbus-ref> + method.</p> + </tp:docstring> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + </tp:possible-errors> + </method> + + <tp:mapping name="VCard_Field_Address_Map" array-name=""> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A mapping of vCard fields and addresses that repreent + the given contact.</p> + </tp:docstring> + <tp:member type="s" name="VCard_Field"/> + <tp:member type="s" name="Address"/> + </tp:mapping> + + <tp:contact-attribute name="addresses" type="a{ss}" + tp:type="VCard_Field_Address_Map"> + <tp:docstring> + The various vCard addresses that identify this contact. + </tp:docstring> + </tp:contact-attribute> + + <tp:contact-attribute name="uris" type="as"> + <tp:docstring> + The various URI addresses that identify this contact. + </tp:docstring> + </tp:contact-attribute> + + <tp:mapping name="Addressing_Normalization_Map"> + <tp:docstring> + A map from URIs/vCard addresses to the corresponding handle. + </tp:docstring> + <tp:added version="0.25.UNRELEASED"/> + + <tp:member type="s" name="Requested_String"> + <tp:docstring> + The URI or vCard address that has been requested by + <tp:member-ref>GetContactsByVCardField</tp:member-ref> or + <tp:member-ref>GetContactsByURI</tp:member-ref>. + </tp:docstring> + </tp:member> + <tp:member type="u" name="Handle" tp:type="Contact_Handle"> + <tp:docstring> + A nonzero handle. + </tp:docstring> + </tp:member> + </tp:mapping> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/extensions/Makefile.am b/extensions/Makefile.am index 47b51b350..8e50ffbce 100644 --- a/extensions/Makefile.am +++ b/extensions/Makefile.am @@ -4,6 +4,7 @@ EXTRA_DIST = \ all.xml \ Channel_Type_FileTransfer_Future.xml \ Connection_Future.xml \ + Connection_Interface_Addressing.xml \ Connection_Interface_Gabble_Decloak.xml \ Gabble_Plugin_Console.xml \ Gabble_Plugin_Gateways.xml \ diff --git a/extensions/all.xml b/extensions/all.xml index 90f52a89b..99997d6db 100644 --- a/extensions/all.xml +++ b/extensions/all.xml @@ -33,6 +33,8 @@ Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA</p> from="Telepathy specification"/> </tp:generic-types> +<xi:include href="Connection_Interface_Addressing.xml"/> + <xi:include href="OLPC_Buddy_Info.xml"/> <xi:include href="OLPC_Activity_Properties.xml"/> @@ -81,6 +83,10 @@ Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA</p> <tp:external-type name="String_Variant_Map" type="a{sv}" from="Telepathy specification"/> + <!-- use types from Connection_Interface_Contacts --> + <tp:external-type name="Contact_Attributes_Map" type="a{ua{sv}}" + from="Telepathy specification"/> + <!-- use types from Connection_Interface_Requests --> <tp:external-type name="Channel_Class" type="a{sv}" from="Telepathy specification"/> |