Add Call_Content_Interface_Audio_Control from telepathy-spec

2 files changed, 112 insertions, 0 deletions

diff --git a/spec/Call_Content_Interface_Audio_Control.xml b/spec/Call_Content_Interface_Audio_Control.xml
new file mode 100644
index 0000000..1229fb5
--- /dev/null
+++ b/spec/Call_Content_Interface_Audio_Control.xml
@@ -0,0 +1,111 @@
+<!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN" "http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
+<node name="/Call_Content_Interface_Audio_Control"
+  xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+  <tp:copyright>Copyright © 2009-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.Call1.Content.Interface.AudioControl"
+    tp:causes-havoc="experimental">
+    <tp:added version="0.25.UNRELEASED">(draft 1)</tp:added>
+    <tp:requires interface="org.freedesktop.Telepathy.Call1.Content.Interface.Media"/>
+    <annotation name="org.freedesktop.DBus.Property.EmitsChangedSignal" value="true"/>
+
+    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+      <p>This interface allows the connection manager to be kept informed of,
+          and control, the input and output volumes of an audio stream.
+          While generally not needed, if the connection manager needs to
+          handle stream volumes directly (typically when using
+          <tp:value-ref>Call_Content_Packetization_Type_Raw</tp:value-ref>),
+          this interface may be necessary.</p>
+
+      <p>If this interface is present, the handler should call
+          <tp:member-ref>ReportInputVolume</tp:member-ref>
+          and <tp:member-ref>ReportOutputVolume</tp:member-ref> whenever the
+          input and output volume change, both when the user manually modifies
+          the volume and when the volumes are adjusted in response to
+          <tp:member-ref>RequestedInputVolume</tp:member-ref> and
+          <tp:member-ref>RequestedOutputVolume</tp:member-ref> changing.</p>
+
+      <p>The maximum volume as used in this interface represent the unamplified
+         hardware volume (0 dB). No software amplification should be used to
+         boost the signal to a higher level when this Interface is in use</p>
+    </tp:docstring>
+
+    <property name="RequestedInputVolume" tp:type="Audio_Control_Volume"
+      type="i" access="read" tp:name-for-bindings="Requested_Input_Volume">
+      <tp:docstring>
+        The input volume as requested by the Connection Manager.
+        Initially and on any changes the client should change its input volume
+        to match the requested volume.
+      </tp:docstring>
+    </property>
+
+    <method name="ReportInputVolume" tp:name-for-bindings="Report_Input_Volume">
+      <arg direction="in" name="Volume" tp:type="Audio_Control_Volume" type="i">
+        <tp:docstring>
+          Report the input volume level as set by the client.
+        </tp:docstring>
+      </arg>
+      <tp:docstring>
+        <p>Report to the CM that the Content input volume has been
+          changed by the client.</p>
+
+        <p>It is the client's responsibility to change the input volume used for
+           the content. However, the client MUST call this whenever it changes
+           input volume for the content.</p>
+      </tp:docstring>
+    </method>
+
+    <property name="RequestedOutputVolume" tp:type="Audio_Control_Volume"
+      type="i" access="read" tp:name-for-bindings="Requested_Output_Volume">
+      <tp:docstring>
+        The input volume as requested by the Connection Manager.
+        Initially and on any changes the client should change its input volume
+        to match the requested volume.
+      </tp:docstring>
+    </property>
+
+    <method name="ReportOutputVolume"
+        tp:name-for-bindings="Report_Output_Volume">
+      <arg direction="in" name="Volume" tp:type="Audio_Control_Volume" type="i">
+        <tp:docstring>
+          Report the output volume level as set by the client.
+        </tp:docstring>
+      </arg>
+      <tp:docstring>
+        <p>Report to the CM that the content output volume has been
+          changed by the client.</p>
+
+        <p>It is the client's responsibility to change the output volume used
+           for the content. However, the client MUST call this whenever it
+           changes output volume for the content.</p>
+      </tp:docstring>
+    </method>
+
+  <tp:simple-type name="Audio_Control_Volume" type="i">
+    <tp:docstring>
+      <p>A volume value either reported to or requested by the Connection
+         Manager. This value should either be -1 for an unknown value or in the
+         range of 0-255, with 0 being the minimal volume and 255 being the
+         highest unamplified volume the input or output is capable of (known
+         as 0 dB)
+      </p>
+    </tp:docstring>
+  </tp:simple-type>
+  </interface>
+</node>
diff --git a/spec/Makefile.am b/spec/Makefile.am
index 21b4a4f..d23f471 100644
--- a/spec/Makefile.am
+++ b/spec/Makefile.am
@@ -1,5 +1,6 @@
 EXTRA_DIST = \
     Call_Content_Codec_Offer.xml \
+    Call_Content_Interface_Audio_Control.xml \
     Call_Content_Interface_Media.xml \
     Call_Content_Interface_Mute.xml \
     Call_Content_Interface_Video_Control.xml \