Collapse all Symbian^3 Application Developer Library

CMmfGlobalAudioEffect Class Reference

class CMmfGlobalAudioEffect : public CBase

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.

Inherits from

CMmfGlobalAudioEffect
- CBase

Public Member Functions
	~CMmfGlobalAudioEffect ()
IMPORT_C TUint	Capability ( TBool )
IMPORT_C void	ExtractValuesL ( TDes8 &)
IMPORT_C TBool	IsActive ()
IMPORT_C TBool	IsEnabled ()
IMPORT_C MMmfGlobalAudioPresetList *	KnownPresetsL ()
IMPORT_C void	RequestNotificationL ( TUid )
IMPORT_C void	SetByValuesL (const TDesC8 &)
IMPORT_C void	SetEnabledL ( TBool )
IMPORT_C void	SetSettingsByDesL (const TDesC8 &)
IMPORT_C void	SetSettingsByUidL ( TUid )
IMPORT_C HBufC8 *	SettingsByDesL ()
IMPORT_C TUid	SettingsByUidL ()

Protected Member Functions
	CMmfGlobalAudioEffect ()
IMPORT_C void	BaseConstructL ( TUid , MMmfGlobalAudioEffectObserver *)
IMPORT_C TInt	CreateCustomInterface ( TUid )
IMPORT_C TAny *	CustomInterface ( TUid )

Inherited Functions
	CBase::CBase()
	CBase::Delete(CBase *)
	CBase::Extension_(TUint,TAny &,TAny )
	CBase::operator new(TUint)
	CBase::operator new(TUint,TAny *)
	CBase::operator new(TUint,TLeave)
	CBase::operator new(TUint,TLeave,TUint)
	CBase::operator new(TUint,TUint)
	CBase::~CBase()

Public Member Enumerations
enum	TCapabilityFlags { ECapabilitySupportsInvidividualValues = 0x0001, ECapabilitySupportsSettingByUid = 0x0002, ECapabilitySupportsSetSettingByUid = 0x0004, ECapabilitySupportsSettingByDes = 0x0008, ECapabilitySupportsSetSettingByDes = 0x0010, ECapabilitySupportsActiveChangedCallback = 0x0020, ECapabilitySupportsEnableChangedCallback = 0x0040, ECapabilitySupportsPresetChangedCallback = 0x0080 }
enum	TVolumeValue { EVolValueAbsolute , EVolValuedB }

Private Attributes
MMmfGlobalAudioImpl *	iBaseImplementation

Constructor & Destructor Documentation

CMmfGlobalAudioEffect()

IMPORT_C

CMmfGlobalAudioEffect

(

)

[protected]

~CMmfGlobalAudioEffect()

IMPORT_C

~CMmfGlobalAudioEffect

(

)

Destructor.

Member Functions Documentation

BaseConstructL(TUid, MMmfGlobalAudioEffectObserver *)

IMPORT_C void	BaseConstructL	(	TUid	aImplementationUid,
			MMmfGlobalAudioEffectObserver *	aObserver
		)	[protected]

Should be called in the ConstructL() of any derived type

leave: KErrNotSupported Cannot find implementation for given derived class

Parameters

TUid aImplementationUid	Fixed for a given derived class, it is used to find the correct plugin or similar that implements that class.
MMmfGlobalAudioEffectObserver * aObserver	Observer class. Could be NULL, in which case RequestNotificationL() would not be supported

Capability(TBool)

IMPORT_C TUint

Capability

(

TBool

aCurrentOnly

)

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.

Parameters

TBool aCurrentOnly

If true, capabilities are for current situation only - see text

CreateCustomInterface(TUid)

IMPORT_C TInt

CreateCustomInterface

(

TUid

aInterfaceUid

)

[protected]

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.

Parameters

TUid aInterfaceUid

Used to indicate which interface is required.

CustomInterface(TUid)

IMPORT_C TAny *

CustomInterface

