// Copyright (c) 2002-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 __MMFSTANDARDCUSTOMCOMMANDS_H

#define __MMFSTANDARDCUSTOMCOMMANDS_H

#include <mmf/common/mmfcontroller.h>

#include <mmf/common/mmfvideo.h>

#include <mmf/common/mmcaf.h>

class CMMFVideoFrameMessage;

class CFbsBitmap;

class CDesC8Array;

/**

@publishedAll

@released

*/

const TInt KPlaybackRateNormal = 1;

/**

@publishedAll

@released

Balance value for centre

*/

const TInt KMMFBalanceCenter = 0;

/**

@publishedAll

@released

Balance value for max left

*/

const TInt KMMFBalanceMaxLeft = -100;

/**

@publishedAll

@released

Balance value for max right

*/

const TInt KMMFBalanceMaxRight = 100;

/**

@publishedAll

@released

*/

const TInt KMMFVideoCurrentFrame = -1;

/**

@publishedAll

@released

*/

enum TMMFDSAEvent

	{

	EAbortDSA,

	EResumeDSA

	};

/**

@publishedAll

@released

Interface UID and messages for the Audio Resource Notification API.

*/

const TUid KMMFEventCategoryAudioResourceAvailable = {0x101FD9F2};

/**

@publishedAll

@released

Interface UID and messages for the Audio Play Device API.

*/

const TUid KUidInterfaceMMFAudioPlayDevice = {0x101F76D6};

/**

@publishedAll

@released

Interface UID and messages for the Audio Record Device API.

*/

const TUid KUidInterfaceMMFAudioRecordDevice = {0x101F76D7};

/**

@publishedAll

@released

Interface UID and messages for the Audio Play Controller API.

*/

const TUid KUidInterfaceMMFAudioPlayController = {0x101F76D8};

/**

@publishedAll

@released

Interface UID and messages for the Audio Record Controller API.

*/

const TUid KUidInterfaceMMFAudioRecordController = {0x101F76D9};

/**

@publishedAll

@released

Interface UID and messages for the Audio Controller API.

*/

const TUid KUidInterfaceMMFAudioController = {0x101F76DA};

/**

@publishedAll

@released

*/

const TUid KUidInterfaceMMFVideoController = {0x101F76DB};

/**

@publishedAll

@released

*/

const TUid KUidInterfaceMMFVideoPlayController = {0x101F7B73};

/**

@publishedAll

@released

*/

const TUid KUidInterfaceMMFVideoRecordController = {0x101F7B74};

/**

@publishedAll

@released

*/

const TUid KUidInterfaceMMFVideoDRMExt = {0x101F7C23};

/**

@publishedAll

@released

Interface UID for the custom command that supports setting the initial screen for video on the controller.

*/

const TUid KUidInterfaceMMFVideoSetInitScreen = {0x102825F7};

/**

@publishedAll

@released

*/

const TUid KUidInterfaceMMFVideoPixelAspectRatio = {0x102831EF};

/**

@publishedAll

@released

*/

const TUid KUidInterfaceMMFVideoAudioSamplingRateAndChannelConfig = {0x102831F0};

/**

@publishedAll

@released

Client class to access Audio Play Device functionality.

The class uses the custom command function of the controller plugin, and removes the necessity

for the client to formulate the custom commands.

@since 7.0s

*/

