Update contrib.
1 // Copyright (c) 2002-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 "Eclipse Public License v1.0"
5 // which accompanies this distribution, and is available
6 // at the URL "http://www.eclipse.org/legal/epl-v10.html".
8 // Initial Contributors:
9 // Nokia Corporation - initial contribution.
16 #ifndef MDAAUDIOSAMPLEEDITOR_H
17 #define MDAAUDIOSAMPLEEDITOR_H
23 #include <mmf/common/mmfbase.h>
24 #include <mmf/common/mmfaudio.h>
25 #include <mmf/common/mmfstandardcustomcommands.h>
26 #include <mmf/common/mmfdrmcustomcommands.h>
28 #include <mda/client/resource.h>
29 #include <mda/client/utility.h>
30 #include <mda/common/audio.h>
31 #include <mmfclntutility.h>
32 #include <mmf/common/mmfdurationinfocustomcommands.h>
40 * Dummy class - not supported in 7.0s
42 class CMdaAudioType : public CBase
48 IMPORT_C ~CMdaAudioType();
55 This class is used by both the audio recorder and audio converter. This class should not be used,
56 other than the TState enum.
58 Prior to 7.0s the pure virtual functions in this class were implemented virtual functions. In 7.0s
59 this changed, so now any classes derived from this one must implement the functions themselves.
61 @see CMdaAudioRecorderUtility
62 @see CMdaAudioConvertUtility
64 class CMdaAudioClipUtility : public CBase,
65 public MMMFClientUtility
69 Defines the possible state of the audio data sample.
73 /** The audio clip recorder or audio converter has been constructed but no file or descriptor
77 /** Files or descriptors are open but no playing or recording operation is in progress.
80 /** Audio sample data is playing.
83 /** New audio sample data is being recorded.
92 Returns the current state of the audio sample data.
94 @return The state of the audio sample data.
98 virtual TState State()=0;
103 Releases any currently open audio sample data.
107 virtual void Close()=0;
112 Begins playback of audio sample data at the current playback position using the current volume,
113 gain and priority settings.
117 virtual void PlayL()=0;
122 Starts appending new audio sample data.
124 The new audio sample data is appended to the existing audio sample data in the same format as
125 the existing audio sample data. If existing data is to be overwritten, then it should be cropped
126 to the appropriate length before appending the new data.
128 Note, before starting to record, make sure that the gain is set by calling
129 CMdaAudioRecorderUtility::SetGain(), as the initial gain is undefined. The gain might also
130 have been modified by another client application.
134 @see CMdaAudioRecorderUtility
135 @see CMdaAudioRecorderUtility::SetGain()
137 virtual void RecordL()=0;
142 Stops the playback or recording operation.
144 The operation is stopped at the current location. For a playback operation, the head is positioned at the last played data.
148 virtual void Stop()=0;
153 Deletes all audio sample data after the current head position. The effects of the function cannot be undone.
155 The function is synchronous and can leave if there is a problem. The leave code depends on the configuration.
159 virtual void CropL()=0;
164 Sets the head position.
166 The playback head is moved to a position which is defined in terms of a time interval measured
167 from the beginning of the audio sample data. A subsequent call to PlayL() starts from
173 virtual void SetPosition(const TTimeIntervalMicroSeconds& aPosition)=0;
178 Returns the current head position.
180 The head position is defined in terms of a time interval measured from the beginning of the audio sample data.
184 virtual const TTimeIntervalMicroSeconds& Position()=0;
189 Returns the recording time available for the selected file or descriptor and encoding format.
193 virtual const TTimeIntervalMicroSeconds& RecordTimeAvailable()=0;
198 Returns the duration of the audio sample data.
202 virtual const TTimeIntervalMicroSeconds& Duration()=0;
207 Defines a window on the audio sample data.
209 The window is defined in terms of a start and end position.
210 When the current playback position reaches the window end position, or Stop() is called, the
211 current playback position is set to the window start position and playback stops.
213 The current playback position is not affected by a call to SetPlayWindow() unless it is outside
214 the new playback window, in which case it is set to the window start or end position depending
215 on which one is closer.
217 The window persists until ClearPlayWindow() is called.
218 Loading new audio sample data without adjusting or clearing the window will result in
219 playback errors if the window is outside the new data.
222 The position defining the start of the window, measured in microseconds. If this
223 value is less than zero, it is set to zero. If this value is greater than aEnd,
224 then it is swapped with aEnd.
226 The position defining the end of the window, measured in microseconds. If this value
227 is greater than the value returned by Duration(), it is set to the value of Duration().
228 If this value is less than aStart, then it is swapped with aStart.
232 virtual void SetPlayWindow(const TTimeIntervalMicroSeconds& aStart, const TTimeIntervalMicroSeconds& aEnd)=0;
237 Removes any window defined on the audio sample data.
239 All subsequent playing, position setting and position querying requests are mapped to the whole of the audio sample data.
243 virtual void ClearPlayWindow()=0;
248 Sets the number of times the audio sample is to be repeated during the PlayL() operation.
250 A period of silence can follow each playing of the audio sample. The audio sample can be repeated
251 indefinitely or until stopped.
253 @param aRepeatNumberOfTimes
254 The number of times the audio sample, together with the trailing silence, is to
255 be repeated. If this is set to KMdaRepeatForever, then the audio sample, together with
256 the trailing silence, is repeated indefinitely. If this is set to zero, then the audio
257 sample is not repeated.
258 @param aTrailingSilence
259 The length of the trailing silence in microseconds.
263 virtual void SetRepeats(TInt aRepeatNumberOfTimes, const TTimeIntervalMicroSeconds& aTrailingSilence)=0;
268 This function is no longer supported. It is provided for binary compatibility with previous
269 releases and always leaves with KErrNotSupported.
271 @return Always returns NULL.
275 virtual CMdaAudioType* TypeL();
280 Sets the maximum size for a file that is being recorded.
282 When this limit is reached, MMF stops recording and notifies the client application. Notification is caused
283 by MMdaObjectStateChangeObserver::MoscoStateChangeEvent() with the error code KErrEof.
285 This function is provided so that applications such as recorders can limit the amount of file storage/memory
286 that should be allocated.
288 @param aMaxWriteLength
289 The maximum file size in kilobytes. If the default value is used, there is no maximum file size.
293 virtual void SetMaxWriteLength(TInt aMaxWriteLength = KMdaClipLocationMaxWriteLengthNone)=0;
298 Deletes all audio sample data from the beginning of the audio clip. The effects of the function cannot be undone.
300 The function is synchronous and can leave if there is a problem. The leave code depends on the configuration.
304 virtual void CropFromBeginningL()=0;
306 // Reserved functions - do not call - to allow virtual additional functions to be added to class
313 virtual void ClipUtil_Reserved3();
320 virtual void ClipUtil_Reserved4();
324 class CMMFMdaAudioRecorderUtility;
330 Plays back, records and edits audio sample data.
332 The class offers an interface to play, record and edit audio sample data. This data can be supplied
333 either in a file or as a descriptor. The functions that start and stop playback and recording are
334 defined in the base class CMdaAudioClipUtility.
336 While this class is abstract, the static NewL() function constructs, initialises and returns a
337 pointer to an instance of a concrete class derived from this abstract class. This concrete class
338 is part of the MMF implementation and is private.
341 class CMdaAudioRecorderUtility : public CMdaAudioClipUtility
346 Device mode. Used by SetAudioDeviceMode method which is not used from 7.0s
352 The default behaviour.
355 If a telephony call is in progress, an attempt is made to connect to the telephony downlink
356 plus the device microphone. If there is no telephony call in progress or a connection to the
357 telephony downlink fails, an attempt is made to connect to the device microphone only.
360 If a telephony call is in progress, an attempt is made to connect to the telephony uplink.
361 If there is no telephony call in progress or a connection to the telephony uplink fails, an
362 attempt is made to connect to the device speaker.
367 ETelephonyOrLocal = EDefault,
370 If a telephony call is in progress the audio source is the telephony downlink mixed with
371 the device microphone. If there is no telephony call in progress or a connection to the telephony
372 downlink fails, no attempt is made to connect to the microphone.
375 If a telephony call is in progress the audio sample data is played to the telephony uplink and
376 the device speaker. If there is no telephony call in progress or a connection to the telephony
377 uplink fails, no attempt is made to connect to the device speaker.
381 When recording, the audio source is the telephony downlink and is not mixed with the device microphone.
383 When playing, the audio sample data is played to the telephony uplink and is not mixed with the
386 ETelephonyNonMixed = 2,
388 When recording, the audio source is the device microphone.
390 When playing, the audio sample data is played to the device speaker.
395 virtual ~CMdaAudioRecorderUtility();
397 IMPORT_C static CMdaAudioRecorderUtility* NewL(
398 MMdaObjectStateChangeObserver& aObserver,
399 CMdaServer* aServer = NULL,
400 TInt aPriority = EMdaPriorityNormal,
401 TInt aPref = EMdaPriorityPreferenceTimeAndQuality);
403 virtual void OpenFileL(const TDesC& aFileName);
404 IMPORT_C void OpenFileL(const RFile& aFile);
406 IMPORT_C void OpenFileL(const TMMSource& aSource);
408 virtual void OpenDesL(const TDesC8& aDescriptor);
410 IMPORT_C void OpenDesL(TDes8& aDescriptor);
412 virtual void OpenL(TMdaClipLocation* aLocation,
413 TMdaClipFormat* aFormat,
414 TMdaPackage* aArg1 = NULL,
415 TMdaPackage* aArg2 = NULL);
417 virtual void SetAudioDeviceMode(TDeviceMode aMode);
419 virtual TInt MaxVolume();
421 virtual TInt MaxGain();
423 virtual TInt SetVolume(TInt aVolume);
425 virtual void SetGain(TInt aGain);
427 virtual void SetVolumeRamp(const TTimeIntervalMicroSeconds& aRampDuration);
429 IMPORT_C void OpenFileL(const TDesC& aFileName,
430 TUid aRecordControllerUid, // controller to use
431 TUid aPlaybackControllerUid=KNullUid, // playback controller (if different)
432 TUid aDestinationFormatUid=KNullUid, // Data format
433 TFourCC aDestinationDataType = KFourCCNULL); // data type for recording
435 IMPORT_C void OpenFileL(const RFile& aFile,
436 TUid aRecordControllerUid, // controller to use
437 TUid aPlaybackControllerUid=KNullUid, // playback controller (if different)
438 TUid aDestinationFormatUid=KNullUid, // Data format
439 TFourCC aDestinationDataType = KFourCCNULL); // data type for recording
441 IMPORT_C void OpenFileL(const TMMSource& aSource,
442 TUid aRecordControllerUid, // controller to use
443 TUid aPlaybackControllerUid=KNullUid, // playback controller (if different)
444 TUid aDestinationFormatUid=KNullUid, // Data format
445 TFourCC aDestinationDataType = KFourCCNULL); // data type for recording
447 IMPORT_C void OpenDesL(TDes8& aDescriptor,
448 TUid aRecordControllerUid, // controller to use
449 TUid aPlaybackControllerUid=KNullUid, // playback controller (if different)
450 TUid aDestinationFormatUid=KNullUid, // Data format
451 TFourCC aDestinationDataType = KFourCCNULL); // data type for recording
453 IMPORT_C void OpenUrlL(const TDesC& aUrl,
454 TInt aIapId, // internet access point
455 TUid aRecordControllerUid, // controller to use
456 TUid aPlaybackControllerUid=KNullUid, // playback controller (if different)
457 TUid aDestinationFormatUid=KNullUid, // Data format
458 TFourCC aDestinationDataType = KFourCCNULL); // data type for recording
460 IMPORT_C void OpenUrlL(const TDesC& aUrl,
461 TInt aIapId =KUseDefaultIap,
462 const TDesC8& aMimeType = KNullDesC8);
464 IMPORT_C TInt GetGain(TInt& aGain);
466 IMPORT_C TInt GetVolume(TInt& aVolume);
468 IMPORT_C TInt SetPlaybackBalance(TInt aBalance = KMMFBalanceCenter);
470 IMPORT_C TInt GetPlaybackBalance(TInt& aBalance);
472 IMPORT_C TInt SetRecordBalance(TInt aBalance = KMMFBalanceCenter);
474 IMPORT_C TInt GetRecordBalance(TInt& aBalance);
476 IMPORT_C TInt GetNumberOfMetaDataEntries(TInt& aNumEntries);
478 IMPORT_C CMMFMetaDataEntry* GetMetaDataEntryL(TInt aMetaDataIndex);
480 IMPORT_C void AddMetaDataEntryL(CMMFMetaDataEntry& aMetaDataEntry);
482 IMPORT_C TInt RemoveMetaDataEntry(TInt aMetaDataIndex);
484 IMPORT_C void ReplaceMetaDataEntryL(TInt aMetaDataIndex, CMMFMetaDataEntry& aMetaDataEntry);
486 IMPORT_C void SetPriority(TInt aPriority, TInt aPref);
490 IMPORT_C void GetSupportedDestinationDataTypesL(RArray<TFourCC>& aSupportedDataTypes);
492 IMPORT_C void SetDestinationDataTypeL(TFourCC aDataType);
494 IMPORT_C TFourCC DestinationDataTypeL();
498 IMPORT_C void SetDestinationBitRateL(TUint aBitRate);
500 IMPORT_C TUint DestinationBitRateL();
502 IMPORT_C TUint SourceBitRateL();
504 IMPORT_C void GetSupportedBitRatesL(RArray<TUint>& aSupportedBitRates);
506 // Sample rate support
508 IMPORT_C void SetDestinationSampleRateL(TUint aSampleRate);
510 IMPORT_C TUint DestinationSampleRateL();
512 IMPORT_C void GetSupportedSampleRatesL(RArray<TUint>& aSupportedSampleRates);
515 IMPORT_C void SetDestinationFormatL(TUid aFormatUid);
517 IMPORT_C TUid DestinationFormatL();
519 // Number of channels
520 IMPORT_C void SetDestinationNumberOfChannelsL(TUint aNumberOfChannels);
522 IMPORT_C TUint DestinationNumberOfChannelsL();
524 IMPORT_C void GetSupportedNumberOfChannelsL(RArray<TUint>& aSupportedNumChannels);
526 virtual TState State();
528 virtual void Close();
530 virtual void PlayL();
532 virtual void RecordL();
536 virtual void CropL();
538 virtual void SetPosition(const TTimeIntervalMicroSeconds& aPosition);
540 virtual const TTimeIntervalMicroSeconds& Position();
542 virtual const TTimeIntervalMicroSeconds& RecordTimeAvailable();
544 virtual const TTimeIntervalMicroSeconds& Duration();
546 IMPORT_C TMMFDurationInfo Duration(TTimeIntervalMicroSeconds& aDuration);
548 virtual void SetPlayWindow(const TTimeIntervalMicroSeconds& aStart, const TTimeIntervalMicroSeconds& aEnd);
550 virtual void ClearPlayWindow();
552 virtual void SetRepeats(TInt aRepeatNumberOfTimes, const TTimeIntervalMicroSeconds& aTrailingSilence);
554 virtual void SetMaxWriteLength(TInt aMaxWriteLength = KMdaClipLocationMaxWriteLengthNone);
556 virtual void CropFromBeginningL();
558 IMPORT_C void RegisterForAudioLoadingNotification(MAudioLoadingObserver& aCallback);
560 IMPORT_C void GetAudioLoadingProgressL(TInt& aPercentageComplete);
562 IMPORT_C const CMMFControllerImplementationInformation& AudioPlayControllerImplementationInformationL();
564 IMPORT_C const CMMFControllerImplementationInformation& AudioRecorderControllerImplementationInformationL();
566 IMPORT_C TInt RecordControllerCustomCommandSync(const TMMFMessageDestinationPckg& aDestination, TInt aFunction, const TDesC8& aDataTo1, const TDesC8& aDataTo2, TDes8& aDataFrom);
568 IMPORT_C TInt RecordControllerCustomCommandSync(const TMMFMessageDestinationPckg& aDestination, TInt aFunction, const TDesC8& aDataTo1, const TDesC8& aDataTo2);
570 IMPORT_C void RecordControllerCustomCommandAsync(const TMMFMessageDestinationPckg& aDestination, TInt aFunction, const TDesC8& aDataTo1, const TDesC8& aDataTo2, TDes8& aDataFrom, TRequestStatus& aStatus);
572 IMPORT_C void RecordControllerCustomCommandAsync(const TMMFMessageDestinationPckg& aDestination, TInt aFunction, const TDesC8& aDataTo1, const TDesC8& aDataTo2, TRequestStatus& aStatus);
574 IMPORT_C TInt PlayControllerCustomCommandSync(const TMMFMessageDestinationPckg& aDestination, TInt aFunction, const TDesC8& aDataTo1, const TDesC8& aDataTo2, TDes8& aDataFrom);
576 IMPORT_C TInt PlayControllerCustomCommandSync(const TMMFMessageDestinationPckg& aDestination, TInt aFunction, const TDesC8& aDataTo1, const TDesC8& aDataTo2);
578 IMPORT_C void PlayControllerCustomCommandAsync(const TMMFMessageDestinationPckg& aDestination, TInt aFunction, const TDesC8& aDataTo1, const TDesC8& aDataTo2, TDes8& aDataFrom, TRequestStatus& aStatus);
580 IMPORT_C void PlayControllerCustomCommandAsync(const TMMFMessageDestinationPckg& aDestination, TInt aFunction, const TDesC8& aDataTo1, const TDesC8& aDataTo2, TRequestStatus& aStatus);
582 IMPORT_C MMMFDRMCustomCommand* GetDRMCustomCommand();
584 IMPORT_C TInt RegisterAudioResourceNotification(MMMFAudioResourceNotificationCallback& aCallback,TUid aNotificationEventUid,const TDesC8& aNotificationRegistrationData = KNullDesC8);
586 IMPORT_C TInt CancelRegisterAudioResourceNotification(TUid aNotificationEventId);
588 IMPORT_C TInt WillResumePlay();
590 IMPORT_C TInt SetThreadPriorityPlayback(const TThreadPriority& aThreadPriority) const;
591 IMPORT_C TInt SetThreadPriorityRecord(const TThreadPriority& aThreadPriority) const;
593 IMPORT_C void UseSharedHeap();
595 CMMFMdaAudioRecorderUtility* iProperties;
598 class CMMFMdaAudioConvertUtility;
604 Converts the type, sample rate and format of audio data.
606 The audio sample data can be supplied either in a file or as a descriptor.
608 class CMdaAudioConvertUtility : public CMdaAudioClipUtility
612 IMPORT_C static CMdaAudioConvertUtility* NewL(
613 MMdaObjectStateChangeObserver& aObserver,
614 CMdaServer* aServer = NULL,
615 TInt aPriority = EMdaPriorityNormal,
616 TInt aPref = EMdaPriorityPreferenceTimeAndQuality);
618 virtual ~CMdaAudioConvertUtility();
620 virtual void OpenL(const TDesC& aPrimaryFile, const TDesC& aSecondaryFile);
622 virtual void OpenL(const TDesC& aPrimaryFile,
623 TMdaClipLocation* aLocation, // Normally file or descriptor
624 TMdaClipFormat* aFormat, // Data format
625 TMdaPackage* aArg1 = NULL, // Normally codec to use
626 TMdaPackage* aArg2 = NULL); // Normally audio settings
628 virtual void OpenL(TMdaClipLocation* aPriLocation,
629 TMdaClipLocation* aSecLocation,
630 TMdaClipFormat* aPriFormat,
631 TMdaClipFormat* aSecFormat,
632 TMdaPackage* aPriArg1 = NULL,
633 TMdaPackage* aPriArg2 = NULL,
634 TMdaPackage* aSecArg1 = NULL,
635 TMdaPackage* aSecArg2 = NULL);
637 // new controller based open
638 // N.B. this override is new and must NOT be made virtual. This is because
639 // it will break BC on the WINS build (due to the MS compiler grouping and
640 // reordering the overrides together in the vtable and _not_ using the
641 // declaration order!)
643 IMPORT_C void OpenL(TMdaClipLocation* aPriLocation,
644 TMdaClipLocation* aSecLocation,
647 TFourCC aDestDataType);
651 IMPORT_C void GetSupportedDestinationDataTypesL(RArray<TFourCC>& aSupportedDestinationDataTypes);
653 IMPORT_C void SetDestinationDataTypeL(TFourCC aDataType);
655 IMPORT_C TFourCC DestinationDataTypeL();
657 IMPORT_C TFourCC SourceDataTypeL();
660 IMPORT_C void SetDestinationBitRateL(TUint aBitRate);
662 IMPORT_C TUint DestinationBitRateL();
664 IMPORT_C void GetSupportedConversionBitRatesL(RArray<TUint>& aSupportedBitRates);
666 IMPORT_C TInt SourceBitRateL();
668 // Sample rate support
669 IMPORT_C void SetDestinationSampleRateL(TUint aSampleRate);
671 IMPORT_C TUint DestinationSampleRateL();
673 IMPORT_C void GetSupportedConversionSampleRatesL(RArray<TUint>& aSupportedSampleRates);
675 IMPORT_C TUint SourceSampleRateL();
678 IMPORT_C void SetDestinationFormatL(TUid aFormatUid);
680 IMPORT_C TUid DestinationFormatL();
682 IMPORT_C TUid SourceFormatL();
684 // Number of channels
685 IMPORT_C void SetDestinationNumberOfChannelsL(TUint aNumberOfChannels);
687 IMPORT_C TUint DestinationNumberOfChannelsL();
689 IMPORT_C void GetSupportedConversionNumberOfChannelsL(RArray<TUint>& aSupportedNumChannels);
691 IMPORT_C TUint SourceNumberOfChannelsL();
693 // New function ConvertL (PlayL and RecordL now deprecated for CMdaAudioConvertUtility)
694 IMPORT_C void ConvertL();
696 virtual TState State();
698 virtual void Close();
700 virtual void PlayL();
702 virtual void RecordL();
706 virtual void CropL();
708 virtual void SetPosition(const TTimeIntervalMicroSeconds& aPosition);
710 virtual const TTimeIntervalMicroSeconds& Position();
712 virtual const TTimeIntervalMicroSeconds& RecordTimeAvailable();
714 virtual const TTimeIntervalMicroSeconds& Duration();
716 virtual void SetPlayWindow(const TTimeIntervalMicroSeconds& aStart, const TTimeIntervalMicroSeconds& aEnd);
718 virtual void ClearPlayWindow();
720 virtual void SetRepeats(TInt aRepeatNumberOfTimes, const TTimeIntervalMicroSeconds& aTrailingSilence);
722 virtual void SetMaxWriteLength(TInt aMaxWriteLength = KMdaClipLocationMaxWriteLengthNone);
724 virtual void CropFromBeginningL();
726 IMPORT_C const CMMFControllerImplementationInformation& ControllerImplementationInformationL();
728 IMPORT_C TInt CustomCommandSync(const TMMFMessageDestinationPckg& aDestination, TInt aFunction, const TDesC8& aDataTo1, const TDesC8& aDataTo2, TDes8& aDataFrom);
730 IMPORT_C TInt CustomCommandSync(const TMMFMessageDestinationPckg& aDestination, TInt aFunction, const TDesC8& aDataTo1, const TDesC8& aDataTo2);
732 IMPORT_C void CustomCommandAsync(const TMMFMessageDestinationPckg& aDestination, TInt aFunction, const TDesC8& aDataTo1, const TDesC8& aDataTo2, TDes8& aDataFrom, TRequestStatus& aStatus);
734 IMPORT_C void CustomCommandAsync(const TMMFMessageDestinationPckg& aDestination, TInt aFunction, const TDesC8& aDataTo1, const TDesC8& aDataTo2, TRequestStatus& aStatus);
736 IMPORT_C TInt SetThreadPriority(const TThreadPriority& aThreadPriority) const;
738 IMPORT_C void UseSharedHeap();
740 CMMFMdaAudioConvertUtility* iProperties;