<?xml version="1.0" ?>
<node name="/Channel_Interface_Subject"
  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.Subject2">
    <tp:requires interface="org.freedesktop.Telepathy.Channel"/>
    <tp:added version="0.24.0">(version 2)</tp:added>
    <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 subjects. Most
        of the time this will be implemented by channels implementing
        the <tp:dbus-ref
        namespace="ofdT.Channel.Interface">Room2</tp:dbus-ref>
        interface, but some protocols support subjects in 1-to-1 chats
        (such as XMPP). Note that this interface is not restricted to
        Text channels, and can also be used on Call channels.</p>
    </tp:docstring>

    <method name="SetSubject" tp:name-for-bindings="Set_Subject">
      <arg direction="in" type="s" name="Subject">
        <tp:docstring>The new subject.</tp:docstring>
      </arg>
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>Set the room's subject. Clients SHOULD look at the subject
          flags before calling this method as the user might not have
          permission to set the subject.</p>

        <p>A successful return of this method indicates a successful
          change in subject, but clients should still listen for changes
          to the <tp:member-ref>Subject</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.PermissionDenied"/>
      </tp:possible-errors>
    </method>

    <property name="Subject" tp:name-for-bindings="Subject"
              type="s" access="read">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>The human-readable subject on the channel such as the topic
          in an IRC channel, or the room name in XMPP MUCs.</p>

        <tp:rationale>This property replaces the subject Telepathy
          property of Text channels, as Telepathy properties are soon to
          be deprecated completely.</tp:rationale>

        <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 subject, or the empty string if it is not known.</p>

        <tp:rationale>This property replaces the subject-contact
          Telepathy property of Text channels, as Telepathy properties
          are soon to be deprecated completely.</tp:rationale>
      </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 subject was last
         modified, or <code>INT_MAX64</code> if unknown.</p>

        <tp:rationale>This property replaces the subject-timestamp
          Telepathy property of Text channels, as Telepathy properties
          are soon to be deprecated completely.</tp:rationale>
      </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>Subject</tp:member-ref> property
          can be set by the user by calling
          <tp:member-ref>SetSubject</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>SetSubject</tp:member-ref> can still fail
          even with this property set to TRUE.</p>

        <tp:rationale>In XMPP it is impossible to know whether an
          occupant can set the subject as XMPP server implementations
          are wildly inconsistent.</tp:rationale>
      </tp:docstring>
    </property>

  </interface>
</node>
<!-- vim:set sw=2 sts=2 et ft=xml: -->
