1 // Copyright (c) 2001-2009 Nokia Corporation and/or its subsidiary(-ies).
2 // All rights reserved.
3 // This component and the accompanying materials are made available
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
5 // which accompanies this distribution, and is available
6 // at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
8 // Initial Contributors:
9 // Nokia Corporation - initial contribution.
16 #ifndef __SOUNDDEVICE_H__
17 #define __SOUNDDEVICE_H__
21 #include <mmf/common/mmfbase.h>
22 #include <mmf/common/mmfutilities.h>
23 #include <mmf/common/mmfcontroller.h>
30 This file defines the DevSound class which acts as an interface to
31 the hardware and is intended to invoke VCR functionality via the plug-ins.
32 The DevSound also contains a product specific policy.
35 //UIDs for buffers: According to Symbian: Not used
37 // Public Media Server includes
43 Sampling rates available.
45 When queried from DevSound by calling the function Capabilities(), iRate indicates
46 the sampling rates supported by the audio device.
48 DevSound by default is configured to 8KHz sampling rate.
49 So to configure DevSound to play/record audio at 16 KHz sampling rate:
51 The mode should not be OR'ed with each other, only single values are accepted.
55 /** 8000 Hz Sampling Rate
57 EMMFSampleRate8000Hz = 0x00000001,
58 /** 11025 Hz Sampling Rate
60 EMMFSampleRate11025Hz = 0x00000002,
61 /** 16000 Hz Sampling Rate
63 EMMFSampleRate16000Hz = 0x00000004,
64 /** 22050 Hz Sampling Rate
66 EMMFSampleRate22050Hz = 0x00000008,
67 /** 32000 Hz Sampling Rate
69 EMMFSampleRate32000Hz = 0x00000010,
70 /** 44100 Hz Sampling Rate
72 EMMFSampleRate44100Hz = 0x00000020,
73 /** 48000 Hz Sampling Rate
75 EMMFSampleRate48000Hz = 0x00000040,
76 /** 88200 Hz Sampling Rate
78 EMMFSampleRate88200Hz = 0x00000080,
79 /** 96000 Hz Sampling Rate
81 EMMFSampleRate96000Hz = 0x00000100,
82 /** 12000 Hz Sampling Rate
84 EMMFSampleRate12000Hz = 0x00000200,
85 /** 24000 Hz Sampling Rate
87 EMMFSampleRate24000Hz = 0x00000400,
88 /** 64000 Hz Sampling Rate
90 EMMFSampleRate64000Hz = 0x00000800
97 Mono Stereo playback and record modes available.
99 When queried from DevSound by calling the function Capabilities(), iChannels
100 indicates whether the underlying audio device supports playing back stereo
101 audio samples and recording audio samples in stereo mode or not.
103 DevSound by default is configured to Mono mode.
104 So to configure DevSound to play/record audio sample in stereo mode:
106 The mode should not be OR'ed with each other, only single values are accepted.
112 EMMFMono = 0x00000001,
115 EMMFStereo = 0x00000002
122 Encoding modes available.
124 When queried from DevSound by calling the function Capabilities(), iEncoding
125 provides information about different encoding supported by audio device.
127 DevSound by default is configured to play PCM16 Bit audio data.
128 Setting encoding mode is not supported yet:
130 enum TMMFSoundEncoding
134 EMMFSoundEncoding8BitPCM = 0x00000001,
135 /** Signed 16 Bit PCM
137 EMMFSoundEncoding16BitPCM = 0x00000002,
138 /** Signed 8 Bit ALaw
140 EMMFSoundEncoding8BitALaw = 0x00000004,
141 /** Signed 8 Bit MuLaw
143 EMMFSoundEncoding8BitMuLaw = 0x00000008,
152 enum TMMFStereoSupport
154 /** No stereo support
156 EMMFNone = 0x00000000,
157 /** Interleaved stereo support
159 EMMFInterleavedOnly = 0x00000001,
160 /** Non Interleaved stereo support
162 EMMFNonInterleavedOnly = 0x00000002,
163 /** Interleaved and Non Interleaved stereo support
165 EMMFBothNonAndInterleaved = 0x00000003,
166 /** Joint stereo support
168 EMMFJoint = 0x00000004
175 Type class for DevSound implementation device capabilities.
177 CMMFDevSound will return Sampling Rates, Encoding and Stereo feature
178 supported in this structure when queried for capabilities. DevSound can
179 also be configured by setting parameters in this structure and passing the
182 class TMMFCapabilities
185 /** Sampling Rates supported
188 /** Encodings supported
191 /** Mono/Stereo support
194 /** Buffer size supported
203 An interface to a set of DevSound callback functions.
206 This serves as the method of communication between the client and the
209 The class is a mixin and is intended to be inherited by the client class
210 that is interested in observing the DevSound operation. The functions
211 encapsulated by this class are called when specific events occur in the
212 process of initializing and playing/recording an audio sample or playing
215 class MDevSoundObserver
219 Handles initialization completion event.
221 A derived class must provide an implementation to handle the initialization
224 CMMFDevSound object calls this function when its InitializeL() function
228 Error code. KErrNone if successful. Other values are possible
229 indicating a problem initializing CMMFDevSound object.
231 virtual void InitializeComplete(TInt aError)=0;
234 Handles tone play completion event.
236 A derived class must provide an implementation to handle the tone play
239 CMMFDevSound object calls this function when an attempt to play tone has
240 completed, successfully or otherwise.
242 The following are the play tone functions; PlayToneL(), PlayDMTFStringL(),
243 PlayToneSequenceL(), and PlayFixedSequenceL().
246 Error code. The status of tone playback. KErrUnderflow playing of
247 the tone is complete. KErrAccessDenied the sound device is in use by
248 another higher priority client. KErrCancel playing of the audio
249 sample is stopped by DevSound client another higher priority client.
251 virtual void ToneFinished(TInt aError)=0;
254 Handles CMMFDevSound object's data request event.
256 A derived class must provide an implementation to supply CMMFDevSound
257 object the data that it needs to play or convert.
259 CMMFDevSound object calls this function when and where it needs data for
260 playing or converting. The observer should notify CMMFDevSound object as
261 quickly as possible after the data is read into buffer, aBuffer by calling
262 PlayData(), otherwise the implementation might callback function PlayError()
263 on derived class object with error code KErrUnderflow.
264 This does not apply to the very first call to PlayData(), however.
265 It is possible for a user of DevSound to hold the first buffer sent in
266 BufferToBeFilled() until ready to play.
267 The use case for this is if a low latency audio response
268 is required, as at this point all the resources used to play audio are open.
269 If used in this way then it is important to be aware that when when the
270 resources for audio are ready at the BufferToBeFilled() callback, a Devsound
271 on a real device will be running at increased power consumption as the audio
272 hw and any required DSPs will be powered up etc.
275 Buffer into which data should be read. The amount of data that is
276 needed is specified in CMMFBuffer::RequestSize().
278 virtual void BufferToBeFilled(CMMFBuffer* aBuffer)=0;
281 Handles play completion or cancel event.
283 A derived class must provide an implementation to handle the play
284 completion or cancel request.
286 CMMFDevSound object calls this function when an attempt to play audio sample
287 has completed, successfully or otherwise.
290 Error code. The status of playback. KErrUnderflow playing of the
291 audio sample is complete. KErrAccessDenied the sound device is in
292 use by another higher priority client.
294 virtual void PlayError(TInt aError)=0;
297 Handles CMMFDevSound object's data request event.
299 A derived class must provide an implementation to process the data
300 supplied by CMMFDevSound object while recording or converting.
302 CMMFDevSound object calls this function when the buffer, aBuffer gets filled
303 while recording or converting. The observer should notify CMMFDevSound
304 object as quickly as possible after data in the buffer is processed by
305 calling RecordData(), otherwise the implementation might callback
306 the function RecordError() on derived class object with error code KErrOverflow.
309 Buffer containing processed (recorded or converted) data. The amount
310 of data that is available is specified in CMMFBuffer::RequestSize().
312 virtual void BufferToBeEmptied(CMMFBuffer* aBuffer)=0;
315 Handles record completion or cancel event.
317 A derived class must provide an implementation to handle the record
318 completion or cancel request.
320 CMMFDevSound object calls this function when an attempt to record audio sample
321 has completed, successfully or otherwise.
324 Error code. The status of recording. KErrOverflow audio devices
325 runs out of internal buffer. KErrAccessDenied the sound device is
326 in use by another higher priority client.
328 virtual void RecordError(TInt aError)=0;
331 Handles conversion completion or cancel event.
333 A derived class must provide an implementation to handle the conversion
334 completion or cancel request.
336 CMMFDevSound object calls this function when an attempt to convert data from
337 source format to destination format has completed, successfully or otherwise.
340 Error code. KErrCancel conversion operation is cancelled. KErrNone
341 conversion is complete. Other values are possible indicating a
342 problem converting data.
344 virtual void ConvertError(TInt aError)=0;
347 Handles device event.
349 A derived class must provide an implementtion to handle the messages from
350 audio hardware device.
352 CMMFDevSound object calls this function when a message is received from the
353 audio hardware device.
356 Defines the type of message. Used to determine how to
357 interpret the contents of aMsg.
359 Message that is packed in the Descriptor format.
361 virtual void DeviceMessage(TUid aMessageType, const TDesC8& aMsg)=0;
365 Handles policy request completion event.
367 A derived class must provide an implementation to handle the policy request
370 CMMFDevSound object calls this function when an attempt to acquire sound
371 device is rejected by audio policy server.
376 inline virtual void SendEventToClient(const TMMFEvent& aEvent);
385 This is the interface from Symbian OS to the raw audio functions on the
388 DevSound is currently loaded as a DLL, and implements the VCR-type
389 functions to be expected for such an interface.
391 The audio functions include the following functionality:
392 - Initialisation and configuration of hardware devices, for example, setting microphone gain,
393 setting setero balance and so on.
394 - The playing and recording of raw audio data.
395 - The playing and dynamic control of tones with user specified frequencies.
396 - The playing of DTMF strings.
398 class CMMFDevSound : public CBase
403 Constructs, and returns a pointer to, a new CMMFDevSound object.
407 IMPORT_C static CMMFDevSound* NewL();
412 Deletes all objects and releases all resource owned by this
415 IMPORT_C ~CMMFDevSound();
418 Initializes CMMFDevSound object to play and record PCM16 raw audio data
419 with sampling rate of 8 KHz.
421 On completion of Initialization, calls InitializeComplete() on
426 @param aDevSoundObserver
427 A reference to DevSound Observer instance.
429 The mode for which this object will be used. Any value other than EMMFStatePlaying, EMMFStateRecording or EMMFStateTonePlaying is unsupported.
433 IMPORT_C void InitializeL(MDevSoundObserver& aDevSoundObserver, TMMFState aMode);
437 Initializes DevSound object for the mode aMode for processing audio data
438 with hardware device aHWDev.
440 On completion of Initialization, the observer will be notified via call back
441 InitializeComplete().
445 @param aDevSoundObserver
446 A reference to DevSound Observer instance.
448 The CMMFHwDevice implementation identifier.
450 The mode for which this object will be used. Any value other than EMMFStatePlaying, EMMFStateRecording or EMMFStateTonePlaying is unsupported.
453 IMPORT_C void InitializeL(MDevSoundObserver& aDevSoundObserver, TUid aHWDev, TMMFState aMode);
456 Initializes DevSound object for the mode aMode for processing audio data
457 with hardware device supporting FourCC aDesiredFourCC.
459 On completion of Initialization, the observer will be notified via call back
460 InitializeComplete().
464 @param aDevSoundObserver
465 A reference to DevSound Observer instance.
466 @param aDesiredFourCC
467 The CMMFHwDevice implementation FourCC code.
469 The mode for which this object will be used. Any value other than EMMFStatePlaying, EMMFStateRecording or EMMFStateTonePlaying is unsupported.
472 IMPORT_C void InitializeL(MDevSoundObserver& aDevSoundObserver, TFourCC aDesiredFourCC, TMMFState aMode);
475 Returns the supported Audio settings ie. encoding, sample rates, mono/stereo operation, buffer
478 @return The device settings.
480 IMPORT_C TMMFCapabilities Capabilities();
483 Returns the current device configuration.
485 @return The device settings.
487 IMPORT_C TMMFCapabilities Config() const;
490 Configure CMMFDevSound object with the settings in aConfig.
492 Use this to set sampling rate, encoding and mono/stereo.
495 The attribute values to which CMMFDevSound object will be configured to.
497 IMPORT_C void SetConfigL(const TMMFCapabilities& aCaps);
500 Returns an integer representing the maximum volume device supports.
502 This is the maximum value which can be passed to CMMFDevSound::SetVolume.
504 @return The maximum volume. This value is platform dependent but is always greater than or equal
507 IMPORT_C TInt MaxVolume();
510 Returns an integer representing the current volume.
512 @return The current volume level.
514 IMPORT_C TInt Volume();
517 Changes the current playback volume to a specified value.
519 The volume can be changed before or during playback and is effective
523 The volume setting. This can be any value from 0 to the value
524 returned by a call to CMMFDevSound::MaxVolume(). If the
525 volume is not within this range, the volume is automatically set to
526 minimum or maximum value based on the value that is being passed.
527 Setting a zero value mutes the sound. Setting the maximum value
528 results in the loudest possible sound.
530 IMPORT_C void SetVolume(TInt aVolume);
533 Returns an integer representing the maximum gain the device supports.
535 This is the maximum value which can be passed to CMMFDevSound::SetGain.
537 @return The maximum gain. This value is platform dependent but is always greater than or equal
540 IMPORT_C TInt MaxGain();
543 Returns an integer representing the current gain.
545 @return The current gain level.
547 IMPORT_C TInt Gain();
550 Changes the current recording gain to a specified value.
552 The gain can be changed before or during recording and is effective
556 The gain setting. This can be any value from zero to the value
557 returned by a call to CMMFDevSound::MaxGain(). If the
558 volume is not within this range, the gain is automatically set to
559 minimum or maximum value based on the value that is being passed.
560 Setting a zero value mutes the sound. Setting the maximum value
561 results in the loudest possible sound.
563 IMPORT_C void SetGain(TInt aGain);
566 Returns the speaker balance set for playing.
570 @param aLeftPercentage
571 On return contains the left speaker volume percentage.
572 @param aRightPercentage
573 On return contains the right speaker volume percentage.
575 IMPORT_C void GetPlayBalanceL(TInt& aLeftPercentage, TInt& aRightPercentage);
578 Sets the speaker balance for playing.
580 The speaker balance can be changed before or during playback and is
581 effective immediately.
583 @param aLeftPercentage
584 On return contains left speaker volume perecentage. This can be any
585 value from zero to 100. Setting a zero value mutes the sound on left
587 @param aRightPercentage
588 On return contains right speaker volume perecentage. This can be any
589 value from zero to 100. Setting a zero value mutes the sound on
592 IMPORT_C void SetPlayBalanceL(TInt aLeftPercentage, TInt aRightPercentage);
595 Returns the microphone gain balance set for recording.
599 @param aLeftPercentage
600 On return contains the left microphone gain percentage.
601 @param aRightPercentage
602 On return contains the right microphone gain percentage.
604 IMPORT_C void GetRecordBalanceL(TInt& aLeftPercentage, TInt& aRightPercentage);
607 Sets the microphone gain balance for recording.
609 The microphone gain balance can be changed before or during recording and
610 is effective immediately.
612 @param aLeftPercentage
613 The left microphone gain precentage. This can be any value from zero to
614 100. Setting a zero value mutes the gain on left microphone.
615 @param aRightPercentage
616 The right microphone gain precentage. This can be any value from zero to
617 100. Setting a zero value mutes the gain on right microphone.
619 IMPORT_C void SetRecordBalanceL(TInt aLeftPercentage, TInt aRightPercentage);
622 Initializes the audio device and starts the play process.
624 This function queries and acquires the audio policy before initializing audio device. If there was
625 an error during policy initialization, PlayError() function will be called on the observer with
626 error code KErrAccessDenied, otherwise BufferToBeFilled() function will be called with a buffer
627 reference. After reading data into the buffer reference passed, the client should call
628 PlayData() to play data.
630 The amount of data that can be played is specified in
631 CMMFBuffer::RequestSize(). Any data that is read into buffer beyond this
632 size will be ignored.
636 @see MDevSoundObserver::PlayError()
637 @see MDevSoundObserver::BufferToBeFilled()
639 IMPORT_C void PlayInitL();
642 Initializes audio device and starts the recording process.
644 This function queries and acquires the audio policy before initializing audio device. If there
645 was an error during policy initialization, RecordError() function will be called on the observer
646 with error code KErrAccessDenied, otherwise BufferToBeEmptied() function will be called with a
647 buffer reference. This buffer contains recorded or encoded data. After processing data in the
648 buffer reference passed, the client should call RecordData() to continue recording process.
650 The amount of data that is available is specified in CMMFBuffer::RequestSize().
654 @see MDevSoundObserver::RecordError()
655 @see MDevSoundObserver::BufferToBeEmptied()
657 @capability UserEnvironment
658 For recording - the requesting client process must have the
659 UserEnvironment capability.
661 IMPORT_C void RecordInitL();
664 Plays data in the buffer at the current volume.
666 The client should fill the buffer with audio data before calling this function. The observer gets
667 a reference to the buffer along with the callback function BufferToBeFilled(). When playing of
668 the audio sample is complete, successfully or otherwise, the function PlayError() on the
671 The last buffer of the audio stream being played should have the last buffer flag set using
672 CMMFBuffer::SetLastBuffer(TBool). If a subsequent attempt to play the clip is made, this flag
673 will need resetting by the client.
675 @see MDevSoundObserver::PlayError()
677 IMPORT_C void PlayData();
680 Contine the process of recording.
682 Once the buffer is filled with recorded data, the Observer gets a reference to the buffer along
683 with the callback function BufferToBeEmptied(). After processing the buffer (copying over to a
684 different buffer or writing to file) the client should call this function to continue the
687 @capability UserEnvironment
688 For recording - the requesting client process must have the
689 UserEnvironment capability.
691 IMPORT_C void RecordData();
694 Stops the ongoing operation (Play, Record, TonePlay, Convert).
696 This function should be synchronous and invoke no callbacks through MDevSoundObserver.
698 IMPORT_C void Stop();
701 Temporarily Stops the ongoing operation (Play, Record, TonePlay, Convert).
703 The behaviour of Pause() is currently undefined when the initialisation mode
704 is not EMMFStateRecording, consequently different DevSound implementations exhibit
705 different behaviour for pause during play. For this reason, it is recommended that
706 when pausing of audio during playing is required, Stop() is used instead of the call
707 to Pause(). To resume audio playing after Stop(), call PlayInitL(). Among other things,
708 this will internally reset the SamplesPlayed() result and the calling code may need to
709 remember the previous result to give the correct "samples played from start" value.
711 In the case of record, Pause is taken to mean halt any further recording
712 but continue to call the MDevSoundObserver::BufferToBeEmptied() passing
713 already recorded buffers. The last buffer flag should be set when
714 all recorded buffers have been flushed.
716 @see CMMFDevSound::Stop()
717 @see CMMFDevSound::PlayInitL()
718 @see CMMFDevSound::SamplesPlayed()
720 IMPORT_C void Pause();
723 Returns the number samples recorded so far.
725 @return The samples recorded.
727 IMPORT_C TInt SamplesRecorded();
730 Returns the number of samples played so far.
732 @return The samples played.
734 IMPORT_C TInt SamplesPlayed();
737 Initializes the audio device and starts playing a tone. The tone is played with the
738 frequency and duration specified.
743 The frequency at which the tone will be played.
745 The period over which the tone will be played. A zero value causes
746 the no tone to be played.
748 IMPORT_C void PlayToneL(TInt aFrequency, const TTimeIntervalMicroSeconds& aDuration);
751 Initializes audio device and starts playing a dual tone.
753 The generated tone consists of two sine waves of different frequencies
756 Dual Tone is played with the specified frequencies and for the specified duration.
759 The first frequency of dual tone.
761 The second frequency of dual tone
763 The period over which the tone will be played. A zero value causes
764 the no tone to be played (Verify this with test app).
766 IMPORT_C void PlayDualToneL(TInt aFrequencyOne, TInt aFrequencyTwo, const TTimeIntervalMicroSeconds& aDuration);
769 Initializes the audio device and starts playing the DTMF string aDTMFString.
774 The DTMF sequence in a descriptor.
776 IMPORT_C void PlayDTMFStringL(const TDesC& aDTMFString);
779 Initializes the audio device and starts playing a tone sequence.
784 The tone sequence in a descriptor.
786 IMPORT_C void PlayToneSequenceL(const TDesC8& aData);
789 Initializes the audio device and starts playing the specified pre-defined tone
794 @param aSequenceNumber
795 The index identifying the specific pre-defined tone sequence. Index
796 values are relative to zero.
797 This can be any value from zero to the value returned by a call to
798 FixedSequenceCount() - 1.
799 The function raises a panic if the sequence number is not within this
801 @see FixedSequenceCount()
803 IMPORT_C void PlayFixedSequenceL(TInt aSequenceNumber);
806 Defines the number of times the audio is to be repeated during the tone
809 A period of silence can follow each playing of a tone. The tone playing can
810 be repeated indefinitely.
813 The number of times the tone, together with the trailing silence,
814 is to be repeated. If this is set to KMdaRepeatForever, then the
815 tone, together with the trailing silence, is repeated indefinitely
816 or until Stop() is called. If this is set to zero, then the tone is
818 @param aRepeatTrailingSilence
819 An interval of silence which will be played after each tone.
820 Supported only during tone playing.
822 IMPORT_C void SetToneRepeats(TInt aRepeatCount,
823 const TTimeIntervalMicroSeconds& aRepeatTrailingSilence);
826 Defines the duration of tone on, tone off and tone pause to be used during the
827 DTMF tone playback operation.
829 Supported only during tone playing.
832 The period over which the tone will be played. If this is set to
833 zero, then the tone is not played.
834 @param aToneOffLength
835 The period over which the no tone will be played.
837 The period over which the tone playing will be paused.
839 IMPORT_C void SetDTMFLengths(TTimeIntervalMicroSeconds32& aToneOnLength,
840 TTimeIntervalMicroSeconds32& aToneOffLength,
841 TTimeIntervalMicroSeconds32& aPauseLength);
844 Defines the period over which the volume level is to rise smoothly from
845 nothing to the normal volume level.
847 The function is only available while the tone is playing.
850 The period over which the volume is to rise. A zero value causes
851 the tone sample to be played at the normal level for the full
852 duration of the playback. A value, which is longer than the duration
853 of the tone sample means that the sample never reaches its normal
856 IMPORT_C void SetVolumeRamp(const TTimeIntervalMicroSeconds& aRampDuration);
859 Defines the priority settings that should be used for this instance.
861 @param aPrioritySettings
862 A class type representing the client's priority, priority preference and state.
864 IMPORT_C void SetPrioritySettings(const TMMFPrioritySettings& aPrioritySettings);
867 Retrieves a custom interface to the device.
870 The interface UID, defined with the custom interface.
872 @return A pointer to the interface implementation, or NULL if the device does not
873 implement the interface requested. The return value must be cast to the
874 correct type by the user.The user should be careful while caching the custom interface pointer,
875 as in some situations the lower level custom interface pointer may become NULL.
877 IMPORT_C TAny* CustomInterface(TUid aInterfaceId);
880 Returns the number of available pre-defined tone sequences.
882 This is the number of fixed sequence supported by DevSound by default.
884 @return The fixed sequence count. This value is implementation dependent but is always greater
885 than or equal to zero.
887 IMPORT_C TInt FixedSequenceCount();
890 Returns the name assigned to a specific pre-defined tone sequence.
892 This is the number of the fixed sequence supported by DevSound by default.
894 The function raises a panic if sequence number specified is invalid.
896 @param aSequenceNumber
897 The index identifying the specific pre-defined tone sequence. Index values are relative
898 to zero. This can be any value from zero to the value returned by a call to
899 FixedSequenceCount() - 1.
900 The function raises a panic if sequence number is not within this
903 @return A reference to a Descriptor containing the fixed sequence name indexed by
906 @see FixedSequenceCount()
908 IMPORT_C const TDesC& FixedSequenceName(TInt aSequenceNumber);
911 Returns a list of the supported input datatypes that can be sent to DevSound for playing audio.
912 The datatypes returned are those that the DevSound supports given the priority settings passed
913 in aPrioritySettings.
915 Note that if no supported data types are found this does not constitute failure, the function will
916 return normally with no entries in aSupportedDataTypes.
918 @param aSupportedDataTypes
919 The array of supported data types that will be filled in by this function.
920 The supported data types of the DevSound are in the form of an array
921 of TFourCC codes. Any existing entries in the array will be overwritten on
922 calling this function. If no supported data types are found given the priority
923 settings, then the aSupportedDatatypes array will have zero entries.
924 @param aPrioritySettings
925 The priority settings used to determine the supported datatypes. Note this
926 does not set the priority settings. For input datatypes the iState member
927 of the priority settings would be expected to be either
928 EMMFStatePlaying or EMMFStatePlayingRecording. The priority settings may
929 effect the supported datatypes depending on the audio routing.
931 IMPORT_C void GetSupportedInputDataTypesL(RArray<TFourCC>& aSupportedDataTypes, const TMMFPrioritySettings& aPrioritySettings) const;
934 Returns a list of the supported output dataypes that can be received from DevSound for
935 recording audio. The datatypes returned are those that the DevSound supports given the priority
936 settings passed in aPrioritySettings.
938 Note that if no supported data types are found this does not constitute failure, the function will
939 return normally with no entries in aSupportedDataTypes.
941 @param aSupportedDataTypes
942 The array of supported data types that will be filled in by this function.
943 The supported datatypes of the DevSound are in the form of an array
945 Any existing entries in the array will be overwritten on calling this function.
946 If no supported datatypes are found given the priority settings, then
947 the aSupportedDatatypes array will have zero entries.
948 @param aPrioritySettings
949 The priority settings used to determine the supported data types. Note this
950 does not set the priority settings. For output data types the iState member
951 of the priority settings would expected to be either
952 EMMFStateRecording or EMMFStatePlayingRecording. The priority settings may
953 effect the supported datatypes depending on the audio routing.
955 IMPORT_C void GetSupportedOutputDataTypesL(RArray<TFourCC>& aSupportedDataTypes, const TMMFPrioritySettings& aPrioritySettings) const;
958 Registers the client for notification of resource avalibility.
961 The Notification event type for which the client needs notification.
962 @param aNotificationRegistrationData
963 The Notification Registration data has been reserved for future use and its value should be always NULL
964 @return An error code indicating if the function call was successful. KErrNone on success,
965 KErrNotSupported if the event type is not supported, KErrArgument if the notification data
966 is not null otherwise another of the system-wide error codes.
968 inline TInt RegisterAsClient(TUid aEventType, const TDesC8& aNotificationRegistrationData = KNullDesC8);
971 Cancels the Registered Notification.
974 The Event type need to cancel
975 @return An error code indicating if the function call was successful. KErrNone on success, KErrNotSupported
976 if the event type is not supported otherwise another of the system-wide error codes.
978 inline TInt CancelRegisterAsClient(TUid aEventType);
981 Returns the Notification data which the client needs to resume playing.
984 The Event type for which to get notification data
985 @param aNotificationData
986 The reference data for which the client needs to resume the play. The actual data depends on the event type.
987 Note that for the event type 'KMMFEventCategoryAudioResourceAvailable' the package buffer returned
988 is TMMFTimeIntervalMicroSecondsPckg,but the contents should be converted to an integer and
989 interpreted as the data returned is samples played ,but not as a microsecond value.
990 @return An error code indicating if the function call was successful. KErrNone on success, otherwise
991 another of the system-wide error codes.
993 inline TInt GetResourceNotificationData(TUid aEventType,TDes8& aNotificationData);
996 Wait for the clients to resume play back even after the default timeout expires.
997 Unless the client cancels the notification request or completes no other client gets
1000 @return An error code indicating if the function call was successful. KErrNone on success,
1001 KErrPermissionDenied if the client does not have MultimediaDD capaility, otherwise
1002 another of the system-wide error codes.
1004 inline TInt WillResumePlay();
1010 Empties the play buffers below DevSound without causing the codec to be deleted.
1012 @return An error code indicating if the function call was successful. KErrNone on success,
1013 KErrNotSupported if called in a mode other than EMMFStatePlaying or if the function is otherwise not supported,
1014 KErrNotReady if this is called before playing,
1015 otherwise another of the system-wide error codes.
1016 If this function is not supported, it is advised to use Stop().
1018 inline TInt EmptyBuffers();
1020 /** Cancels the initialization process of a CMMFDevSound object
1022 @return An error code indicating if the function call was successful.
1023 KErrNone on success,
1024 KerrNotReady if this is called before InitializeL() call or after
1025 the object has been initialized,
1027 inline TInt CancelInitialize();
1030 Sets client thread info for devsound to make proper policy and routing decisions
1033 The thread Id of real client.
1035 @capability MultimediaDD
1036 A process requires MultimediaDD capability to make this call.
1038 inline TInt SetClientThreadInfo(TThreadId aTid);
1041 Retrieves the current play time from the audio renderer
1044 A reference to TTimeIntervalMicroSeconds object which will be filled with the current play time by this function.
1045 @return An error code indicating if the function call was successful.
1046 KErrNone on success,
1047 KErrNotSupported if the underlying devsound implementation or the HwDevice does not support this API,
1048 otherwise any of the system-wide error codes.
1049 If this function is not supported, SamplesPlayed() needs to be used instead.
1051 @see IsGetTimePlayedSupported()
1053 inline TInt GetTimePlayed(TTimeIntervalMicroSeconds& aTime);
1056 This method can be used by devsound clients to check if the devsound implementation supports
1057 GetTimePlayed API. If this method returns EFalse, SamplesPlayed needs to be used.
1059 @return ETrue if the underlying devsound implementation supports GetTimePlayed API,
1060 EFalse if the the underlying devsound implementation does not support GetTimePlayed API
1062 @see GetTimePlayed()
1064 inline TBool IsGetTimePlayedSupported();
1067 This method can be used by devsound clients to check if the devsound implementation ignores the underflow
1068 errors from the sound driver and does not propagate them to its clients.
1070 @return ETrue if devsound ignores all the underflow errors from the sound driver except for the last buffer
1071 That means DevSound propagates the underflow error from sound driver to its clients only when
1072 client sets the last buffer flag on the CMMFBuffer type buffer.
1073 EFalse if devsound propagates the underflow errors from the sound driver in all the cases
1076 inline TBool QueryIgnoresUnderflow();
1079 This method can be used by devsound clients to check if current configuration supports resume
1080 This call is only valid when DevSound is initialized
1081 @return ETrue if current format does supports resume
1084 inline TBool IsResumeSupported();
1087 Resume play back, recording or tone playing after this has been paused
1088 @return An error code indicating if the function call was successful.
1089 KErrNone on success,
1090 KErrNotSupported if current format configuration does not support this functionality
1091 KErrNotReady if DevSound is not paused
1093 inline TInt Resume();
1098 Default Constructor.
1100 //So that nobody can extend derive from CMMFDevSound.
1104 Second phase constructor.
1116 inline void MDevSoundObserver::SendEventToClient(const TMMFEvent& /*aEvent*/)
1120 #include <mmf/server/sounddevice.inl>
1122 #endif // __SOUNDDEVICE_H__