Symaptic: os/mm/devsound/devsoundpluginsupport/inc/plugin/devsoundplugin.h@bde4ae8d615e

     2 // Copyright (c) 2001-2009 Nokia Corporation and/or its subsidiary(-ies).

     3 // All rights reserved.

     4 // This component and the accompanying materials are made available

     5 // under the terms of "Eclipse Public License v1.0"

     6 // which accompanies this distribution, and is available

     7 // at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 //

     9 // Initial Contributors:

    10 // Nokia Corporation - initial contribution.

    11 //

    12 // Contributors:

    13 //

    14 // Description:

    15 //

    17 /**

    18  @file

    19  @publishedPartner

    20  @released

    21 */

    23 #ifndef DEVSOUNDPLUGIN_H

    24 #define DEVSOUNDPLUGIN_H

    26 _LIT8(KDevSoundPluginMatchString, "*"); // ECom insists on something

    28 /**

    29 Interface class used in the plugin implementation of DevSound.

    30 The CMMFDevSound implementation loads a plugin based on this interface class.

    31 Once this has been constructed, calls to method functions of CMMFDevSound are passed

    32 verbatim to this interface. For further description of required functionality,

    33 see CMMFDevSound.

    35 @see CMMFDevSound

    36 */

    38 class MMMFDevSoundPlugin

    39 	{

    40 public:

    41 	/**

    42 	This must provide an implementation as defined by CMMFDevSound::~CMMFDevSound()

    44 	@see CMMFDevSound::~CMMFDevSound()

    45 	*/

    46 	virtual ~MMMFDevSoundPlugin() {}

    48 	/**

    49 	This must provide an implementation as defined by

    50 	CMMFDevSound::InitializeL(MDevSoundObserver& aDevSoundObserver, TMMFState aMode)

    52 	@param  aDevSoundObserver

    53 	        A reference to DevSound Observer instance.

    54 	@param  aMode

    55 	        The mode for which this object will be used.

    57 	@see CMMFDevSound::InitializeL(MDevSoundObserver& aDevSoundObserver, TMMFState aMode)

    58 	*/

    59     virtual void InitializeL(MDevSoundObserver& aDevSoundObserver, TMMFState aMode)=0;

    62 	/**

    63 	This must provide an implementation as defined by

    64 	CMMFDevSound::InitializeL(MDevSoundObserver& aDevSoundObserver, TUid aHWDev, TMMFState aMode)

    66 	@param  aDevSoundObserver

    67 	        A reference to DevSound Observer instance.

    68 	@param  aHWDev

    69 	        The CMMFHwDevice implementation identifier.

    70 	@param  aMode

    71 	        The mode for which this object will be used.

    73 	@see CMMFDevSound::InitializeL(MDevSoundObserver& aDevSoundObserver, TUid aHWDev, TMMFState aMode)

    74 	*/

    75 	virtual void InitializeL(MDevSoundObserver& aDevSoundObserver, TUid aHWDev, TMMFState aMode)=0;

    77 	/**

    78 	This must provide an implementation as defined by

    79 	CMMFDevSound::InitializeL(MDevSoundObserver& aDevSoundObserver, TFourCC aDesiredFourCC, TMMFState aMode)

    81 	@param  aDevSoundObserver

    82 	        A reference to DevSound Observer instance.

    83 	@param  aDesiredFourCC

    84 	        The CMMFHwDevice implementation FourCC code.

    85 	@param  aMode

    86 	        The mode for which this object will be used.

    88 	@see CMMFDevSound::InitializeL(MDevSoundObserver& aDevSoundObserver, TFourCC aDesiredFourCC, TMMFState aMode)

    89 	*/

    90 	virtual void InitializeL(MDevSoundObserver& aDevSoundObserver, TFourCC aDesiredFourCC, TMMFState aMode)=0;

    92 	/**

    93 	This must provide an implementation as defined by CMMFDevSound::Capabilities()

    95 	@return	The device settings.

    97 	@see CMMFDevSound::Capabilities()

    98 	*/

    99 	virtual TMMFCapabilities Capabilities()=0;

   101 	/**

   102 	This must provide an implementation as defined by CMMFDevSound::Config()

   104 	@return	The device settings.

   106 	@see CMMFDevSound::Config()

   107 	*/

   108 	virtual TMMFCapabilities Config() const=0;

   110 	/**

   111 	This must provide an implementation as defined by CMMFDevSound::SetConfigL(const TMMFCapabilities& aCaps)

   113 	@param  aCaps The attribute values to which CMMFDevSound object will be configured to.

   115 	@see CMMFDevSound::SetConfigL(const TMMFCapabilities& aCaps)

   116 	*/

   117 	virtual void SetConfigL(const TMMFCapabilities& aCaps)=0;

   119 	/**

   120 	This must provide an implementation as defined by CMMFDevSound::MaxVolume()

   122 	@return	The maximum volume. This value is platform dependent but is always greater than or equal

   123 	to one.

   125 	@see CMMFDevSound::MaxVolume()

   126 	*/

   127 	virtual TInt MaxVolume()=0;

   129 	/**

   130 	This must provide an implementation as defined by CMMFDevSound::Volume()

   132 	@return The current volume level.

   134 	@see CMMFDevSound::Volume()

   135 	*/

   136 	virtual TInt Volume()=0;

   138 	/**

   139 	This must provide an implementation as defined by CMMFDevSound::SetVolume()

   141 	@param  aVolume

   142 	        The volume setting. This can be any value from 0 to the value

   143 	        returned by a call to CMMFDevSound::MaxVolume(). If the

   144 	        volume is not within this range, the volume is automatically set to

   145 	        minimum or maximum value based on the value that is being passed.

   146 	        Setting a zero value mutes the sound. Setting the maximum value

   147 	        results in the loudest possible sound.

   149 	@see CMMFDevSound::SetVolume()

   150 	*/

   151 	virtual void SetVolume(TInt aVolume)=0;

   153 	/**

   154 	This must provide an implementation as defined by CMMFDevSound::MaxGain()

   156 	@return The maximum gain. This value is platform dependent but is always greater than or equal

   157 	to one.

   159 	@see CMMFDevSound::MaxGain()

   160 	*/

   161 	virtual TInt MaxGain()=0;

   163 	/**

   164 	This must provide an implementation as defined by CMMFDevSound::Gain()

   166 	@return The current gain level.

   168 	@see CMMFDevSound::Gain()

   169 	*/

   170 	virtual TInt Gain()=0;

   172 	/**

   173 	This must provide an implementation as defined by CMMFDevSound::SetGain()

   175 	@param  aGain

   176 		    The gain setting. This can be any value from zero to the value

   177 		    returned by a call to CMMFDevSound::MaxGain(). If the

   178 		    volume is not within this range, the gain is automatically set to

   179 		    minimum or maximum value based on the value that is being passed.

   180 		    Setting a zero value mutes the sound. Setting the maximum value

   181 		    results in the loudest possible sound.

   182 	@see CMMFDevSound::SetGain()

   183 	*/

   184 	virtual void SetGain(TInt aGain)=0;

   186 	/**

   187 	This must provide an implementation as defined by

   188 	CMMFDevSound::GetPlayBalanceL(TInt& aLeftPercentage, TInt& aRightPercentage)

   190 	@param  aLeftPercentage

   191 	        On return contains the left speaker volume percentage.

   192 	@param  aRightPercentage

   193 	        On return contains the right speaker volume percentage.

   195 	@see CMMFDevSound::GetPlayBalanceL(TInt& aLeftPercentage, TInt& aRightPercentage)

   196 	*/

   197 	virtual void GetPlayBalanceL(TInt& aLeftPercentage, TInt& aRightPercentage)=0;

   199 	/**

   200 	This must provide an implementation as defined by

   201 	CMMFDevSound::SetPlayBalanceL(TInt aLeftPercentage, TInt aRightPercentage)

   203 	@param  aLeftPercentage

   204 	        On return contains left speaker volume perecentage. This can be any

   205 	        value from zero to 100. Setting a zero value mutes the sound on left

   206 	        speaker.

   207 	@param  aRightPercentage

   208 	        On return contains right speaker volume perecentage. This can be any

   209 	        value from zero to 100. Setting a zero value mutes the sound on

   210 	        right speaker.

   212 	@see CMMFDevSound::SetPlayBalanceL(TInt aLeftPercentage, TInt aRightPercentage)

   213 	*/

   214 	virtual void SetPlayBalanceL(TInt aLeftPercentage, TInt aRightPercentage)=0;

   216 	/**

   217 	This must provide an implementation as defined by

   218 	CMMFDevSound::GetRecordBalanceL(TInt& aLeftPercentage, TInt& aRightPercentage)

   220 	@param  aLeftPercentage

   221 	        On return contains the left microphone gain percentage.

   222 	@param  aRightPercentage

   223 	        On return contains the right microphone gain percentage.

   225 	@see CMMFDevSound::GetRecordBalanceL(TInt& aLeftPercentage, TInt& aRightPercentage)

   226 	*/

   227 	virtual void GetRecordBalanceL(TInt& aLeftPercentage, TInt& aRightPercentage)=0;

   229 	/**

   230 	This must provide an implementation as defined by

   231 	CMMFDevSound::GetRecordBalanceL(TInt aLeftPercentage, TInt aRightPercentage)

   233 	@param  aLeftPercentage

   234 	        The left microphone gain precentage. This can be any value from zero to

   235 	        100. Setting a zero value mutes the gain on left microphone.

   236 	@param  aRightPercentage

   237 	        The right microphone gain precentage. This can be any value from zero to

   238 	        100. Setting a zero value mutes the gain on right microphone.

   240 	@see CMMFDevSound::GetRecordBalanceL(TInt aLeftPercentage, TInt aRightPercentage)

   241 	*/

   242 	virtual void SetRecordBalanceL(TInt aLeftPercentage, TInt aRightPercentage)=0;

   244 	/**

   245 	This must provide an implementation as defined by CMMFDevSound::PlayInitL()

   247 	@see CMMFDevSound::PlayInitL()

   248 	*/

   249 	virtual void PlayInitL()=0;

   251 	/**

   252 	This must provide an implementation as defined by CMMFDevSound::RecordInitL()

   254 	@see CMMFDevSound::RecordInitL()

   255 	*/

   256 	virtual void RecordInitL()=0;

   258 	/**

   259 	This must provide an implementation as defined by CMMFDevSound::PlayData()

   261 	@see CMMFDevSound::PlayData()

   262 	*/

   263 	virtual void PlayData()=0;

   265 	/**

   266 	This must provide an implementation as defined by CMMFDevSound::RecordData()

   268 	@see CMMFDevSound::RecordData()

   269 	*/

   270 	virtual void RecordData()=0;

   272 	/**

   273 	This must provide an implementation as defined by CMMFDevSound::Stop()

   275 	@see CMMFDevSound::Stop()

   276 	*/

   277 	virtual void Stop()=0;

   279 	/**

   280 	This must provide an implementation as defined by CMMFDevSound::Pause()

   282 	@see CMMFDevSound::Pause()

   283 	*/

   284 	virtual void Pause()=0;

   286 	/**

   287 	This must provide an implementation as defined by CMMFDevSound::SamplesRecorded()

   289 	@return The samples recorded.

   291 	@see CMMFDevSound::SamplesRecorded()

   292 	*/

   293 	virtual TInt SamplesRecorded()=0;

   295 	/**

   296 	This must provide an implementation as defined by CMMFDevSound::SamplesPlayed()

   298 	@return The samples played.

   300 	@see CMMFDevSound::SamplesPlayed()

   301 	*/

   302 	virtual TInt SamplesPlayed()=0;

   304 	/**

   305 	This must provide an implementation as defined by

   306 	CMMFDevSound::PlayToneL(TInt aFrequency, const TTimeIntervalMicroSeconds& aDuration)

   308 	@param  aFrequency

   309 	        The frequency at which the tone will be played.

   310 	@param  aDuration

   311 	        The period over which the tone will be played. A zero value causes

   312 	        the no tone to be played.

   314 	@see CMMFDevSound::PlayToneL(TInt aFrequency, const TTimeIntervalMicroSeconds& aDuration)

   315 	*/

   316 	virtual void PlayToneL(TInt aFrequency, const TTimeIntervalMicroSeconds& aDuration)=0;

   318 	/**

   319 	This must provide an implementation as defined by

   320 	CMMFDevSound::PlayDualToneL(TInt aFrequencyOne, TInt aFrequencyTwo, const TTimeIntervalMicroSeconds& aDuration)

   322 	@param  aFrequencyOne

   323 	        The first frequency of dual tone.

   324 	@param  aFrequencyTwo

   325 	        The second frequency of dual tone

   326 	@param  aDuration

   327 	        The period over which the tone will be played. A zero value causes

   328 	        the no tone to be played (Verify this with test app).

   330 	@see CMMFDevSound::PlayDualToneL(TInt aFrequencyOne, TInt aFrequencyTwo, const TTimeIntervalMicroSeconds& aDuration)

   331 	*/

   332 	virtual void PlayDualToneL(TInt aFrequencyOne, TInt aFrequencyTwo, const TTimeIntervalMicroSeconds& aDuration)=0;

   334 	/**

   335 	This must provide an implementation as defined by CMMFDevSound::PlayDTMFStringL(const TDesC& aDTMFString)

   337 	@param  aDTMFString The DTMF sequence in a descriptor.

   339 	@see CMMFDevSound::PlayDTMFStringL(const TDesC& aDTMFString)

   340 	*/

   341 	virtual void PlayDTMFStringL(const TDesC& aDTMFString)=0;

   343 	/**

   344 	This must provide an implementation as defined by CMMFDevSound::PlayToneSequenceL(const TDesC8& aData)

   346 	@param  aData The tone sequence in a descriptor.

   348 	@see CMMFDevSound::PlayToneSequenceL(const TDesC8& aData)

   349 	*/

   350 	virtual void PlayToneSequenceL(const TDesC8& aData)=0;

   352 	/**

   353 	This must provide an implementation as defined by CMMFDevSound::PlayFixedSequenceL(TInt aSequenceNumber)

   355 	@param  aSequenceNumber

   356 	        The index identifying the specific pre-defined tone sequence. Index

   357 	        values are relative to zero.

   358 	        This can be any value from zero to the value returned by a call to

   359 	        FixedSequenceCount() - 1.

   360 	        The function raises a panic if the sequence number is not within this

   361 	        range.

   363 	@see CMMFDevSound::PlayFixedSequenceL(TInt aSequenceNumber)

   364 	@see FixedSequenceCount()

   365 	*/

   366 	virtual void PlayFixedSequenceL(TInt aSequenceNumber)=0;

   368 	/**

   369 	This must provide an implementation as defined by

   370 	CMMFDevSound::SetToneRepeats(TInt aRepeatCount,

   371 					const TTimeIntervalMicroSeconds& aRepeatTrailingSilence)

   373 	@param  aRepeatCount

   374 	        The number of times the tone, together with the trailing silence,

   375 	        is to be repeated. If this is set to KMdaRepeatForever, then the

   376 	        tone, together with the trailing silence, is repeated indefinitely

   377 	        or until Stop() is called. If this is set to zero, then the tone is

   378 	        not repeated.

   379 	@param  aRepeatTrailingSilence

   380 	        An interval of silence which will be played after each tone.

   381 	        Supported only during tone playing.

   383 	@see CMMFDevSound::SetToneRepeats(TInt aRepeatCount,

   384 					const TTimeIntervalMicroSeconds& aRepeatTrailingSilence)

   385 	*/

   386 	virtual void SetToneRepeats(TInt aRepeatCount,

   387 					const TTimeIntervalMicroSeconds& aRepeatTrailingSilence)=0;

   389 	/**

   390 	This must provide an implementation as defined by

   391 	CMMFDevSound::(TTimeIntervalMicroSeconds32& aToneOnLength,

   392 									TTimeIntervalMicroSeconds32& aToneOffLength,

   393 									TTimeIntervalMicroSeconds32& aPauseLength)

   395 	@param  aToneOnLength

   396 	        The period over which the tone will be played. If this is set to

   397 	        zero, then the tone is not played.

   398 	@param  aToneOffLength

   399 	        The period over which the no tone will be played.

   400 	@param  aPauseLength

   401 	        The period over which the tone playing will be paused.

   403 	@see CMMFDevSound::(TTimeIntervalMicroSeconds32& aToneOnLength,

   404 									TTimeIntervalMicroSeconds32& aToneOffLength,

   405 									TTimeIntervalMicroSeconds32& aPauseLength)

   406 	*/

   407 	virtual void SetDTMFLengths(TTimeIntervalMicroSeconds32& aToneOnLength,

   408 									TTimeIntervalMicroSeconds32& aToneOffLength,

   409 									TTimeIntervalMicroSeconds32& aPauseLength)=0;

   411 	/**

   412 	This must provide an implementation as defined by

   413 	CMMFDevSound::SetVolumeRamp(const TTimeIntervalMicroSeconds& aRampDuration)

   415 	@param  aRampDuration

   416 	        The period over which the volume is to rise. A zero value causes

   417 	        the tone sample to be played at the normal level for the full

   418 	        duration of the playback. A value, which is longer than the duration

   419 	        of the tone sample means that the sample never reaches its normal

   420 	        volume level.

   422 	@see CMMFDevSound::SetVolumeRamp(const TTimeIntervalMicroSeconds& aRampDuration)

   423 	*/

   424 	virtual void SetVolumeRamp(const TTimeIntervalMicroSeconds& aRampDuration)=0;

   426 	/**

   427 	This must provide an implementation as defined by

   428 	CMMFDevSound::SetPrioritySettings(const TMMFPrioritySettings& aPrioritySettings)

   430 	@param	aPrioritySettings

   431 			A class type representing the client's priority, priority preference and state.

   433 	@see CMMFDevSound::SetPrioritySettings(const TMMFPrioritySettings& aPrioritySettings)

   434 	*/

   435 	virtual void SetPrioritySettings(const TMMFPrioritySettings& aPrioritySettings)=0;

   437 	/**

   438 	This must provide an implementation as defined by CMMFDevSound::CustomInterface(TUid aInterfaceId)

   440 	@param  aInterfaceId

   441 	        The interface UID, defined with the custom interface.

   443 	@return A pointer to the interface implementation, or NULL if the device does not

   444 	        implement the interface requested. The return value must be cast to the

   445 	        correct type by the user.The user should be careful while caching the custom interface pointer,

   446 	        as in some situations the lower level custom interface pointer may become NULL

   448 	@see CMMFDevSound::CustomInterface(TUid aInterfaceId)

   449 	*/

   450 	virtual TAny* CustomInterface(TUid aInterfaceId)=0;

   452 	/**

   453 	This must provide an implementation as defined by CMMFDevSound::FixedSequenceCount()

   455 	@return The fixed sequence count. This value is implementation dependent but is always greater

   456 	        than or equal to zero.

   458 	@see CMMFDevSound::FixedSequenceCount()

   459 	*/

   460 	virtual TInt FixedSequenceCount()=0;

   462 	/**

   463 	This must provide an implementation as defined by CMMFDevSound::FixedSequenceName(TInt aSequenceNumber)

   465 	@param  aSequenceNumber

   466 	        The index identifying the specific pre-defined tone sequence. Index values are relative

   467 	        to zero. This can be any value from zero to the value returned by a call to

   468 	        FixedSequenceCount() - 1.

   469 	        The function raises a panic if sequence number is not within this

   470 	        range.

   472 	@return A reference to a Descriptor containing the fixed sequence name indexed by

   473 	        aSequenceNumber.

   475 	@see CMMFDevSound::FixedSequenceName(TInt aSequenceNumber)

   476 	@see FixedSequenceCount()

   477 	*/

   478 	virtual const TDesC& FixedSequenceName(TInt aSequenceNumber)=0;

   480 	/**

   481 	This must provide an implementation as defined by

   482 	CMMFDevSound::GetSupportedInputDataTypesL(RArray<TFourCC>& aSupportedDataTypes,

   483 													const TMMFPrioritySettings& aPrioritySettings) const

   485 	@param  aSupportedDataTypes

   486 	        The array of supported data types that will be filled in by this function.

   487 	        The supported data types of the DevSound are in the form of an array

   488 	        of TFourCC codes. Any existing entries in the array will be overwritten on

   489 	        calling this function. If no supported data types are found given the priority

   490 	        settings, then the aSupportedDatatypes array will have zero entries.

   491 	@param  aPrioritySettings

   492 	        The priority settings used to determine the supported datatypes.  Note this

   493 	        does not set the priority settings. For input datatypes the iState member

   494 	        of the priority settings would be expected to be either

   495 	        EMMFStatePlaying or EMMFStatePlayingRecording. The priority settings may

   496 	        effect the supported datatypes depending on the audio routing.

   498 	@see CMMFDevSound::GetSupportedInputDataTypesL(RArray<TFourCC>& aSupportedDataTypes,

   499 													const TMMFPrioritySettings& aPrioritySettings) const

   500 	*/

   501 	virtual void GetSupportedInputDataTypesL(RArray<TFourCC>& aSupportedDataTypes, const TMMFPrioritySettings& aPrioritySettings) const=0;

   503 	/**

   504 	This must provide an implementation as defined by

   505 	CMMFDevSound::GetSupportedOutputDataTypesL(RArray<TFourCC>& aSupportedDataTypes, const TMMFPrioritySettings& aPrioritySettings) const

   507 	@param  aSupportedDataTypes

   508 	        The array of supported data types that will be filled in by this function.

   509 	        The supported datatypes of the DevSound are in the form of an array

   510 	        of TFourCC codes.

   511 	        Any existing entries in the array will be overwritten on calling this function.

   512 	        If no supported datatypes are found given the priority settings, then

   513 	        the aSupportedDatatypes array will have zero entries.

   514 	@param  aPrioritySettings

   515 	        The priority settings used to determine the supported data types.  Note this

   516 	        does not set the priority settings. For output data types the iState member

   517 	        of the priority settings would expected to be either

   518 	        EMMFStateRecording or EMMFStatePlayingRecording. The priority settings may

   519 	        effect the supported datatypes depending on the audio routing.

   521 	@see CMMFDevSound::GetSupportedOutputDataTypesL(RArray<TFourCC>& aSupportedDataTypes, const TMMFPrioritySettings& aPrioritySettings) const

   522 	*/

   523 	virtual void GetSupportedOutputDataTypesL(RArray<TFourCC>& aSupportedDataTypes, const TMMFPrioritySettings& aPrioritySettings) const=0;

   525 	};

   527 #endif // DEVSOUNDPLUGIN_H

author	sl@SLION-WIN7.fritz.box
	Fri, 15 Jun 2012 03:10:57 +0200
changeset 0	bde4ae8d615e
permissions	-rw-r--r--