epoc32/include/mmf/server/sounddevice.h
author William Roberts <williamr@symbian.org>
Tue, 16 Mar 2010 16:12:26 +0000
branchSymbian2
changeset 2 2fe1408b6811
child 4 837f303aceeb
permissions -rw-r--r--
Final list of Symbian^2 public API header files
williamr@2
     1
// Copyright (c) 2001-2009 Nokia Corporation and/or its subsidiary(-ies).
williamr@2
     2
// All rights reserved.
williamr@2
     3
// This component and the accompanying materials are made available
williamr@2
     4
// under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
williamr@2
     5
// which accompanies this distribution, and is available
williamr@2
     6
// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
williamr@2
     7
//
williamr@2
     8
// Initial Contributors:
williamr@2
     9
// Nokia Corporation - initial contribution.
williamr@2
    10
//
williamr@2
    11
// Contributors:
williamr@2
    12
//
williamr@2
    13
// Description:
williamr@2
    14
//
williamr@2
    15
williamr@2
    16
#ifndef __SOUNDDEVICE_H__
williamr@2
    17
#define __SOUNDDEVICE_H__
williamr@2
    18
williamr@2
    19
#include <e32base.h>
williamr@2
    20
#include <f32file.h>
williamr@2
    21
#include <mmf/common/mmfbase.h>
williamr@2
    22
#include <mmf/common/mmfutilities.h>
williamr@2
    23
#include <mmf/common/mmfcontroller.h>
williamr@2
    24
williamr@2
    25
williamr@2
    26
//Debugging info
williamr@2
    27
williamr@2
    28
/*
williamr@2
    29
Notes: 
williamr@2
    30
This file defines the DevSound class which acts as an interface to
williamr@2
    31
the hardware and is intended to invoke VCR functionality via the plug-ins.
williamr@2
    32
The DevSound also contains a product specific policy.
williamr@2
    33
*/
williamr@2
    34
williamr@2
    35
//UIDs for buffers: According to Symbian: Not used
williamr@2
    36
williamr@2
    37
// Public Media Server includes
williamr@2
    38
williamr@2
    39
/**
williamr@2
    40
@publishedAll
williamr@2
    41
@released
williamr@2
    42
williamr@2
    43
Sampling rates available.
williamr@2
    44
williamr@2
    45
When queried from DevSound by calling the function Capabilities(), iRate indicates
williamr@2
    46
the sampling rates supported by the audio device.
williamr@2
    47
williamr@2
    48
DevSound by default is configured to 8KHz sampling rate.
williamr@2
    49
So to configure DevSound to play/record audio at 16 KHz sampling rate:
williamr@2
    50
williamr@2
    51
The mode should not be OR'ed with each other, only single values are accepted. 
williamr@2
    52
*/
williamr@2
    53
enum TMMFSampleRate
williamr@2
    54
	{
williamr@2
    55
  	/** 8000 Hz Sampling Rate
williamr@2
    56
	*/
williamr@2
    57
	EMMFSampleRate8000Hz  = 0x00000001,
williamr@2
    58
  	/** 11025 Hz Sampling Rate
williamr@2
    59
	*/
williamr@2
    60
	EMMFSampleRate11025Hz = 0x00000002,
williamr@2
    61
  	/** 16000 Hz Sampling Rate
williamr@2
    62
	*/
williamr@2
    63
	EMMFSampleRate16000Hz = 0x00000004,
williamr@2
    64
  	/** 22050 Hz Sampling Rate
williamr@2
    65
	*/
williamr@2
    66
	EMMFSampleRate22050Hz = 0x00000008,
williamr@2
    67
  	/** 32000 Hz Sampling Rate
williamr@2
    68
	*/
williamr@2
    69
	EMMFSampleRate32000Hz = 0x00000010,
williamr@2
    70
  	/** 44100 Hz Sampling Rate
williamr@2
    71
	*/
williamr@2
    72
	EMMFSampleRate44100Hz = 0x00000020,
williamr@2
    73
  	/** 48000 Hz Sampling Rate
williamr@2
    74
	*/
williamr@2
    75
	EMMFSampleRate48000Hz = 0x00000040,
williamr@2
    76
  	/** 88200 Hz Sampling Rate
williamr@2
    77
	*/
williamr@2
    78
	EMMFSampleRate88200Hz = 0x00000080,
williamr@2
    79
  	/** 96000 Hz Sampling Rate
williamr@2
    80
	*/
williamr@2
    81
	EMMFSampleRate96000Hz = 0x00000100,
williamr@2
    82
  	/** 12000 Hz Sampling Rate
williamr@2
    83
	*/
williamr@2
    84
	EMMFSampleRate12000Hz = 0x00000200,
williamr@2
    85
  	/** 24000 Hz Sampling Rate
williamr@2
    86
	*/
williamr@2
    87
	EMMFSampleRate24000Hz = 0x00000400,
williamr@2
    88
  	/** 64000 Hz Sampling Rate
williamr@2
    89
	*/
williamr@2
    90
	EMMFSampleRate64000Hz = 0x00000800
williamr@2
    91
	};
williamr@2
    92
williamr@2
    93
/**
williamr@2
    94
@publishedAll
williamr@2
    95
@released
williamr@2
    96
williamr@2
    97
Mono Stereo playback and record modes available.
williamr@2
    98
williamr@2
    99
When queried from DevSound by calling the function Capabilities(), iChannels
williamr@2
   100
indicates whether the underlying audio device supports playing back stereo
williamr@2
   101
audio samples and recording audio samples in stereo mode or not.
williamr@2
   102
williamr@2
   103
DevSound by default is configured to Mono mode.
williamr@2
   104
So to configure DevSound to play/record audio sample in stereo mode:
williamr@2
   105
williamr@2
   106
The mode should not be OR'ed with each other, only single values are accepted. 
williamr@2
   107
*/
williamr@2
   108
enum TMMFMonoStereo
williamr@2
   109
	{
williamr@2
   110
	/** Mono mode
williamr@2
   111
	*/
williamr@2
   112
	EMMFMono	= 0x00000001,
williamr@2
   113
	/** Stereo mode
williamr@2
   114
	*/
williamr@2
   115
	EMMFStereo	= 0x00000002
williamr@2
   116
	};
williamr@2
   117
williamr@2
   118
/**
williamr@2
   119
@publishedAll
williamr@2
   120
@released
williamr@2
   121
williamr@2
   122
Encoding modes available.
williamr@2
   123
williamr@2
   124
When queried from DevSound by calling the function Capabilities(), iEncoding
williamr@2
   125
provides information about different encoding supported by audio device.
williamr@2
   126
williamr@2
   127
DevSound by default is configured to play PCM16 Bit audio data.
williamr@2
   128
Setting encoding mode is not supported yet:
williamr@2
   129
*/
williamr@2
   130
enum TMMFSoundEncoding
williamr@2
   131
	{
williamr@2
   132
  	/** Signed 8 Bit PCM
williamr@2
   133
	*/
williamr@2
   134
	EMMFSoundEncoding8BitPCM		= 0x00000001,
williamr@2
   135
  	/** Signed 16 Bit PCM
williamr@2
   136
	*/
williamr@2
   137
	EMMFSoundEncoding16BitPCM		= 0x00000002,
williamr@2
   138
  	/** Signed 8 Bit ALaw
williamr@2
   139
	*/
williamr@2
   140
	EMMFSoundEncoding8BitALaw		= 0x00000004,
williamr@2
   141
  	/** Signed 8 Bit MuLaw
williamr@2
   142
	*/
williamr@2
   143
	EMMFSoundEncoding8BitMuLaw		= 0x00000008,
williamr@2
   144
	};
