summaryrefslogtreecommitdiff
path: root/extensions
diff options
context:
space:
mode:
authorWill Thompson <will.thompson@collabora.co.uk>2011-11-24 15:15:58 +0000
committerWill Thompson <will.thompson@collabora.co.uk>2011-11-24 15:25:12 +0000
commitf467b8cd4dffca20516be46d6da58f0bb4868df3 (patch)
treeb501e4c1e29b8dc20af34709a0e53cecf4f9cad0 /extensions
parent6a0ed9a2f9c49d21060dd0053c8b71864ee59e10 (diff)
parent7fa869b1f319ab42c75d61fdd3b22859f3bb1dfb (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.xml245
-rw-r--r--extensions/Makefile.am1
-rw-r--r--extensions/all.xml6
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"/>