The Tor Browser / file revision

 /* 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 nsIDOMWindow;

 [uuid(194b55d9-39c0-45c6-b8ef-b8049f978ea5)]

 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 muted state, component SHOULD stop

    *        playing media associated with this channel as soon as possible. if

    *        it is faded state then the volume of media should be reduced.

    */

   void canPlayChanged(in long canPlay);

   /**

    * Notified when the window volume/mute is changed

    */

   void windowVolumeChanged();

 };

 /**

  * 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.

  */

 [uuid(2b0222a5-8f7b-49d2-9ab8-cd01b744b23e)]

 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;

   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;

   /**

    * 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 nsIDOMWindow 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 nsIDOMWindow window, in long channelType,

                             in nsIAudioChannelAgentCallback callback);

   /**

    * This method is just like init(), and specify the channel is associated

    * with video.

    *

    * @param weak

    *    true if weak reference should be hold.

    */

   void initWithVideo(in nsIDOMWindow window, in long channelType,

                      in nsIAudioChannelAgentCallback callback, in boolean weak);

   /**

    * 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

    *    normal state: the agent has registered with audio channel service and

    *          the component should start playback.

    *    muted state: the agent has registered with audio channel service but

    *          the component should not start playback.

    *    faded state: the agent has registered with audio channel service the

    *          component should start playback as well as reducing the volume.

    */

   long 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);

   /**

    * Retrieve the volume from the window.

    */

   readonly attribute float windowVolume;

 };