1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/mm/mmlibs/mmfw/Effect/inc/mmf/common/MmfGlblAudioEffect.h Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,357 @@
1.4 +
1.5 +// MmfGlblAudioEffect.h
1.6 +
1.7 +// Copyright (c) 2005-2009 Nokia Corporation and/or its subsidiary(-ies).
1.8 +// All rights reserved.
1.9 +// This component and the accompanying materials are made available
1.10 +// under the terms of "Eclipse Public License v1.0"
1.11 +// which accompanies this distribution, and is available
1.12 +// at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.13 +//
1.14 +// Initial Contributors:
1.15 +// Nokia Corporation - initial contribution.
1.16 +//
1.17 +// Contributors:
1.18 +//
1.19 +// Description:
1.20 +//
1.21 +
1.22 +#ifndef MMFGLBLAUDIOEFFECT_H
1.23 +#define MMFGLBLAUDIOEFFECT_H
1.24 +
1.25 +#include <e32std.h>
1.26 +#include <e32base.h>
1.27 +#include <bamdesca.h>
1.28 +#include <mmf/common/mmfbase.hrh>
1.29 +
1.30 +/**
1.31 +@publishedPartner
1.32 +@released
1.33 +@file
1.34 +*/
1.35 +
1.36 +//forward decs
1.37 +class MMmfGlobalAudioImpl;
1.38 +class CMmfGlobalAudioEffect;
1.39 +class MMmfGlobalAudioPresetList;
1.40 +
1.41 +/**
1.42 +Notify changes as requested
1.43 +*/
1.44 +class MMmfGlobalAudioEffectObserver
1.45 + {
1.46 +public:
1.47 + /**
1.48 + Callback that event is occuring, as requested.
1.49 + This pairs with CMmfGlobalAudioEffect::RequestNotificationL()
1.50 + @param aEffect
1.51 + The effect object from where the notification is being signaled
1.52 + @param aEventUid
1.53 + The uid passed to CMmfGlobalAudioEffect::RequestNotificationL()
1.54 + @param aParam
1.55 + Parameter data, exact use will depend on aEventUid
1.56 + @see CMmfGlobalAudioEffect::RequestNotificationL()
1.57 + */
1.58 + virtual void GAEEventNotificationL(CMmfGlobalAudioEffect* aEffect, TUid aEventUid, const TDesC8& aParam)=0;
1.59 + };
1.60 +
1.61 +/**
1.62 +EnableChanged event Uid
1.63 +@see CMmfGlobalAudioEffect::RequestNotificationL()
1.64 +*/
1.65 +const TUid KUidMmfGlblAudioEnableChanged = {KUidMmfGlblAudioEnableChangedDefine};
1.66 +
1.67 +/**
1.68 +ActiveChanged event Uid
1.69 +@see CMmfGlobalAudioEffect::RequestNotificationL()
1.70 +*/
1.71 +const TUid KUidMmfGlblAudioActiveChanged = {KUidMmfGlblAudioActiveChangedDefine};
1.72 +
1.73 +/**
1.74 +PresetsChanged event Uid
1.75 +@see CMmfGlobalAudioEffect::RequestNotificationL()
1.76 +*/
1.77 +const TUid KUidMmfGlblAudioPresetsChanged = {KUidMmfGlblAudioPresetsChangedDefine};
1.78 +
1.79 +/**
1.80 +The value associated with the callback has been changed
1.81 +@see CMmfGlobalAudioEffect::RequestNotificationL()
1.82 +*/
1.83 +const TUid KUidMmfGlblAudioValueChanged = {KUidMmfGlblAudioValueChangedDefine};
1.84 +
1.85 +
1.86 +/**
1.87 +Parent class for global audio effects
1.88 +All global effect class derive from this class. It should be seen as an abstract class providing
1.89 +common facilities, that they all share. Users of these classes should be aware that there could
1.90 +be multiple instances, at any one go - e.g. in separate processes. All instances should use
1.91 +event notification (see RequestNotificationL()) to observe changes in values, in case another
1.92 +instance has changed things.
1.93 +If there is more than one output device on a phone, then the behaviour is system dependent,
1.94 +but typical behaviour would be for the settings etc only to apply to the current device -
1.95 +switching output device would lead to a direct change in the settings reported.
1.96 +*/
1.97 +class CMmfGlobalAudioEffect : public CBase
1.98 + {
1.99 +public:
1.100 + /**
1.101 + Destructor.
1.102 + */
1.103 + IMPORT_C ~CMmfGlobalAudioEffect();
1.104 +
1.105 + /**
1.106 + Flags denoting capability of specific global effect.
1.107 + These flags allow the client app to equire about the capabilities of the given effect.
1.108 + It should be noted that these refer to the specific implementation, and not
1.109 + necessarily the effect class
1.110 + */
1.111 + enum TCapabilityFlags
1.112 + {
1.113 + ECapabilitySupportsInvidividualValues =0x0001, //*< Supports ExtractValuesL() and SetByValuesL()
1.114 + ECapabilitySupportsSettingByUid =0x0002, //*< Supports current setting to be requested by Uid
1.115 + ECapabilitySupportsSetSettingByUid =0x0004, //*< Supports current value to be changed by Uid
1.116 + ECapabilitySupportsSettingByDes =0x0008, //*< Supports current setting to be required by Descriptor
1.117 + ECapabilitySupportsSetSettingByDes =0x0010, //*< Supports current value to be changed by Descriptor
1.118 + ECapabilitySupportsActiveChangedCallback=0x0020, //*< Supports KUidMmfGlblAudioActiveChanged callbacks
1.119 + ECapabilitySupportsEnableChangedCallback=0x0040, //*< Supports KUidMmfGlblAudioEnableChanged callbacks
1.120 + ECapabilitySupportsPresetChangedCallback=0x0080, //*< Supports KUidMmfGlblAudioPresetsChanged callbacks
1.121 + };
1.122 +
1.123 + /**
1.124 + Indication of how to interpret volume settings.
1.125 + */
1.126 + enum TVolumeValue
1.127 + {
1.128 + EVolValueAbsolute, //*< Interpret volume and similar values as some form of absolute scale
1.129 + EVolValuedB //*< Interpret volume and similar values as dB
1.130 + };
1.131 +
1.132 + /**
1.133 + Request capabilities of this object.
1.134 + Return the capabilities of the particular GlobalAudioEffect. If aCurrentOnly is false, then
1.135 + it will return all the possible features of the implementation, whereas if it is true only
1.136 + the features available at that moment are indicated. For example, an implementation may
1.137 + support returning the value by UID, but if it was set by UID. In such a circumstance, the
1.138 + bit will always be true if aCurrentOnly is false, but if aCurrentOnly is true and the
1.139 + value had been (say) set by descriptor, then that bit will be false.
1.140 + @param aCurrentOnly
1.141 + If true, capabilities are for current situation only - see text
1.142 + @return Capability settings, as given in TCapabilityFlags
1.143 + */
1.144 + IMPORT_C TUint Capability(TBool aCurrentOnly);
1.145 +
1.146 + /**
1.147 + Request to be told about particular events occuring
1.148 + This is a generic facility for providing callbacks as particular events occur. All callbacks
1.149 + are sent to the Observer that was passed on object creation, invoking GAEEventNotificationL().
1.150 + The following Uids are defined:
1.151 +
1.152 + KUidMmfGlblAudioEnableChanged - Indicates the value of IsEnabled() has changed.
1.153 + KUidMmfGlblAudioActiveChanged - Indicates the value of IsActive() has changed.
1.154 + KUidMmfGlblAudioPresetsChanged - Indicates the list of known presets etc has been modified.
1.155 + KUidMmfGlblAudioValueChanged - Indicates the settings have been changed
1.156 +
1.157 + With all these settings, the value of aParam returned to GAEEventNotificationL() will be empty.
1.158 +
1.159 + @param aEventUid
1.160 + Uid specifying event for which notification is requested
1.161 +
1.162 + @leave KErrNotSupported
1.163 + If Observer passed during construction was NULL.
1.164 + The Uid is not recognised.
1.165 + The feature is simply not supported in this implementation.
1.166 + @see MMmfGlobalAudioEffectObserver::GAEEventNotificationL()
1.167 + */
1.168 + IMPORT_C void RequestNotificationL(TUid aEventUid);
1.169 +
1.170 + /**
1.171 + The particular effect is enabled
1.172 + @return True if SetEnabledL(ETrue), or similar, has been called on this effect
1.173 + @see SetEnabledL()
1.174 + */
1.175 + IMPORT_C TBool IsEnabled() const;
1.176 +
1.177 + /**
1.178 + The particular effect is active
1.179 + Active is defined as being that the effect is in use - that is audio data is being played
1.180 + through it
1.181 + @return True if the effect is in use
1.182 + */
1.183 + IMPORT_C TBool IsActive() const;
1.184 +
1.185 + /**
1.186 + Enable (or disable) this effect
1.187 + If not enabled, the Effect will not change the data being passed through. However, the
1.188 + values associated with the effect. Where audio data is being played, the effect will
1.189 + take place immediately.
1.190 + @param aValue
1.191 + If true, enables this specific effect. If false, disables it.
1.192 + */
1.193 + IMPORT_C void SetEnabledL(TBool aValue);
1.194 +
1.195 + /**
1.196 + Obtain uid-based current settings
1.197 + If the value was set using SetSettingsByUidL() then this returns that setting. Note: can use
1.198 + Capability(ETrue) to avoid unnecessarily leave.
1.199 + @return The Uid used by SetSettingsByUidL()
1.200 + @leave KErrNotSupported
1.201 + The settings cannot be expressed as a Uid (usually means SetSettingsByUidL() was not the last
1.202 + thing to change them).
1.203 + */
1.204 + IMPORT_C TUid SettingsByUidL() const;
1.205 +
1.206 + /**
1.207 + Change settings by passing Uid
1.208 + Change the settings using a uid, that represents a preset. The uid could be known, but
1.209 + should preferably be obtained by using RequestPresets()
1.210 + @param aPresetUid
1.211 + Uid representing the preset in question
1.212 + @leave KErrNotSupported
1.213 + This implementation does not support presets for this effect
1.214 + @leave KErrUnknown
1.215 + The value of aUid does not correspond to a known preset
1.216 + @see RequestPresets()
1.217 + */
1.218 + IMPORT_C void SetSettingsByUidL(TUid aPresetUid);
1.219 +
1.220 + /**
1.221 + Obtain current settings by descriptor
1.222 + Return an HBufC8* representing the current settings. The format of this descriptor
1.223 + is not specified, but in any given implementation it must be usable by SetSettingsByDesL().
1.224 + Ownership of the descriptor is passed back to the calling code.
1.225 + @return HBufC8 containing current settings
1.226 + @leave KErrNotSupported
1.227 + This implementation does not support expressing settings in descriptor form
1.228 + @see SetSettingsByDesL()
1.229 + */
1.230 + IMPORT_C HBufC8* SettingsByDesL() const;
1.231 +
1.232 + /**
1.233 + Change settings by descriptor
1.234 + Update the current settings from values stored in a descriptor. The value in the
1.235 + descriptor will typically have been created using SettingsByDesL().
1.236 + @param aParam
1.237 + Descriptor value to use
1.238 + @leave KErrNotSupported
1.239 + This implementation does not support expressing settings in descriptor form
1.240 + @leave KErrCorrupt
1.241 + Value in descriptor does not correspond to known format
1.242 + */
1.243 + IMPORT_C void SetSettingsByDesL(const TDesC8& aParam);
1.244 +
1.245 + /**
1.246 + Return info about known presets by Uid
1.247 + This is used in connection with SetSettingsByUidL(). It allows the user to select a preset by
1.248 + name but this to be fed back as a Uid. It should also allow a Uid to be translated back to
1.249 + a name, if required. Ownership of the list itself remains within the effect implementation.
1.250 + The list may be changed on each call to KnownPresetsL() - users should be careful about
1.251 + caching the returned pointer.
1.252 + @return List of known preset names and uids
1.253 + @see SetSettingsByUidL()
1.254 + @leave KErrNotSupported
1.255 + This feature may not be supported in some circumstances
1.256 + */
1.257 + IMPORT_C MMmfGlobalAudioPresetList* KnownPresetsL();
1.258 +
1.259 + /**
1.260 + Extract the settings into a struct
1.261 + This extracts the current settings, and other data such as min/max values supported.
1.262 + This is intended to support direct selecting of values via graphical controls.
1.263 + Unlike SettingsByDesL(), the parameter is expected to be a package buffer wrapping a
1.264 + known class/struct, which will be defined by the particular derivation of this class.
1.265 + @param aPackageBuf
1.266 + This should be a package buffer wrapping the appropriate class/struct, and will be
1.267 + specific to a particular CMmfGlobalAudioEffect derivitive.
1.268 + @leave KErrNotSupported
1.269 + This will only be supported by some child classes, and even then will not
1.270 + be supported by all implementations.
1.271 + */
1.272 + IMPORT_C void ExtractValuesL(TDes8& aPackageBuf);
1.273 +
1.274 + /**
1.275 + Sets current settings from appropriate struct.
1.276 + This takes the same struct as used for ExtractValuesL() and changes the current settings.
1.277 + Typically it will be used at the end of a dialog to update the data.
1.278 + @param aPackageBuf
1.279 + This should be a package buffer wrapping the appropriate class/struct, and will be
1.280 + specific to a particular CMmfGlobalAudioEffect derivitive.
1.281 + @leave KErrNotSupported
1.282 + This will only be supported by some child classes, and even then will not
1.283 + be supported by all implementations.
1.284 + @leave KErrArgument
1.285 + Passed package buffer is not the expected size, or individual values are out of range
1.286 + */
1.287 + IMPORT_C void SetByValuesL(const TDesC8& aPackageBuf);
1.288 +
1.289 +protected:
1.290 + IMPORT_C CMmfGlobalAudioEffect();
1.291 +
1.292 + /**
1.293 + Should be called in the ConstructL() of any derived type
1.294 + @param aImplementationUid
1.295 + Fixed for a given derived class, it is used to find the correct plugin or similar
1.296 + that implements that class.
1.297 + @param aObserver
1.298 + Observer class. Could be NULL, in which case RequestNotificationL() would not be supported
1.299 + @leave KErrNotSupported
1.300 + Cannot find implementation for given derived class
1.301 + */
1.302 + IMPORT_C void BaseConstructL(TUid aImplementationUid, MMmfGlobalAudioEffectObserver* aObserver);
1.303 +
1.304 + /**
1.305 + Request extension feature.
1.306 + This is intended to provide additional features, should a particular global effect
1.307 + need it. In typical use, the global effect will make a call to this interface on
1.308 + construction. Repeatedly calling this interface will have no additional effect -
1.309 + if the interface has already been setup internally, then no further activity will
1.310 + take place.
1.311 + @param aInterfaceUid
1.312 + Used to indicate which interface is required.
1.313 + @return Standard error code. KErrNotSupported is used to indicate that the particular
1.314 + plugin is used.
1.315 + */
1.316 + IMPORT_C TInt CreateCustomInterface(TUid aInterfaceUid);
1.317 +
1.318 +
1.319 + /**
1.320 + Return previously created extension.
1.321 + This returns a custom interface, used to provide additional features for a certain
1.322 + global effect. This should only be used if CreateCustomInterface() has already
1.323 + been called for the same UID value. This means that any construction for that interface
1.324 + has already been called, and thus this call cannot fail. Typically the returned class
1.325 + will be another Mixin.No transfer of ownership is implied.
1.326 +
1.327 + @param aInterfaceUid
1.328 + Used to indicate which interface is required.
1.329 + @return The requested interface, or NULL if not known.
1.330 + @see CreateCustomInterface()
1.331 + */
1.332 + IMPORT_C TAny* CustomInterface(TUid aInterfaceUid);
1.333 +
1.334 +private:
1.335 + MMmfGlobalAudioImpl* iBaseImplementation; //*< Implementation Object
1.336 + };
1.337 +
1.338 +
1.339 +/**
1.340 +List of preset names against their Uid
1.341 +Array of preset name and uid pairs. Returned by CMmfGlobalAudioEffect::KnownPresetsL()
1.342 +
1.343 +@see CMmfGlobalAudioEffect::KnownPresetsL()
1.344 +*/
1.345 +class MMmfGlobalAudioPresetList : public MDesCArray
1.346 + {
1.347 +public:
1.348 + /**
1.349 + Return Uid corresponding to the name of the same index - the name being returned by
1.350 + McaPoint()
1.351 + @param aIndex
1.352 + Select element from list
1.353 + @return Uid of that element
1.354 + */
1.355 + virtual TUid GAPUidPoint(TInt aIndex) const=0;
1.356 + };
1.357 +
1.358 +
1.359 +
1.360 +#endif // MMFGLBLAUDIOEFFECT_H