Bug 815069 - Part 1: nsIAudioChannelAgent.idl r=roc, a=blocking-basecamp

[Audio ] mechanism for Gecko components without media element to join audio competing policy.

dom/audiochannel/nsIAudioChannelAgent.idl

@@ -0,0 +1,98 @@
+/* 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"
+
+[scriptable, uuid(35dddb4c-3d35-11e2-978c-10bf48d64bd4)]
+interface nsIAudioChannelAgentCallback : nsISupports
+{
+  /**
+   * Notified when the playable status of channel is changed.
+   *
+   * @param canPlay
+   *        Callback from agent to notify component of the playable status
+   *        of the channel. If canPlay is false, component SHOULD stop playing
+   *        media associated with this channel as soon as possible.
+   */
+  void canPlayChanged(in boolean canPlay);
+};
+
+/**
+ * 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. Before playing, checking the playable status of the channel.
+ *   3. Notifying the agent when they start/stop using this channel.
+ *   4. Notifying the agent of changes to the visibility of the component using
+ *       this channel.
+ *
+ * The agent will invoke a callback to notify Gecko components of
+ *   1. Changes to the playable status of this channel.
+ */
+
+[scriptable, uuid(4d01d4f0-3d16-11e2-a0db-10bf48d64bd4)]
+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_ERROR              = 1000;
+
+  /**
+   * Before init() is called, this returns AUDIO_AGENT_CHANNEL_ERROR.
+   */
+  readonly attribute long audioChannelType;
+
+  /**
+   * Initialize the agent with a channel type.
+   * Note: This function should only be called once.
+   *
+   * @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.
+   */
+  void init(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.
+   *
+   *
+   * @return
+   *    true: the agent has registered with audio channel service and the
+   *          component should start playback.
+   *    false: the agent has registered with audio channel service but the
+   *          component should not start playback.
+   */
+  boolean startPlaying();
+
+  /**
+   * Notify the agent we no longer want to play.
+   *
+   * Note : even if startPlaying() returned false, the agent would still be
+   *        registered with the audio channel service and receive callbacks for status changes.
+   *        So stopPlaying must still eventually be called to unregister the agent with the
+   *        channel service.
+   */
+  void stopPlaying();
+
+  /**
+   * Notify the agent of the visibility state of the window using this agent.
+   * @param visible
+   *    True if the window associated with the agent is visible.
+   */
+  void setVisibilityState(in boolean visible);
+
+};
+