1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/dom/audiochannel/nsIAudioChannelAgent.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,142 @@
1.4 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.5 + * License, v. 2.0. If a copy of the MPL was not distributed with this file,
1.6 + * You can obtain one at http://mozilla.org/MPL/2.0/. */
1.7 +
1.8 +#include "nsISupports.idl"
1.9 +
1.10 +interface nsIDOMWindow;
1.11 +
1.12 +[uuid(194b55d9-39c0-45c6-b8ef-b8049f978ea5)]
1.13 +interface nsIAudioChannelAgentCallback : nsISupports
1.14 +{
1.15 + /**
1.16 + * Notified when the playable status of channel is changed.
1.17 + *
1.18 + * @param canPlay
1.19 + * Callback from agent to notify component of the playable status
1.20 + * of the channel. If canPlay is muted state, component SHOULD stop
1.21 + * playing media associated with this channel as soon as possible. if
1.22 + * it is faded state then the volume of media should be reduced.
1.23 + */
1.24 + void canPlayChanged(in long canPlay);
1.25 +
1.26 + /**
1.27 + * Notified when the window volume/mute is changed
1.28 + */
1.29 + void windowVolumeChanged();
1.30 +};
1.31 +
1.32 +/**
1.33 + * This interface provides an agent for gecko components to participate
1.34 + * in the audio channel service. Gecko components are responsible for
1.35 + * 1. Indicating what channel type they are using (via the init() member
1.36 + * function).
1.37 + * 2. Before playing, checking the playable status of the channel.
1.38 + * 3. Notifying the agent when they start/stop using this channel.
1.39 + * 4. Notifying the agent of changes to the visibility of the component using
1.40 + * this channel.
1.41 + *
1.42 + * The agent will invoke a callback to notify Gecko components of
1.43 + * 1. Changes to the playable status of this channel.
1.44 + */
1.45 +
1.46 +[uuid(2b0222a5-8f7b-49d2-9ab8-cd01b744b23e)]
1.47 +interface nsIAudioChannelAgent : nsISupports
1.48 +{
1.49 + const long AUDIO_AGENT_CHANNEL_NORMAL = 0;
1.50 + const long AUDIO_AGENT_CHANNEL_CONTENT = 1;
1.51 + const long AUDIO_AGENT_CHANNEL_NOTIFICATION = 2;
1.52 + const long AUDIO_AGENT_CHANNEL_ALARM = 3;
1.53 + const long AUDIO_AGENT_CHANNEL_TELEPHONY = 4;
1.54 + const long AUDIO_AGENT_CHANNEL_RINGER = 5;
1.55 + const long AUDIO_AGENT_CHANNEL_PUBLICNOTIFICATION = 6;
1.56 +
1.57 + const long AUDIO_AGENT_CHANNEL_ERROR = 1000;
1.58 +
1.59 + const long AUDIO_AGENT_STATE_NORMAL = 0;
1.60 + const long AUDIO_AGENT_STATE_MUTED = 1;
1.61 + const long AUDIO_AGENT_STATE_FADED = 2;
1.62 +
1.63 + /**
1.64 + * Before init() is called, this returns AUDIO_AGENT_CHANNEL_ERROR.
1.65 + */
1.66 + readonly attribute long audioChannelType;
1.67 +
1.68 + /**
1.69 + * Initialize the agent with a channel type.
1.70 + * Note: This function should only be called once.
1.71 + *
1.72 + * @param window
1.73 + * The window
1.74 + * @param channelType
1.75 + * Audio Channel Type listed as above
1.76 + * @param callback
1.77 + * 1. Once the playable status changes, agent uses this callback function
1.78 + * to notify Gecko component.
1.79 + * 2. The callback is allowed to be null. Ex: telephony doesn't need to
1.80 + * listen change of the playable status.
1.81 + * 3. The AudioChannelAgent keeps a strong reference to the callback
1.82 + * object.
1.83 + */
1.84 + void init(in nsIDOMWindow window, in long channelType,
1.85 + in nsIAudioChannelAgentCallback callback);
1.86 +
1.87 + /**
1.88 + * This method is just like init(), except the audio channel agent keeps a
1.89 + * weak reference to the callback object.
1.90 + *
1.91 + * In order for this to work, |callback| must implement
1.92 + * nsISupportsWeakReference.
1.93 + */
1.94 + void initWithWeakCallback(in nsIDOMWindow window, in long channelType,
1.95 + in nsIAudioChannelAgentCallback callback);
1.96 +
1.97 + /**
1.98 + * This method is just like init(), and specify the channel is associated
1.99 + * with video.
1.100 + *
1.101 + * @param weak
1.102 + * true if weak reference should be hold.
1.103 + */
1.104 + void initWithVideo(in nsIDOMWindow window, in long channelType,
1.105 + in nsIAudioChannelAgentCallback callback, in boolean weak);
1.106 +
1.107 + /**
1.108 + * Notify the agent that we want to start playing.
1.109 + * Note: Gecko component SHOULD call this function first then start to
1.110 + * play audio stream only when return value is true.
1.111 + *
1.112 + *
1.113 + * @return
1.114 + * normal state: the agent has registered with audio channel service and
1.115 + * the component should start playback.
1.116 + * muted state: the agent has registered with audio channel service but
1.117 + * the component should not start playback.
1.118 + * faded state: the agent has registered with audio channel service the
1.119 + * component should start playback as well as reducing the volume.
1.120 + */
1.121 + long startPlaying();
1.122 +
1.123 + /**
1.124 + * Notify the agent we no longer want to play.
1.125 + *
1.126 + * Note : even if startPlaying() returned false, the agent would still be
1.127 + * registered with the audio channel service and receive callbacks for status changes.
1.128 + * So stopPlaying must still eventually be called to unregister the agent with the
1.129 + * channel service.
1.130 + */
1.131 + void stopPlaying();
1.132 +
1.133 + /**
1.134 + * Notify the agent of the visibility state of the window using this agent.
1.135 + * @param visible
1.136 + * True if the window associated with the agent is visible.
1.137 + */
1.138 + void setVisibilityState(in boolean visible);
1.139 +
1.140 + /**
1.141 + * Retrieve the volume from the window.
1.142 + */
1.143 + readonly attribute float windowVolume;
1.144 +};
1.145 +
