--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/devsound/devsoundpluginsupport/inc/plugin/devsoundplugin.h Fri Oct 08 19:40:43 2010 +0100
@@ -0,0 +1,527 @@
+
+// Copyright (c) 2001-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:
+//
+
+/**
+ @file
+ @publishedPartner
+ @released
+*/
+
+#ifndef DEVSOUNDPLUGIN_H
+#define DEVSOUNDPLUGIN_H
+
+_LIT8(KDevSoundPluginMatchString, "*"); // ECom insists on something
+
+/**
+Interface class used in the plugin implementation of DevSound.
+The CMMFDevSound implementation loads a plugin based on this interface class.
+Once this has been constructed, calls to method functions of CMMFDevSound are passed
+verbatim to this interface. For further description of required functionality,
+see CMMFDevSound.
+
+@see CMMFDevSound
+*/
+
+class MMMFDevSoundPlugin
+ {
+public:
+ /**
+ This must provide an implementation as defined by CMMFDevSound::~CMMFDevSound()
+
+ @see CMMFDevSound::~CMMFDevSound()
+ */
+ virtual ~MMMFDevSoundPlugin() {}
+
+ /**
+ This must provide an implementation as defined by
+ CMMFDevSound::InitializeL(MDevSoundObserver& aDevSoundObserver, TMMFState aMode)
+
+ @param aDevSoundObserver
+ A reference to DevSound Observer instance.
+ @param aMode
+ The mode for which this object will be used.
+
+ @see CMMFDevSound::InitializeL(MDevSoundObserver& aDevSoundObserver, TMMFState aMode)
+ */
+ virtual void InitializeL(MDevSoundObserver& aDevSoundObserver, TMMFState aMode)=0;
+
+
+ /**
+ This must provide an implementation as defined by
+ CMMFDevSound::InitializeL(MDevSoundObserver& aDevSoundObserver, TUid aHWDev, TMMFState aMode)
+
+ @param aDevSoundObserver
+ A reference to DevSound Observer instance.
+ @param aHWDev
+ The CMMFHwDevice implementation identifier.
+ @param aMode
+ The mode for which this object will be used.
+
+ @see CMMFDevSound::InitializeL(MDevSoundObserver& aDevSoundObserver, TUid aHWDev, TMMFState aMode)
+ */
+ virtual void InitializeL(MDevSoundObserver& aDevSoundObserver, TUid aHWDev, TMMFState aMode)=0;
+
+ /**
+ This must provide an implementation as defined by
+ CMMFDevSound::InitializeL(MDevSoundObserver& aDevSoundObserver, TFourCC aDesiredFourCC, TMMFState aMode)
+
+ @param aDevSoundObserver
+ A reference to DevSound Observer instance.
+ @param aDesiredFourCC
+ The CMMFHwDevice implementation FourCC code.
+ @param aMode
+ The mode for which this object will be used.
+
+ @see CMMFDevSound::InitializeL(MDevSoundObserver& aDevSoundObserver, TFourCC aDesiredFourCC, TMMFState aMode)
+ */
+ virtual void InitializeL(MDevSoundObserver& aDevSoundObserver, TFourCC aDesiredFourCC, TMMFState aMode)=0;
+
+ /**
+ This must provide an implementation as defined by CMMFDevSound::Capabilities()
+
+ @return The device settings.
+
+ @see CMMFDevSound::Capabilities()
+ */
+ virtual TMMFCapabilities Capabilities()=0;
+
+ /**
+ This must provide an implementation as defined by CMMFDevSound::Config()
+
+ @return The device settings.
+
+ @see CMMFDevSound::Config()
+ */
+ virtual TMMFCapabilities Config() const=0;
+
+ /**
+ This must provide an implementation as defined by CMMFDevSound::SetConfigL(const TMMFCapabilities& aCaps)
+
+ @param aCaps The attribute values to which CMMFDevSound object will be configured to.
+
+ @see CMMFDevSound::SetConfigL(const TMMFCapabilities& aCaps)
+ */
+ virtual void SetConfigL(const TMMFCapabilities& aCaps)=0;
+
+ /**
+ This must provide an implementation as defined by CMMFDevSound::MaxVolume()
+
+ @return The maximum volume. This value is platform dependent but is always greater than or equal
+ to one.
+
+ @see CMMFDevSound::MaxVolume()
+ */
+ virtual TInt MaxVolume()=0;
+
+ /**
+ This must provide an implementation as defined by CMMFDevSound::Volume()
+
+ @return The current volume level.
+
+ @see CMMFDevSound::Volume()
+ */
+ virtual TInt Volume()=0;
+
+ /**
+ This must provide an implementation as defined by CMMFDevSound::SetVolume()
+
+ @param aVolume
+ The volume setting. This can be any value from 0 to the value
+ returned by a call to CMMFDevSound::MaxVolume(). If the
+ volume is not within this range, the volume is automatically set to
+ minimum or maximum value based on the value that is being passed.
+ Setting a zero value mutes the sound. Setting the maximum value
+ results in the loudest possible sound.
+
+ @see CMMFDevSound::SetVolume()
+ */
+ virtual void SetVolume(TInt aVolume)=0;
+
+ /**
+ This must provide an implementation as defined by CMMFDevSound::MaxGain()
+
+ @return The maximum gain. This value is platform dependent but is always greater than or equal
+ to one.
+
+ @see CMMFDevSound::MaxGain()
+ */
+ virtual TInt MaxGain()=0;
+
+ /**
+ This must provide an implementation as defined by CMMFDevSound::Gain()
+
+ @return The current gain level.
+
+ @see CMMFDevSound::Gain()
+ */
+ virtual TInt Gain()=0;
+
+ /**
+ This must provide an implementation as defined by CMMFDevSound::SetGain()
+
+ @param aGain
+ The gain setting. This can be any value from zero to the value
+ returned by a call to CMMFDevSound::MaxGain(). If the
+ volume is not within this range, the gain is automatically set to
+ minimum or maximum value based on the value that is being passed.
+ Setting a zero value mutes the sound. Setting the maximum value
+ results in the loudest possible sound.
+ @see CMMFDevSound::SetGain()
+ */
+ virtual void SetGain(TInt aGain)=0;
+
+ /**
+ This must provide an implementation as defined by
+ CMMFDevSound::GetPlayBalanceL(TInt& aLeftPercentage, TInt& aRightPercentage)
+
+ @param aLeftPercentage
+ On return contains the left speaker volume percentage.
+ @param aRightPercentage
+ On return contains the right speaker volume percentage.
+
+ @see CMMFDevSound::GetPlayBalanceL(TInt& aLeftPercentage, TInt& aRightPercentage)
+ */
+ virtual void GetPlayBalanceL(TInt& aLeftPercentage, TInt& aRightPercentage)=0;
+
+ /**
+ This must provide an implementation as defined by
+ CMMFDevSound::SetPlayBalanceL(TInt aLeftPercentage, TInt aRightPercentage)
+
+ @param aLeftPercentage
+ On return contains left speaker volume perecentage. This can be any
+ value from zero to 100. Setting a zero value mutes the sound on left
+ speaker.
+ @param aRightPercentage
+ On return contains right speaker volume perecentage. This can be any
+ value from zero to 100. Setting a zero value mutes the sound on
+ right speaker.
+
+ @see CMMFDevSound::SetPlayBalanceL(TInt aLeftPercentage, TInt aRightPercentage)
+ */
+ virtual void SetPlayBalanceL(TInt aLeftPercentage, TInt aRightPercentage)=0;
+
+ /**
+ This must provide an implementation as defined by
+ CMMFDevSound::GetRecordBalanceL(TInt& aLeftPercentage, TInt& aRightPercentage)
+
+ @param aLeftPercentage
+ On return contains the left microphone gain percentage.
+ @param aRightPercentage
+ On return contains the right microphone gain percentage.
+
+ @see CMMFDevSound::GetRecordBalanceL(TInt& aLeftPercentage, TInt& aRightPercentage)
+ */
+ virtual void GetRecordBalanceL(TInt& aLeftPercentage, TInt& aRightPercentage)=0;
+
+ /**
+ This must provide an implementation as defined by
+ CMMFDevSound::GetRecordBalanceL(TInt aLeftPercentage, TInt aRightPercentage)
+
+ @param aLeftPercentage
+ The left microphone gain precentage. This can be any value from zero to
+ 100. Setting a zero value mutes the gain on left microphone.
+ @param aRightPercentage
+ The right microphone gain precentage. This can be any value from zero to
+ 100. Setting a zero value mutes the gain on right microphone.
+
+ @see CMMFDevSound::GetRecordBalanceL(TInt aLeftPercentage, TInt aRightPercentage)
+ */
+ virtual void SetRecordBalanceL(TInt aLeftPercentage, TInt aRightPercentage)=0;
+
+ /**
+ This must provide an implementation as defined by CMMFDevSound::PlayInitL()
+
+ @see CMMFDevSound::PlayInitL()
+ */
+ virtual void PlayInitL()=0;
+
+ /**
+ This must provide an implementation as defined by CMMFDevSound::RecordInitL()
+
+ @see CMMFDevSound::RecordInitL()
+ */
+ virtual void RecordInitL()=0;
+
+ /**
+ This must provide an implementation as defined by CMMFDevSound::PlayData()
+
+ @see CMMFDevSound::PlayData()
+ */
+ virtual void PlayData()=0;
+
+ /**
+ This must provide an implementation as defined by CMMFDevSound::RecordData()
+
+ @see CMMFDevSound::RecordData()
+ */
+ virtual void RecordData()=0;
+
+ /**
+ This must provide an implementation as defined by CMMFDevSound::Stop()
+
+ @see CMMFDevSound::Stop()
+ */
+ virtual void Stop()=0;
+
+ /**
+ This must provide an implementation as defined by CMMFDevSound::Pause()
+
+ @see CMMFDevSound::Pause()
+ */
+ virtual void Pause()=0;
+
+ /**
+ This must provide an implementation as defined by CMMFDevSound::SamplesRecorded()
+
+ @return The samples recorded.
+
+ @see CMMFDevSound::SamplesRecorded()
+ */
+ virtual TInt SamplesRecorded()=0;
+
+ /**
+ This must provide an implementation as defined by CMMFDevSound::SamplesPlayed()
+
+ @return The samples played.
+
+ @see CMMFDevSound::SamplesPlayed()
+ */
+ virtual TInt SamplesPlayed()=0;
+
+ /**
+ This must provide an implementation as defined by
+ CMMFDevSound::PlayToneL(TInt aFrequency, const TTimeIntervalMicroSeconds& aDuration)
+
+ @param aFrequency
+ The frequency at which the tone will be played.
+ @param aDuration
+ The period over which the tone will be played. A zero value causes
+ the no tone to be played.
+
+ @see CMMFDevSound::PlayToneL(TInt aFrequency, const TTimeIntervalMicroSeconds& aDuration)
+ */
+ virtual void PlayToneL(TInt aFrequency, const TTimeIntervalMicroSeconds& aDuration)=0;
+
+ /**
+ This must provide an implementation as defined by
+ CMMFDevSound::PlayDualToneL(TInt aFrequencyOne, TInt aFrequencyTwo, const TTimeIntervalMicroSeconds& aDuration)
+
+ @param aFrequencyOne
+ The first frequency of dual tone.
+ @param aFrequencyTwo
+ The second frequency of dual tone
+ @param aDuration
+ The period over which the tone will be played. A zero value causes
+ the no tone to be played (Verify this with test app).
+
+ @see CMMFDevSound::PlayDualToneL(TInt aFrequencyOne, TInt aFrequencyTwo, const TTimeIntervalMicroSeconds& aDuration)
+ */
+ virtual void PlayDualToneL(TInt aFrequencyOne, TInt aFrequencyTwo, const TTimeIntervalMicroSeconds& aDuration)=0;
+
+ /**
+ This must provide an implementation as defined by CMMFDevSound::PlayDTMFStringL(const TDesC& aDTMFString)
+
+ @param aDTMFString The DTMF sequence in a descriptor.
+
+ @see CMMFDevSound::PlayDTMFStringL(const TDesC& aDTMFString)
+ */
+ virtual void PlayDTMFStringL(const TDesC& aDTMFString)=0;
+
+ /**
+ This must provide an implementation as defined by CMMFDevSound::PlayToneSequenceL(const TDesC8& aData)
+
+ @param aData The tone sequence in a descriptor.
+
+ @see CMMFDevSound::PlayToneSequenceL(const TDesC8& aData)
+ */
+ virtual void PlayToneSequenceL(const TDesC8& aData)=0;
+
+ /**
+ This must provide an implementation as defined by CMMFDevSound::PlayFixedSequenceL(TInt aSequenceNumber)
+
+ @param aSequenceNumber
+ The index identifying the specific pre-defined tone sequence. Index
+ values are relative to zero.
+ This can be any value from zero to the value returned by a call to
+ FixedSequenceCount() - 1.
+ The function raises a panic if the sequence number is not within this
+ range.
+
+ @see CMMFDevSound::PlayFixedSequenceL(TInt aSequenceNumber)
+ @see FixedSequenceCount()
+ */
+ virtual void PlayFixedSequenceL(TInt aSequenceNumber)=0;
+
+ /**
+ This must provide an implementation as defined by
+ CMMFDevSound::SetToneRepeats(TInt aRepeatCount,
+ const TTimeIntervalMicroSeconds& aRepeatTrailingSilence)
+
+ @param aRepeatCount
+ The number of times the tone, together with the trailing silence,
+ is to be repeated. If this is set to KMdaRepeatForever, then the
+ tone, together with the trailing silence, is repeated indefinitely
+ or until Stop() is called. If this is set to zero, then the tone is
+ not repeated.
+ @param aRepeatTrailingSilence
+ An interval of silence which will be played after each tone.
+ Supported only during tone playing.
+
+ @see CMMFDevSound::SetToneRepeats(TInt aRepeatCount,
+ const TTimeIntervalMicroSeconds& aRepeatTrailingSilence)
+ */
+ virtual void SetToneRepeats(TInt aRepeatCount,
+ const TTimeIntervalMicroSeconds& aRepeatTrailingSilence)=0;
+
+ /**
+ This must provide an implementation as defined by
+ CMMFDevSound::(TTimeIntervalMicroSeconds32& aToneOnLength,
+ TTimeIntervalMicroSeconds32& aToneOffLength,
+ TTimeIntervalMicroSeconds32& aPauseLength)
+
+ @param aToneOnLength
+ The period over which the tone will be played. If this is set to
+ zero, then the tone is not played.
+ @param aToneOffLength
+ The period over which the no tone will be played.
+ @param aPauseLength
+ The period over which the tone playing will be paused.
+
+ @see CMMFDevSound::(TTimeIntervalMicroSeconds32& aToneOnLength,
+ TTimeIntervalMicroSeconds32& aToneOffLength,
+ TTimeIntervalMicroSeconds32& aPauseLength)
+ */
+ virtual void SetDTMFLengths(TTimeIntervalMicroSeconds32& aToneOnLength,
+ TTimeIntervalMicroSeconds32& aToneOffLength,
+ TTimeIntervalMicroSeconds32& aPauseLength)=0;
+
+ /**
+ This must provide an implementation as defined by
+ CMMFDevSound::SetVolumeRamp(const TTimeIntervalMicroSeconds& aRampDuration)
+
+ @param aRampDuration
+ The period over which the volume is to rise. A zero value causes
+ the tone sample to be played at the normal level for the full
+ duration of the playback. A value, which is longer than the duration
+ of the tone sample means that the sample never reaches its normal
+ volume level.
+
+ @see CMMFDevSound::SetVolumeRamp(const TTimeIntervalMicroSeconds& aRampDuration)
+ */
+ virtual void SetVolumeRamp(const TTimeIntervalMicroSeconds& aRampDuration)=0;
+
+ /**
+ This must provide an implementation as defined by
+ CMMFDevSound::SetPrioritySettings(const TMMFPrioritySettings& aPrioritySettings)
+
+ @param aPrioritySettings
+ A class type representing the client's priority, priority preference and state.
+
+ @see CMMFDevSound::SetPrioritySettings(const TMMFPrioritySettings& aPrioritySettings)
+ */
+ virtual void SetPrioritySettings(const TMMFPrioritySettings& aPrioritySettings)=0;
+
+ /**
+ This must provide an implementation as defined by CMMFDevSound::CustomInterface(TUid aInterfaceId)
+
+ @param aInterfaceId
+ The interface UID, defined with the custom interface.
+
+ @return A pointer to the interface implementation, or NULL if the device does not
+ implement the interface requested. The return value must be cast to the
+ correct type by the user.The user should be careful while caching the custom interface pointer,
+ as in some situations the lower level custom interface pointer may become NULL
+
+ @see CMMFDevSound::CustomInterface(TUid aInterfaceId)
+ */
+ virtual TAny* CustomInterface(TUid aInterfaceId)=0;
+
+ /**
+ This must provide an implementation as defined by CMMFDevSound::FixedSequenceCount()
+
+ @return The fixed sequence count. This value is implementation dependent but is always greater
+ than or equal to zero.
+
+ @see CMMFDevSound::FixedSequenceCount()
+ */
+ virtual TInt FixedSequenceCount()=0;
+
+ /**
+ This must provide an implementation as defined by CMMFDevSound::FixedSequenceName(TInt aSequenceNumber)
+
+ @param aSequenceNumber
+ The index identifying the specific pre-defined tone sequence. Index values are relative
+ to zero. This can be any value from zero to the value returned by a call to
+ FixedSequenceCount() - 1.
+ The function raises a panic if sequence number is not within this
+ range.
+
+ @return A reference to a Descriptor containing the fixed sequence name indexed by
+ aSequenceNumber.
+
+ @see CMMFDevSound::FixedSequenceName(TInt aSequenceNumber)
+ @see FixedSequenceCount()
+ */
+ virtual const TDesC& FixedSequenceName(TInt aSequenceNumber)=0;
+
+ /**
+ This must provide an implementation as defined by
+ CMMFDevSound::GetSupportedInputDataTypesL(RArray<TFourCC>& aSupportedDataTypes,
+ const TMMFPrioritySettings& aPrioritySettings) const
+
+ @param aSupportedDataTypes
+ The array of supported data types that will be filled in by this function.
+ The supported data types of the DevSound are in the form of an array
+ of TFourCC codes. Any existing entries in the array will be overwritten on
+ calling this function. If no supported data types are found given the priority
+ settings, then the aSupportedDatatypes array will have zero entries.
+ @param aPrioritySettings
+ The priority settings used to determine the supported datatypes. Note this
+ does not set the priority settings. For input datatypes the iState member
+ of the priority settings would be expected to be either
+ EMMFStatePlaying or EMMFStatePlayingRecording. The priority settings may
+ effect the supported datatypes depending on the audio routing.
+
+ @see CMMFDevSound::GetSupportedInputDataTypesL(RArray<TFourCC>& aSupportedDataTypes,
+ const TMMFPrioritySettings& aPrioritySettings) const
+ */
+ virtual void GetSupportedInputDataTypesL(RArray<TFourCC>& aSupportedDataTypes, const TMMFPrioritySettings& aPrioritySettings) const=0;
+
+ /**
+ This must provide an implementation as defined by
+ CMMFDevSound::GetSupportedOutputDataTypesL(RArray<TFourCC>& aSupportedDataTypes, const TMMFPrioritySettings& aPrioritySettings) const
+
+ @param aSupportedDataTypes
+ The array of supported data types that will be filled in by this function.
+ The supported datatypes of the DevSound are in the form of an array
+ of TFourCC codes.
+ Any existing entries in the array will be overwritten on calling this function.
+ If no supported datatypes are found given the priority settings, then
+ the aSupportedDatatypes array will have zero entries.
+ @param aPrioritySettings
+ The priority settings used to determine the supported data types. Note this
+ does not set the priority settings. For output data types the iState member
+ of the priority settings would expected to be either
+ EMMFStateRecording or EMMFStatePlayingRecording. The priority settings may
+ effect the supported datatypes depending on the audio routing.
+
+ @see CMMFDevSound::GetSupportedOutputDataTypesL(RArray<TFourCC>& aSupportedDataTypes, const TMMFPrioritySettings& aPrioritySettings) const
+ */
+ virtual void GetSupportedOutputDataTypesL(RArray<TFourCC>& aSupportedDataTypes, const TMMFPrioritySettings& aPrioritySettings) const=0;
+
+ };
+
+#endif // DEVSOUNDPLUGIN_H