williamr@2
   145
williamr@2
   146
/**
williamr@2
   147
@publishedAll
williamr@2
   148
@released
williamr@2
   149
williamr@2
   150
Stereo support enum.
williamr@2
   151
*/
williamr@2
   152
enum TMMFStereoSupport
williamr@2
   153
	{
williamr@2
   154
	/** No stereo support
williamr@2
   155
	*/
williamr@2
   156
	EMMFNone						= 0x00000000,
williamr@2
   157
	/** Interleaved stereo support
williamr@2
   158
	*/
williamr@2
   159
	EMMFInterleavedOnly				= 0x00000001,
williamr@2
   160
	/** Non Interleaved stereo support
williamr@2
   161
	*/
williamr@2
   162
	EMMFNonInterleavedOnly			= 0x00000002,
williamr@2
   163
	/** Interleaved and Non Interleaved stereo support
williamr@2
   164
	*/
williamr@2
   165
	EMMFBothNonAndInterleaved		= 0x00000003,
williamr@2
   166
 	/** Joint stereo support
williamr@2
   167
 	*/
williamr@2
   168
 	EMMFJoint						= 0x00000004
williamr@2
   169
	};
williamr@2
   170
williamr@2
   171
/**
williamr@2
   172
@publishedAll
williamr@2
   173
@released
williamr@2
   174
williamr@2
   175
Type class for DevSound implementation device capabilities.
williamr@2
   176
williamr@2
   177
CMMFDevSound will return Sampling Rates, Encoding and Stereo feature
williamr@2
   178
supported in this structure when queried for capabilities. DevSound can
williamr@2
   179
also be configured by setting parameters in this structure and passing the
williamr@2
   180
structure to it.
williamr@2
   181
*/
williamr@2
   182
class TMMFCapabilities
williamr@2
   183
	{
williamr@2
   184
public:
williamr@2
   185
	/** Sampling Rates supported
williamr@2
   186
	*/
williamr@2
   187
	TUint	iRate;
williamr@2
   188
	/** Encodings supported
williamr@2
   189
	*/
williamr@2
   190
	TUint	iEncoding;
williamr@2
   191
	/** Mono/Stereo support
williamr@2
   192
	*/
williamr@2
   193
	TUint	iChannels;
williamr@2
   194
	/** Buffer size supported
williamr@2
   195
	*/
williamr@2
   196
	TInt	iBufferSize;
williamr@2
   197
	};
williamr@2
   198
williamr@2
   199
/**
williamr@2
   200
@publishedAll
williamr@2
   201
@released
williamr@2
   202
williamr@2
   203
An interface to a set of DevSound callback functions.
williamr@2
   204
williamr@2
   205
williamr@2
   206
This serves as the method of communication between the client and the
williamr@2
   207
DevSound.
williamr@2
   208
williamr@2
   209
The class is a mixin and is intended to be inherited by the client class
williamr@2
   210
that is interested in observing the DevSound operation. The functions
williamr@2
   211
encapsulated by this class are called when specific events occur in the
williamr@2
   212
process of initializing and playing/recording an audio sample or playing
williamr@2
   213
tones.
williamr@2
   214
*/
williamr@2
   215
class MDevSoundObserver
williamr@2
   216
	{
williamr@2
   217
public:
williamr@2
   218
	/**
williamr@2
   219
	Handles initialization completion event.
williamr@2
   220
	
williamr@2
   221
	A derived class must provide an implementation to handle the initialization
williamr@2
   222
	request.
williamr@2
   223
	
williamr@2
   224
	CMMFDevSound object calls this function when its InitializeL() function
williamr@2
   225
	completes.
williamr@2
   226
	
williamr@2
   227
	@param  aError
williamr@2
   228
	        Error code. KErrNone if successful. Other values are possible
williamr@2
   229
	        indicating a problem initializing CMMFDevSound object.
williamr@2
   230
	*/
williamr@2
   231
	virtual void InitializeComplete(TInt aError)=0;
williamr@2
   232
williamr@2
   233
	/**
williamr@2
   234
	Handles tone play completion event.
williamr@2
   235
	
williamr@2
   236
	A derived class must provide an implementation to handle the tone play
williamr@2
   237
	completion request.
williamr@2
   238
	
williamr@2
   239
	CMMFDevSound object calls this function when an attempt to play tone has
williamr@2
   240
	completed, successfully or otherwise.
williamr@2
   241
williamr@2
   242
	The following are the play tone functions; PlayToneL(), PlayDMTFStringL(),
williamr@2
   243
	PlayToneSequenceL(), and PlayFixedSequenceL().
williamr@2
   244
	
williamr@2
   245
	@param	aError
williamr@2
   246
	        Error code. The status of tone playback. KErrUnderflow playing of
williamr@2
   247
	        the tone is complete. KErrAccessDenied the sound device is in use by
williamr@2
   248
	        another higher priority client. KErrCancel playing of the audio
williamr@2
   249
	        sample is stopped by DevSound client another higher priority client.
williamr@2
   250
	*/
williamr@2
   251
	virtual void ToneFinished(TInt aError)=0;
williamr@2
   252
williamr@2
   253
	/**
williamr@2
   254
	Handles CMMFDevSound object's data request event.
williamr@2
   255
	
williamr@2
   256
	A derived class must provide an implementation to supply CMMFDevSound
williamr@2
   257
	object the data that it needs to play or convert.
williamr@2
   258
	
williamr@2
   259
	CMMFDevSound object calls this function when and where it needs data for
williamr@2
   260
	playing or converting. The observer should notify CMMFDevSound object as
williamr@2
   261
	quickly as possible after the data is read into buffer, aBuffer by calling
williamr@2
   262
	PlayData(), otherwise the implementation might callback function PlayError()
williamr@2
   263
	on derived class object with error code KErrUnderflow.
williamr@2
   264
	This does not apply to the very first call to PlayData(), however.
williamr@2
   265
	It is possible for a user of DevSound to hold the first buffer sent in
williamr@2
   266
	BufferToBeFilled() until ready to play.
williamr@2
   267
	The use case for this is if a low latency audio response
williamr@2
   268
	is required, as at this point all the resources used to play audio are open.
williamr@2
   269
	If used in this way then it is important to be aware that when when the
williamr@2
   270
	resources for audio are ready at the BufferToBeFilled() callback, a Devsound
williamr@2
   271
	on a real device will be running at increased power consumption as the audio
williamr@2
   272
	hw and any required DSPs will be powered up etc.
williamr@2
   273
	
williamr@2
   274
	@param  aBuffer
williamr@2
   275
	        Buffer into which data should be read. The amount of data that is
williamr@2
   276
	        needed is specified in CMMFBuffer::RequestSize().
williamr@2
   277
	*/
williamr@2
   278
	virtual void BufferToBeFilled(CMMFBuffer* aBuffer)=0;
williamr@2
   279
williamr@2
   280
	/**
williamr@2
   281
	Handles play completion or cancel event.
williamr@2
   282
williamr@2
   283
	A derived class must provide an implementation to handle the play
williamr@2
   284
	completion or cancel request.
williamr@2
   285
williamr@2
   286
	CMMFDevSound object calls this function when an attempt to play audio sample
williamr@2
   287
	has completed, successfully or otherwise.
williamr@2
   288
williamr@2
   289
	@param  aError
williamr@2
   290
	        Error code. The status of playback. KErrUnderflow playing of the
williamr@2
   291
	        audio sample is complete. KErrAccessDenied the sound device is in
williamr@2
   292
	        use by another higher priority client.
williamr@2
   293
	*/
williamr@2
   294
	virtual void PlayError(TInt aError)=0;
williamr@2
   295
williamr@2
   296
	/**
williamr@2
   297
	Handles CMMFDevSound object's data request event.
williamr@2
   298
williamr@2
   299
	A derived class must provide an implementation to process the data
williamr@2
   300
	supplied by CMMFDevSound object while recording or converting.
williamr@2
   301
williamr@2
   302
	CMMFDevSound object calls this function when the buffer, aBuffer gets filled
williamr@2
   303
	while recording or converting. The observer should notify CMMFDevSound
williamr@2
   304
	object as quickly as possible after data in the buffer is processed by
williamr@2
   305
	calling RecordData(), otherwise the implementation might callback
williamr@2
   306
	the function RecordError() on derived class object with error code KErrOverflow.
williamr@2
   307
williamr@2
   308
	@param  aBuffer
williamr@2
   309
	        Buffer containing processed (recorded or converted) data. The amount
williamr@2
   310
	        of data that is available is specified in CMMFBuffer::RequestSize().
williamr@2
   311
	*/
williamr@2
   312
	virtual void BufferToBeEmptied(CMMFBuffer* aBuffer)=0;
williamr@2
   313
williamr@2
   314
	/**
williamr@2
   315
	Handles record completion or cancel event.
williamr@2
   316
	
williamr@2
   317
	A derived class must provide an implementation to handle the record
williamr@2
   318
	completion or cancel request.
williamr@2
   319
	
williamr@2
   320
	CMMFDevSound object calls this function when an attempt to record audio sample
williamr@2
   321
	has completed, successfully or otherwise.
williamr@2
   322
	
williamr@2
   323
	@param  aError
williamr@2
   324
	        Error code. The status of recording. KErrOverflow audio devices
williamr@2
   325
	        runs out of internal buffer. KErrAccessDenied the sound device is
williamr@2
   326
	        in use by another higher priority client.
williamr@2
   327
	*/
williamr@2
   328
	virtual void RecordError(TInt aError)=0;
williamr@2
   329
williamr@2
   330
	/**
williamr@2
   331
	Handles conversion completion or cancel event.
williamr@2
   332
williamr@2
   333
	A derived class must provide an implementation to handle the conversion
williamr@2
   334
	completion or cancel request.
williamr@2
   335
williamr@2
   336
	CMMFDevSound object calls this function when an attempt to convert data from
williamr@2
   337
	source format to destination format has completed, successfully or otherwise.
williamr@2
   338
williamr@2
   339
	@param  aError
williamr@2
   340
	        Error code. KErrCancel conversion operation is cancelled. KErrNone
williamr@2
   341
	        conversion is complete. Other values are possible indicating a
williamr@2
   342
	        problem converting data.
williamr@2
   343
	*/
williamr@2
   344
	virtual void ConvertError(TInt aError)=0;
williamr@2
   345
williamr@2
   346
	/**
williamr@2
   347
	Handles device event.
williamr@2
   348
	
williamr@2
   349
	A derived class must provide an implementtion to handle the messages from
williamr@2
   350
	audio hardware device.
williamr@2
   351
	
williamr@2
   352
	CMMFDevSound object calls this function when a message is received from the
williamr@2
   353
	audio hardware device.
williamr@2
   354
	
williamr@2
   355
	@param	aMessageType
williamr@2
   356
			Defines the type of message. Used to determine how to
williamr@2
   357
			interpret the contents of aMsg.
williamr@2
   358
	@param	aMsg
williamr@2
   359
			Message that is packed in the Descriptor format.
williamr@2
   360
	*/
williamr@2
   361
	virtual void DeviceMessage(TUid aMessageType, const TDesC8& aMsg)=0;
williamr@2
   362
williamr@2
   363
williamr@2
   364
	/**
williamr@2
   365
	Handles policy request completion event.
williamr@2
   366
	
williamr@2
   367
	A derived class must provide an implementation to handle the policy request
williamr@2
   368
	completion event.
williamr@2
   369
	
williamr@2
   370
	CMMFDevSound object calls this function when an attempt to acquire sound
williamr@2
   371
	device is rejected by audio policy server.
williamr@2
   372
	
williamr@2
   373
	@param	aEvent
williamr@2
   374
			Not used
williamr@2
   375
	*/
williamr@2
   376
	inline virtual void SendEventToClient(const TMMFEvent& aEvent);
williamr@2
   377
williamr@2
   378
	};
