--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/mmlibs/mmfw/Effect/inc/mmf/common/MmfGlblAudioEffect.h Tue Feb 02 01:56:55 2010 +0200
@@ -0,0 +1,357 @@
+
+// MmfGlblAudioEffect.h
+
+// Copyright (c) 2005-2009 Nokia Corporation and/or its subsidiary(-ies).
+// All rights reserved.
+// This component and the accompanying materials are made available
+// under the terms of "Eclipse Public License v1.0"
+// which accompanies this distribution, and is available
+// at the URL "http://www.eclipse.org/legal/epl-v10.html".
+//
+// Initial Contributors:
+// Nokia Corporation - initial contribution.
+//
+// Contributors:
+//
+// Description:
+//
+
+#ifndef MMFGLBLAUDIOEFFECT_H
+#define MMFGLBLAUDIOEFFECT_H
+
+#include <e32std.h>
+#include <e32base.h>
+#include <bamdesca.h>
+#include <mmf/common/mmfbase.hrh>
+
+/**
+@publishedPartner
+@released
+@file
+*/
+
+//forward decs
+class MMmfGlobalAudioImpl;
+class CMmfGlobalAudioEffect;
+class MMmfGlobalAudioPresetList;
+
+/**
+Notify changes as requested
+*/
+class MMmfGlobalAudioEffectObserver
+ {
+public:
+ /**
+ Callback that event is occuring, as requested.
+ This pairs with CMmfGlobalAudioEffect::RequestNotificationL()
+ @param aEffect
+ The effect object from where the notification is being signaled
+ @param aEventUid
+ The uid passed to CMmfGlobalAudioEffect::RequestNotificationL()
+ @param aParam
+ Parameter data, exact use will depend on aEventUid
+ @see CMmfGlobalAudioEffect::RequestNotificationL()
+ */
+ virtual void GAEEventNotificationL(CMmfGlobalAudioEffect* aEffect, TUid aEventUid, const TDesC8& aParam)=0;
+ };
+
+/**
+EnableChanged event Uid
+@see CMmfGlobalAudioEffect::RequestNotificationL()
+*/
+const TUid KUidMmfGlblAudioEnableChanged = {KUidMmfGlblAudioEnableChangedDefine};
+
+/**
+ActiveChanged event Uid
+@see CMmfGlobalAudioEffect::RequestNotificationL()
+*/
+const TUid KUidMmfGlblAudioActiveChanged = {KUidMmfGlblAudioActiveChangedDefine};
+
+/**
+PresetsChanged event Uid
+@see CMmfGlobalAudioEffect::RequestNotificationL()
+*/
+const TUid KUidMmfGlblAudioPresetsChanged = {KUidMmfGlblAudioPresetsChangedDefine};
+
+/**
+The value associated with the callback has been changed
+@see CMmfGlobalAudioEffect::RequestNotificationL()
+*/
+const TUid KUidMmfGlblAudioValueChanged = {KUidMmfGlblAudioValueChangedDefine};
+
+
+/**
+Parent class for global audio effects
+All global effect class derive from this class. It should be seen as an abstract class providing
+common facilities, that they all share. Users of these classes should be aware that there could
+be multiple instances, at any one go - e.g. in separate processes. All instances should use
+event notification (see RequestNotificationL()) to observe changes in values, in case another
+instance has changed things.
+If there is more than one output device on a phone, then the behaviour is system dependent,
+but typical behaviour would be for the settings etc only to apply to the current device -
+switching output device would lead to a direct change in the settings reported.
+*/
+class CMmfGlobalAudioEffect : public CBase
+ {
+public:
+ /**
+ Destructor.
+ */
+ IMPORT_C ~CMmfGlobalAudioEffect();
+
+ /**
+ Flags denoting capability of specific global effect.
+ These flags allow the client app to equire about the capabilities of the given effect.
+ It should be noted that these refer to the specific implementation, and not
+ necessarily the effect class
+ */
+ enum TCapabilityFlags
+ {
+ ECapabilitySupportsInvidividualValues =0x0001, //*< Supports ExtractValuesL() and SetByValuesL()
+ ECapabilitySupportsSettingByUid =0x0002, //*< Supports current setting to be requested by Uid
+ ECapabilitySupportsSetSettingByUid =0x0004, //*< Supports current value to be changed by Uid
+ ECapabilitySupportsSettingByDes =0x0008, //*< Supports current setting to be required by Descriptor
+ ECapabilitySupportsSetSettingByDes =0x0010, //*< Supports current value to be changed by Descriptor
+ ECapabilitySupportsActiveChangedCallback=0x0020, //*< Supports KUidMmfGlblAudioActiveChanged callbacks
+ ECapabilitySupportsEnableChangedCallback=0x0040, //*< Supports KUidMmfGlblAudioEnableChanged callbacks
+ ECapabilitySupportsPresetChangedCallback=0x0080, //*< Supports KUidMmfGlblAudioPresetsChanged callbacks
+ };
+
+ /**
+ Indication of how to interpret volume settings.
+ */
+ enum TVolumeValue
+ {
+ EVolValueAbsolute, //*< Interpret volume and similar values as some form of absolute scale
+ EVolValuedB //*< Interpret volume and similar values as dB
+ };
+
+ /**
+ Request capabilities of this object.
+ Return the capabilities of the particular GlobalAudioEffect. If aCurrentOnly is false, then
+ it will return all the possible features of the implementation, whereas if it is true only
+ the features available at that moment are indicated. For example, an implementation may
+ support returning the value by UID, but if it was set by UID. In such a circumstance, the
+ bit will always be true if aCurrentOnly is false, but if aCurrentOnly is true and the
+ value had been (say) set by descriptor, then that bit will be false.
+ @param aCurrentOnly
+ If true, capabilities are for current situation only - see text
+ @return Capability settings, as given in TCapabilityFlags
+ */
+ IMPORT_C TUint Capability(TBool aCurrentOnly);
+
+ /**
+ Request to be told about particular events occuring
+ This is a generic facility for providing callbacks as particular events occur. All callbacks
+ are sent to the Observer that was passed on object creation, invoking GAEEventNotificationL().
+ The following Uids are defined:
+
+ KUidMmfGlblAudioEnableChanged - Indicates the value of IsEnabled() has changed.
+ KUidMmfGlblAudioActiveChanged - Indicates the value of IsActive() has changed.
+ KUidMmfGlblAudioPresetsChanged - Indicates the list of known presets etc has been modified.
+ KUidMmfGlblAudioValueChanged - Indicates the settings have been changed
+
+ With all these settings, the value of aParam returned to GAEEventNotificationL() will be empty.
+
+ @param aEventUid
+ Uid specifying event for which notification is requested
+
+ @leave KErrNotSupported
+ If Observer passed during construction was NULL.
+ The Uid is not recognised.
+ The feature is simply not supported in this implementation.
+ @see MMmfGlobalAudioEffectObserver::GAEEventNotificationL()
+ */
+ IMPORT_C void RequestNotificationL(TUid aEventUid);
+
+ /**
+ The particular effect is enabled
+ @return True if SetEnabledL(ETrue), or similar, has been called on this effect
+ @see SetEnabledL()
+ */
+ IMPORT_C TBool IsEnabled() const;
+
+ /**
+ The particular effect is active
+ Active is defined as being that the effect is in use - that is audio data is being played
+ through it
+ @return True if the effect is in use
+ */
+ IMPORT_C TBool IsActive() const;
+
+ /**
+ Enable (or disable) this effect
+ If not enabled, the Effect will not change the data being passed through. However, the
+ values associated with the effect. Where audio data is being played, the effect will
+ take place immediately.
+ @param aValue
+ If true, enables this specific effect. If false, disables it.
+ */
+ IMPORT_C void SetEnabledL(TBool aValue);
+
+ /**
+ Obtain uid-based current settings
+ If the value was set using SetSettingsByUidL() then this returns that setting. Note: can use
+ Capability(ETrue) to avoid unnecessarily leave.
+ @return The Uid used by SetSettingsByUidL()
+ @leave KErrNotSupported
+ The settings cannot be expressed as a Uid (usually means SetSettingsByUidL() was not the last
+ thing to change them).
+ */
+ IMPORT_C TUid SettingsByUidL() const;
+
+ /**
+ Change settings by passing Uid
+ Change the settings using a uid, that represents a preset. The uid could be known, but
+ should preferably be obtained by using RequestPresets()
+ @param aPresetUid
+ Uid representing the preset in question
+ @leave KErrNotSupported
+ This implementation does not support presets for this effect
+ @leave KErrUnknown
+ The value of aUid does not correspond to a known preset
+ @see RequestPresets()
+ */
+ IMPORT_C void SetSettingsByUidL(TUid aPresetUid);
+
+ /**
+ Obtain current settings by descriptor
+ Return an HBufC8* representing the current settings. The format of this descriptor
+ is not specified, but in any given implementation it must be usable by SetSettingsByDesL().
+ Ownership of the descriptor is passed back to the calling code.
+ @return HBufC8 containing current settings
+ @leave KErrNotSupported
+ This implementation does not support expressing settings in descriptor form
+ @see SetSettingsByDesL()
+ */
+ IMPORT_C HBufC8* SettingsByDesL() const;
+
+ /**
+ Change settings by descriptor
+ Update the current settings from values stored in a descriptor. The value in the
+ descriptor will typically have been created using SettingsByDesL().
+ @param aParam
+ Descriptor value to use
+ @leave KErrNotSupported
+ This implementation does not support expressing settings in descriptor form
+ @leave KErrCorrupt
+ Value in descriptor does not correspond to known format
+ */
+ IMPORT_C void SetSettingsByDesL(const TDesC8& aParam);
+
+ /**
+ Return info about known presets by Uid
+ This is used in connection with SetSettingsByUidL(). It allows the user to select a preset by
+ name but this to be fed back as a Uid. It should also allow a Uid to be translated back to
+ a name, if required. Ownership of the list itself remains within the effect implementation.
+ The list may be changed on each call to KnownPresetsL() - users should be careful about
+ caching the returned pointer.
+ @return List of known preset names and uids
+ @see SetSettingsByUidL()
+ @leave KErrNotSupported
+ This feature may not be supported in some circumstances
+ */
+ IMPORT_C MMmfGlobalAudioPresetList* KnownPresetsL();
+
+ /**
+ Extract the settings into a struct
+ This extracts the current settings, and other data such as min/max values supported.
+ This is intended to support direct selecting of values via graphical controls.
+ Unlike SettingsByDesL(), the parameter is expected to be a package buffer wrapping a
+ known class/struct, which will be defined by the particular derivation of this class.
+ @param aPackageBuf
+ This should be a package buffer wrapping the appropriate class/struct, and will be
+ specific to a particular CMmfGlobalAudioEffect derivitive.
+ @leave KErrNotSupported
+ This will only be supported by some child classes, and even then will not
+ be supported by all implementations.
+ */
+ IMPORT_C void ExtractValuesL(TDes8& aPackageBuf);
+
+ /**
+ Sets current settings from appropriate struct.
+ This takes the same struct as used for ExtractValuesL() and changes the current settings.
+ Typically it will be used at the end of a dialog to update the data.
+ @param aPackageBuf
+ This should be a package buffer wrapping the appropriate class/struct, and will be
+ specific to a particular CMmfGlobalAudioEffect derivitive.
+ @leave KErrNotSupported
+ This will only be supported by some child classes, and even then will not
+ be supported by all implementations.
+ @leave KErrArgument
+ Passed package buffer is not the expected size, or individual values are out of range
+ */
+ IMPORT_C void SetByValuesL(const TDesC8& aPackageBuf);
+
+protected:
+ IMPORT_C CMmfGlobalAudioEffect();
+
+ /**
+ Should be called in the ConstructL() of any derived type
+ @param aImplementationUid
+ Fixed for a given derived class, it is used to find the correct plugin or similar
+ that implements that class.
+ @param aObserver
+ Observer class. Could be NULL, in which case RequestNotificationL() would not be supported
+ @leave KErrNotSupported
+ Cannot find implementation for given derived class
+ */
+ IMPORT_C void BaseConstructL(TUid aImplementationUid, MMmfGlobalAudioEffectObserver* aObserver);
+
+ /**
+ Request extension feature.
+ This is intended to provide additional features, should a particular global effect
+ need it. In typical use, the global effect will make a call to this interface on
+ construction. Repeatedly calling this interface will have no additional effect -
+ if the interface has already been setup internally, then no further activity will
+ take place.
+ @param aInterfaceUid
+ Used to indicate which interface is required.
+ @return Standard error code. KErrNotSupported is used to indicate that the particular
+ plugin is used.
+ */
+ IMPORT_C TInt CreateCustomInterface(TUid aInterfaceUid);
+
+
+ /**
+ Return previously created extension.
+ This returns a custom interface, used to provide additional features for a certain
+ global effect. This should only be used if CreateCustomInterface() has already
+ been called for the same UID value. This means that any construction for that interface
+ has already been called, and thus this call cannot fail. Typically the returned class
+ will be another Mixin.No transfer of ownership is implied.
+
+ @param aInterfaceUid
+ Used to indicate which interface is required.
+ @return The requested interface, or NULL if not known.
+ @see CreateCustomInterface()
+ */
+ IMPORT_C TAny* CustomInterface(TUid aInterfaceUid);
+
+private:
+ MMmfGlobalAudioImpl* iBaseImplementation; //*< Implementation Object
+ };
+
+
+/**
+List of preset names against their Uid
+Array of preset name and uid pairs. Returned by CMmfGlobalAudioEffect::KnownPresetsL()
+
+@see CMmfGlobalAudioEffect::KnownPresetsL()
+*/
+class MMmfGlobalAudioPresetList : public MDesCArray
+ {
+public:
+ /**
+ Return Uid corresponding to the name of the same index - the name being returned by
+ McaPoint()
+ @param aIndex
+ Select element from list
+ @return Uid of that element
+ */
+ virtual TUid GAPUidPoint(TInt aIndex) const=0;
+ };
+
+
+
+#endif // MMFGLBLAUDIOEFFECT_H