class RMMFAudioPlayDeviceCustomCommands : public RMMFCustomCommandsBase

	{

public:

	/**

	Constructor.

	@param  aController

	        The client side controller object to be used by this custom command interface.

	@since 7.0s

	*/

	IMPORT_C RMMFAudioPlayDeviceCustomCommands(RMMFController& aController);

	/**

	Sets the volume of the sound device.

	@param  aVolume

	        The new volume.

	@return	One of the system-wide error codes.

	@since 7.0s

	*/

	IMPORT_C TInt SetVolume(TInt aVolume) const;

	/**

	Gets the maximum volume supported by the sound device.

	@param  aMaxVolume

	        The maximum volume, filled in by the controller.

	@return One of the system-wide error codes.

	@since  7.0s

	*/

	IMPORT_C TInt GetMaxVolume(TInt& aMaxVolume) const;

	/**

	Gets the current playback volume.

	@param  aVolume

	        On return contains the current playback volume.

	@return One of the system-wide error codes.

	@since  7.0s

	*/

	IMPORT_C TInt GetVolume(TInt& aVolume) const;

	/**

	Sets a volume ramp.

	This will cause the sound device to start playing with zero volume,

	increasing the volume over aRampDuration microseconds.

	The volume ramp can be removed by setting the ramp duration to zero.

	@param  aRampDuration

	        The duration over which the volume is to be increased, in microseconds.

	@return One of the system-wide error codes.

	@since 7.0s

	*/

	IMPORT_C TInt SetVolumeRamp(const TTimeIntervalMicroSeconds& aRampDuration) const;

	/**

	Sets the balance between the left and right stereo audio channels.

	@param  aBalance

	        Use a value between KMMFBalanceMaxLeft and KMMFBalanceMaxRight. Centre balance can be

	        restored by using KMMFBalanceCenter.

	@return	One of the system-wide error codes.

	@since 7.0s

	*/

	IMPORT_C TInt SetBalance(TInt aBalance) const;

	/**

	Gets the balance between the left and right stereo audio channels.

	@param  aBalance

	        The current balance, filled in by the controller.

	@return One of the system-wide error codes.

	@since 7.0s

	*/

	IMPORT_C TInt GetBalance(TInt& aBalance) const;

	};

/**

@publishedAll

@released

Mixin class to be derived from controller plugins that could support the audio play device

custom commands.

*/

class MMMFAudioPlayDeviceCustomCommandImplementor

	{

public:

	/**

	Sets the volume of the sound device.

	This function can leave with one of the system-wide error codes. The request will be

	completed with the leave code.

	@param  aVolume

	        The new volume.

	@since 7.0s

	*/

	virtual void MapdSetVolumeL(TInt aVolume) = 0;

	/**

	Gets the maximum volume supported by the sound device.

	This function can leave with one of the system-wide error codes. The request will be

	completed with the leave code.

	@param  aMaxVolume

	        The maximum volume, to be filled in by the controller plugin.

	@since 7.0s

	*/

	virtual void MapdGetMaxVolumeL(TInt& aMaxVolume) = 0;

	/**

	Gets the current playback volume.

	This function can leave with one of the system-wide error codes. The request will be

	completed with the leave code.

	@param  aVolume

	        The volume, to be filled in by the controller.

	@since 7.0s

	*/

	virtual void MapdGetVolumeL(TInt& aVolume) = 0;

	/**

	Sets a volume ramp.

	This will cause the sound device to start playing with zero volume,

	increasing the volume over aRampDuration microseconds.

	The volume ramp can be removed by setting the ramp duration to zero.

	This function can leave with one of the system-wide error codes. The request will be

	completed with the leave code.

	@param  aRampDuration

	        The duration over which the volume is to be increased, in microseconds.

	@since 7.0s

	*/

	virtual void MapdSetVolumeRampL(const TTimeIntervalMicroSeconds& aRampDuration) = 0;

	/**

	Sets the balance between the left and right stereo audio channels.

	This function can leave with one of the system-wide error codes. The request will be

	completed with the leave code.

	@param  aBalance

	        Use a value between KMMFBalanceMaxLeft and KMMFBalanceMaxRight. Centre balance can be

	        restored by using KMMFBalanceCenter.

	@since 7.0s

	*/

	virtual void MapdSetBalanceL(TInt aBalance) = 0;

	/**

	Gets the balance between the left and right stereo audio channels.

	This function can leave with one of the system-wide error codes. The request will be

	completed with the leave code.

	@param  aBalance

	        The current balance, filled in by the controller.

	@since 7.0s

	*/

	virtual void MapdGetBalanceL(TInt& aBalance) = 0;

	};

