// Copyright (c) 2003-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:

//

/**

 @publishedAll

 @released

 @file

*/

#ifndef __DEVSOUNDSTANDARDCUSTOMINTERFACES_H__

#define __DEVSOUNDSTANDARDCUSTOMINTERFACES_H__

#include <e32std.h>

/**

UID associated with the custom interface MMMFDevSoundCustomInterfaceBitRate.

*/

const TUid KUidCustomInterfaceDevSoundBitRate = {0x101F7DD5};

/**

This class provides an interface to set and retrive the DevSound bit rate.

*/

class MMMFDevSoundCustomInterfaceBitRate

	{	

public:

	/**

	Gets the bit rates that are supported by DevSound in its current configuration.

	@param  aSupportedBitRates

	The supported bit rates, in bits per second, shall be appended to this array. Note that 

	the array shall be reset by this method.

	*/

	virtual void GetSupportedBitRatesL(RArray<TInt>& aSupportedBitRates) = 0;

	/**

	Returns	the current bit rate.

	@return	The current bit rate, in bits per second.

	*/

	virtual TInt BitRateL() = 0;

	/**

	Sets the bit rate to a new value.

	@param  aBitRate

	The new bit rate, in bits per second.

	*/

	virtual void SetBitRateL(TInt aBitRate) = 0;

	};

/*****************************************************************************/

/**

UID associated with the Custom interface MMMFDevSoundCustomInterfaceFileBlockLength.

*/

const TUid KUidCustomInterfaceDevSoundFileBlockLength = {0x10273806};

/**

Custom interface class for setting the file's block length on the hwdevice. 

Note also that this interface is just a simple interface to 

set file's block length. No checking is perfomed on the values sent (hence the

Set methods do not return an error code).

*/

class MMMFDevSoundCustomInterfaceFileBlockLength

	{

public:

	/**

	Sets the file's block length on the hwdevice

	@param aBlockAlign

	       The file's block length 

	*/

	virtual void SetFileBlockLength(TUint aBlockAlign)=0;

	};

/*****************************************************************************/

/**

UID associated with the Custom interface MMMFGsmConfig

*/

const TUid KUidGsmConfig = {0x102825FC};

/**

This class provides an interface to set and retrive the GSM conversion format.

*/

class MMMFGsmConfig

	{

public: 

	/** The GSM conversion format */

	enum TMMFGsmConversionFormat

		{

		/** no conversion specified */

		ENone, 

		/** for use in Full rate (06.10) and half rate (GSM 06.20 Half Rate (HR)) Vocoder */

		EALaw8bit, 

		/** for use in Full rate (06.10) and half rate (GSM 06.20 Half Rate (HR)) Vocoder */

		EULaw8bit,

		/** for use in GSM 06.60 Enhanced Full Rate (EFR) Vocoder.*/

		EAlawPCM

		};

	/**

	Set the conversion format using the TMMFGsmConversionFormat enum.

	This conversion must be set before the coder/decoder is started.

	@param aConvFormat - format desired.  For encoding behaviour, format will 

	be the input format and for decoding behaviour format will be the output 

	format.

	@return KErrNone - Format change supported, KErrNotSupported - Format 

	change not supported, KErrInUse - Format change attempted whilst decoding.

	*/	

	virtual TInt SetConversionFormat(TMMFGsmConversionFormat aConvFormat) = 0;

	/** 

	Provides the current conversion format.  Can be called at any time.

	@param aConvFormat - after the call contains the current format.

	For encoding behaviour, format will be the input format and for decoding

	behaviour format will be the output format.

	@return KErrNone if value returned successfully, 

			KErrUnknown if value has not been successfully configured using

			SetConversionFormat() at least once for the current instance of the

			interface and there is no default value.

			KErrGeneral for all other error scenario.

	*/

	virtual TInt ConversionFormat(TMMFGsmConversionFormat& aConvFormat) const = 0;

	};