(

TUid

aInterfaceUid

)

[protected]

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.

CreateCustomInterface()

Parameters

TUid aInterfaceUid

Used to indicate which interface is required.

ExtractValuesL(TDes8 &)

IMPORT_C void

ExtractValuesL

(

TDes8 &

aPackageBuf

)

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.

leave: KErrNotSupported This will only be supported by some child classes, and even then will not be supported by all implementations.

Parameters

TDes8 & aPackageBuf

This should be a package buffer wrapping the appropriate class/struct, and will be specific to a particular CMmfGlobalAudioEffect derivitive.

IsActive()

IMPORT_C TBool

IsActive

(

)

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

IsEnabled()

IMPORT_C TBool

IsEnabled

(

)

const

The particular effect is enabled SetEnabledL()

KnownPresetsL()

IMPORT_C MMmfGlobalAudioPresetList *

KnownPresetsL

(

)

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. SetSettingsByUidL()

leave: KErrNotSupported This feature may not be supported in some circumstances

RequestNotificationL(TUid)

IMPORT_C void

RequestNotificationL

(

TUid

aEventUid

)

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.

leave: KErrNotSupported If Observer passed during construction was NULL. The Uid is not recognised. The feature is simply not supported in this implementation.

MMmfGlobalAudioEffectObserver::GAEEventNotificationL()

Parameters

TUid aEventUid

Uid specifying event for which notification is requested

SetByValuesL(const TDesC8 &)

IMPORT_C void

SetByValuesL

(

const TDesC8 &

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.

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

Parameters

const TDesC8 & aPackageBuf

This should be a package buffer wrapping the appropriate class/struct, and will be specific to a particular CMmfGlobalAudioEffect derivitive.

SetEnabledL(TBool)

IMPORT_C void

SetEnabledL

(

TBool

aValue

)

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.

Parameters

TBool aValue

If true, enables this specific effect. If false, disables it.

SetSettingsByDesL(const TDesC8 &)

IMPORT_C void

SetSettingsByDesL

(

const TDesC8 &

aParam

)

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() .

leave: KErrNotSupported This implementation does not support expressing settings in descriptor form

leave: KErrCorrupt Value in descriptor does not correspond to known format

Parameters

const TDesC8 & aParam

Descriptor value to use

SetSettingsByUidL(TUid)

IMPORT_C void

SetSettingsByUidL

(

TUid

aPresetUid

)

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()

leave: KErrNotSupported This implementation does not support presets for this effect

leave: KErrUnknown The value of aUid does not correspond to a known preset

RequestPresets()

Parameters

TUid aPresetUid

Uid representing the preset in question

SettingsByDesL()

IMPORT_C HBufC8 *

SettingsByDesL

(

)

const

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.

leave: KErrNotSupported This implementation does not support expressing settings in descriptor form

SetSettingsByDesL()

SettingsByUidL()

IMPORT_C TUid

SettingsByUidL

(

)

const

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.

leave: KErrNotSupported The settings cannot be expressed as a Uid (usually means SetSettingsByUidL() was not the last thing to change them).

Member Enumerations Documentation

Enum TCapabilityFlags

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

Enumerators

ECapabilitySupportsInvidividualValues = 0x0001
ECapabilitySupportsSettingByUid = 0x0002
ECapabilitySupportsSetSettingByUid = 0x0004
ECapabilitySupportsSettingByDes = 0x0008
ECapabilitySupportsSetSettingByDes = 0x0010
ECapabilitySupportsActiveChangedCallback = 0x0020
ECapabilitySupportsEnableChangedCallback = 0x0040
ECapabilitySupportsPresetChangedCallback = 0x0080

Enum TVolumeValue

Indication of how to interpret volume settings.

Enumerators

EVolValueAbsolute
EVolValuedB

Member Data Documentation

MMmfGlobalAudioImpl * iBaseImplementation

MMmfGlobalAudioImpl *

iBaseImplementation

[private]