/**

@publishedAll

@released

Custom command parser class to be used by controller plugins wishing to support

audio play device commands.

The controller plugin must be derived from MMMFAudioPlayDeviceCustomCommandImplementor

to use this class.

The controller plugin should create an object of this type and add it to the list of custom

command parsers in the controller framework. See the following example code for details.

@code

void CMMFAudioController::ConstructL()

	{

	// Construct custom command parsers

	CMMFAudioPlayDeviceCustomCommandParser* audPlayDevParser = CMMFAudioPlayDeviceCustomCommandParser::NewL(*this);

	CleanupStack::PushL(audPlayDevParser);

	AddCustomCommandParserL(*audPlayDevParser); //parser now owned by controller framework

	CleanupStack::Pop();//audPlayDevParser

	CMMFAudioRecordDeviceCustomCommandParser* audRecDevParser = CMMFAudioRecordDeviceCustomCommandParser::NewL(*this);

	CleanupStack::PushL(audRecDevParser);

	AddCustomCommandParserL(*audRecDevParser); //parser now owned by controller framework

	CleanupStack::Pop();//audRecDevParser

etc.

	}

@endcode

@since 7.0s

*/

class CMMFAudioPlayDeviceCustomCommandParser : public CMMFCustomCommandParserBase

	{

public:

	/**

	Creates a new custom command parser capable of handling audio play device commands.

	This function may leave with one of the system-wide error codes.

	@param  aImplementor

	        A reference to the controller plugin that owns this new object.

	@return	A pointer to the object created.

	@since  7.0s

	*/

	IMPORT_C static CMMFAudioPlayDeviceCustomCommandParser* NewL(MMMFAudioPlayDeviceCustomCommandImplementor& aImplementor);

	/**

	Destructor.

	@since  7.0s

	*/

	IMPORT_C ~CMMFAudioPlayDeviceCustomCommandParser();

	/**

	Handles a request from the client. Called by the controller framework.

	@param  aMessage

	        The message to be handled.

	@since  7.0s

	*/

	void HandleRequest(TMMFMessage& aMessage);

private:

	/**

	Constructor.

	@param  aImplementor

	        A reference to the controller plugin that owns this new object.

	@since	7.0s

	*/

	CMMFAudioPlayDeviceCustomCommandParser(MMMFAudioPlayDeviceCustomCommandImplementor& aImplementor);

	// Internal request handling methods.

	void DoHandleRequestL(TMMFMessage& aMessage);

	TBool DoSetVolumeL(TMMFMessage& aMessage);

	TBool DoGetMaxVolumeL(TMMFMessage& aMessage);

	TBool DoGetVolumeL(TMMFMessage& aMessage);

	TBool DoSetVolumeRampL(TMMFMessage& aMessage);

	TBool DoSetBalanceL(TMMFMessage& aMessage);

	TBool DoGetBalanceL(TMMFMessage& aMessage);

private:

	/** The object that implements the audio play device interface */

	MMMFAudioPlayDeviceCustomCommandImplementor& iImplementor;

	};

/**

@publishedAll

@released

Client class to access Audio Record Device functionality.

The class uses the custom command function of the controller plugin, and removes the necessity

for the client to formulate the custom commands.

@since 7.0s

*/

class RMMFAudioRecordDeviceCustomCommands : public RMMFCustomCommandsBase

	{

public:

	/**

	Constructor.

	@param  aController

	        The client side controller object to be used by this custom command interface.

	@since 7.0s

	*/

	IMPORT_C RMMFAudioRecordDeviceCustomCommands(RMMFController& aController);

	/**

	Sets the gain of the sound device.

	@param  aGain

	        The new gain.

	@return One of the system-wide error codes.

	@since 7.0s

	*/

	IMPORT_C TInt SetGain(TInt aGain) const;

	/**

	Gets the maximum gain supported by the sound device.

	@param  aMaxGain

	        The maximum gain, filled in by the controller.

	@return One of the system-wide error codes.

	@since 7.0s

	*/

	IMPORT_C TInt GetMaxGain(TInt& aMaxGain) const;

	/**

	Gets the current recording gain.

	@param  aGain

	        The gain, filled in by the controller.

	@return One of the system-wide error codes.

	@since  7.0s

	*/

	IMPORT_C TInt GetGain(TInt& aGain) const;

	/**

	Sets the balance between the left and right stereo microphone channels.

	@param  aBalance

	        Use a value between KMMFBalanceMaxLeft and KMMFBalanceMaxRight. Centre balance can be 

	        restored by using KMMFBalanceCenter.

	@return One of the system-wide error codes.

	@since 7.0s

	*/

	IMPORT_C TInt SetBalance(TInt aBalance) const;

	/**

	Gets the balance between the left and right stereo microphone channels.

	@param  aBalance

	        The current balance, filled in by the controller.

	@return One of the system-wide error codes.

	@since  7.0s

	*/

	IMPORT_C TInt GetBalance(TInt& aBalance) const;

	};

