path: root/spec/Channel_Interface_Room_Config1.xml

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

  <tp:copyright>Copyright © 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="im.telepathy1.Channel.Interface.RoomConfig1">
    <tp:added version="0.24.0">version 1. This replaces the old-school
      Telepathy properties on <tp:dbus-ref
      namespace='imt1.Channel.Type'>Text</tp:dbus-ref>.</tp:added>
    <tp:requires interface='im.telepathy1.Channel.Interface.Room1'/>
    <annotation name="org.freedesktop.DBus.Property.EmitsChangedSignal"
                value="true"/>

    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
      <p>Represents the configuration of a chatroom, some aspects of which may
        be modifiable by the user, depending on their priviledges. This
        corresponds to the room configuration on XMPP, and various channel mode
        flags on IRC.</p>

      <p>The “topic” (on IRC) or “subject” (on XMPP) is not part of this
        interface; it can be found on the <tp:dbus-ref
        namespace='imt1.Channel.Interface'>Subject1</tp:dbus-ref>
        interface.</p>
    </tp:docstring>

    <property name="Anonymous" tp:name-for-bindings="Anonymous" type="b" access="read">
      <tp:docstring>
      <code>True</code> if people may join the channel without other members being made
      aware of their identity.
      </tp:docstring>
    </property>
    <property name="InviteOnly" tp:name-for-bindings="InviteOnly" type="b" access="read">
      <tp:docstring>
      <code>True</code> if people may not join the channel until they have been invited.
      </tp:docstring>
    </property>
    <property name="Limit" tp:name-for-bindings="Limit" type="u" access="read">
      <tp:docstring>
      The limit to the number of members; or <tt>0</tt> if there is no limit.
      </tp:docstring>
    </property>
    <property name="Moderated" tp:name-for-bindings="Moderated" type="b" access="read">
      <tp:docstring>
      <code>True</code> if channel membership is not sufficient to allow participation.
      </tp:docstring>
    </property>
    <property name="Title" tp:name-for-bindings="Title" type="s" access="read">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
      A human-visible name for the channel, if it differs from <tp:dbus-ref
      namespace='imt1.Channel.Interface'>Room1.RoomName</tp:dbus-ref>; the
      empty string, otherwise.

      <tp:rationale>
        <p>On XMPP, this represents the <code>muc#roomconfig_roomname</code>
        field of the <a
        href='http://xmpp.org/extensions/xep-0045.html#registrar-formtype-owner'><code>muc#roomconfig</code></a>
        form. So for <code>jdev@conference.jabber.org</code>, for example:</p>

        <ul>
          <li><tp:dbus-ref
            namespace='imt1.Channel.Interface'>Room1.RoomName</tp:dbus-ref>
            = <code>"jdev"</code>;</li>
          <li><tp:dbus-ref
            namespace='imt1.Channel.Interface'>Room1.Server</tp:dbus-ref>
            = <code>"conference.jabber.org"</code>;</li>
          <li><tp:member-ref>Title</tp:member-ref> = <code>"General Jabber
            development discussion"</code>.</li>
        </ul>

        <p>XEP-0045 is awful.</p>
      </tp:rationale>
      </tp:docstring>
    </property>
    <property name="Description" tp:name-for-bindings="Description" type="s" access="read">
      <tp:docstring>
      A human-readable description of the channel's overall purpose; if any.
      </tp:docstring>
    </property>
    <property name="Persistent" tp:name-for-bindings="Persistent" type="b" access="read">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
      <code>True</code> if the channel will remain in existence on the server after all
      members have left it.
      </tp:docstring>
    </property>
    <property name="Private" tp:name-for-bindings="Private" type="b" access="read">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
      <code>True</code> if the channel is not visible to non-members.
      </tp:docstring>
    </property>

    <property name="PasswordProtected" type="b" access="read"
              tp:name-for-bindings="Password_Protected">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <code>True</code> if contacts joining this channel must provide a
        password to be granted entry.  Note that this property does not
        indicate that a password is required <em>right now</em>; see the
        <tp:dbus-ref namespace='imt1.Channel.Interface'>Password1</tp:dbus-ref>
        interface for the API used to provide a password while joining a room.
      </tp:docstring>
    </property>

    <property name="Password" tp:name-for-bindings="Password" type="s" access="read">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        If <tp:member-ref>PasswordProtected</tp:member-ref> is
        <code>True</code>, the password required to enter the channel, if
        known. If the password is unknown, or
        <tp:member-ref>PasswordProtected</tp:member-ref> is
        <code>False</code>, the empty string.

        <tp:rationale>
          On XMPP—bless its cotton socks!—non-owners of a MUC cannot see its
          current password, even if they just provided the password in order to
          join the room…
        </tp:rationale>
      </tp:docstring>
    </property>

    <property name="PasswordHint" tp:name-for-bindings="Password_Hint"
              type="s" access="read">
      <tp:added version="0.25.0"/>
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>If <tp:member-ref>PasswordProtected</tp:member-ref> is
          <code>True</code>, an optional hint for the password.</p>

        <p>On protocols supporting PasswordHint (indicated by its presence
          in <tp:member-ref>MutableProperties</tp:member-ref>),
          <tp:member-ref>Password</tp:member-ref> and PasswordHint MUST be
          set in a single call to
          <tp:member-ref>UpdateConfiguration</tp:member-ref>.</p>

        <tp:rationale>
          Skype requires that the password and its hint be supplied together.
        </tp:rationale>
      </tp:docstring>
    </property>

    <property name="CanUpdateConfiguration" type="b" access="read"
              tp:name-for-bindings="Can_Update_Configuration">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        If <code>True</code>, the user may call
        <tp:member-ref>UpdateConfiguration</tp:member-ref> to change the values
        of the properties listed in
        <tp:member-ref>MutableProperties</tp:member-ref>.
      </tp:docstring>
    </property>

    <property name="MutableProperties" type="as" access="read"
              tp:name-for-bindings="Mutable_Properties">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>A list of (unqualified) property names on this interface which may
          be modified using <tp:member-ref>UpdateConfiguration</tp:member-ref>
          (if <tp:member-ref>CanUpdateConfiguration</tp:member-ref> is
          <code>True</code>). Properties not listed here cannot be
          modified.</p>

        <p>For example, IRC does not have the concept of joining a room without
          other participants knowing your true identity; so on IRC the
          <tp:member-ref>Anonymous</tp:member-ref> property will always be
          <code>False</code>, and
          <tp:member-ref>MutableProperties</tp:member-ref> will not include
          <code>"Anonymous"</code>.</p>
      </tp:docstring>
    </property>

    <property name="ConfigurationRetrieved" type="b" access="read"
              tp:name-for-bindings="Configuration_Retrieved">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p><code>True</code> once the initial room configuration has been
          retrieved, or <code>False</code> otherwise. On some services, this
          may take some time after you've joined a room to fetch the
          configuration. Once this property changes to <code>True</code>, the
          other properties on this interface can be assumed to be accurate;
          this property MUST not change to <code>False</code> after it becomes
          <code>True</code>.</p>

        <tp:rationale>
          <p>An application's “configure this room” dialog might choose to
            display a spinner while this property is <code>False</code>, rather
            than allowing the user to edit probably-inaccurate
            configuration.</p>
        </tp:rationale>
      </tp:docstring>
    </property>

    <method name="UpdateConfiguration" tp:name-for-bindings="Update_Configuration">
      <arg direction="in" name="Properties" type="a{sv}">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>
            The new values of one or more properties on this interface, which
            must be listed in
            <tp:member-ref>MutableProperties</tp:member-ref>. For
            instance, to set up a channel for discussing top-secret corporate
            merge plans, this parameter might be:
          </p>

          <blockquote>
            <pre>{
  'Private': True,
  'InviteOnly': True,
  'Description': "The first rule of #inteltakeover is: do not talk about #inteltakeover",
}</pre></blockquote>
        </tp:docstring>
      </arg>
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>If <tp:member-ref>CanUpdateConfiguration</tp:member-ref> is
          <code>True</code>, modifies the current values of one or more
          room properties. This method SHOULD NOT return until the change has
          been accepted or declined by the server.</p>

        <p>Note that the server may ostensibly accept the changes (thus
          allowing this method to return success) but signal different values;
          for example, the server might truncate
          <tp:member-ref>Title</tp:member-ref> to some maximum length. Callers
          SHOULD continue to listen for the <code>PropertiesChanged</code>
          signal, and trust the values it signals over those provided to this
          method.</p>
      </tp:docstring>

      <tp:error name="im.telepathy1.Error.PermissionDenied">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          The user is not allowed to reconfigure this room.
        </tp:docstring>
      </tp:error>

      <tp:error name="im.telepathy1.Error.InvalidArgument">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          One or more of the specified properties is unknown, or ill-typed.
        </tp:docstring>
      </tp:error>

      <tp:error name="im.telepathy1.Error.NotImplemented">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          One or more of the specified properties cannot be modified on this
          protocol.
        </tp:docstring>
      </tp:error>

      <tp:error name="im.telepathy1.Error.NotAvailable">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          The room's current configuration has not yet been retrieved, so we
          cannot update it just yet. The application might like to try again
          once the <tp:member-ref>ConfigurationRetrieved</tp:member-ref>
          property becomes <code>True</code>.
        </tp:docstring>
      </tp:error>
    </method>

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