|
1 |
|
2 // MmfGlblAudioEffect.h |
|
3 |
|
4 // Copyright (c) 2005-2009 Nokia Corporation and/or its subsidiary(-ies). |
|
5 // All rights reserved. |
|
6 // This component and the accompanying materials are made available |
|
7 // under the terms of "Eclipse Public License v1.0" |
|
8 // which accompanies this distribution, and is available |
|
9 // at the URL "http://www.eclipse.org/legal/epl-v10.html". |
|
10 // |
|
11 // Initial Contributors: |
|
12 // Nokia Corporation - initial contribution. |
|
13 // |
|
14 // Contributors: |
|
15 // |
|
16 // Description: |
|
17 // |
|
18 |
|
19 #ifndef MMFGLBLAUDIOEFFECT_H |
|
20 #define MMFGLBLAUDIOEFFECT_H |
|
21 |
|
22 #include <e32std.h> |
|
23 #include <e32base.h> |
|
24 #include <bamdesca.h> |
|
25 #include <mmf/common/mmfbase.hrh> |
|
26 |
|
27 /** |
|
28 @publishedPartner |
|
29 @released |
|
30 @file |
|
31 */ |
|
32 |
|
33 //forward decs |
|
34 class MMmfGlobalAudioImpl; |
|
35 class CMmfGlobalAudioEffect; |
|
36 class MMmfGlobalAudioPresetList; |
|
37 |
|
38 /** |
|
39 Notify changes as requested |
|
40 */ |
|
41 class MMmfGlobalAudioEffectObserver |
|
42 { |
|
43 public: |
|
44 /** |
|
45 Callback that event is occuring, as requested. |
|
46 This pairs with CMmfGlobalAudioEffect::RequestNotificationL() |
|
47 @param aEffect |
|
48 The effect object from where the notification is being signaled |
|
49 @param aEventUid |
|
50 The uid passed to CMmfGlobalAudioEffect::RequestNotificationL() |
|
51 @param aParam |
|
52 Parameter data, exact use will depend on aEventUid |
|
53 @see CMmfGlobalAudioEffect::RequestNotificationL() |
|
54 */ |
|
55 virtual void GAEEventNotificationL(CMmfGlobalAudioEffect* aEffect, TUid aEventUid, const TDesC8& aParam)=0; |
|
56 }; |
|
57 |
|
58 /** |
|
59 EnableChanged event Uid |
|
60 @see CMmfGlobalAudioEffect::RequestNotificationL() |
|
61 */ |
|
62 const TUid KUidMmfGlblAudioEnableChanged = {KUidMmfGlblAudioEnableChangedDefine}; |
|
63 |
|
64 /** |
|
65 ActiveChanged event Uid |
|
66 @see CMmfGlobalAudioEffect::RequestNotificationL() |
|
67 */ |
|
68 const TUid KUidMmfGlblAudioActiveChanged = {KUidMmfGlblAudioActiveChangedDefine}; |
|
69 |
|
70 /** |
|
71 PresetsChanged event Uid |
|
72 @see CMmfGlobalAudioEffect::RequestNotificationL() |
|
73 */ |
|
74 const TUid KUidMmfGlblAudioPresetsChanged = {KUidMmfGlblAudioPresetsChangedDefine}; |
|
75 |
|
76 /** |
|
77 The value associated with the callback has been changed |
|
78 @see CMmfGlobalAudioEffect::RequestNotificationL() |
|
79 */ |
|
80 const TUid KUidMmfGlblAudioValueChanged = {KUidMmfGlblAudioValueChangedDefine}; |
|
81 |
|
82 |
|
83 /** |
|
84 Parent class for global audio effects |
|
85 All global effect class derive from this class. It should be seen as an abstract class providing |
|
86 common facilities, that they all share. Users of these classes should be aware that there could |
|
87 be multiple instances, at any one go - e.g. in separate processes. All instances should use |
|
88 event notification (see RequestNotificationL()) to observe changes in values, in case another |
|
89 instance has changed things. |
|
90 If there is more than one output device on a phone, then the behaviour is system dependent, |
|
91 but typical behaviour would be for the settings etc only to apply to the current device - |
|
92 switching output device would lead to a direct change in the settings reported. |
|
93 */ |
|
94 class CMmfGlobalAudioEffect : public CBase |
|
95 { |
|
96 public: |
|
97 /** |
|
98 Destructor. |
|
99 */ |
|
100 IMPORT_C ~CMmfGlobalAudioEffect(); |
|
101 |
|
102 /** |
|
103 Flags denoting capability of specific global effect. |
|
104 These flags allow the client app to equire about the capabilities of the given effect. |
|
105 It should be noted that these refer to the specific implementation, and not |
|
106 necessarily the effect class |
|
107 */ |
|
108 enum TCapabilityFlags |
|
109 { |
|
110 ECapabilitySupportsInvidividualValues =0x0001, //*< Supports ExtractValuesL() and SetByValuesL() |
|
111 ECapabilitySupportsSettingByUid =0x0002, //*< Supports current setting to be requested by Uid |
|
112 ECapabilitySupportsSetSettingByUid =0x0004, //*< Supports current value to be changed by Uid |
|
113 ECapabilitySupportsSettingByDes =0x0008, //*< Supports current setting to be required by Descriptor |
|
114 ECapabilitySupportsSetSettingByDes =0x0010, //*< Supports current value to be changed by Descriptor |
|
115 ECapabilitySupportsActiveChangedCallback=0x0020, //*< Supports KUidMmfGlblAudioActiveChanged callbacks |
|
116 ECapabilitySupportsEnableChangedCallback=0x0040, //*< Supports KUidMmfGlblAudioEnableChanged callbacks |
|
117 ECapabilitySupportsPresetChangedCallback=0x0080, //*< Supports KUidMmfGlblAudioPresetsChanged callbacks |
|
118 }; |
|
119 |
|
120 /** |
|
121 Indication of how to interpret volume settings. |
|
122 */ |
|
123 enum TVolumeValue |
|
124 { |
|
125 EVolValueAbsolute, //*< Interpret volume and similar values as some form of absolute scale |
|
126 EVolValuedB //*< Interpret volume and similar values as dB |
|
127 }; |
|
128 |
|
129 /** |
|
130 Request capabilities of this object. |
|
131 Return the capabilities of the particular GlobalAudioEffect. If aCurrentOnly is false, then |
|
132 it will return all the possible features of the implementation, whereas if it is true only |
|
133 the features available at that moment are indicated. For example, an implementation may |
|
134 support returning the value by UID, but if it was set by UID. In such a circumstance, the |
|
135 bit will always be true if aCurrentOnly is false, but if aCurrentOnly is true and the |
|
136 value had been (say) set by descriptor, then that bit will be false. |
|
137 @param aCurrentOnly |
|
138 If true, capabilities are for current situation only - see text |
|
139 @return Capability settings, as given in TCapabilityFlags |
|
140 */ |
|
141 IMPORT_C TUint Capability(TBool aCurrentOnly); |
|
142 |
|
143 /** |
|
144 Request to be told about particular events occuring |
|
145 This is a generic facility for providing callbacks as particular events occur. All callbacks |
|
146 are sent to the Observer that was passed on object creation, invoking GAEEventNotificationL(). |
|
147 The following Uids are defined: |
|
148 |
|
149 KUidMmfGlblAudioEnableChanged - Indicates the value of IsEnabled() has changed. |
|
150 KUidMmfGlblAudioActiveChanged - Indicates the value of IsActive() has changed. |
|
151 KUidMmfGlblAudioPresetsChanged - Indicates the list of known presets etc has been modified. |
|
152 KUidMmfGlblAudioValueChanged - Indicates the settings have been changed |
|
153 |
|
154 With all these settings, the value of aParam returned to GAEEventNotificationL() will be empty. |
|
155 |
|
156 @param aEventUid |
|
157 Uid specifying event for which notification is requested |
|
158 |
|
159 @leave KErrNotSupported |
|
160 If Observer passed during construction was NULL. |
|
161 The Uid is not recognised. |
|
162 The feature is simply not supported in this implementation. |
|
163 @see MMmfGlobalAudioEffectObserver::GAEEventNotificationL() |
|
164 */ |
|
165 IMPORT_C void RequestNotificationL(TUid aEventUid); |
|
166 |
|
167 /** |
|
168 The particular effect is enabled |
|
169 @return True if SetEnabledL(ETrue), or similar, has been called on this effect |
|
170 @see SetEnabledL() |
|
171 */ |
|
172 IMPORT_C TBool IsEnabled() const; |
|
173 |
|
174 /** |
|
175 The particular effect is active |
|
176 Active is defined as being that the effect is in use - that is audio data is being played |
|
177 through it |
|
178 @return True if the effect is in use |
|
179 */ |
|
180 IMPORT_C TBool IsActive() const; |
|
181 |
|
182 /** |
|
183 Enable (or disable) this effect |
|
184 If not enabled, the Effect will not change the data being passed through. However, the |
|
185 values associated with the effect. Where audio data is being played, the effect will |
|
186 take place immediately. |
|
187 @param aValue |
|
188 If true, enables this specific effect. If false, disables it. |
|
189 */ |
|
190 IMPORT_C void SetEnabledL(TBool aValue); |
|
191 |
|
192 /** |
|
193 Obtain uid-based current settings |
|
194 If the value was set using SetSettingsByUidL() then this returns that setting. Note: can use |
|
195 Capability(ETrue) to avoid unnecessarily leave. |
|
196 @return The Uid used by SetSettingsByUidL() |
|
197 @leave KErrNotSupported |
|
198 The settings cannot be expressed as a Uid (usually means SetSettingsByUidL() was not the last |
|
199 thing to change them). |
|
200 */ |
|
201 IMPORT_C TUid SettingsByUidL() const; |
|
202 |
|
203 /** |
|
204 Change settings by passing Uid |
|
205 Change the settings using a uid, that represents a preset. The uid could be known, but |
|
206 should preferably be obtained by using RequestPresets() |
|
207 @param aPresetUid |
|
208 Uid representing the preset in question |
|
209 @leave KErrNotSupported |
|
210 This implementation does not support presets for this effect |
|
211 @leave KErrUnknown |
|
212 The value of aUid does not correspond to a known preset |
|
213 @see RequestPresets() |
|
214 */ |
|
215 IMPORT_C void SetSettingsByUidL(TUid aPresetUid); |
|
216 |
|
217 /** |
|
218 Obtain current settings by descriptor |
|
219 Return an HBufC8* representing the current settings. The format of this descriptor |
|
220 is not specified, but in any given implementation it must be usable by SetSettingsByDesL(). |
|
221 Ownership of the descriptor is passed back to the calling code. |
|
222 @return HBufC8 containing current settings |
|
223 @leave KErrNotSupported |
|
224 This implementation does not support expressing settings in descriptor form |
|
225 @see SetSettingsByDesL() |
|
226 */ |
|
227 IMPORT_C HBufC8* SettingsByDesL() const; |
|
228 |
|
229 /** |
|
230 Change settings by descriptor |
|
231 Update the current settings from values stored in a descriptor. The value in the |
|
232 descriptor will typically have been created using SettingsByDesL(). |
|
233 @param aParam |
|
234 Descriptor value to use |
|
235 @leave KErrNotSupported |
|
236 This implementation does not support expressing settings in descriptor form |
|
237 @leave KErrCorrupt |
|
238 Value in descriptor does not correspond to known format |
|
239 */ |
|
240 IMPORT_C void SetSettingsByDesL(const TDesC8& aParam); |
|
241 |
|
242 /** |
|
243 Return info about known presets by Uid |
|
244 This is used in connection with SetSettingsByUidL(). It allows the user to select a preset by |
|
245 name but this to be fed back as a Uid. It should also allow a Uid to be translated back to |
|
246 a name, if required. Ownership of the list itself remains within the effect implementation. |
|
247 The list may be changed on each call to KnownPresetsL() - users should be careful about |
|
248 caching the returned pointer. |
|
249 @return List of known preset names and uids |
|
250 @see SetSettingsByUidL() |
|
251 @leave KErrNotSupported |
|
252 This feature may not be supported in some circumstances |
|
253 */ |
|
254 IMPORT_C MMmfGlobalAudioPresetList* KnownPresetsL(); |
|
255 |
|
256 /** |
|
257 Extract the settings into a struct |
|
258 This extracts the current settings, and other data such as min/max values supported. |
|
259 This is intended to support direct selecting of values via graphical controls. |
|
260 Unlike SettingsByDesL(), the parameter is expected to be a package buffer wrapping a |
|
261 known class/struct, which will be defined by the particular derivation of this class. |
|
262 @param aPackageBuf |
|
263 This should be a package buffer wrapping the appropriate class/struct, and will be |
|
264 specific to a particular CMmfGlobalAudioEffect derivitive. |
|
265 @leave KErrNotSupported |
|
266 This will only be supported by some child classes, and even then will not |
|
267 be supported by all implementations. |
|
268 */ |
|
269 IMPORT_C void ExtractValuesL(TDes8& aPackageBuf); |
|
270 |
|
271 /** |
|
272 Sets current settings from appropriate struct. |
|
273 This takes the same struct as used for ExtractValuesL() and changes the current settings. |
|
274 Typically it will be used at the end of a dialog to update the data. |
|
275 @param aPackageBuf |
|
276 This should be a package buffer wrapping the appropriate class/struct, and will be |
|
277 specific to a particular CMmfGlobalAudioEffect derivitive. |
|
278 @leave KErrNotSupported |
|
279 This will only be supported by some child classes, and even then will not |
|
280 be supported by all implementations. |
|
281 @leave KErrArgument |
|
282 Passed package buffer is not the expected size, or individual values are out of range |
|
283 */ |
|
284 IMPORT_C void SetByValuesL(const TDesC8& aPackageBuf); |
|
285 |
|
286 protected: |
|
287 IMPORT_C CMmfGlobalAudioEffect(); |
|
288 |
|
289 /** |
|
290 Should be called in the ConstructL() of any derived type |
|
291 @param aImplementationUid |
|
292 Fixed for a given derived class, it is used to find the correct plugin or similar |
|
293 that implements that class. |
|
294 @param aObserver |
|
295 Observer class. Could be NULL, in which case RequestNotificationL() would not be supported |
|
296 @leave KErrNotSupported |
|
297 Cannot find implementation for given derived class |
|
298 */ |
|
299 IMPORT_C void BaseConstructL(TUid aImplementationUid, MMmfGlobalAudioEffectObserver* aObserver); |
|
300 |
|
301 /** |
|
302 Request extension feature. |
|
303 This is intended to provide additional features, should a particular global effect |
|
304 need it. In typical use, the global effect will make a call to this interface on |
|
305 construction. Repeatedly calling this interface will have no additional effect - |
|
306 if the interface has already been setup internally, then no further activity will |
|
307 take place. |
|
308 @param aInterfaceUid |
|
309 Used to indicate which interface is required. |
|
310 @return Standard error code. KErrNotSupported is used to indicate that the particular |
|
311 plugin is used. |
|
312 */ |
|
313 IMPORT_C TInt CreateCustomInterface(TUid aInterfaceUid); |
|
314 |
|
315 |
|
316 /** |
|
317 Return previously created extension. |
|
318 This returns a custom interface, used to provide additional features for a certain |
|
319 global effect. This should only be used if CreateCustomInterface() has already |
|
320 been called for the same UID value. This means that any construction for that interface |
|
321 has already been called, and thus this call cannot fail. Typically the returned class |
|
322 will be another Mixin.No transfer of ownership is implied. |
|
323 |
|
324 @param aInterfaceUid |
|
325 Used to indicate which interface is required. |
|
326 @return The requested interface, or NULL if not known. |
|
327 @see CreateCustomInterface() |
|
328 */ |
|
329 IMPORT_C TAny* CustomInterface(TUid aInterfaceUid); |
|
330 |
|
331 private: |
|
332 MMmfGlobalAudioImpl* iBaseImplementation; //*< Implementation Object |
|
333 }; |
|
334 |
|
335 |
|
336 /** |
|
337 List of preset names against their Uid |
|
338 Array of preset name and uid pairs. Returned by CMmfGlobalAudioEffect::KnownPresetsL() |
|
339 |
|
340 @see CMmfGlobalAudioEffect::KnownPresetsL() |
|
341 */ |
|
342 class MMmfGlobalAudioPresetList : public MDesCArray |
|
343 { |
|
344 public: |
|
345 /** |
|
346 Return Uid corresponding to the name of the same index - the name being returned by |
|
347 McaPoint() |
|
348 @param aIndex |
|
349 Select element from list |
|
350 @return Uid of that element |
|
351 */ |
|
352 virtual TUid GAPUidPoint(TInt aIndex) const=0; |
|
353 }; |
|
354 |
|
355 |
|
356 |
|
357 #endif // MMFGLBLAUDIOEFFECT_H |