/**

@publishedAll

@released

Mixin class to be derived from controller plugins that could support the audio record device

custom commands.

*/

class MMMFAudioRecordDeviceCustomCommandImplementor

	{

public:

	/**

	Sets the gain of the sound device.

	This function can leave with one of the system-wide error codes. The request will be

	completed with the leave code.

	@param  aGain

	        The new gain.

	@since 7.0s

	*/

	virtual void MardSetGainL(TInt aGain) = 0;

	/**

	Gets the maximum gain supported by the sound device.

	This function can leave with one of the system-wide error codes. The request will be

	completed with the leave code.

	@param  aMaxGain

	        The maximum gain, to be filled in by the controller plugin.

	@since 7.0s

	*/

	virtual void MardGetMaxGainL(TInt& aMaxGain) = 0;

	/**

	Gets the current recording gain.

	This function can leave with one of the system-wide error codes. The request will be

	completed with the leave code.

	@param  aGain

	        The gain, to be filled in by the controller.

	@since 7.0s

	*/

	virtual void MardGetGainL(TInt& aGain) = 0;

	/**

	Sets the balance between the left and right stereo microphone channels.

	This function can leave with one of the system-wide error codes. The request will be

	completed with the leave code.

	@param  aBalance

	        Use a value between KMMFBalanceMaxLeft and KMMFBalanceMaxRight. Centre balance can be

	        restored by using KMMFBalanceCenter.

	@since 7.0s

	*/

	virtual void MardSetBalanceL(TInt aBalance) = 0;

	/**

	Gets the balance between the left and right stereo microphone channels.

	This function can leave with one of the system-wide error codes. The request will be

	completed with the leave code.

	@param  aBalance

	        The current balance, filled in by the controller.

	@since 7.0s

	*/

	virtual void MardGetBalanceL(TInt& aBalance) = 0;

	};

/**

@publishedAll

@released

Custom command parser class to be used by controller plugins wishing to support

audio record device commands.

The controller plugin must be derived from MMMFAudioRecordDeviceCustomCommandImplementor

to use this class.

The controller plugin should create an object of this type and add it to the list of custom

command parsers in the controller framework.  See the following example code for details.

@code

void CMMFAudioController::ConstructL()

	{

	// Construct custom command parsers

	CMMFAudioPlayDeviceCustomCommandParser* audPlayDevParser = CMMFAudioPlayDeviceCustomCommandParser::NewL(*this);

	CleanupStack::PushL(audPlayDevParser);

	AddCustomCommandParserL(*audPlayDevParser); //parser now owned by controller framework

	CleanupStack::Pop();//audPlayDevParser

	CMMFAudioRecordDeviceCustomCommandParser* audRecDevParser = CMMFAudioRecordDeviceCustomCommandParser::NewL(*this);

	CleanupStack::PushL(audRecDevParser);

	AddCustomCommandParserL(*audRecDevParser); //parser now owned by controller framework

	CleanupStack::Pop();//audRecDevParser

etc.

	}

@endcode

@since 7.0s

*/

