Update to telepathy-spec 0.24.0

This also includes the updates to the Call-based example code omitted
from fa81060.

1 files changed, 248 insertions, 0 deletions

diff --git a/spec/Channel_Interface_Room_Config.xml b/spec/Channel_Interface_Room_Config.xml
new file mode 100644
index 000000000..2ae7f1fd8
--- /dev/null
+++ b/spec/Channel_Interface_Room_Config.xml
@@ -0,0 +1,248 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Interface_Room_Config"
+  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="org.freedesktop.Telepathy.Channel.Interface.RoomConfig1">
+    <tp:added version="0.24.0">version 1. This replaces the old-school
+      Telepathy properties on <tp:dbus-ref
+      namespace='ofdT.Channel.Type'>Text</tp:dbus-ref>.</tp:added>
+    <tp:requires interface='org.freedesktop.Telepathy.Channel.Interface.Room2'/>
+    <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='ofdT.Channel.Interface'>Subject2</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='ofdT.Channel.Interface'>Room2.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='ofdT.Channel.Interface'>Room2.RoomName</tp:dbus-ref>
+            = <code>"jdev"</code>;</li>
+          <li><tp:dbus-ref
+            namespace='ofdT.Channel.Interface'>Room2.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='ofdT.Channel.Interface'>Password</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="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="org.freedesktop.Telepathy.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="org.freedesktop.Telepathy.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="org.freedesktop.Telepathy.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="org.freedesktop.Telepathy.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: -->