/*****************************************************************************/

/**

UID associated with the Custom interface MSpeechEncoderConfig

*/

const TUid KUidSpeechEncoderConfig = {0x102825FB};

/**

This class provides an interface to those CMMFHwDevices providing speech encoding. 

This interface is used for querying and configuring the operational modes of speech 

encoders as supported by those specific encoders. 

If a speech encoder does not support a mode provided by the interface, it will return KErrNotSupported.

*/

class MSpeechEncoderConfig 

	{

public:

	/**

	Controls voice activity detection (VAD) mode.

	This method can be called at all times - while actively encoding or not.

	It should be noted that a VAD mode change could also instigate a change in the 

	mode of encoding (fixed rate encoding versus variable rate) e.g. in cases where 

	VAD requires variable rate encoding.

	The effects of activating VAD mode behaviour should be documented in the 

	CMMFHwDevice specification implementing it.

	@param aVadModeOn ETrue=On, EFalse=Off

	@return KErrNone if successful. KErrNotSupported if this method is not implemented 

	or not supported by the encoder. 

	*/

	virtual TInt SetVadMode(TBool aVadModeOn) = 0;

	/**

	Gets the current state of the voice activity detection (VAD) mode.

	This method can be called at all times - while actively encoding or not.

	@param aVadModeOn On output ETrue = On, EFalse = Off

	@return KErrNone if successful, KErrNotSupported if this method is not implemented 

	or not supported by the encoder. 

	*/

	virtual TInt GetVadMode(TBool& aVadModeOn) = 0;

	};

/*****************************************************************************/

/**

UID associated with the Custom interface MAacDecoderConfig

*/

const TUid KUidAacDecoderConfig = {0x102825FD};

/**

This class provides an interface to the AAC decoder CMMFHwDevice in order 

to provide additional configuration information for decoding raw AAC data blocks. 

The sample rate can be configured via the CMMFHwDevice::SetConfig() method. 

An extension mechanism will be provided for further functionality as required.

The CMMFHwDevice does not contain Output channel configuration at time of writing. 

The HWA decoders to date have been hardcoded for 2ch (left / right) output. 

Additional configuration information may be provided by using extension mechanisms. 

*/

class MAacDecoderConfig 

	{

public: 

	/**

	This is a class containing an enumerated type that defines the audio object types 

	required for configuring the AAC decoder for decoding raw AACDefined within TAudioConfig.

	*/

	class TAudioConfig

		{

	public:

		/**  The audio object type */

	    enum TAudioObjectType

	    	{

			/** Null */

	       	ENull    = 0,

			/** AacMain */

	       	EAacMain = 1,

			/** AacLc */

	       	EAacLc   = 2,

			/** AacSsr */

	       	EAacSsr  = 3,

			/** AacLtp */

	       	EAacLtp  = 4,

			/** Sbr */

	       	ESbr     = 5

	       	};

		TAudioObjectType iAudioObjectType;

		};	

public:

	/**

	Sets additional configuration parameters required for decoding raw AAC. 

	This method can be called when encoding is not active - anytime before the CMMFHwDevice is started. 

	For consistent configuration, this method should be called sometime before each 

	start is called on the CMMFHwDevice when decoding raw AAC. That is to say the 

	CMMFHwDevice is not required to retain prior configuration information, detect raw 

	AAC sent to it, and reconfigure the decoder with this saved information after stop 

	is called on the CMMFHwDevice. However, calling pause on the CMMFHwDevice implies 

	that the next start call will be resuming same content. For this condition, this API 

	is not required when restarting the CMMFHwDevice.

	@param aAudioConfig The structure containing the additional information required for decoding the raw AAC.

	@return KErrNone if successful or KErrInUse if this method is used when decoding is active. 

	*/

	virtual TInt SetAudioConfig(TAudioConfig& aAudioConfig) = 0;

	/**

	Gets additional configuration parameters supported for decoding raw AAC. 

	This method is allowable when encoding is not active - anytime before the CMMFHwDevice is started. 

	@param aSupportedAudioConfigs An array of structures containing the additional supported configurations.

	@return KErrNone if successful. 

			KErrInUse if this method is used when decoding is active. 

	*/

	virtual TInt GetSupportedAudioConfigs(RArray<TAudioConfig>& aSupportedAudioConfigs) = 0;

	};

