sl@0: // Copyright (c) 2002-2009 Nokia Corporation and/or its subsidiary(-ies).
sl@0: // All rights reserved.
sl@0: // This component and the accompanying materials are made available
sl@0: // under the terms of "Eclipse Public License v1.0"
sl@0: // which accompanies this distribution, and is available
sl@0: // at the URL "http://www.eclipse.org/legal/epl-v10.html".
sl@0: //
sl@0: // Initial Contributors:
sl@0: // Nokia Corporation - initial contribution.
sl@0: //
sl@0: // Contributors:
sl@0: //
sl@0: // Description:
sl@0: //
sl@0: 
sl@0: #ifndef __MDAAUDIOTONEPLAYER_H__
sl@0: #define __MDAAUDIOTONEPLAYER_H__
sl@0: 
sl@0: 
sl@0: #include <e32std.h>
sl@0: #include <mmf/common/mmfbase.h>
sl@0: #include <mmf/common/mmfstandardcustomcommands.h>
sl@0: #include <mmfclntutility.h>
sl@0: 
sl@0: class CMdaServer;
sl@0: 
sl@0: 
sl@0: /**
sl@0: @publishedAll
sl@0: @released
sl@0: 
sl@0: The state of the audio tone utility.
sl@0: */
sl@0: enum TMdaAudioToneUtilityState
sl@0: 	{
sl@0: 	/** The audio tone utility has not been prepared to play a tone.
sl@0: 	*/
sl@0: 	EMdaAudioToneUtilityNotReady=0,
sl@0: 	/** The audio tone utility has been prepared to play a tone and is ready.
sl@0: 	*/
sl@0: 	EMdaAudioToneUtilityPrepared,
sl@0: 	/** The audio tone utility is currently playing a tone.
sl@0: 	*/
sl@0: 	EMdaAudioToneUtilityPlaying,
sl@0: 	/** The audio tone utility is currently paused.
sl@0: 	This state is only reached if underlying DevSound implementations supports resume.
sl@0: 	*/
sl@0: 	EMdaAudioToneUtilityPaused
sl@0: 	};
sl@0: 
sl@0: const TInt KMdaInfiniteDurationDTMFToneOnLength = -1; 
sl@0: const TInt KMdaAudioToneRepeatForever = -2;
sl@0: 
sl@0: /**
sl@0: @publishedAll
sl@0: @released
sl@0: 
sl@0: An interface to a set of audio tone player callback functions.
sl@0: 
sl@0: The class is a mixin and is intended to be inherited by the client
sl@0: class which is observing the audio tone playing operation. The
sl@0: functions encapsulated by this class are called when specific events
sl@0: occur in the process of preparing to play a tone and during the
sl@0: playing of a tone. A reference to this object is passed as a
sl@0: parameter when constructing an audio tone player utility, using the
sl@0: CMdaAudioToneUtility interface.
sl@0: 
sl@0: @since 5.0
sl@0: */
sl@0: class MMdaAudioToneObserver
sl@0: 	{
sl@0: public:
sl@0: 
sl@0: 	/**
sl@0: 	Defines required client behaviour when an attempt to configure the
sl@0: 	audio tone player utility has completed, successfully or otherwise.
sl@0: 
sl@0: 	@param     aError
sl@0: 	           KErrNone if successful. One of the system
sl@0: 	           wide error codes if the attempt failed. The possible
sl@0: 	           values depend on the EPOC platform.
sl@0: 	*/
sl@0: 	virtual void MatoPrepareComplete(TInt aError) = 0;
sl@0: 
sl@0: 	/**
sl@0: 	Defines required client behaviour when the tone playing operation has
sl@0: 	completed, successfully or otherwise.
sl@0: 
sl@0: 	@param     aError
sl@0: 	           KErrNone if successful. One of the system
sl@0: 	           wide error codes if the attempt failed. The possible
sl@0: 	           values depend on the EPOC platform.
sl@0: 	*/
sl@0: 	virtual void MatoPlayComplete(TInt aError) = 0;
sl@0: 	};
sl@0: 
sl@0: 
sl@0: class MMdaAudioTonePlayStartObserver
sl@0: 	{
sl@0: public:
sl@0: 	/**
sl@0: 	Defines required client behaviour when the tone playing operation has
sl@0: 	started, successfully or otherwise.
sl@0: 
sl@0: 	@param     aError
sl@0: 	           KErrNone if successful. One of the system
sl@0: 	           wide error codes if the attempt failed. The possible
sl@0: 	           values depend on the EPOC platform.
sl@0: 	*/
sl@0: 	virtual void MatoPlayStarted(TInt aError) = 0;
sl@0: 	};
sl@0: 
sl@0: 
sl@0: class CMMFMdaAudioToneUtility;
sl@0: 
sl@0: /**
sl@0: @publishedAll
sl@0: @released
sl@0: 
sl@0: Generates tones on an audio capable EPOC device.
sl@0: 
sl@0: The class offers an interface for generating tones on all audio
sl@0: capable EPOC devices.
sl@0: 
sl@0: To use the tone utility:
sl@0: 
sl@0: 1. Create an instance by calling NewL().
sl@0: 
sl@0: 2. Call the appropriate PrepareToPlay variant for the required tone type
sl@0: and wait for the callback indicating success.
sl@0: 
sl@0: 3. Call Play and either wait for the callback to indicate completion,
sl@0: or call CancelPlay to end playback early.
sl@0: 
sl@0: 4. Delete the instance.
sl@0: 
sl@0: It is possible to call Play before calling any PrepareToPlay variant. This
sl@0: will result in a default fixed sequence tone being played.
sl@0: 
sl@0: @since 5.0
sl@0: */
sl@0: class CMdaAudioToneUtility : public CBase,
sl@0: 							 public MMMFClientUtility
sl@0: 	{
sl@0: public:
sl@0: 
sl@0: 	IMPORT_C static CMdaAudioToneUtility* NewL(MMdaAudioToneObserver& aObserver, CMdaServer* aServer = NULL);
sl@0: 
sl@0: 	IMPORT_C static CMdaAudioToneUtility* NewL(MMdaAudioToneObserver& aObserver, CMdaServer* aServer,
sl@0: 											   TInt aPriority, 
sl@0: 											   TInt aPref = EMdaPriorityPreferenceTimeAndQuality);
sl@0: 
sl@0: 	~CMdaAudioToneUtility();
sl@0: 
sl@0: 	virtual TMdaAudioToneUtilityState State();
sl@0: 
sl@0: 	virtual TInt MaxVolume();
sl@0: 
sl@0: 	virtual TInt Volume();
sl@0: 
sl@0: 	virtual void SetVolume(TInt aVolume);
sl@0: 
sl@0: 	virtual void SetPriority(TInt aPriority, TInt aPref);
sl@0: 
sl@0: 	virtual void SetDTMFLengths(TTimeIntervalMicroSeconds32 aToneLength,
sl@0: 								TTimeIntervalMicroSeconds32 aToneOffLength,
sl@0: 								TTimeIntervalMicroSeconds32 aPauseLength);
sl@0: 
sl@0: 	virtual void SetRepeats(TInt aRepeatNumberOfTimes, const TTimeIntervalMicroSeconds& aTrailingSilence);
sl@0: 
sl@0: 	virtual void SetVolumeRamp(const TTimeIntervalMicroSeconds& aRampDuration);
sl@0: 
sl@0: 	virtual TInt FixedSequenceCount();
sl@0: 
sl@0: 	virtual const TDesC& FixedSequenceName(TInt aSequenceNumber);
sl@0: 
sl@0: 	virtual void PrepareToPlayTone(TInt aFrequency, const TTimeIntervalMicroSeconds& aDuration);
sl@0: 
sl@0: 	virtual void PrepareToPlayDTMFString(const TDesC& aDTMF);
sl@0: 
sl@0: 	virtual void PrepareToPlayDesSequence(const TDesC8& aSequence);
sl@0: 
sl@0: 	virtual void PrepareToPlayFileSequence(const TDesC& aFileName);
sl@0: 
sl@0: 	virtual void PrepareToPlayFixedSequence(TInt aSequenceNumber);
sl@0: 
sl@0: 	virtual void CancelPrepare();
sl@0: 
sl@0: 	virtual void Play();
sl@0: 
sl@0: 	virtual void CancelPlay();
sl@0: 
sl@0: 	IMPORT_C TInt Pause();
sl@0: 
sl@0: 	IMPORT_C TInt Resume();
sl@0: 	
sl@0: 	IMPORT_C void SetBalanceL(TInt aBalance=KMMFBalanceCenter);
sl@0: 
sl@0: 	IMPORT_C TInt GetBalanceL();
sl@0: 
sl@0: 	IMPORT_C void PrepareToPlayDualTone(TInt aFrequencyOne, TInt aFrequencyTwo, const TTimeIntervalMicroSeconds& aDuration);
sl@0: 	
sl@0: 	IMPORT_C void PrepareToPlayFileSequence(RFile& aFile);
sl@0: 	
sl@0: 	IMPORT_C TAny* CustomInterface(TUid aInterfaceId);
sl@0: 
sl@0: 	IMPORT_C void RegisterPlayStartCallback(MMdaAudioTonePlayStartObserver& aObserver);
sl@0: 
sl@0: protected:
sl@0: 	/**
sl@0: 	This member is internal and not intended for use.
sl@0: 	*/
sl@0: 	CMMFMdaAudioToneUtility* iProperties;
sl@0: 	};
sl@0: 
sl@0: 
sl@0: #endif