Final cleanup pass over audio device API

extensions/common/api/audio.idl

Index: extensions/common/api/audio.idl
diff --git a/extensions/common/api/audio.idl b/extensions/common/api/audio.idl
index a1706126b68ffa83854e1eb15c2960da5ffe452b..617be48c56219856da1111f6204b883e482f3758 100644
--- a/extensions/common/api/audio.idl
+++ b/extensions/common/api/audio.idl
@@ -81,15 +81,35 @@ namespace audio {
     DOMString? stableDeviceId;
   };
 
+  dictionary DeviceFilter {
+    // If set, only audio devices whose stream type is included in this list
+    // will satisfy the filter.
+    StreamType[]? streamTypes;
+
+    // If set, only audio devices whose active state matches this value will
+    // satisfy the filter.
+    boolean? isActive;
+  };
+
   dictionary DeviceProperties {
     // True if this is muted.
     [deprecated="Use $(ref:setMute) to set mute state."] boolean? isMuted;
+
     // If this is an output device then this field indicates the output volume.
     // If this is an input device then this field is ignored.
-    double? volume;
+    [deprecated="Use |level| to set output volume."] double? volume;
+
     // If this is an input device then this field indicates the input gain.
     // If this is an output device then this field is ignored.
-    double? gain;
+    [deprecated="Use |level| to set input gain."] double? gain;
+ 
+    // <p>
+    //   The audio device's desired sound level. Defaults to the device's
+    //   current sound level.
+    // </p> 
+    // <p>If used with audio input device, represents audio device gain.</p>
+    // <p>If used with audio output device, represents audio device volume.</p>
+    long? level;
   };
 
   dictionary DeviceIdLists {
@@ -113,15 +133,31 @@ namespace audio {
     boolean isMuted;
   };
 
+  dictionary LevelChangedEvent {
+    // ID of device whose sound level has changed.
+    DOMString deviceId;
+
+    // The device's new sound level.
+    long level;
+  };
+
   callback GetInfoCallback = void(OutputDeviceInfo[] outputInfo,
                                   InputDeviceInfo[] inputInfo);
-  callback EmptyCallback = void();
+  callback GetDevicesCallback = void(AudioDeviceInfo[] devices);
   callback GetMuteCallback = void(boolean value);
+  callback EmptyCallback = void();
 
   interface Functions {
     // Gets the information of all audio output and input devices.
     static void getInfo(GetInfoCallback callback);
 
+    // Gets a list of audio devices filtered based on |filter|.
+    // |filter|: Device properties by which to filter the list of returned
+    //     audio devices. Use <code>{}</code> to get all available audio
+    //     devices.
+    // |callback|: Reports the requested list of audio devices. 
+    static void getDevices(DeviceFilter filter, GetDevicesCallback callback);
+
     // Sets lists of active input and/or output devices.
     // |ids|: <p>Specifies IDs of devices that should be active. If either the
     //     input or output list is not set, devices in that category are
@@ -161,9 +197,7 @@ namespace audio {
     static void onDeviceChanged();
 
     // Fired when sound level changes for an active audio device.
-    // |id|: id of the audio device.
-    // |level|: new sound level of device(volume for output, gain for input).
-    static void OnLevelChanged(DOMString id, long level);
+    static void onLevelChanged(LevelChangedEvent event);
 
     // Fired when the mute state of the audio input or output changes.
     // Note that mute state is system-wide and the new value applies to every
@@ -173,6 +207,6 @@ namespace audio {
     // Fired when audio devices change, either new devices being added, or
     // existing devices being removed.
     // |devices|: List of all present audio devices after the change.
-    static void OnDevicesChanged(AudioDeviceInfo[] devices);
+    static void onDeviceListChanged(AudioDeviceInfo[] devices);
   };
 };