/*****************************************************************************/

/**

UID associated with the Custom interface MEAacPlusDecoderIntfc

*/

const TUid KUidEAacPlusDecoderIntfc = {0x102825FF};

/**

This class provides an interface to the eAAC+ decoder hwdevice in order to provide configuration information.

The Get.. methods can be used to retrieve the last successfully applied configuration parameters.  

A message is not sent to adaptation or the decoder. Instead, a locally saved set of the 

parameters will be updated upon successful use of ApplyConfig(). It is these saved values that 

the proxy maintains that will be returned to the user. For instance, if two interfaces are used 

and one interface is used to modify the settings, the other interface's Get… methods would not 

return those settings.  The Get.. methods will return an error if a successful use of ApplyConfig() 

has not been performed.

The Set.. methods are used to update a configuration structure within the implementation of the 

interface. When the interface is instantiated, the state of SBR and Downsampled modes will be 

disabled. Therefore it is not necessary to configure these parameters before using 

ApplyConfig() the first time. However, once modified using this instance of the interface, they 

remain in that state until Set.. again.  The values of these items are updated in an internal 

structure when each Set.. is called. 

The ApplyConfig() method is used to configure the encoder with the parameters specified by 

the Set.. methods. ApplyConfig will send back an error (KErrUnknown) if not all items are 

Set at least once. This check and the parameter values returned will be implemented in the interface proxy 

and will not query the actual decoder. The exception to this is for configuration parameters with defined 

default values (see next paragraph). 

Calling ApplyConfig() will send these values using a single message to the message handler.

ApplyConfig() should fail if it is used during decoding with a KErrInUse (or, as previously stated, 

KErrUnknown if a value without a default is not set). Since the interface proxy is not aware of decoding state, 

this check would have to be done in the adaptation implementation for this interface.

*/

