diff -r c1e808730d6c -r c36d67f77f75 devsound/devsoundpluginsupport/inc/plugin/devsoundplugin.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/devsound/devsoundpluginsupport/inc/plugin/devsoundplugin.h Thu Jun 24 10:37:45 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& 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& aSupportedDataTypes, + const TMMFPrioritySettings& aPrioritySettings) const + */ + virtual void GetSupportedInputDataTypesL(RArray& aSupportedDataTypes, const TMMFPrioritySettings& aPrioritySettings) const=0; + + /** + This must provide an implementation as defined by + CMMFDevSound::GetSupportedOutputDataTypesL(RArray& 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& aSupportedDataTypes, const TMMFPrioritySettings& aPrioritySettings) const + */ + virtual void GetSupportedOutputDataTypesL(RArray& aSupportedDataTypes, const TMMFPrioritySettings& aPrioritySettings) const=0; + + }; + +#endif // DEVSOUNDPLUGIN_H