<?xml version="1.0" ?>
<node name="/Protocol_Interface_Avatars"
  xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">

  <tp:copyright>Copyright © 2009-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.Avatars">
    <tp:added version="0.21.5">(as stable API)</tp:added>
    <tp:requires interface="org.freedesktop.Telepathy.Protocol"/>

    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
      <p>An interface for protocols where it might be possible to set the
        user's avatar, and the expected size limits and supported MIME types
        are known before connecting.</p>

      <tp:rationale>
        <p>If the avatar requirements cannot be discovered while offline,
          it's impossible to avoid setting the <tp:dbus-ref
            namespace="org.freedesktop.Telepathy"
            >Account</tp:dbus-ref>'s <tp:dbus-ref
            namespace="org.freedesktop.Telepathy.Account.Interface.Avatar"
            >Avatar</tp:dbus-ref> property to an unsupported avatar.</p>
      </tp:rationale>

      <p>Each property on this interface SHOULD be cached in the
        <code>.manager</code> file, using a key of the same name as the
        property in the <code>[Protocol <em>proto</em>]</code>
        group. All properties are encoded in ASCII decimal in the obvious
        way, except for
        <tp:member-ref>SupportedAvatarMIMETypes</tp:member-ref> which is
        encoded as a sequence of strings each followed by a semicolon
        (as for the "localestrings" type in the Desktop Entry
        Specification).</p>

      <p>For instance, an XMPP connection manager might have this
        <code>.manager</code> file:</p>

<pre>[Protocol jabber]
Interfaces=org.freedesktop.Telepathy.Protocol.Interface.Avatars;
param-account=s required
param-password=s required
SupportedAvatarMIMETypes=image/png;image/jpeg;image/gif;
MinimumAvatarHeight=32
RecommendedAvatarHeight=64
MaximumAvatarHeight=96
MinimumAvatarWidth=32
RecommendedAvatarWidth=64
MaximumAvatarWidth=96
MaximumAvatarBytes=8192
</pre>
    </tp:docstring>

    <property name="SupportedAvatarMIMETypes"
      tp:name-for-bindings="Supported_Avatar_MIME_Types"
      type="as" access="read" tp:immutable="yes">
      <tp:docstring>
        The expected value of the <tp:dbus-ref
          namespace="org.freedesktop.Telepathy"
          >Connection.Interface.Avatars.SupportedAvatarMIMETypes</tp:dbus-ref>
        property on connections to this protocol.
      </tp:docstring>
    </property>

    <property name="MinimumAvatarHeight"
      tp:name-for-bindings="Minimum_Avatar_Height"
      type="u" access="read" tp:immutable="yes">
      <tp:docstring>
        The expected value of the <tp:dbus-ref
          namespace="org.freedesktop.Telepathy"
          >Connection.Interface.Avatars.MinimumAvatarHeight</tp:dbus-ref>
        property on connections to this protocol.
</tp:docstring>
    </property>

    <property name="MinimumAvatarWidth"
      tp:name-for-bindings="Minimum_Avatar_Width"
      type="u" access="read" tp:immutable="yes">
      <tp:docstring>
        The expected value of the <tp:dbus-ref
          namespace="org.freedesktop.Telepathy"
          >Connection.Interface.Avatars.MinimumAvatarWidth</tp:dbus-ref>
        property on connections to this protocol.
      </tp:docstring>
    </property>

    <property name="RecommendedAvatarHeight"
      tp:name-for-bindings="Recommended_Avatar_Height"
      type="u" access="read" tp:immutable="yes">
      <tp:docstring>
        The expected value of the <tp:dbus-ref
          namespace="org.freedesktop.Telepathy"
          >Connection.Interface.Avatars.RecommendedAvatarHeight</tp:dbus-ref>
        property on connections to this protocol.
      </tp:docstring>
    </property>

    <property name="RecommendedAvatarWidth"
      tp:name-for-bindings="Recommended_Avatar_Width"
      type="u" access="read" tp:immutable="yes">
      <tp:docstring>
        The expected value of the <tp:dbus-ref
          namespace="org.freedesktop.Telepathy"
          >Connection.Interface.Avatars.RecommendedAvatarWidth</tp:dbus-ref>
        property on connections to this protocol.
      </tp:docstring>
    </property>

    <property name="MaximumAvatarHeight"
      tp:name-for-bindings="Maximum_Avatar_Height"
      type="u" access="read" tp:immutable="yes">
      <tp:docstring>
        The expected value of the <tp:dbus-ref
          namespace="org.freedesktop.Telepathy"
          >Connection.Interface.Avatars.MaximumAvatarHeight</tp:dbus-ref>
        property on connections to this protocol.
      </tp:docstring>
    </property>

    <property name="MaximumAvatarWidth"
      tp:name-for-bindings="Maximum_Avatar_Width"
      type="u" access="read" tp:immutable="yes">
      <tp:docstring>
        The expected value of the <tp:dbus-ref
          namespace="org.freedesktop.Telepathy"
          >Connection.Interface.Avatars.MaximumAvatarWidth</tp:dbus-ref>
        property on connections to this protocol.
      </tp:docstring>
    </property>

    <property name="MaximumAvatarBytes"
      tp:name-for-bindings="Maximum_Avatar_Bytes"
      type="u" access="read" tp:immutable="yes">
      <tp:docstring>
        The expected value of the <tp:dbus-ref
          namespace="org.freedesktop.Telepathy"
          >Connection.Interface.Avatars.MaximumAvatarBytes</tp:dbus-ref>
        property on connections to this protocol.
      </tp:docstring>
    </property>
  </interface>
</node>
