diff options
Diffstat (limited to 'qt4/spec/Protocol_Interface_Addressing.xml')
| -rw-r--r-- | qt4/spec/Protocol_Interface_Addressing.xml | 300 |
1 files changed, 300 insertions, 0 deletions
diff --git a/qt4/spec/Protocol_Interface_Addressing.xml b/qt4/spec/Protocol_Interface_Addressing.xml new file mode 100644 index 000000000..3722c3b81 --- /dev/null +++ b/qt4/spec/Protocol_Interface_Addressing.xml @@ -0,0 +1,300 @@ +<?xml version="1.0" ?> +<node name="/Protocol_Interface_Addressing" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + + <tp:copyright>Copyright © 2010 Collabora Ltd.</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.Protocol.Interface.Addressing.DRAFT" + tp:causes-havoc="experimental"> + <tp:added version="0.19.12">(as draft)</tp:added> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An interface for protocols that support multiple forms of + addressing contacts, for example through vCard addresses and URIs.</p> + + <p>If the ConnectionManager has a <tt>.manager</tt> file, and it + supports this interface, the interface's immutable properties + must be represented in the file; the representation is described as + part of the documentation for each property.</p> + + <p>For instance, a SIP connection manager might have the + following lines in the <tt>.manager</tt> file.</p> + +<pre> +[Protocol sip] +AddressableVCardFields=tel;x-sip; +AddressableURISchemes=tel;sip; +</pre> + </tp:docstring> + + <property name="AddressableVCardFields" + tp:name-for-bindings="Addressable_VCard_Fields" + access="read" type="as"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The vCard fields that can be used to request a contact with + normalized to lower case. If the <code>URL</code> vCard + field is addressable, a colon, followed by the supported URI + schemes will be concatenated.</p> + + <p>For example: <code>["tel", "x-sip"]</code>.</p> + + <p>The <code>url</code> vCard field MUST NOT appear here; see + <tp:member-ref>AddressableURISchemes</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> + + <p>This property should only be used when the connection is + offline. When it is connected the addressable fields should be + retrieved from the + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface">Requests.RequestableChannelClasses</tp:dbus-ref>'s + TargetVCardField fixed-property instead.</p> + + <p>Connection managers with a <code>.manager</code> file + MUST cache this property in the protocol's section of the + <code>.manager</code> file if it is non-empty, using the key + <code>AddressableVCardFields</code>. The corresponding value + is a list of strings, each followed with a semicolon and in the + syntax of the "localestring" type from the Desktop Entry + Specification.</p> + + <p>Well-known vCard fields:</p> + + <dl> + <dt><code>tel</code></dt> + <dd>The TEL vCard field. Used for phone numbers.</dd> + <dt><code>x-sip</code></dt> + <dd>The X-SIP vCard field. Used for SIP addresses.</dd> + <dt><code>x-aim</code></dt> + <dd>The X-AIM vCard field. Used for AIM user IDs.</dd> + <dt><code>x-icq</code></dt> + <dd>The X-ICQ vCard field. Used for ICQ UINs.</dd> + <dt><code>x-skype</code></dt> + <dd>The X-SKYPE vCard field. Used for Skype user names or + telephone numbers. There is also a X-SKYPE-USERNAME field, + but for Telepathy purposes, <code>x-skype</code> is preferred</dd> + <dt><code>x-groupwise</code></dt> + <dd>The X-GROUPWISE vCard field. Used for Groupwise contacts.</dd> + <dt><code>x-gadugadu</code></dt> + <dd>The X-GADUGADU vCard field. Used for Gadu-Gadu contacts.</dd> + <dt><code>x-jabber</code></dt> + <dd>The X-JABBER vCard field. Used for XMPP JIDs.</dd> + <dt><code>x-msn</code></dt> + <dd>The X-MSN vCard field. Used for MSN contacts.</dd> + <dt><code>x-yahoo</code></dt> + <dd>The X-YAHOO vCard field. Used for Yahoo! IDs.</dd> + </dl> + + </tp:docstring> + </property> + + <property name="AddressableURISchemes" + tp:name-for-bindings="Addressable_URI_Schemes" + access="read" type="as"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The URI schemes that are supported by this protocol.</p> + + <p>For example: <code>["tel", "sip"]</code>.</p> + + <p>This property should only be used when the connection is + offline. When it is connected the addressable URI schemes should be + retrieved from the + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface">Requests.RequestableChannelClasses</tp:dbus-ref>'s + TargetURIScheme fixed-property instead.</p> + + <p>Connection managers with a <code>.manager</code> file + MUST cache this property in the protocol's section of the + <code>.manager</code> file if it is non-empty, using the key + <code>AddressableURISchemes</code>. The corresponding value + is a list of strings, each followed with a semicolon and in the + syntax of the "localestring" type from the Desktop Entry + Specification.</p> + + <p>Well-known URI schemes:</p> + + <dl> + <dt><code>sip</code></dt> + <dd>SIP protocol. + For example: <code>sip:julien@example.com</code>.</dd> + <dt><code>sips</code></dt> + <dd>Secure (encrypted) SIP protocol. + For example: <code>sips:julien@example.com</code>.</dd> + <dt><code>tel</code></dt> + <dd>Used for telephone numbers. + For example: <code>tel:+12065551234</code>.</dd> + <dt><code>xmpp</code></dt> + <dd>XMPP protocol. + For example: <code>xmpp:julien@example.com</code>.</dd> + <dt><code>msnim</code></dt> + <dd>For the purposes of + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Protocol.Interface.Addressing.DRAFT</tp:dbus-ref>, + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Addressing.DRAFT</tp:dbus-ref>, + and + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.Interface.Addressing.DRAFT</tp:dbus-ref>, + the verb part is ignored, and SHOULD be <code>add</code>; the + <code>contact</code> field in the query string is used to + identify the contact. + For example: <code>msnim:add?contact=julien</code>.</dd> + <dt><code>aim</code></dt> + <dd>For the purposes of + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Protocol.Interface.Addressing.DRAFT</tp:dbus-ref>, + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Addressing.DRAFT</tp:dbus-ref>, + and + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.Interface.Addressing.DRAFT</tp:dbus-ref>, + the verb part is ignored, and SHOULD be <code>addbuddy</code>; the + <code>screenname</code> field in the query string is used to + identify the contact. + For example: <code>aim:addbuddy?screenname=julien</code>.</dd> + <dt><code>skype</code></dt> + <dd>Skype protocol. + For example: <code>skype:julien</code>.</dd> + <dt><code>ymsgr</code></dt> + <dd>For the purposes of + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Protocol.Interface.Addressing.DRAFT</tp:dbus-ref>, + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Addressing.DRAFT</tp:dbus-ref>, + and + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.Interface.Addressing.DRAFT</tp:dbus-ref>, + the verb part is ignored, and SHOULD be <code>addfriend</code>; the + query string is used to identify the contact. + For example: <code>ymsgr:addfriend?julien</code>.</dd> + <dt><code>gg</code></dt> + <dd>Gadu-Gadu protocol. + For example: <code>gg:julien</code>.</dd> + </dl> + </tp:docstring> + </property> + + <method name="NormalizeVCardAddress" + tp:name-for-bindings="Normalize_VCard_Address"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Attempt to normalize the given vCard address. Where possible, this + SHOULD return an address that would appear in the + <code>org.freedesktop.Telepathy.Connection.Interface.Addressing.DRAFT/addresses</code> + attribute for a contact on a connected + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>. + </p> + + <p>If full normalization requires network activity or is otherwise + impossible to do without a <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>, + this method SHOULD perform a best-effort normalization.</p> + + <p>An example would be a vCard TEL field with a formatted + number in the form of <code>+1 (206) 555 1234</code>, this would be + normalized to <code>+12065551234</code>.</p> + + <p>This method MAY simply raise NotImplemented on some + protocols, if it has no use.</p> + </tp:docstring> + + <arg direction="in" name="VCard_Field" type="s"> + <tp:docstring> + The vCard field of the address we are normalizing. The + field name SHOULD be in lower case, and MUST appear in + <tp:member-ref>AddressableVCardFields</tp:member-ref>. + </tp:docstring> + </arg> + + <arg direction="in" name="VCard_Address" type="s"> + <tp:docstring> + The address to normalize. + </tp:docstring> + </arg> + + <arg direction="out" name="Normalized_VCard_Address" type="s"> + <tp:docstring> + The vCard address, normalized as much as possible. + </tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + The vCard field is not supported (it is not in + <tp:member-ref>AddressableVCardFields</tp:member-ref>). + </tp:docstring> + </tp:error> + + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring> + The address is syntactically incorrect. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <method name="NormalizeURI" + tp:name-for-bindings="Normalize_URI"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Attempt to normalize the given contact URI. Where possible, this + SHOULD return an address that would appear in the + <code>org.freedesktop.Telepathy.Connection.Interface.Addressing.DRAFT/uris</code> + attribute for a contact on a connected + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>. + </p> + + <p>If full normalization requires network activity or is otherwise + impossible to do without a <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>, + this method SHOULD perform a best-effort normalization.</p> + + <p>Example: <code>xmpp:eitan@EXAMPLE.COM</code> would be normalized to + <code>xmpp:eitan@example.com</code>.</p> + + <p>This method MAY simply raise NotImplemented on some + protocols, if it has no use.</p> + </tp:docstring> + + <arg direction="in" name="URI" type="s"> + <tp:docstring> + The URI to normalize. The URI's scheme (i.e. the part before + the first colon) MUST appear in + <tp:member-ref>AddressableURISchemes</tp:member-ref>. + </tp:docstring> + </arg> + + <arg direction="out" name="Normalized_URI" type="s"> + <tp:docstring> + A URI, normalized as much as possible. + </tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + The URI scheme is not supported (it is not in + <tp:member-ref>AddressableURISchemes</tp:member-ref>). + </tp:docstring> + </tp:error> + + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring> + The URI is syntactically incorrect. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> |