diff options
-rw-r--r-- | spec/Channel_Interface_Picture.xml | 198 | ||||
-rw-r--r-- | spec/all.xml | 1 |
2 files changed, 199 insertions, 0 deletions
diff --git a/spec/Channel_Interface_Picture.xml b/spec/Channel_Interface_Picture.xml new file mode 100644 index 00000000..883878e2 --- /dev/null +++ b/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/all.xml b/spec/all.xml index 4a2ab145..dfa1cb47 100644 --- a/spec/all.xml +++ b/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"> |