<?xml version="1.0" ?>
<node name="/Call_Interface_Mute" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
  <tp:copyright> Copyright © 2005-2010 Nokia Corporation </tp:copyright>
  <tp:copyright> Copyright © 2005-2010 Collabora Ltd </tp:copyright>
  <tp:license xmlns="http://www.w3.org/1999/xhtml">
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.

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.

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.
  </tp:license>

  <interface name="org.freedesktop.Telepathy.Call1.Interface.Mute" tp:causes-havoc="experimental">
    <tp:added version="0.25.2">(as stable API)</tp:added>
    <tp:xor-requires>
      <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.Call1"/>
      <tp:requires interface="org.freedesktop.Telepathy.Call1.Content"/>
      <tp:requires interface="org.freedesktop.Telepathy.Call1.Stream"/>
    </tp:xor-requires>

    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
      <p>Interface for calls which may be muted.  This only makes sense
        for channels where audio or video is streaming between members.</p>

      <p>Muting a call content indicates that the user does not wish to send
        outgoing audio or video.</p>

      <p>It should always be possible to mute an entire call. It is sometimes
        also possible to mute individual Contents (e.g. to prevent background
        noise from disturbing other participants, but remain visible on
        webcam) or to mute individual streams (e.g. to "whisper" to other call
        participants)</p>

      <tp:rationale>
        For some protocols, the fact that the content is muted needs
        to be transmitted to the peer; for others, the notification
        to the peer is only informational (eg. XMPP), and some
        protocols may have no notion of muting at all.
      </tp:rationale>
    </tp:docstring>

    <tp:enum name="Local_Mute_State" type="u">
      <tp:docstring>
        The mute state of (at least part of) the call. See
        <tp:member-ref>LocalMuteState</tp:member-ref> for more details.
      </tp:docstring>

      <tp:enumvalue value="0" suffix="Unmuted">
        <tp:docstring>
          All streams are unmuted (the call is active). New channels SHOULD
          have this mute state.
        </tp:docstring>
      </tp:enumvalue>

      <tp:enumvalue value="1" suffix="Muted">
        <tp:docstring>
          All streams are Muted.
        </tp:docstring>
      </tp:enumvalue>

      <tp:enumvalue value="2" suffix="Pending_Mute">
        <tp:docstring>
          The connection manager is attempting to move to state Muted, but
          has not yet completed that operation. It is unspecified whether
          any, all or none of the streams making up the channel are muted.
          Examining the Mute state of Call Contents (if applicable) may
          provide more useful information.
        </tp:docstring>
      </tp:enumvalue>

      <tp:enumvalue value="3" suffix="Pending_Unmute">
        <tp:docstring>
          The connection manager is attempting to move to state Unmuted, but
          has not yet completed that operation. It is unspecified whether
          any, all or none of the streams making up the channel are muted.
          Examining the Mute state of Call Contents or Streams may
          provide more useful information.
        </tp:docstring>
      </tp:enumvalue>

      <tp:enumvalue value="4" suffix="Partially_Muted">
        <tp:docstring>
          Some of the constituent Streams are Muted. This state only makes
          sense on Call Channels or Contents.
          Examining the Mute state of Call Contents or Streams should
          provide more useful information.
        </tp:docstring>
      </tp:enumvalue>
    </tp:enum>

    <signal name="MuteStateChanged" tp:name-for-bindings="Mute_State_Changed">
      <tp:docstring>
        Emitted to indicate that the mute state has changed for this call content.
        This may occur as a consequence of the client calling
        <tp:member-ref>RequestMuted</tp:member-ref>, or as an indication that another
        client has (un)muted the content.
      </tp:docstring>
      <arg name="MuteState" type="u" tp:type="Local_Mute_State">
        <tp:docstring>
          The new mute state.
        </tp:docstring>
      </arg>
    </signal>

    <property name="LocalMuteState" type="u" tp:type="Local_Mute_State"
      access="read" tp:name-for-bindings="Local_Mute_State">
      <tp:docstring>
        The current mute state of this part of the call. New
        <tp:dbus-ref namespace="ofdT.Call1">Content</tp:dbus-ref>s should
        inherit the value of this property from the parent
        <tp:dbus-ref namespace="ofdT.Channel.Type">Call1</tp:dbus-ref>.
        Similarly, <tp:dbus-ref namespace="ofdT.Call1">Stream</tp:dbus-ref>s
        should inherit it from the parent <tp:dbus-ref
        namespace="ofdT.Call1">Content</tp:dbus-ref>.
      </tp:docstring>
    </property>

    <method name="RequestMuted" tp:name-for-bindings="Request_Muted">
      <tp:changed version="0.21.2">renamed from SetMuted to Mute</tp:changed>
      <tp:changed version="0.21.3">renamed back from Mute to SetMuted</tp:changed>
      <arg direction="in" name="Muted" type="b">
        <tp:docstring>
          True if the client wishes to mute the Content or Call.
        </tp:docstring>
      </arg>
      <tp:docstring>
        <p>Inform the CM that the Call, Content or Stream should be muted or
          unmuted.</p>

        <p>The CM will tell the streaming implementation to Mute Streams as
          required, and emit <tp:member-ref>MuteStateChanged</tp:member-ref>
          when done.</p>
      </tp:docstring>
    </method>

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