class MEAacPlusDecoderIntfc 

	{

public:

	/**

	Defines additional configuration elements required to decode eAAC+.

	*/

	enum TAudioObjectType

        {

        /** Null */

        ENull    = 0,

        /** AacLc */

        EAacLc   = 2,

        /** AacLtp */

        EAacLtp  = 4

        };

	/**

	Sets the value of the sampling frequency of the decoder to be configured by the ApplyConfig() 

	method. This is the sample rate of the core decoder, not the output sampling frequency of the decoder.

	This method can be called at all times but if ApplyConfig() is subsequently called 

	after changing this value whilst decoding, a KErrInUse error will result.

	@param aInputSamplingFrequency  value of the sampling frequency. 

	*/

	virtual void SetInputSamplingFrequency(TUint aInputSamplingFrequency) = 0;

	/**

	Sets the object type of the core decoder to be configured by the ApplyConfig() method.

	This method can be called at all times but if ApplyConfig() is subsequently called after 

	changing this value whilst decoding, a KErrInUse error will result.

	@param  aAudioObjectType TAudioObjectType for core decoder as supported by the decoder.

	*/

	virtual void SetAudioObjectType(TAudioObjectType aAudioObjectType) = 0;

	/**

	Sets the number of channels for the output of the decoder to be configured by the ApplyConfig() 

	method. The use of this method is to ensure coordination of output channels rendered by the decoder 

	and channel configuration of the audio system. This method does not imply that stereo to mono downmix 

	is supported by the decoder. The main purpose is for the case considering the presence of PS. A user 

	may not know if the decoder output will be mono or stereo based on header information alone, but may 

	configure the decoder for two channel output to match the audio system configuration. If the user were 

	to set the output to 1 channel and stereo data is present, the decoder may choose only one channel to 

	output or to downmix the stereo to mono. Regarding this interface, it would be more desirable to configure 

	the decoder when it is known to be mono source data and rely on downmix from the audio system instead of 

	from the decoder. The decoder, however, would provide for duplicating mono data into 2 channel data when 

	configured for 2 channels and the source data contains only 1 channel.

	This method is allowable at all times - while actively encoding or not, but using ApplyConfig() 

	if changing this value while encoding will return an error.

	@param aNumOfChannels 1 - output one channel audio  = 0; 2 - output two channel audio.

	 */

	virtual void SetNumOfChannels(TUint aNumOfChannels) = 0;

	/**

	Controls the SBR mode of the decoder to be configured by the ApplyConfig() method. 

	If SBR is enabled and no SBR data is present, the audio data will be upsampled, 

	unless Down Sampled mode is enabled.

	This method can be called at all times but if ApplyConfig() is subsequently called 

	after changing this value whilst decoding, a KErrInUse error will result.

	@param aSbrEnabled ETrue - SBR mode enabled, EFalse - SBR mode disabled 

	*/

	virtual void SetSbr(TBool aSbrEnabled) = 0;

	/**

	Controls the downsampled mode of the decoder to be configured by the ApplyConfig() method. This setting is only meaningful if SBR is enabled.

	This method can be called at all times but if ApplyConfig() is subsequently called after 

	changing this value whilst decoding, a KErrInUse error will result.

	@param aDsmEnabled ETrue - downsampled mode enabled, EFalse - downsampled mode disabled.

	*/

	virtual void SetDownSampledMode(TBool aDsmEnabled) = 0;

	/**

	Used to configure the decoder with parameters passed in the Set methods.

	This method can be called all times but will return an KErrInUse if the configuration 

	parameters would change while decoding (as none of the set parameters can be changed 

	during decoding). This checking operational state of the decoder would be done by the 

	adaptation implementation of this interface since the interface proxy is not aware of 

	the decoder state. The adaptation implementation will return an error if incorrect values 

	are used to configure the decoder.

	@return KErrNone if successful, KErrNotSupported if this method is not implemented, 

			KErrInUse if encoding in active and values are changed that are not allowed to be 

			changed during encoding, KErrArgument if one of the configuration items is not appropriate or not set. 

	*/

	virtual TInt ApplyConfig() = 0;

	/**

	Returns the value of the sampling frequency of the decoder that was last successfully 

	configured by the ApplyConfig() method.

	This method can be called at all times but must be called after a value has been set via 

	the ApplyConfig

	@param aInputSamplingFrequency last setting successfully applied using ApplyConfig().

	@return KErrNone if value returned successfully, 

			KErrUnknown if value has not been successfully configured using ApplyConfig() at 

			least once for the current instance of the interface or 

			KErrInUse if the encoder is active.

	*/

	virtual TInt GetInputSamplingFrequency(TUint& aInputSamplingFrequency) = 0;

	/**

	Returns the object type of the core decoder that was last successfully configured by the 

	ApplyConfig() method.

	This method can be called at all times. 

	@param aAudioObjectType last setting successfully applied using ApplyConfig().

	@return KErrNone if value returned successfully, 

			KErrUnknown if value has not been successfully configured using ApplyConfig() 

			at least once for the current instance of the interface.

	*/

	virtual TInt GetAudioObjectType(TAudioObjectType& aAudioObjectType) = 0;

	/**

	Returns the number of channels that was last successfully configured by the 

	ApplyConfig() method.

	This method can be called at all times. It will return an error if used before 

	ApplyConfig() has been used successfully.

	@param aNumOfChannels last setting successfully applied using ApplyConfig().	 

	@return KErrNone if value returned successfully, 

			KErrUnknown if value has not been successfully configured using ApplyConfig() 

			at least once for the current instance of the interface.

	*/

	virtual TInt GetNumOfChannels(TUint& aNumOfChannels) = 0;

	/**

	Returns the SBR mode that was last successfully configured by the ApplyConfig() method.

	This method can be called at all times.  It will return an error if used before 

	ApplyConfig() has been used successfully.

	@param aSbrEnabled last setting successfully applied using ApplyConfig().

	@return KErrNone if value returned successfully, 

			KErrUnknown if value has not been successfully configured using ApplyConfig() 

			at least once for the current instance of the interface.	 

	*/

	virtual TInt GetSbr(TBool& aSbrEnabled) = 0;

	/**

	Returns the downsampled mode that was last successfully configured by the ApplyConfig() method.

	This method can be called at all times.  It will return an error if used before 

	ApplyConfig() has been used successfully.

	@param aDsmEnabled last setting successfully applied using ApplyConfig().	 

	@return KErrNone if value returned successfully, 

			KErrUnknown if value has not been successfully configured using ApplyConfig() at least 

			once for the current instance of the interface.

	*/

	virtual TInt GetDownSampledMode(TBool& aDsmEnabled) = 0;

	};

