Add AudioControl specification

Add a simple interface for a CM to control the input and output volume.
Based on work by Mike Ruprecht, but modified to have more meaningfull
property and method names and a nicer range for Volume

2 files changed, 108 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 00000000..a89db912
--- /dev/null
+++ b/spec/Call_Content_Interface_Audio_Control.xml
@@ -0,0 +1,107 @@
+<!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 Raw
+          <tp:type>Call_Content_Packetization_Type</tp:type>), this interface may be necessary.</p>
+
+      <p>If this interface is present, the handler should call ReportInputVolume
+          and ReportOutputVolume whenever the the input or output volume is
+          changed. Regardless of whether this is in response to the local user
+          changing volume controls or after updating the stream volumes in
+          response to changes in InputVolume and OutputVolume signalled by the
+          connection manager.</p>
+
+      <p>The maximum volume as used in this Interface represent the unamplified
+         hardware volume (0db). 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 curently 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>
+          The input volume level currently in use.
+        </tp:docstring>
+      </arg>
+      <tp:docstring>
+        <p>Inform the CM that the Content input volume has been
+          changed by the client.</p>
+
+        <p>It is the clients 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 curently 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 currently used 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 0db)
+      </p>
+    </tp:docstring>
+  </tp:simple-type>
+  </interface>
+</node>
diff --git a/spec/all.xml b/spec/all.xml
index 277b54ab..fde4d808 100644
--- a/spec/all.xml
+++ b/spec/all.xml
@@ -242,6 +242,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
    <xi:include href="Call_Content_Interface_Media.xml"/>
    <xi:include href="Call_Interface_Mute.xml"/>
    <xi:include href="Call_Content_Interface_Video_Control.xml"/>
+   <xi:include href="Call_Content_Interface_Audio_Control.xml"/>
    <xi:include href="Call_Content_Media_Description.xml"/>
    <xi:include href="Call_Content_Media_Description_Interface_RTP_Header_Extensions.xml"/>
    <xi:include href="Call_Content_Media_Description_Interface_RTCP_Feedback.xml"/>