1 files changed, 187 insertions, 0 deletions
diff --git a/dom/audiochannel/nsIAudioChannelAgent.idl b/dom/audiochannel/nsIAudioChannelAgent.idl
new file mode 100644
index 000000000..820f8da85
--- /dev/null
+++ b/dom/audiochannel/nsIAudioChannelAgent.idl
@@ -0,0 +1,187 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this file,
+ * You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+#include "nsISupports.idl"
+
+interface mozIDOMWindow;
+
+typedef uint32_t nsSuspendedTypes;
+
+[scriptable, builtinclass, uuid(2822a840-f009-11e5-a837-0800200c9a66)]
+interface nsISuspendedTypes : nsISupports
+{
+  /**
+   * The suspended enum is used in three different situations,
+   * - platform audio focus (Fennec/B2G)
+   * - remote media control (Fennec)
+   * - block auto-play video in non-active page
+   *
+   * Note: the "remote side" must control the AudioChannelAgent using
+   * nsIAudioChannelAgentCallback.windowSuspendChanged() callback instead using
+   * play/pause methods or any button in the webpage.
+   *
+   * - SUSPENDED_PAUSE :
+   * It's used when transiently losing audio focus, the media can't be resumed
+   * until we gain the audio focus again. It would change the internal state of
+   * MediaElement when it's being suspended/resumed, and it would trigger the
+   * related JS event. eg. "play" and "pause" event.
+   *
+   * - SUSPENDED_BLOCK
+   * It's used to prevent auto-playing media in inactive page in order to
+   * reduce the power consumption, and the media can't be resumed until the
+   * page becomes active again. It would change the internal state of
+   * MediaElement when it's being blocked/resumed, so it won't trigger the
+   * related JS event. eg. "play" and "pause" event.
+   *
+   * - SUSPENDED_PAUSE_DISPOSABLE
+   * It's used for remote media-control to pause the playing media and when we
+   * lose audio focus permanently. It's disposable suspended, so the media can
+   * be resumed arbitrary after that. Same as SUSPENDED_PAUSE, it would change
+   * the internal state of MediaElement when it's being suspended.
+   *
+   * - SUSPENDED_STOP_DISPOSABLE
+   * It's used for remote media-control to stop the playing media. The remote
+   * control would disappear after stopping the media, so we would disconnect
+   * the audio channel agent. It's disposable suspended, so the media can be
+   * resumed arbitrary after that. Same as SUSPENDED_PAUSE, it would change
+   * the internal state of MediaElement when it's being suspended.
+   */
+
+  const uint32_t NONE_SUSPENDED             = 0;
+  const uint32_t SUSPENDED_PAUSE            = 1;
+  const uint32_t SUSPENDED_BLOCK            = 2;
+  const uint32_t SUSPENDED_PAUSE_DISPOSABLE = 3;
+  const uint32_t SUSPENDED_STOP_DISPOSABLE  = 4;
+};
+
+%{C++
+namespace mozilla {
+namespace dom {
+// It's defined in dom/audiochannel/AudioChannelService.h.
+class AudioPlaybackConfig;
+}
+}
+%}
+[ptr] native AudioPlaybackConfig(mozilla::dom::AudioPlaybackConfig);
+
+[uuid(15c05894-408e-4798-b527-a8c32d9c5f8c)]
+interface nsIAudioChannelAgentCallback : nsISupports
+{
+  /**
+   * Notified when the window volume/mute is changed
+   */
+  void windowVolumeChanged(in float aVolume, in bool aMuted);
+
+   /**
+   * Notified when the window needs to be suspended or resumed.
+   */
+  void windowSuspendChanged(in uint32_t aSuspend);
+
+  /**
+   * Notified when the capture state is changed.
+   */
+  void windowAudioCaptureChanged(in bool aCapture);
+};
+
+/**
+ * This interface provides an agent for gecko components to participate
+ * in the audio channel service. Gecko components are responsible for
+ *   1. Indicating what channel type they are using (via the init() member
+ *      function).
+ *   2. Notifying the agent when they start/stop using this channel.
+ *   3. Notifying the agent when they are audible.
+ *
+ * The agent will invoke a callback to notify Gecko components of
+ *   1. Changes to the playable status of this channel.
+ */
+
+[uuid(ab7e21c0-970c-11e5-a837-0800200c9a66)]
+interface nsIAudioChannelAgent : nsISupports
+{
+  const long AUDIO_AGENT_CHANNEL_NORMAL             = 0;
+  const long AUDIO_AGENT_CHANNEL_CONTENT            = 1;
+  const long AUDIO_AGENT_CHANNEL_NOTIFICATION       = 2;
+  const long AUDIO_AGENT_CHANNEL_ALARM              = 3;
+  const long AUDIO_AGENT_CHANNEL_TELEPHONY          = 4;
+  const long AUDIO_AGENT_CHANNEL_RINGER             = 5;
+  const long AUDIO_AGENT_CHANNEL_PUBLICNOTIFICATION = 6;
+  const long AUDIO_AGENT_CHANNEL_SYSTEM             = 7;
+
+  const long AUDIO_AGENT_CHANNEL_ERROR              = 1000;
+
+  const long AUDIO_AGENT_STATE_NORMAL               = 0;
+  const long AUDIO_AGENT_STATE_MUTED                = 1;
+  const long AUDIO_AGENT_STATE_FADED                = 2;
+
+  /**
+   * Before init() is called, this returns AUDIO_AGENT_CHANNEL_ERROR.
+   */
+  readonly attribute long audioChannelType;
+
+  %{C++
+  inline int32_t AudioChannelType() {
+    int32_t channel;
+    return NS_SUCCEEDED(GetAudioChannelType(&channel)) ? channel : AUDIO_AGENT_CHANNEL_ERROR;
+  }
+  %}
+
+  /**
+   * Initialize the agent with a channel type.
+   * Note: This function should only be called once.
+   *
+   * @param window
+   *    The window
+   * @param channelType
+   *    Audio Channel Type listed as above
+   * @param callback
+   *    1. Once the playable status changes, agent uses this callback function
+   *       to notify Gecko component.
+   *    2. The callback is allowed to be null. Ex: telephony doesn't need to
+   *       listen change of the playable status.
+   *    3. The AudioChannelAgent keeps a strong reference to the callback
+   *       object.
+   */
+  void init(in mozIDOMWindow window, in long channelType,
+            in nsIAudioChannelAgentCallback callback);
+
+  /**
+   * This method is just like init(), except the audio channel agent keeps a
+   * weak reference to the callback object.
+   *
+   * In order for this to work, |callback| must implement
+   * nsISupportsWeakReference.
+   */
+  void initWithWeakCallback(in mozIDOMWindow window, in long channelType,
+                            in nsIAudioChannelAgentCallback callback);
+
+  /**
+   * Notify the agent that we want to start playing.
+   * Note: Gecko component SHOULD call this function first then start to
+   *          play audio stream only when return value is true.
+   *
+   * @param config
+   *    It contains the playback related states (volume/mute/suspend)
+   */
+  void notifyStartedPlaying(in AudioPlaybackConfig config, in uint8_t audible);
+
+  /**
+   * Notify the agent we no longer want to play.
+   *
+   * Note : even if notifyStartedPlaying() returned false, the agent would
+   * still be registered with the audio channel service and receive callbacks
+   * for status changes. So notifyStoppedPlaying must still eventually be
+   * called to unregister the agent with the channel service.
+   */
+  void notifyStoppedPlaying();
+
+
+  /**
+   * Notify agent that we already start producing audible data.
+   *
+   * Note : sometime audio might become silent during playing, this method is used to
+   * notify the actually audible state to other services which want to know
+   * about that, ex. tab sound indicator.
+   */
+  void notifyStartedAudible(in uint8_t audible, in uint32_t reason);
+};