New iface: Channel.Interface.Picture

Lets the users set/get the picture for a chatroom.

Fixes: https://bugs.freedesktop.org/show_bug.cgi?id=42653

2 files changed, 199 insertions, 0 deletions

diff --git a/spec/spec/Channel_Interface_Picture.xml b/spec/spec/Channel_Interface_Picture.xml
new file mode 100644
index 000000000..883878e25
--- /dev/null
+++ b/spec/spec/Channel_Interface_Picture.xml
@@ -0,0 +1,198 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Interface_Picture"
+  xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+
+  <tp:copyright>Copyright © 2010–2011 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.Channel.Interface.Picture1"
+             tp:causes-havoc="draft">
+    <tp:requires interface="org.freedesktop.Telepathy.Channel"/>
+    <tp:added version="UNRELEASED"/>
+    <annotation name="org.freedesktop.DBus.Property.EmitsChangedSignal"
+                value="true"/>
+
+    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+      <p>An interface channels can implement to support a picture. Most
+        of the time this will be implemented by channels implementing
+        the <tp:dbus-ref
+        namespace="ofdT.Channel.Interface">Room2</tp:dbus-ref>
+        interface. Note that this interface is not restricted to
+        Text channels, and can also be used on Call channels.</p>
+
+      <tp:rationale>
+        This is a separate interface from
+        <tp:dbus-ref namespace="ofdT.Channel.Interface">RoomConfig1</tp:dbus-ref>
+        because (a) it's possible some protocol might support pictures for
+        1:1 chats; and (b) it avoids downloading an unwanted picture in a
+        GetAll request.
+      </tp:rationale>
+    </tp:docstring>
+
+    <method name="SetPicture" tp:name-for-bindings="Set_Picture">
+      <arg direction="in" type="ay" name="Picture">
+        <tp:docstring>The new picture.</tp:docstring>
+      </arg>
+      <arg direction="in" type="s" name="MIME_Type">
+        <tp:docstring>The MIME type.</tp:docstring>
+      </arg>
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>Set the room's picture. Clients SHOULD look at the picture
+          flags before calling this method as the user might not have
+          permission to set the picture.</p>
+
+        <p>A successful return of this method indicates a successful
+          change in picture, but clients should still listen for changes
+          to the <tp:member-ref>Picture</tp:member-ref> property for
+          further changes by other users or the server.</p>
+      </tp:docstring>
+      <tp:possible-errors>
+        <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"/>
+        <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+          <tp:docstring>
+            Picture is somehow invalid: e.g. unsupported MIME type,
+            too big, etc.
+          </tp:docstring>
+        </tp:error>
+        <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
+      </tp:possible-errors>
+    </method>
+
+    <property name="Picture" tp:name-for-bindings="Picture"
+              type="(ays)" tp:type="Avatar" access="read">
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>The picture representing this channel.</p>
+
+        <p>This property may change during the lifetime of the channel and
+          MUST not be included in a channel request.</p>
+      </tp:docstring>
+    </property>
+
+    <property name="Actor" tp:name-for-bindings="Actor"
+              type="s" access="read">
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>The normalized contact ID representing who last modified
+          the picture, or the empty string if it is not known.</p>
+      </tp:docstring>
+    </property>
+
+    <property name="ActorHandle" tp:name-for-bindings="Actor_Handle"
+              type="u" tp:type="Contact_Handle" access="read">
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>The handle corresponding to <tp:member-ref>Actor</tp:member-ref>,
+        or 0 if the <tp:member-ref>Actor</tp:member-ref> is unknown.</p>
+      </tp:docstring>
+    </property>
+
+    <property name="Timestamp" tp:name-for-bindings="Timestamp"
+              type="x" tp:type="Unix_Timestamp64" access="read">
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>A unix timestamp indicating when the picture was last
+         modified, or <code>INT_MAX64</code> if unknown.</p>
+      </tp:docstring>
+    </property>
+
+    <property name="CanSet" tp:name-for-bindings="Can_Set"
+              type="b" access="read">
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>TRUE if the <tp:member-ref>Picture</tp:member-ref> property
+          can be set by the user by calling
+          <tp:member-ref>SetPicture</tp:member-ref>, otherwise
+          FALSE.</p>
+
+        <p>If implementations are unsure of what this value should be
+          it SHOULD still be set to what it believes the value
+          is. As a result, clients should be aware that
+          <tp:member-ref>SetPicture</tp:member-ref> can still fail
+          even with this property set to TRUE.</p>
+      </tp:docstring>
+    </property>
+
+    <property name="SupportedMIMETypes"
+      tp:name-for-bindings="Supported_MIME_Types"
+      type="as" access="read" tp:immutable="yes">
+      <tp:docstring>
+        An array of supported MIME types (e.g. "image/jpeg").
+        Clients MAY assume that the first type in this array is preferred.
+      </tp:docstring>
+    </property>
+
+    <property name="MinimumHeight"
+      tp:name-for-bindings="Minimum_Height"
+      type="u" access="read" tp:immutable="yes">
+      <tp:docstring>
+        The minimum height in pixels of the picture, which MAY be 0.
+      </tp:docstring>
+    </property>
+
+    <property name="MinimumWidth"
+      tp:name-for-bindings="Minimum_Width"
+      type="u" access="read" tp:immutable="yes">
+      <tp:docstring>
+        The minimum width in pixels of the picture, which MAY be 0.
+      </tp:docstring>
+    </property>
+
+    <property name="RecommendedHeight"
+      tp:name-for-bindings="Recommended_Height"
+      type="u" access="read" tp:immutable="yes">
+      <tp:docstring>
+        The recommended height in pixels of the picture, or 0 if
+        there is no preferred height.
+      </tp:docstring>
+    </property>
+
+    <property name="RecommendedWidth"
+      tp:name-for-bindings="Recommended_Width"
+      type="u" access="read" tp:immutable="yes">
+      <tp:docstring>
+        The recommended width in pixels of the picture, or 0 if
+        there is no preferred width.
+      </tp:docstring>
+    </property>
+
+    <property name="MaximumHeight"
+      tp:name-for-bindings="Maximum_Height"
+      type="u" access="read" tp:immutable="yes">
+      <tp:docstring>
+        The maximum height in pixels of the picture, or 0 if
+        there is no limit.
+      </tp:docstring>
+    </property>
+
+    <property name="MaximumWidth"
+      tp:name-for-bindings="Maximum_Width"
+      type="u" access="read" tp:immutable="yes">
+      <tp:docstring>
+        The maximum width in pixels of the picture, or 0 if
+        there is no limit.
+      </tp:docstring>
+    </property>
+
+    <property name="MaximumBytes"
+      tp:name-for-bindings="Maximum_Bytes"
+      type="u" access="read" tp:immutable="yes">
+      <tp:docstring>
+        The maximum size in bytes of the picture, or 0 if
+        there is no limit.
+      </tp:docstring>
+    </property>
+
+  </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/spec/all.xml b/spec/spec/all.xml
index 4a2ab1456..dfa1cb474 100644
--- a/spec/spec/all.xml
+++ b/spec/spec/all.xml
@@ -171,6 +171,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
    <xi:include href="Channel_Interface_Securable.xml"/>
    <xi:include href="Channel_Interface_Service_Point.xml"/>
    <xi:include href="Channel_Interface_Subject.xml"/>
+   <xi:include href="Channel_Interface_Picture.xml"/>
    <xi:include href="Channel_Interface_Tube.xml"/>
 
    <tp:section name="Text-specific interfaces">