class CMMFAudioRecordDeviceCustomCommandParser : public CMMFCustomCommandParserBase

	{

public:

	/**

	Creates a new custom command parser capable of handling audio record device commands.

	This function may leave with one of the system-wide error codes.

	@param  aImplementor

	        A reference to the controller plugin that owns this new object.

	@return A pointer to the object created.

	@since	7.0s

	*/

	IMPORT_C static CMMFAudioRecordDeviceCustomCommandParser* NewL(MMMFAudioRecordDeviceCustomCommandImplementor& aImplementor);

	/**

	Destructor.

	@since  7.0s

	*/

	IMPORT_C ~CMMFAudioRecordDeviceCustomCommandParser();

	/**

	Handles a request from the client. Called by the controller framework.

	@param  aMessage

	        The message to be handled.

	@since	7.0s

	*/

	void HandleRequest(TMMFMessage& aMessage);

private:

	/**

	Constructor.

	@param  aImplementor

	        A reference to the controller plugin that owns this new object.

	@since	7.0s

	*/

	CMMFAudioRecordDeviceCustomCommandParser(MMMFAudioRecordDeviceCustomCommandImplementor& aImplementor);

	// Internal request handling methods.

	void DoHandleRequestL(TMMFMessage& aMessage);

	TBool DoSetGainL(TMMFMessage& aMessage);

	TBool DoGetMaxGainL(TMMFMessage& aMessage);

	TBool DoGetGainL(TMMFMessage& aMessage);

	TBool DoSetBalanceL(TMMFMessage& aMessage);

	TBool DoGetBalanceL(TMMFMessage& aMessage);

private:

	/** The object that implements the audio record device interface */

	MMMFAudioRecordDeviceCustomCommandImplementor& iImplementor;

	};

/**

@publishedAll

@released

Client class to access functionality specific to an audio play controller.

The class uses the custom command function of the controller plugin, and removes the necessity

for the client to formulate the custom commands.

@since 7.0s

*/

class RMMFAudioPlayControllerCustomCommands : public RMMFCustomCommandsBase

	{

public:

	/**

	Constructor.

	@param  aController

	        The client side controller object to be used by this custom command interface.

	@since  7.0s

	*/

	IMPORT_C RMMFAudioPlayControllerCustomCommands(RMMFController& aController);

	/**

	Sets a playback window.  The controller will start playing from the start of the window,

	and finish playing at the end of the window.

	@param  aStart

	        The start of the window, in microseconds.

	@param  aEnd

	        The end of the window, in microseconds.

	@return One of the system-wide error codes.

	@since 7.0s

	*/

	IMPORT_C TInt SetPlaybackWindow(const TTimeIntervalMicroSeconds& aStart, const TTimeIntervalMicroSeconds& aEnd) const;

	/**

	Removes a previously defined playback window.

	@return One of the system-wide error codes.

	@since 7.0s

	*/

	IMPORT_C TInt DeletePlaybackWindow();

	/**

	Gets the audio loading progress as a percentage.

	@param  aPercentageProgress

	        The progress loading the clip, as a percentage.

	@return One of the system-wide error codes.

	@since 7.0s

	*/

	IMPORT_C TInt GetLoadingProgress(TInt& aPercentageProgress) const;

	};

/**

@publishedAll

@released

Mixin class to be derived from controller plugins that could support the audio play controller

custom commands.

*/

class MMMFAudioPlayControllerCustomCommandImplementor

	{

public:

	/**

	Sets a playback window. The controller will start playing from the start of the window,

	and finish playing at the end of the window.

	This function can leave with one of the system-wide error codes. The request will be

	completed with the leave code.

	@param  aStart

	        The start of the window, in microseconds.

	@param  aEnd

	        The end of the window, in microseconds.

	@since 7.0s

	*/

	virtual void MapcSetPlaybackWindowL(const TTimeIntervalMicroSeconds& aStart, const TTimeIntervalMicroSeconds& aEnd) = 0;

	/**

	Removes a previously defined playback window.

	This function can leave with one of the system-wide error codes. The request will be

	completed with the leave code.

	@since 7.0s

	*/

	virtual void MapcDeletePlaybackWindowL() = 0;

	/**

	Gets the completion status of loading/rebuffering the current audio clip.

	This function can leave with one of the system-wide error codes. The request will be

	completed with the leave code.

	@param  aPercentageComplete

	        The status of loading as a percentage completed.

	@since 7.0s

	*/

	virtual void MapcGetLoadingProgressL(TInt& aPercentageComplete) = 0;

	};

