The Tor Browser: dom/audiochannel/nsIAudioChannelAgent.idl@a63d609f5ebe (annotated)

dom/audiochannel/nsIAudioChannelAgent.idl@a63d609f5ebe (annotated)

dom/audiochannel/nsIAudioChannelAgent.idl

Thu, 15 Jan 2015 15:55:04 +0100

author: Michael Schloh von Bennewitz <michael@schloh.com>
date: Thu, 15 Jan 2015 15:55:04 +0100
branch: TOR_BUG_9701
changeset 9: a63d609f5ebe
permissions: -rw-r--r--

Back out 97036ab72558 which inappropriately compared turds to third parties.

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

The Tor Browser / annotate

dom/audiochannel/nsIAudioChannelAgent.idl@a63d609f5ebe (annotated)

dom/audiochannel/nsIAudioChannelAgent.idl