Source code

Revision control

Other Tools

1
/* This Source Code Form is subject to the terms of the Mozilla Public
2
* License, v. 2.0. If a copy of the MPL was not distributed with this file,
3
* You can obtain one at http://mozilla.org/MPL/2.0/. */
4
5
#include "nsISupports.idl"
6
7
interface mozIDOMWindow;
8
9
typedef uint32_t nsSuspendedTypes;
10
11
[scriptable, builtinclass, uuid(2822a840-f009-11e5-a837-0800200c9a66)]
12
interface nsISuspendedTypes : nsISupports
13
{
14
/**
15
* The suspended enum is used in three different situations,
16
* - platform audio focus (Fennec/B2G)
17
* - remote media control (Fennec)
18
* - block auto-play video in non-active page
19
*
20
* Note: the "remote side" must control the AudioChannelAgent using
21
* nsIAudioChannelAgentCallback.windowSuspendChanged() callback instead using
22
* play/pause methods or any button in the webpage.
23
*
24
* - SUSPENDED_PAUSE :
25
* It's used when transiently losing audio focus, the media can't be resumed
26
* until we gain the audio focus again. It would change the internal state of
27
* MediaElement when it's being suspended/resumed, and it would trigger the
28
* related JS event. eg. "play" and "pause" event.
29
*
30
* - SUSPENDED_BLOCK
31
* It's used to prevent auto-playing media in inactive page in order to
32
* reduce the power consumption, and the media can't be resumed until the
33
* page becomes active again. It would change the internal state of
34
* MediaElement when it's being blocked/resumed, so it won't trigger the
35
* related JS event. eg. "play" and "pause" event.
36
*
37
* - SUSPENDED_PAUSE_DISPOSABLE
38
* It's used for remote media-control to pause the playing media and when we
39
* lose audio focus permanently. It's disposable suspended, so the media can
40
* be resumed arbitrary after that. Same as SUSPENDED_PAUSE, it would change
41
* the internal state of MediaElement when it's being suspended.
42
*
43
* - SUSPENDED_STOP_DISPOSABLE
44
* It's used for remote media-control to stop the playing media. The remote
45
* control would disappear after stopping the media, so we would disconnect
46
* the audio channel agent. It's disposable suspended, so the media can be
47
* resumed arbitrary after that. Same as SUSPENDED_PAUSE, it would change
48
* the internal state of MediaElement when it's being suspended.
49
*/
50
51
const uint32_t NONE_SUSPENDED = 0;
52
const uint32_t SUSPENDED_PAUSE = 1;
53
const uint32_t SUSPENDED_BLOCK = 2;
54
const uint32_t SUSPENDED_PAUSE_DISPOSABLE = 3;
55
const uint32_t SUSPENDED_STOP_DISPOSABLE = 4;
56
};
57
58
[uuid(15c05894-408e-4798-b527-a8c32d9c5f8c)]
59
interface nsIAudioChannelAgentCallback : nsISupports
60
{
61
/**
62
* Notified when the window volume/mute is changed
63
*/
64
void windowVolumeChanged(in float aVolume, in bool aMuted);
65
66
/**
67
* Notified when the window needs to be suspended or resumed.
68
*/
69
void windowSuspendChanged(in uint32_t aSuspend);
70
71
/**
72
* Notified when the capture state is changed.
73
*/
74
void windowAudioCaptureChanged(in bool aCapture);
75
};
76
77
/**
78
* This interface provides an agent for gecko components to participate
79
* in the audio channel service. Gecko components are responsible for
80
* 1. Notifying the agent when they start/stop using this channel.
81
* 2. Notifying the agent when they are audible.
82
*
83
* The agent will invoke a callback to notify Gecko components of
84
* 1. Changes to the playable status of this channel.
85
*/
86
87
[uuid(4d212770-5d7b-446f-9394-632e351d96ee)]
88
interface nsIAudioChannelAgent : nsISupports
89
{
90
const long AUDIO_AGENT_STATE_NORMAL = 0;
91
const long AUDIO_AGENT_STATE_MUTED = 1;
92
const long AUDIO_AGENT_STATE_FADED = 2;
93
94
/**
95
* Initialize the agent with a channel type.
96
* Note: This function should only be called once.
97
*
98
* @param window
99
* The window
100
* @param callback
101
* 1. Once the playable status changes, agent uses this callback function
102
* to notify Gecko component.
103
* 2. The callback is allowed to be null. Ex: telephony doesn't need to
104
* listen change of the playable status.
105
* 3. The AudioChannelAgent keeps a strong reference to the callback
106
* object.
107
*/
108
void init(in mozIDOMWindow window, in nsIAudioChannelAgentCallback callback);
109
110
/**
111
* This method is just like init(), except the audio channel agent keeps a
112
* weak reference to the callback object.
113
*
114
* In order for this to work, |callback| must implement
115
* nsISupportsWeakReference.
116
*/
117
void initWithWeakCallback(in mozIDOMWindow window,
118
in nsIAudioChannelAgentCallback callback);
119
120
/**
121
* Notify the agent that we want to start playing.
122
* Note: Gecko component SHOULD call this function first then start to
123
* play audio stream only when return value is true.
124
*/
125
void notifyStartedPlaying(in uint8_t audible);
126
127
/**
128
* Notify the agent we no longer want to play.
129
*
130
* Note : even if notifyStartedPlaying() returned false, the agent would
131
* still be registered with the audio channel service and receive callbacks
132
* for status changes. So notifyStoppedPlaying must still eventually be
133
* called to unregister the agent with the channel service.
134
*/
135
void notifyStoppedPlaying();
136
137
138
/**
139
* Notify agent that we already start producing audible data.
140
*
141
* Note : sometime audio might become silent during playing, this method is used to
142
* notify the actually audible state to other services which want to know
143
* about that, ex. tab sound indicator.
144
*/
145
void notifyStartedAudible(in uint8_t audible, in uint32_t reason);
146
};