/**

@publishedAll

@released

Custom command parser class to be used by controller plugins wishing to support

audio play controller commands.

The controller plugin must be derived from MMMFAudioPlayControllerCustomCommandImplementor to use 

this class.

The controller plugin should create an object of this type and add it to the list of custom

command parsers in the controller framework. See the following example code for details.

@code

void CMMFAudioController::ConstructL()

	{

	// Construct custom command parsers

	CMMFAudioPlayDeviceCustomCommandParser* audPlayDevParser = CMMFAudioPlayDeviceCustomCommandParser::NewL(*this);

	CleanupStack::PushL(audPlayDevParser);

	AddCustomCommandParserL(*audPlayDevParser); //parser now owned by controller framework

	CleanupStack::Pop();//audPlayDevParser

	CMMFAudioRecordDeviceCustomCommandParser* audRecDevParser = CMMFAudioRecordDeviceCustomCommandParser::NewL(*this);

	CleanupStack::PushL(audRecDevParser);

	AddCustomCommandParserL(*audRecDevParser); //parser now owned by controller framework

	CleanupStack::Pop();//audRecDevParser

etc.

	}

@endcode

@since  7.0s

*/

class CMMFAudioPlayControllerCustomCommandParser : public CMMFCustomCommandParserBase

	{

public:

	/**

	Creates a new custom command parser capable of handling audio play controller commands.

	@param  aImplementor

	        A reference to the controller plugin that owns this new object.

	@return A pointer to the object created.

	@since	7.0s

	*/

	IMPORT_C static CMMFAudioPlayControllerCustomCommandParser* NewL(MMMFAudioPlayControllerCustomCommandImplementor& aImplementor);

	/**

	Destructor.

	@since 7.0s

	*/

	IMPORT_C ~CMMFAudioPlayControllerCustomCommandParser();

	/**

	Handles a request from the client. Called by the controller framework.

	@param  aMessage

	        The message to be handled.

	@since  7.0s

	*/

	void HandleRequest(TMMFMessage& aMessage);

private:

	/**

	Constructor.

	@param  aImplementor

	        A reference to the controller plugin that owns this new object.

	@since	7.0s

	*/

	CMMFAudioPlayControllerCustomCommandParser(MMMFAudioPlayControllerCustomCommandImplementor& aImplementor);

	// Internal request handling methods.

	void DoHandleRequestL(TMMFMessage& aMessage);

	TBool DoSetPlaybackWindowL(TMMFMessage& aMessage);

	TBool DoDeletePlaybackWindowL(TMMFMessage& aMessage);

	TBool DoGetLoadingProgressL(TMMFMessage& aMessage);

private:

	/** 

	The object that implements the audio play controller interface 

	*/

	MMMFAudioPlayControllerCustomCommandImplementor& iImplementor;

	};

/**

@publishedAll

@released

Client class to access functionality specific to an audio record controller.

The class uses the custom command function of the controller plugin, and removes the necessity

for the client to formulate the custom commands.

@since  7.0s

*/

class RMMFAudioRecordControllerCustomCommands : public RMMFCustomCommandsBase

	{

public:

	/**

	Constructor.

	@param  aController

	        The client side controller object to be used by this custom command	interface.

	@since  7.0s

	*/

	IMPORT_C RMMFAudioRecordControllerCustomCommands(RMMFController& aController);

	/**

	Gets the (possibly estimated) record time left in the clip.

	@param  aTime

	        The record time available, in microseconds.

	@return One of the system-wide error codes.

	@since 7.0s

	*/

	IMPORT_C TInt GetRecordTimeAvailable(TTimeIntervalMicroSeconds& aTime) const;

	/**

	Sets the maximum duration of the recorded clip, in microseconds.

	@param  aMaxDuration

	        The maximum duration of the recorded clip, in microseconds.

	@return One of the system-wide error codes.

	@since 7.0s

	*/

	IMPORT_C TInt SetMaxDuration(const TTimeIntervalMicroSeconds& aMaxDuration) const;

	/**

	Sets the maximum size of the recorded clip, in bytes.

	@param  aMaxSize

	        The maximum size of the recorded clip, in bytes.

	@return One of the system-wide error codes.

	@since 7.0s

	*/

	IMPORT_C TInt SetMaxFileSize(TInt aMaxSize) const;

	/**

	Removes a portion from the clip, either from the current position to the beginning or the 

	current position to the end.

	@param  aToEnd

	        A boolean indicating whether to crop to the end. Crops to the end if set to ETrue, to 

			the beginning set to EFalse.

	@return One of the system-wide error codes.

	@since  7.0s

	*/

	IMPORT_C TInt Crop(TBool aToEnd);

	/**

	Adds meta data to the clip.