/*****************************************************************************/

/**

UID associated with the Custom interface MSbcEncoderIntfc

*/

const TUid KUidSbcEncoderIntfc = {0x10282600};

/**

This class provides an interface to the SBC encoder hwdevice in order to provide configuration information.

The Get... supported methods can be used to check capabilities of the encoder by retrieving 

the last successfully applied configuration parameters. The purpose of the Get 

functions is to return the last successfully applied configuration of decoder by this 

interface. A message is not sent to adaptation or the decoder. Instead, a locally saved set 

of the parameters will be updated upon successful use of ApplyConfig(). The Get.. methods 

return an error (KErrUnknown ) if a successful use of ApplyConfig() has not been performed 

apart from the following methods, which return the range of properties supported by the 

implementation ( GetSupportedSamplingFrequencies, GetSupportedChannelModes, 

GetSupportedNumOfSubbands, GetSupportedAllocationMethods, GetSupportedNumOfBlocks, 

GetSupportedBitpoolRange).  These methods do not have setter functions as they are not 

configurable and hence will return valid data at all times.

ApplyConfig() will send these values using one message with these values in the internally 

defined structure. The message handler should define this structure in the SBC messages 

header file.   ApplyConfig() should fail (KErrInUse) if it is used during encoding and any 

values are changed other than bitpool value. Since the interface proxy is not aware of 

encoding state, this check would have to be done in the adaptation implementation for 

this interface.  The Bitpool can be updated during encoding to change the bitrate. This would 

require the use of the SetBitpoolSize() and ApplyConfig() methods.  Any other parameters can 

be changed but will result in a KErrInUse when ApplyConfig() is called.

The Set... methods are used update a client-side maintained configuration structure within the 

implementation of the interface.  When the structure is completed, ApplyConfig() should be called 

to send these client side settings to the actual hwdevice implementation.  There are no default 

values for the configuration parameters (hence all values must be set before ApplyConfig() is 

called or an error (KErrArgument) will result).

@note  This constraint is only true for configurations 

where this is supported (e.g. If GetSupportedChannelModes returns KErrNotSupported then SetChannelMode 

does not need to be set before ApplyConfig() is called). This check and the parameter values 

returned will be implemented in the interface proxy and will not query the actual encoder. If 

multiple instances of the interface are created, each would have this requirement.  

*/

class MSbcEncoderIntfc 

	{

public:

	/**

	Defines the channel modes for the SBC encoder

	*/

	enum TSbcChannelMode

        {

        /** SbcChannelMono */

    	ESbcChannelMono,

        /** SbcChannelDual */

		ESbcChannelDual,

        /** SbcChannelStereo */

   	 	ESbcChannelStereo,

        /** SbcChannelJointStereo */

    	ESbcChannelJointStereo

        };