williamr@2
   379
williamr@2
   380
williamr@2
   381
/**
williamr@2
   382
@publishedAll
williamr@2
   383
@released
williamr@2
   384
williamr@2
   385
This is the interface from Symbian OS to the raw audio functions on the
williamr@2
   386
device hardware.
williamr@2
   387
williamr@2
   388
DevSound is currently loaded as a DLL, and implements the VCR-type
williamr@2
   389
functions to be expected for such an interface.
williamr@2
   390
williamr@2
   391
The audio functions include the following functionality:
williamr@2
   392
- Initialisation and configuration of hardware devices, for example, setting microphone gain, 
williamr@2
   393
setting setero balance and so on.
williamr@2
   394
- The playing and recording of raw audio data.
williamr@2
   395
- The playing and dynamic control of tones with user specified frequencies.
williamr@2
   396
- The playing of DTMF strings.
williamr@2
   397
*/
williamr@2
   398
class CMMFDevSound : public CBase
williamr@2
   399
	{
williamr@2
   400
public:
williamr@2
   401
williamr@2
   402
	/**
williamr@2
   403
	Constructs, and returns a pointer to, a new CMMFDevSound object.
williamr@2
   404
williamr@2
   405
	Leaves on failure.
williamr@2
   406
	*/
williamr@2
   407
	IMPORT_C static CMMFDevSound* NewL();
williamr@2
   408
williamr@2
   409
	/**
williamr@2
   410
	Destructor.
williamr@2
   411
williamr@2
   412
	Deletes all objects and releases all resource owned by this
williamr@2
   413
	instance.
williamr@2
   414
	*/
williamr@2
   415
	IMPORT_C ~CMMFDevSound();
williamr@2
   416
williamr@2
   417
	/**
williamr@2
   418
	Initializes CMMFDevSound object to play and record PCM16 raw audio data
williamr@2
   419
	with sampling rate of 8 KHz.
williamr@2
   420
williamr@2
   421
	On completion of Initialization, calls InitializeComplete() on
williamr@2
   422
	aDevSoundObserver.
williamr@2
   423
williamr@2
   424
	Leaves on failure.
williamr@2
   425
williamr@2
   426
	@param  aDevSoundObserver
williamr@2
   427
	        A reference to DevSound Observer instance.
williamr@2
   428
	@param  aMode
williamr@2
   429
	        The mode for which this object will be used. Any value other than EMMFStatePlaying, EMMFStateRecording or EMMFStateTonePlaying is unsupported. 
williamr@2
   430
	
williamr@2
   431
	 
williamr@2
   432
	*/
williamr@2
   433
    IMPORT_C void InitializeL(MDevSoundObserver& aDevSoundObserver, TMMFState aMode);
williamr@2
   434
williamr@2
   435
williamr@2
   436
	/**
williamr@2
   437
	Initializes DevSound object for the mode aMode for processing audio data
williamr@2
   438
	with hardware device aHWDev.
williamr@2
   439
williamr@2
   440
	On completion of Initialization, the observer will be notified via call back
williamr@2
   441
	InitializeComplete().
williamr@2
   442
williamr@2
   443
	Leaves on failure.
williamr@2
   444
williamr@2
   445
	@param  aDevSoundObserver
williamr@2
   446
	        A reference to DevSound Observer instance.
williamr@2
   447
	@param  aHWDev
williamr@2
   448
	        The CMMFHwDevice implementation identifier.
williamr@2
   449
	@param  aMode
williamr@2
   450
	        The mode for which this object will be used. Any value other than EMMFStatePlaying, EMMFStateRecording or EMMFStateTonePlaying is unsupported.
williamr@2
   451
	        
williamr@2
   452
   	*/
williamr@2
   453
	IMPORT_C void InitializeL(MDevSoundObserver& aDevSoundObserver, TUid aHWDev, TMMFState aMode);
williamr@2
   454
williamr@2
   455
	/**
williamr@2
   456
	Initializes DevSound object for the mode aMode for processing audio data
williamr@2
   457
	with hardware device supporting FourCC aDesiredFourCC.
williamr@2
   458
williamr@2
   459
	On completion of Initialization, the observer will be notified via call back
williamr@2
   460
	InitializeComplete().
williamr@2
   461
williamr@2
   462
	Leaves on failure.
williamr@2
   463
williamr@2
   464
	@param  aDevSoundObserver
williamr@2
   465
	        A reference to DevSound Observer instance.
williamr@2
   466
	@param  aDesiredFourCC
williamr@2
   467
	        The CMMFHwDevice implementation FourCC code.
williamr@2
   468
	@param  aMode
williamr@2
   469
	        The mode for which this object will be used. Any value other than EMMFStatePlaying, EMMFStateRecording or EMMFStateTonePlaying is unsupported.
williamr@2
   470
	        
williamr@2
   471
    */
williamr@2
   472
	IMPORT_C void InitializeL(MDevSoundObserver& aDevSoundObserver, TFourCC aDesiredFourCC, TMMFState aMode);
williamr@2
   473
williamr@2
   474
	/**
williamr@2
   475
	Returns the supported Audio settings ie. encoding, sample rates, mono/stereo operation, buffer 
williamr@2
   476
	size etc.
williamr@2
   477
williamr@2
   478
	@return	The device settings.
williamr@2
   479
	*/
williamr@2
   480
	IMPORT_C TMMFCapabilities Capabilities();
williamr@2
   481
williamr@2
   482
	/**
williamr@2
   483
	Returns the current device configuration.
williamr@2
   484
williamr@2
   485
	@return	The device settings.
williamr@2
   486
	*/
williamr@2
   487
	IMPORT_C TMMFCapabilities Config() const;
williamr@2
   488
williamr@2
   489
	/**
williamr@2
   490
	Configure CMMFDevSound object with the settings in aConfig.
williamr@2
   491
williamr@2
   492
	Use this to set sampling rate, encoding and mono/stereo.
williamr@2
   493
williamr@2
   494
	@param  aCaps
williamr@2
   495
	        The attribute values to which CMMFDevSound object will be configured to.
williamr@2
   496
	*/
williamr@2
   497
	IMPORT_C void SetConfigL(const TMMFCapabilities& aCaps);
williamr@2
   498
williamr@2
   499
	/**
williamr@2
   500
	Returns an integer representing the maximum volume device supports.
williamr@2
   501
williamr@2
   502
	This is the maximum value which can be passed to CMMFDevSound::SetVolume.
williamr@2
   503
williamr@2
   504
	@return	The maximum volume. This value is platform dependent but is always greater than or equal
williamr@2
   505
	to one.
williamr@2
   506
	*/
williamr@2
   507
	IMPORT_C TInt MaxVolume();
williamr@2
   508
williamr@2
   509
	/**
williamr@2
   510
	Returns an integer representing the current volume.
williamr@2
   511
williamr@2
   512
	@return The current volume level.
williamr@2
   513
	*/
williamr@2
   514
	IMPORT_C TInt Volume();
williamr@2
   515
williamr@2
   516
	/**
williamr@2
   517
	Changes the current playback volume to a specified value.
williamr@2
   518
williamr@2
   519
	The volume can be changed before or during playback and is effective
williamr@2
   520
	immediately.
williamr@2
   521
williamr@2
   522
	@param  aVolume
williamr@2
   523
	        The volume setting. This can be any value from 0 to the value
williamr@2
   524
	        returned by a call to CMMFDevSound::MaxVolume(). If the
williamr@2
   525
	        volume is not within this range, the volume is automatically set to
williamr@2
   526
	        minimum or maximum value based on the value that is being passed.
williamr@2
   527
	        Setting a zero value mutes the sound. Setting the maximum value
williamr@2
   528
	        results in the loudest possible sound.
williamr@2
   529
	*/
williamr@2
   530
	IMPORT_C void SetVolume(TInt aVolume);
williamr@2
   531
williamr@2
   532
	/**
williamr@2
   533
	Returns an integer representing the maximum gain the device supports.
williamr@2
   534
williamr@2
   535
	This is the maximum value which can be passed to CMMFDevSound::SetGain.
williamr@2
   536
williamr@2
   537
	@return The maximum gain. This value is platform dependent but is always greater than or equal
williamr@2
   538
	to one.
williamr@2
   539
	*/
williamr@2
   540
	IMPORT_C TInt MaxGain();
williamr@2
   541
williamr@2
   542
	/**
williamr@2
   543
	Returns an integer representing the current gain.
williamr@2
   544
williamr@2
   545
	@return The current gain level.
williamr@2
   546
	*/
williamr@2
   547
	IMPORT_C TInt Gain();
williamr@2
   548
williamr@2
   549
	/**
williamr@2
   550
	Changes the current recording gain to a specified value.
williamr@2
   551
williamr@2
   552
	The gain can be changed before or during recording and is effective
williamr@2
   553
	immediately.
williamr@2
   554
williamr@2
   555
	@param  aGain
williamr@2
   556
	        The gain setting. This can be any value from zero to the value
williamr@2
   557
	        returned by a call to CMMFDevSound::MaxGain(). If the
williamr@2
   558
	        volume is not within this range, the gain is automatically set to
williamr@2
   559
	        minimum or maximum value based on the value that is being passed.
williamr@2
   560
	        Setting a zero value mutes the sound. Setting the maximum value
williamr@2
   561
	        results in the loudest possible sound.
williamr@2
   562
	*/
williamr@2
   563
	IMPORT_C void SetGain(TInt aGain);
williamr@2
   564
williamr@2
   565
	/**
williamr@2
   566
	Returns the speaker balance set for playing.
williamr@2
   567
williamr@2
   568
	Leaves on failure.
williamr@2
   569
williamr@2
   570
	@param  aLeftPercentage
williamr@2
   571
	        On return contains the left speaker volume percentage.
williamr@2
   572
	@param  aRightPercentage
williamr@2
   573
	        On return contains the right speaker volume percentage.
williamr@2
   574
	*/
williamr@2
   575
	IMPORT_C void GetPlayBalanceL(TInt& aLeftPercentage, TInt& aRightPercentage);
williamr@2
   576
williamr@2
   577
	/**
williamr@2
   578
	Sets the speaker balance for playing.
williamr@2
   579
williamr@2
   580
	The speaker balance can be changed before or during playback and is
williamr@2
   581
	effective immediately.
williamr@2
   582
williamr@2
   583
	@param  aLeftPercentage
williamr@2
   584
	        On return contains left speaker volume perecentage. This can be any
williamr@2
   585
	        value from zero to 100. Setting a zero value mutes the sound on left
williamr@2
   586
	        speaker.
williamr@2
   587
	@param  aRightPercentage
williamr@2
   588
	        On return contains right speaker volume perecentage. This can be any
williamr@2
   589
	        value from zero to 100. Setting a zero value mutes the sound on
williamr@2
   590
	        right speaker.
williamr@2
   591
	*/
williamr@2
   592
	IMPORT_C void SetPlayBalanceL(TInt aLeftPercentage, TInt aRightPercentage);
williamr@2
   593
williamr@2
   594
	/**
williamr@2
   595
	Returns the microphone gain balance set for recording.
williamr@2
   596
williamr@2
   597
	Leaves on failure.
williamr@2
   598
williamr@2
   599
	@param  aLeftPercentage
williamr@2
   600
	        On return contains the left microphone gain percentage.
williamr@2
   601
	@param  aRightPercentage
williamr@2
   602
	        On return contains the right microphone gain percentage.
williamr@2
   603
	*/
williamr@2
   604
	IMPORT_C void GetRecordBalanceL(TInt& aLeftPercentage, TInt& aRightPercentage);
williamr@2
   605
williamr@2
   606
	/**
williamr@2
   607
	Sets the microphone gain balance for recording.
williamr@2
   608
williamr@2
   609
	The microphone gain balance can be changed before or during recording and
williamr@2
   610
	is effective immediately.
williamr@2
   611
williamr@2
   612
	@param  aLeftPercentage
williamr@2
   613
	        The left microphone gain precentage. This can be any value from zero to
williamr@2
   614
	        100. Setting a zero value mutes the gain on left microphone.
williamr@2
   615
	@param  aRightPercentage
williamr@2
   616
	        The right microphone gain precentage. This can be any value from zero to
williamr@2
   617
	        100. Setting a zero value mutes the gain on right microphone.
williamr@2
   618
	*/
williamr@2
   619
	IMPORT_C void SetRecordBalanceL(TInt aLeftPercentage, TInt aRightPercentage);
williamr@2
   620
williamr@2
   621
	/**
williamr@2
   622
	Initializes the audio device and starts the play process.
williamr@2
   623
williamr@2
   624
	This function queries and acquires the audio policy before initializing audio device. If there was
williamr@2
   625
	an error during policy initialization, PlayError() function will be called on	the observer with
williamr@2
   626
	error code KErrAccessDenied, otherwise BufferToBeFilled() function will be called with a buffer
williamr@2
   627
	reference. After reading data into the buffer reference passed, the client should call
williamr@2
   628
	PlayData() to play data.
williamr@2
   629
williamr@2
   630
	The amount of data that can be played is specified in
williamr@2
   631
	CMMFBuffer::RequestSize(). Any data that is read into buffer beyond this
williamr@2
   632
	size will be ignored.
williamr@2
   633
williamr@2
   634
	Leaves on failure.
williamr@2
   635
williamr@2
   636
	@see    MDevSoundObserver::PlayError()
williamr@2
   637
	@see    MDevSoundObserver::BufferToBeFilled()
williamr@2
   638
	*/
williamr@2
   639
	IMPORT_C void PlayInitL();
williamr@2
   640
williamr@2
   641
	/**
williamr@2
   642
	Initializes audio device and starts the recording process. 
williamr@2
   643
williamr@2
   644
	This function queries and acquires the audio policy before initializing audio device. If there 
williamr@2
   645
	was an error during policy initialization, RecordError() function will be called on the observer 
williamr@2
   646
	with error code KErrAccessDenied, otherwise BufferToBeEmptied()	function will be called with a 
williamr@2
   647
	buffer reference. This buffer contains recorded	or encoded data. After processing data in the 
williamr@2
   648
	buffer reference passed, the client should call RecordData() to continue recording process.
williamr@2
   649
williamr@2
   650
	The amount of data that is available is specified in CMMFBuffer::RequestSize().
williamr@2
   651
williamr@2
   652
	Leaves on failure.
williamr@2
   653
williamr@2
   654
	@see    MDevSoundObserver::RecordError() 
williamr@2
   655
	@see    MDevSoundObserver::BufferToBeEmptied()
williamr@2
   656
	
williamr@2
   657
	@capability	UserEnvironment
williamr@2
   658
			For recording - the requesting client process must have the 
williamr@2
   659
			UserEnvironment capability.
williamr@2
   660
	*/
williamr@2
   661
	IMPORT_C void RecordInitL();
williamr@2
   662
williamr@2
   663
	/**
williamr@2
   664
	Plays data in the buffer at the current volume. 
williamr@2
   665
williamr@2
   666
	The client should fill the buffer with audio data before calling this function. The observer gets
williamr@2
   667
	a reference to the buffer along with the callback function BufferToBeFilled(). When playing of
williamr@2
   668
	the audio sample is complete, successfully or otherwise, the function PlayError() on the
williamr@2
   669
	observer is called.
williamr@2
   670
williamr@2
   671
	The last buffer of the audio stream being played should have the last buffer flag set using
williamr@2
   672
	CMMFBuffer::SetLastBuffer(TBool). If a subsequent attempt to play the clip is made, this flag 
williamr@2
   673
	will need resetting by the client.
williamr@2
   674
williamr@2
   675
	@see    MDevSoundObserver::PlayError()
williamr@2
   676
	*/
williamr@2
   677
	IMPORT_C void PlayData();
williamr@2
   678
williamr@2
   679
	/**
williamr@2
   680
	Contine the process of recording. 
williamr@2
   681
williamr@2
   682
	Once the buffer is filled with recorded	data, the Observer gets a reference to the buffer along 
williamr@2
   683
	with the callback function BufferToBeEmptied(). After processing the buffer (copying over to a
williamr@2
   684
	different buffer or writing to file) the client should call this function to continue the 
williamr@2
   685
	recording process.
williamr@2
   686
	
williamr@2
   687
	@capability	UserEnvironment
williamr@2
   688
			For recording - the requesting client process must have the 
williamr@2
   689
			UserEnvironment capability.
williamr@2
   690
	*/
williamr@2
   691
	IMPORT_C void RecordData();
williamr@2
   692
williamr@2
   693
	/**
williamr@2
   694
	Stops the ongoing operation (Play, Record, TonePlay, Convert).
williamr@2
   695
williamr@2
   696
	This function should be synchronous and invoke no callbacks through MDevSoundObserver.
williamr@2
   697
	*/
williamr@2
   698
	IMPORT_C void Stop();
williamr@2
   699
williamr@2
   700
	/**
williamr@2
   701
	Temporarily Stops the ongoing operation (Play, Record, TonePlay, Convert).
williamr@2
   702
	
williamr@2
   703
	The behaviour of Pause() is currently undefined when the initialisation mode
williamr@2
   704
	is not EMMFStateRecording, consequently different DevSound implementations exhibit
williamr@2
   705
	different behaviour for pause during play.  For this reason, it is recommended that
williamr@2
   706
	when pausing of audio during playing is required, Stop() is used instead of the call
williamr@2
   707
	to Pause(). To resume audio playing after Stop(), call PlayInitL(). Among other things,
williamr@2
   708
	this will internally reset the SamplesPlayed() result and the calling code may need to
williamr@2
   709
	remember the previous result to give the correct "samples played from start" value.
williamr@2
   710
williamr@2
   711
	In the case of record, Pause is taken to mean halt any further recording
williamr@2
   712
	but continue to call the MDevSoundObserver::BufferToBeEmptied() passing
williamr@2
   713
	already recorded buffers. The last buffer flag should be set when
williamr@2
   714
	all recorded buffers have been flushed.
williamr@2
   715
	
williamr@2
   716
	@see CMMFDevSound::Stop()
williamr@2
   717
	@see CMMFDevSound::PlayInitL()
williamr@2
   718
	@see CMMFDevSound::SamplesPlayed()
williamr@2
   719
	*/
williamr@2
   720
	IMPORT_C void Pause();
williamr@2
   721
williamr@2
   722
	/**
williamr@2
   723
	Returns the number samples recorded so far.
williamr@2
   724
williamr@2
   725
	@return The samples recorded.
williamr@2
   726
	*/
williamr@2
   727
	IMPORT_C TInt SamplesRecorded();
williamr@2
   728
williamr@2
   729
	/**
williamr@2
   730
	Returns the number of samples played so far.
williamr@2
   731
williamr@2
   732
	@return The samples played.
williamr@2
   733
	*/
williamr@2
   734
	IMPORT_C TInt SamplesPlayed();
williamr@2
   735
williamr@2
   736
	/**
williamr@2
   737
	Initializes the audio device and starts playing a tone. The tone is played with the
williamr@2
   738
	frequency and duration specified.
williamr@2
   739
williamr@2
   740
	Leaves on failure.
williamr@2
   741
williamr@2
   742
	@param  aFrequency
williamr@2
   743
	        The frequency at which the tone will be played.
williamr@2
   744
	@param  aDuration
williamr@2
   745
	        The period over which the tone will be played. A zero value causes
williamr@2
   746
	        the no tone to be played.
williamr@2
   747
	*/
williamr@2
   748
	IMPORT_C void PlayToneL(TInt aFrequency, const TTimeIntervalMicroSeconds& aDuration);
williamr@2
   749
williamr@2
   750
	/**
williamr@2
   751
	Initializes audio device and starts playing a dual tone.
williamr@2
   752
williamr@2
   753
	The generated tone consists of two sine waves of different frequencies
williamr@2
   754
	summed together.
williamr@2
   755
williamr@2
   756
	Dual Tone is played with the specified frequencies and for the specified duration.
williamr@2
   757
williamr@2
   758
	@param  aFrequencyOne
williamr@2
   759
	        The first frequency of dual tone.
williamr@2
   760
	@param  aFrequencyTwo
williamr@2
   761
	        The second frequency of dual tone
williamr@2
   762
	@param  aDuration
williamr@2
   763
	        The period over which the tone will be played. A zero value causes
williamr@2
   764
	        the no tone to be played (Verify this with test app).
williamr@2
   765
	*/
williamr@2
   766
	IMPORT_C void PlayDualToneL(TInt aFrequencyOne, TInt aFrequencyTwo, const TTimeIntervalMicroSeconds& aDuration);
williamr@2
   767
williamr@2
   768
	/**
williamr@2
   769
	Initializes the audio device and starts playing the DTMF string aDTMFString.
williamr@2
   770
williamr@2
   771
	Leaves on failure.
williamr@2
   772
williamr@2
   773
	@param  aDTMFString
williamr@2
   774
	        The DTMF sequence in a descriptor.
williamr@2
   775
	*/
williamr@2
   776
	IMPORT_C void PlayDTMFStringL(const TDesC& aDTMFString);
williamr@2
   777
williamr@2
   778
	/**
williamr@2
   779
	Initializes the audio device and starts playing a tone sequence.
williamr@2
   780
williamr@2
   781
	Leaves on failure.
williamr@2
   782
williamr@2
   783
	@param  aData
williamr@2
   784
	        The tone sequence in a descriptor.
williamr@2
   785
	*/
williamr@2
   786
	IMPORT_C void PlayToneSequenceL(const TDesC8& aData);
williamr@2
   787
williamr@2
   788
	/**
williamr@2
   789
	Initializes the audio device and starts playing the specified pre-defined tone
williamr@2
   790
	sequence.
williamr@2
   791
williamr@2
   792
	Leaves on failure.
williamr@2
   793
williamr@2
   794
	@param  aSequenceNumber
williamr@2
   795
	        The index identifying the specific pre-defined tone sequence. Index
williamr@2
   796
	        values are relative to zero.
williamr@2
   797
	        This can be any value from zero to the value returned by a call to
williamr@2
   798
			FixedSequenceCount() - 1.
williamr@2
   799
	        The function raises a panic if the sequence number is not within this
williamr@2
   800
	        range.
williamr@2
   801
	@see	FixedSequenceCount()
williamr@2
   802
	*/
williamr@2
   803
	IMPORT_C void PlayFixedSequenceL(TInt aSequenceNumber);
williamr@2
   804
williamr@2
   805
	/**
williamr@2
   806
	Defines the number of times the audio is to be repeated during the tone
williamr@2
   807
	playback operation.
williamr@2
   808
williamr@2
   809
	A period of silence can follow each playing of a tone. The tone playing can
williamr@2
   810
	be repeated indefinitely.
williamr@2
   811
williamr@2
   812
	@param  aRepeatCount
williamr@2
   813
	        The number of times the tone, together with the trailing silence,
williamr@2
   814
	        is to be repeated. If this is set to KMdaRepeatForever, then the
williamr@2
   815
	        tone, together with the trailing silence, is repeated indefinitely
williamr@2
   816
	        or until Stop() is called. If this is set to zero, then the tone is
williamr@2
   817
	        not repeated.
williamr@2
   818
	@param  aRepeatTrailingSilence
williamr@2
   819
	        An interval of silence which will be played after each tone.
williamr@2
   820
	        Supported only during tone playing.
williamr@2
   821
	*/
williamr@2
   822
	IMPORT_C void SetToneRepeats(TInt aRepeatCount,
williamr@2
   823
					const TTimeIntervalMicroSeconds& aRepeatTrailingSilence);
williamr@2
   824
williamr@2
   825
	/**
williamr@2
   826
	Defines the duration of tone on, tone off and tone pause to be used during the
williamr@2
   827
	DTMF tone playback operation.
williamr@2
   828
williamr@2
   829
	Supported only during tone playing.
williamr@2
   830
williamr@2
   831
	@param  aToneOnLength
williamr@2
   832
	        The period over which the tone will be played. If this is set to
williamr@2
   833
	        zero, then the tone is not played.
williamr@2
   834
	@param  aToneOffLength
williamr@2
   835
	        The period over which the no tone will be played.
williamr@2
   836
	@param  aPauseLength
williamr@2
   837
	        The period over which the tone playing will be paused.
williamr@2
   838
	*/
williamr@2
   839
	IMPORT_C void SetDTMFLengths(TTimeIntervalMicroSeconds32& aToneOnLength,
williamr@2
   840
									TTimeIntervalMicroSeconds32& aToneOffLength,
williamr@2
   841
									TTimeIntervalMicroSeconds32& aPauseLength);
williamr@2
   842
williamr@2
   843
	/**
williamr@2
   844
	Defines the period over which the volume level is to rise smoothly from
williamr@2
   845
	nothing to the normal volume level.
williamr@2
   846
williamr@2
   847
	The function is only available while the tone is playing.
williamr@2
   848
williamr@2
   849
	@param  aRampDuration
williamr@2
   850
	        The period over which the volume is to rise. A zero value causes
williamr@2
   851
	        the tone sample to be played at the normal level for the full
williamr@2
   852
	        duration of the playback. A value, which is longer than the duration
williamr@2
   853
	        of the tone sample means that the sample never reaches its normal
williamr@2
   854
	        volume level.
williamr@2
   855
	*/
williamr@2
   856
	IMPORT_C void SetVolumeRamp(const TTimeIntervalMicroSeconds& aRampDuration);
williamr@2
   857
williamr@2
   858
	/**
williamr@2
   859
	Defines the priority settings that should be used for this instance.
williamr@2
   860
williamr@2
   861
	@param  aPrioritySettings
williamr@2
   862
	        A class type representing the client's priority, priority preference and state.
williamr@2
   863
	*/
williamr@2
   864
	IMPORT_C void SetPrioritySettings(const TMMFPrioritySettings& aPrioritySettings);
williamr@2
   865
williamr@2
   866
	/**
williamr@2
   867
	Retrieves a custom interface to the device.
williamr@2
   868
williamr@2
   869
	@param  aInterfaceId
williamr@2
   870
	        The interface UID, defined with the custom interface.
williamr@2
   871
	
williamr@2
   872
	@return A pointer to the interface implementation, or NULL if the device does not
williamr@2
   873
	        implement the interface requested. The return value must be cast to the
williamr@2
   874
	        correct type by the user.The user should be careful while caching the custom interface pointer,
williamr@2
   875
	        as in some situations the lower level custom interface pointer may become NULL.
williamr@2
   876
	*/
williamr@2
   877
	IMPORT_C TAny* CustomInterface(TUid aInterfaceId);
williamr@2
   878
williamr@2
   879
	/**
williamr@2
   880
	Returns the number of available pre-defined tone sequences.
williamr@2
   881
williamr@2
   882
	This is the number of fixed sequence supported by DevSound by default.
williamr@2
   883
williamr@2
   884
	@return The fixed sequence count. This value is implementation dependent but is always greater 
williamr@2
   885
	        than or equal to zero.
williamr@2
   886
	*/
williamr@2
   887
	IMPORT_C TInt FixedSequenceCount();
williamr@2
   888
williamr@2
   889
	/**
williamr@2
   890
	Returns the name assigned to a specific pre-defined tone sequence.
williamr@2
   891
williamr@2
   892
	This is the number of the fixed sequence supported by DevSound by default.
williamr@2
   893
williamr@2
   894
	The function raises a panic if sequence number specified is invalid.
williamr@2
   895
williamr@2
   896
	@param  aSequenceNumber
williamr@2
   897
	        The index identifying the specific pre-defined tone sequence. Index values are relative 
williamr@2
   898
	        to zero. This can be any value from zero to the value returned by a call to
williamr@2
   899
	        FixedSequenceCount() - 1.
williamr@2
   900
	        The function raises a panic if sequence number is not within this
williamr@2
   901
	        range.
williamr@2
   902
williamr@2
   903
	@return A reference to a Descriptor containing the fixed sequence name indexed by
williamr@2
   904
	        aSequenceNumber.
williamr@2
   905
	        
williamr@2
   906
	@see	FixedSequenceCount()
williamr@2
   907
	*/
williamr@2
   908
	IMPORT_C const TDesC& FixedSequenceName(TInt aSequenceNumber);
williamr@2
   909
williamr@2
   910
	/**
williamr@2
   911
	Returns a list of the supported input datatypes that can be sent to DevSound for playing audio.
williamr@2
   912
	The datatypes returned are those that the DevSound supports given the priority settings passed
williamr@2
   913
	in aPrioritySettings.
williamr@2
   914
williamr@2
   915
	Note that if no supported data types are found this does not constitute failure, the function will
williamr@2
   916
	return normally with no entries in aSupportedDataTypes.
williamr@2
   917
williamr@2
   918
	@param  aSupportedDataTypes
williamr@2
   919
	        The array of supported data types that will be filled in by this function.
williamr@2
   920
	        The supported data types of the DevSound are in the form of an array
williamr@2
   921
	        of TFourCC codes. Any existing entries in the array will be overwritten on 
williamr@2
   922
	        calling this function. If no supported data types are found given the priority 
williamr@2
   923
	        settings, then the aSupportedDatatypes array will have zero entries.
williamr@2
   924
	@param  aPrioritySettings
williamr@2
   925
	        The priority settings used to determine the supported datatypes.  Note this
williamr@2
   926
	        does not set the priority settings. For input datatypes the iState member
williamr@2
   927
	        of the priority settings would be expected to be either
williamr@2
   928
	        EMMFStatePlaying or EMMFStatePlayingRecording. The priority settings may
williamr@2
   929
	        effect the supported datatypes depending on the audio routing.
williamr@2
   930
	*/
williamr@2
   931
	IMPORT_C void GetSupportedInputDataTypesL(RArray<TFourCC>& aSupportedDataTypes, const TMMFPrioritySettings& aPrioritySettings) const;
williamr@2
   932
williamr@2
   933
	/**
williamr@2
   934
	Returns a list of the supported output dataypes that can be received from DevSound for
williamr@2
   935
	recording audio.  The datatypes returned are those that the DevSound supports given the priority 
williamr@2
   936
	settings passed in aPrioritySettings.
williamr@2
   937
williamr@2
   938
	Note that if no supported data types are found this does not constitute failure, the function will 
williamr@2
   939
	return normally with no entries in aSupportedDataTypes.
williamr@2
   940
williamr@2
   941
	@param  aSupportedDataTypes
williamr@2
   942
	        The array of supported data types that will be filled in by this function.
williamr@2
   943
	        The supported datatypes of the DevSound are in the form of an array
williamr@2
   944
	        of TFourCC codes.
williamr@2
   945
	        Any existing entries in the array will be overwritten on calling this function.
williamr@2
   946
	        If no supported datatypes are found given the priority settings, then
williamr@2
   947
	        the aSupportedDatatypes array will have zero entries.
williamr@2
   948
	@param  aPrioritySettings
williamr@2
   949
	        The priority settings used to determine the supported data types.  Note this
williamr@2
   950
	        does not set the priority settings. For output data types the iState member
williamr@2
   951
	        of the priority settings would expected to be either
williamr@2
   952
	        EMMFStateRecording or EMMFStatePlayingRecording. The priority settings may
williamr@2
   953
	        effect the supported datatypes depending on the audio routing.
williamr@2
   954
	*/
williamr@2
   955
	IMPORT_C void GetSupportedOutputDataTypesL(RArray<TFourCC>& aSupportedDataTypes, const TMMFPrioritySettings& aPrioritySettings) const;
williamr@2
   956
	
williamr@2
   957
	/** 
williamr@2
   958
	Registers the client for notification of resource avalibility.
williamr@2
   959
williamr@2
   960
	@param  aEventType
williamr@2
   961
	        The Notification event type for which the client needs notification.
williamr@2
   962
	@param  aNotificationRegistrationData
williamr@2
   963
	        The Notification Registration data has been reserved for future use and its value should be always NULL
williamr@2
   964
	@return An error code indicating if the function call was successful. KErrNone on success, 
williamr@2
   965
			KErrNotSupported if the event type is not supported, KErrArgument if the notification data
williamr@2
   966
			is not null otherwise another of the system-wide error codes.
williamr@2
   967
	*/
williamr@2
   968
	inline TInt RegisterAsClient(TUid aEventType, const TDesC8& aNotificationRegistrationData = KNullDesC8);
williamr@2
   969
	
williamr@2
   970
	/**
williamr@2
   971
	Cancels the Registered Notification.
williamr@2
   972
	
williamr@2
   973
	@param  aEventType
williamr@2
   974
	        The Event type need to cancel
williamr@2
   975
	@return An error code indicating if the function call was successful. KErrNone on success, KErrNotSupported
williamr@2
   976
			if the event type is not supported otherwise another of the system-wide error codes.
williamr@2
   977
	*/	
williamr@2
   978
	inline TInt CancelRegisterAsClient(TUid aEventType);
williamr@2
   979
	
williamr@2
   980
	/**
williamr@2
   981
	Returns the Notification data which the client needs to resume playing.
williamr@2
   982
	
williamr@2
   983
	@param aEventType
williamr@2
   984
	       The Event type for which to get notification data  
williamr@2
   985
	@param aNotificationData
williamr@2
   986
			The reference data for which the client needs to resume the play. The actual data depends on the event type.
williamr@2
   987
			Note that for the event type 'KMMFEventCategoryAudioResourceAvailable' the package buffer returned
williamr@2
   988
			is TMMFTimeIntervalMicroSecondsPckg,but the contents should be converted to an integer and
williamr@2
   989
			interpreted as the data returned is samples played ,but not as a microsecond value.
williamr@2
   990
	@return An error code indicating if the function call was successful. KErrNone on success, otherwise
williamr@2
   991
	        another of the system-wide error codes.
williamr@2
   992
	*/
williamr@2
   993
	inline TInt GetResourceNotificationData(TUid aEventType,TDes8& aNotificationData);
williamr@2
   994
	
williamr@2
   995
	/**
williamr@2
   996
	Wait for the clients to resume play back even after the default timeout expires.
williamr@2
   997
	Unless the client cancels the notification request or completes no other client gets
williamr@2
   998
	notification.
williamr@2
   999
	
williamr@2
  1000
	@return An error code indicating if the function call was successful. KErrNone on success,
williamr@2
  1001
			KErrPermissionDenied if the client does not have MultimediaDD capaility, otherwise
williamr@2
  1002
	        another of the system-wide error codes.
williamr@2
  1003
	*/
williamr@2
  1004
	inline TInt WillResumePlay();
williamr@2
  1005
	
williamr@2
  1006
	/**
williamr@2
  1007
	@publishedPartner
williamr@2
  1008
	@prototype
williamr@2
  1009
williamr@2
  1010
	Empties the play buffers below DevSound without causing the codec to be deleted.
williamr@2
  1011
williamr@2
  1012
	@return An error code indicating if the function call was successful. KErrNone on success,
williamr@2
  1013
			KErrNotSupported if called in a mode other than EMMFStatePlaying or if the function is otherwise not supported,
williamr@2
  1014
			KErrNotReady if this is called before playing,
williamr@2
  1015
			otherwise another of the system-wide error codes.
williamr@2
  1016
			If this function is not supported, it is advised to use Stop().
williamr@2
  1017
	*/
williamr@2
  1018
	inline TInt EmptyBuffers();
williamr@2
  1019
williamr@2
  1020
	/** Cancels the initialization process of a CMMFDevSound object
williamr@2
  1021
williamr@2
  1022
	@return An error code indicating if the function call was successful. 
williamr@2
  1023
			KErrNone on success,
williamr@2
  1024
			KerrNotReady if this is called before InitializeL() call or after      
williamr@2
  1025
			the object has been initialized, 
williamr@2
  1026
	*/
williamr@2
  1027
	inline TInt CancelInitialize();
williamr@2
  1028
	
williamr@2
  1029
	/**
williamr@2
  1030
	Sets client thread info for devsound to make proper policy and routing decisions
williamr@2
  1031
	
williamr@2
  1032
	@param  aTid
williamr@2
  1033
			The thread Id of real client.
williamr@2
  1034
	
williamr@2
  1035
	@capability MultimediaDD
williamr@2
  1036
			A process requires MultimediaDD capability to make this call. 
williamr@2
  1037
	*/
williamr@2
  1038
	inline TInt SetClientThreadInfo(TThreadId aTid);
williamr@2
  1039
williamr@2
  1040
	/**
williamr@2
  1041
	Retrieves the current play time from the audio renderer
williamr@2
  1042
	
williamr@2
  1043
	@param  aTime
williamr@2
  1044
	        A reference to TTimeIntervalMicroSeconds object which will be filled with the current play time by this function.  
williamr@2
  1045
	@return An error code indicating if the function call was successful. 
williamr@2
  1046
			KErrNone on success,
williamr@2
  1047
			KErrNotSupported if the underlying devsound implementation or the HwDevice does not support this API,
williamr@2
  1048
			otherwise any of the system-wide error codes.
williamr@2
  1049
			If this function is not supported, SamplesPlayed() needs to be used instead.
williamr@2
  1050
	
williamr@2
  1051
	@see	IsGetTimePlayedSupported()
williamr@2
  1052
	*/
williamr@2
  1053
	inline TInt GetTimePlayed(TTimeIntervalMicroSeconds& aTime);
williamr@2
  1054
	
williamr@2
  1055
	/**
williamr@2
  1056
	This method can be used by devsound clients to check if the devsound implementation supports
williamr@2
  1057
	GetTimePlayed API. If this method returns EFalse, SamplesPlayed needs to be used.
williamr@2
  1058
	
williamr@2
  1059
	@return ETrue if the underlying devsound implementation supports GetTimePlayed API,
williamr@2
  1060
			EFalse if the the underlying devsound implementation does not support GetTimePlayed API
williamr@2
  1061
	
williamr@2
  1062
	@see	GetTimePlayed()
williamr@2
  1063
	*/
williamr@2
  1064
	inline TBool IsGetTimePlayedSupported();
williamr@2
  1065
williamr@2
  1066
	/**
williamr@2
  1067
	This method can be used by devsound clients to check if the devsound implementation ignores the underflow
williamr@2
  1068
	errors from the sound driver and does not propagate them to its clients. 
williamr@2
  1069
	
williamr@2
  1070
	@return ETrue 	if devsound ignores all the underflow errors from the sound driver except for the last buffer
williamr@2
  1071
					That means DevSound propagates the underflow error from sound driver to its clients only when 
williamr@2
  1072
					client sets the last buffer flag on the CMMFBuffer type buffer.
williamr@2
  1073
			EFalse 	if devsound propagates the underflow errors from the sound driver in all the cases
williamr@2
  1074
	
williamr@2
  1075
	*/
williamr@2
  1076
	inline TBool QueryIgnoresUnderflow();
williamr@2
  1077
williamr@2
  1078
	/**
williamr@2
  1079
	This method can be used by devsound clients to check if current configuration supports resume
williamr@2
  1080
	This call is only valid when DevSound is initialized
williamr@2
  1081
	@return ETrue 	if current format does supports resume
williamr@2
  1082
			EFalse 	otherwise
williamr@2
  1083
	*/
williamr@2
  1084
	inline TBool IsResumeSupported();
williamr@2
  1085
williamr@2
  1086
	/**
williamr@2
  1087
	Resume play back, recording or tone playing after this has been paused
williamr@2
  1088
	@return An error code indicating if the function call was successful. 
williamr@2
  1089
			KErrNone on success,
williamr@2
  1090
			KErrNotSupported if current format configuration does not support this functionality
williamr@2
  1091
			KErrNotReady if DevSound is not paused
williamr@2
  1092
	*/
williamr@2
  1093
	inline TInt Resume();
williamr@2
  1094
williamr@2
  1095
protected:
williamr@2
  1096
williamr@2
  1097
	/**
williamr@2
  1098
	Default Constructor.
williamr@2
  1099
	*/
williamr@2
  1100
	//So that nobody can extend derive from CMMFDevSound.
williamr@2
  1101
	CMMFDevSound();
williamr@2
  1102
williamr@2
  1103
	/**
williamr@2
  1104
	Second phase constructor.
williamr@2
  1105
	*/
williamr@2
  1106
	void ConstructL();
williamr@2
  1107
williamr@2
  1108
	class CBody;
williamr@2
  1109
	
williamr@2
  1110
	/**
williamr@2
  1111
	DevSound body
williamr@2
  1112
	*/
williamr@2
  1113
	CBody* iBody;
williamr@2
  1114
	};
williamr@2
  1115
williamr@2
  1116
inline void MDevSoundObserver::SendEventToClient(const TMMFEvent& /*aEvent*/)
williamr@2
  1117
	{
williamr@2
  1118
	}
williamr@2
  1119
williamr@2
  1120
#include <mmf/server/sounddevice.inl>
williamr@2
  1121
williamr@2
  1122
#endif // __SOUNDDEVICE_H__