Tizen 2.0 Release
[framework/osp/media.git] / src / FMedia_AudioRecorderImpl.h
1 //
2 // Open Service Platform
3 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
4 //
5 // Licensed under the Apache License, Version 2.0 (the License);
6 // you may not use this file except in compliance with the License.
7 // You may obtain a copy of the License at
8 //
9 //     http://www.apache.org/licenses/LICENSE-2.0
10 //
11 // Unless required by applicable law or agreed to in writing, software
12 // distributed under the License is distributed on an "AS IS" BASIS,
13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 // See the License for the specific language governing permissions and
15 // limitations under the License.
16 //
17
18 /**
19  * @file                FMedia_AudioRecorderImpl.h
20  * @brief               This header file contains the declaration of the _AudioRecorder_Impl class.
21  */
22
23 #ifndef _FMEDIA_INTERNAL_AUDIORECORDER_IMPL_H_
24 #define _FMEDIA_INTERNAL_AUDIORECORDER_IMPL_H_
25
26 #include <FBaseColArrayListT.h>
27 #include <FMediaTypes.h>
28 #include <FMediaAudioRecorderTypes.h>
29 #include "FMedia_RecorderTypes.h"
30 #include "FMedia_RecorderTypes.h"
31
32 namespace Tizen { namespace Media
33 {
34 class AudioRecorder;
35 class IAudioRecorderEventListener;
36 class _AudioRecorderEvent;
37 class _RecorderManager;
38
39 /**
40  * @class       _AudioRecorderImpl
41  * @brief       This class records the audio data into a file.
42  */
43
44 class _AudioRecorderImpl
45         : public Tizen::Base::Object
46 {
47
48 public:
49         /**
50          * This is the default constructor for this class.
51          *
52          * @remarks             After creating an instance of this class, the Construct() method must be called explicitly to
53          *              initialize this instance.
54          * @see         Construct()
55          */
56         _AudioRecorderImpl(void);
57
58         /**
59          * This is the destructor for this class. @n
60          * All allocated resources are released by this method. This method should be called in the same thread in
61          * which the Construct() method is called.
62          *
63          * @see     Construct()
64          */
65         virtual ~_AudioRecorderImpl(void);
66
67
68 public:
69         /**
70         * Initializes this instance of %_AudioRecorderImpl with the specified listener.
71         *
72         * @return               An error code
73         * @param[in]    listener                        An event listener instance
74         * @exception    E_SUCCESS                       The method is successful.
75         * @exception    E_INVALID_STATE     This instance is in an invalid state for this method.
76         * @exception    E_SYSTEM                        A system error has occurred.
77         * @exception    E_DEVICE_BUSY           The device cannot be approached because of other operations.
78         */
79         result Construct(IAudioRecorderEventListener& listener);
80
81         /**
82         * Creates an audio file for the recording.
83         *
84         * @return               An error code
85         * @param[in]    destMediaPath                   The file destination to write @n
86         *                                                                               The available paths start with prefixes retrieved from the functions such as: @n
87         *                                                                               Tizen::App::App::GetInstance()->GetAppRootPath() @n
88         *                                                                               Tizen::System::Environment::GetMediaPath() @n
89         *                                                                               Tizen::System::Environment::GetExternalStoragePath()
90         * @param[in]    overwrite                   Set to @c true to overwrite a file if it already exists, @n
91         *                                                                               else @c false
92         * @exception    E_SUCCESS                               The method is successful.
93         * @exception    E_INVALID_STATE                 This instance is in an invalid state for this method.
94         * @exception    E_RESOURCE_UNAVAILABLE  The required path is unavailable.
95         * @exception    E_SYSTEM                                A system error has occurred.
96         * @exception    E_FILE_ALREADY_EXIST    The specified file already exists.
97         * @exception    E_STORAGE_FULL                  The storage is full.
98         * @exception    E_OUT_OF_MEMORY                 The memory is insufficient.
99         * @exception    E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
100         * @see Close()
101         */
102         result CreateAudioFile(const Tizen::Base::String& destMediaPath, bool overwrite);
103
104         /**
105         * Closes a file.
106         *
107         * @return               An error code
108         * @exception    E_SUCCESS                               The method is successful.
109         * @exception    E_INVALID_STATE                 This instance is in an invalid state for this method.
110         * @exception    E_SYSTEM                                A system error has occurred.
111         * @exception    E_OUT_OF_MEMORY                 The memory is insufficient.
112         * @exception    E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
113         * @see                  CreateAudioFile()
114         * @remarks      This method is synchronous.
115         */
116         result Close(void);
117
118         /**
119         * Starts recording or resumes a recording after Pause() is called.
120         *
121         * @return           An error code
122         * @exception    E_SUCCESS                               The method is successful.
123         * @exception    E_INVALID_STATE                 This instance is in an invalid state for this method.
124         * @exception    E_SYSTEM                                A system error has occurred.
125         * @exception    E_DEVICE_BUSY                   The device cannot be approached because of other operations.
126         * @exception    E_OUT_OF_MEMORY                 The memory is insufficient.
127         * @exception    E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
128         * @see                  Stop(), Pause()
129         */
130         result Record(void);
131
132         /**
133         * Stops a recording.
134         *
135         * @return               An error code
136         * @exception    E_SUCCESS                               The method is successful.
137         * @exception    E_INVALID_STATE                 This instance is in an invalid state for this method.
138         * @exception    E_SYSTEM                                A system error has occurred.
139         * @exception    E_OUT_OF_MEMORY                 The memory is insufficient.
140         * @exception    E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
141         * @see                  Record(), Pause()
142         */
143         result Stop(void);
144
145         /**
146         * Pauses a recording. @n
147         * To resume a recording after this method is called, the Record() method must be called.
148         *
149         * @return               An error code
150         * @exception    E_SUCCESS                               The method is successful.
151         * @exception    E_INVALID_STATE                 This instance is in an invalid state for this method.
152         * @exception    E_SYSTEM                                A system error has occurred.
153         * @exception    E_OUT_OF_MEMORY                 The memory is insufficient.
154         * @exception    E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
155         * @see                  Record(), Stop()
156         */
157         result Pause(void);
158
159         /**
160         * Cancels a recording operation without saving the data.
161         *
162         * @return           An error code
163         * @exception    E_SUCCESS                               The method is successful.
164         * @exception    E_INVALID_STATE                 This instance is in an invalid state for this method.
165         * @exception    E_SYSTEM                                A system error has occurred.
166         * @exception    E_OUT_OF_MEMORY                 The memory is insufficient.
167         * @exception    E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
168         * @remarks      If this method is called, the state is changed to ::RECORDER_STATE_STOPPING. @n
169         *                       After IAudioRecorderEventListener::OnAudioRecorderCanceled() is called, the state is changed
170         *                       to ::RECORDER_STATE_STOPPED.
171         * @see          Record(), Stop()
172         */
173         result Cancel(void);
174
175         /**
176         * Gets the state of an audio recorder.
177         *
178         * @return           The current state of an audio recorder
179         * @exception    E_SUCCESS                               The method is successful.
180         * @exception    E_INVALID_STATE                 This instance is in an invalid state for this method.
181         * @exception    E_OUT_OF_MEMORY                 The memory is insufficient.
182         * @exception    E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
183         * @remarks              The specific error code can be accessed using the GetLastResult() method.
184         * @see                  CreateAudioFile(), Close(), Record(), Stop(), Pause()
185         */
186         RecorderState GetState(void) const;
187
188         /**
189         * Gets the current recording time.
190         *
191         * @return           The value indicating the current recording time in milliseconds, @n
192         *                               else @c -1 if the recording has not started as yet
193         * @exception    E_SUCCESS                               The method is successful.
194         * @exception    E_INVALID_STATE                 This instance is in an invalid state for this method.
195         * @exception    E_OUT_OF_MEMORY                 The memory is insufficient.
196         * @exception    E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
197         * @remarks              The specific error code can be accessed using the GetLastResult() method.
198         */
199         long GetRecordingTime(void) const;
200
201         /**
202         * Gets the current recording size.
203         *
204         * @return               The value indicating the current recording size in bytes, @n
205         *                               else @c -1 if the recording has not started as yet
206         * @exception    E_SUCCESS                               The method is successful.
207         * @exception    E_INVALID_STATE                 This instance is in an invalid state for this method.
208         * @exception    E_OUT_OF_MEMORY                 The memory is insufficient.
209         * @exception    E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
210         * @remarks              The specific error code can be accessed using the GetLastResult() method.
211         */
212         long GetRecordingSize(void) const;
213
214         /**
215         * Sets the recording time limit for a file in milliseconds.
216         *
217         * @return               An error code
218         * @param[in]    msTime          The maximum recording time in milliseconds @n
219         *                                                       The time must be greater than @c 0.
220         * @exception    E_SUCCESS                               The method is successful.
221         * @exception    E_INVALID_STATE                 This instance is in an invalid state for this method.
222         * @exception    E_OUT_OF_RANGE                  The specified time is out of range.
223         * @exception    E_OUT_OF_MEMORY                 The memory is insufficient.
224         * @exception    E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
225         * @remarks              The default time is @c 60 seconds.
226         * @see                  GetMaxRecordingTime()
227         */
228         result SetMaxRecordingTime(long msTime);
229
230         /**
231         * Gets the recording time limit of a file in milliseconds.
232         *
233         * @return               A @c long value indicating the maximum recording time in milliseconds
234         * @exception    E_SUCCESS                               The method is successful.
235         * @exception    E_INVALID_STATE                 This instance is in an invalid state for this method.
236         * @exception    E_OUT_OF_MEMORY                 The memory is insufficient.
237         * @exception    E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
238         * @remarks              The specific error code can be accessed using the GetLastResult() method.
239         * @see                  SetMaxRecordingTime()
240         */
241         long GetMaxRecordingTime(void) const;
242
243         /**
244         * Sets the audio format of an audio recorder. @n
245         * Initially, the default format is set using the internal configuration.
246         *
247         * @return               An error code
248         * @param[in]    format          The audio format to set @n
249         *                                                       ::AUDIORECORDING_FORMAT_DEFAULT sets the system's default recording format.
250         * @exception    E_SUCCESS                               The method is successful.
251         * @exception    E_INVALID_STATE                 This instance is in an invalid state for this method.
252         * @exception    E_UNSUPPORTED_FORMAT    The specified format is not supported.
253         * @exception    E_OUT_OF_MEMORY                 The memory is insufficient.
254         * @exception    E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
255         * @see                  GetFormat()
256         */
257         result SetFormat(AudioRecordingFormat format);
258
259         /**
260         * Gets the audio recording format of an audio recorder.
261         *
262         * @return               The audio recording format, @n
263         *               else default format if SetFormat() is not called before calling this method
264         * @exception    E_SUCCESS                               The method is successful.
265         * @exception    E_INVALID_STATE                 This instance is in an invalid state for this method.
266         * @exception    E_OUT_OF_MEMORY                 The memory is insufficient.
267         * @exception    E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
268         * @remarks              The specific error code can be accessed using the GetLastResult() method.
269         * @see                  SetFormat()
270         */
271         AudioRecordingFormat GetFormat(void) const;
272
273         /**
274         * Sets the audio codec and the container of an audio recorder. @n
275         * Initially, the default codec and the container format are set using the internal configuration.
276         *
277         * @return               An error code
278         * @param[in]    audioCodec                              The audio codec to set
279         * @param[in]    container                               The media container to set
280         * @exception    E_SUCCESS                               The method is successful.
281         * @exception    E_INVALID_STATE                 This instance is in an invalid state for this method.
282         * @exception    E_UNSUPPORTED_CODEC             The specified codec is not supported.
283         * @exception    E_UNSUPPORTED_FORMAT    The specified container format is not supported.
284         * @exception    E_SYSTEM                                A system error has occurred.
285         * @exception    E_OUT_OF_MEMORY                 The memory is insufficient.
286         * @exception    E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
287         * @remarks              If the specified container does not support the specified codec, E_UNSUPPORTED_FORMAT may be thrown.
288         * @see                  GetFormat( CodecType& audioCodec, MediaContainerType& container ) const
289         */
290         result SetFormat(CodecType audioCodec, MediaContainerType container);
291
292         /**
293         * Gets the audio codec and container of an audio recorder.
294         *
295         * @return               An error code
296         * @param[out]   audioCodec                      The retrieved audio codec
297         * @param[out]   container                       The retrieved container
298         * @remarks              If SetFormat(CodecType audioCodec, MediaContainerType container) is not called before calling
299         *                               this method, the default codec and container are retrieved.
300         * @see                  SetFormat( CodecType audioCodec, MediaContainerType container )
301         */
302         void GetFormat(CodecType& audioCodec, MediaContainerType& container) const;
303
304         /**
305         * Gets a list of the supported audio codecs. @n
306         * Each list's item has a ::CodecType value.
307         *
308         * @return       A list of supported audio codecs, @n
309         *                               else @c null if no codec is supported or if an exception occurs
310         * @exception    E_SUCCESS                               The method is successful.
311         * @exception    E_INVALID_STATE                 This instance is in an invalid state for this method.
312         * @exception    E_SYSTEM                                A system error has occurred.
313         * @exception    E_OUT_OF_MEMORY                 The memory is insufficient.
314         * @exception    E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
315         * @remarks              The specific error code can be accessed using the GetLastResult() method. @n
316         *               The return value must be released by the caller.
317         * @see                  SetFormat(CodecType audioCodec, MediaContainerType container), GetFormat(CodecType&
318         *                               audioCodec, MediaContainerType& container) const
319         */
320         Tizen::Base::Collection::ArrayListT <CodecType>* GetSupportedCodecListN(void) const;
321
322         /**
323         * Gets a list of the supported containers. @n
324         * Each list's item has a ::MediaContainerType value.
325         *
326         * @return       A list of supported container list, @n
327         *                               else @c null if no container is supported or if an exception occurs
328         * @exception    E_SUCCESS                       The method is successful.
329         * @exception    E_INVALID_STATE         This instance is in an invalid state for this method.
330         * @exception    E_SYSTEM                        A system error has occurred.
331         * @exception    E_OUT_OF_MEMORY         The memory is insufficient.
332         * @exception    E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
333         * @remarks              The specific error code can be accessed using the GetLastResult() method. @n
334         *               The return value must be released by the caller.
335         * @see                  SetFormat(CodecType audioCodec, MediaContainerType container), GetFormat(CodecType&
336         *                               audioCodec, MediaContainerType& container) const
337         */
338         Tizen::Base::Collection::ArrayListT <MediaContainerType>* GetSupportedContainerListN(void) const;
339
340         /**
341         * Sets the audio recording quality of the audio recorder.
342         *
343         * @return               An error code
344         * @param[in]    quality                         The audio recording quality of the audio recorder @n
345         *                                                                       The default value is ::RECORDING_QUALITY_MEDIUM.
346         * @exception    E_SUCCESS                       The method is successful.
347         * @exception    E_INVALID_STATE         This instance is in an invalid state for this method.
348         * @exception    E_INVALID_ARG           The specified @c quality is not supported.
349         * @exception    E_OUT_OF_MEMORY         The memory is insufficient.
350         * @exception    E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
351         * @see                  GetQuality()
352         */
353         result SetQuality(RecordingQuality quality);
354
355         /**
356         * Gets the audio recording quality of the audio recorder.
357         *
358         * @return               The current audio recording quality of the audio recorder
359         * @exception    E_SUCCESS                               The method is successful.
360         * @exception    E_INVALID_STATE                 This instance is in an invalid state for this method.
361         * @exception    E_OUT_OF_MEMORY                 The memory is insufficient.
362         * @exception    E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
363         * @remarks              The specific error code can be accessed using the GetLastResult() method.
364         * @see                  SetQuality()
365         */
366         RecordingQuality GetQuality(void) const;
367
368         /**
369         * Enables or disables the mute state of an audio recorder.
370         *
371         * @return               An error code
372         * @param[in]    mute                The mute state @n
373         *                                                                       By default, the mute state is disabled.
374         * @exception    E_SUCCESS                       The method is successful.
375         * @exception    E_INVALID_STATE         This instance is in an invalid state for this method.
376         * @exception    E_OUT_OF_MEMORY         The memory is insufficient.
377         * @exception    E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
378         * @remarks              The audio recording continues even though the audio recorder is in the mute state.
379         * @see                  IsMuted()
380         */
381         result SetMute(bool mute);
382
383         /**
384         * Checks whether the mute state is enabled for an audio recorder.
385         *
386         * @return               @c true if the audio recorder is not recording any sound, @n
387         *                               else @c false
388         * @exception    E_SUCCESS                               The method is successful.
389         * @exception    E_INVALID_STATE                 This instance is in an invalid state for this method.
390         * @exception    E_OUT_OF_MEMORY                 The memory is insufficient.
391         * @exception    E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
392         * @remarks              The specific error code can be accessed using the GetLastResult() method.
393         * @see                  SetMute()
394         */
395         bool IsMuted(void) const;
396
397         /**
398         * Sets the state.
399         *
400         * @param[in]    state           new _AudioRecorder's state
401         */
402         void SetState(RecorderState state);
403
404         /**
405         * Sets the recording time
406         *
407         * @param[in]    recTime             recording time in milliseconds
408         */
409         void SetRecordingTime(long recTime);
410
411         /**
412         * Sets the recording size
413         *
414         * @param[in]    recSize             recording size in bytes
415         */
416         void SetRecordingSize(long recSize);
417
418         /**
419         * Gets the new media type from the old type.
420         *
421         * @param[in]    format          recording type
422         * @param[out]   codec           codec type matching the input format
423         * @param[out]   container       container type matching the input format
424         *
425         */
426         void GetMediaType(AudioRecordingFormat format, CodecType& codec, MediaContainerType& container) const;
427
428         /**
429         * Gets the old media type from the new type.
430         *
431         * @param[in]    container       container type
432         * @param[out]   format          format type  matching the input container
433         *
434         */
435         void GetMediaType(MediaContainerType container, AudioRecordingFormat& format) const;
436
437         /**
438         * Gets the recorder's state.
439         *
440         * @return           The state
441         *
442         */
443         recorder_state_e GetMmState(void) const;
444
445         /**
446         * Get the event processing object.
447         *
448         * @return       The event processing object.
449         * @remarks      This event is working synchronously.
450         */
451         _AudioRecorderEvent* GetEvent(void) const;
452
453         /**
454         * Message callback function
455         *
456         * @param[in]    previous         Previous recorder state
457         * @param[in]    current         Current recorder state
458         * @param[in]    byPolicy                true if the state is changed by policy, otherewise false
459         * @param[in]    pUserData               User data
460          */
461         static void StateChangedCb(recorder_state_e previous, recorder_state_e current, bool byPolicy, void* pUserData);
462
463         /**
464         * Recording Status callback function
465         *
466         * @param[in]    elapsedTime      recording time elapsed
467         * @param[in]    fileSize         size of file written
468         * @param[in]    pUserData        User data
469          */
470         static void RecordingStatusCb(unsigned long long elapsedTime, unsigned long long fileSize, void *pUserData);
471
472         /**
473         * Audio stream callback function
474         *
475         * @param[in]    pStream          Stream data
476         * @param[in]    format          Sample format
477         * @param[in]    channel         Sample channel
478         * @param[in]    timeStampl      The time stamp
479         * @param[in]    pUserData               User data
480          */
481         static void AudioStreamCb(void* pStream, int size, audio_sample_type_e format, int channel, unsigned int timeStamp, void *pUserData);
482
483         /**
484         * Limit reached callback function
485         *
486         * @param[in]    type          Limit reached reason
487         * @param[in]    pUserData               User data
488          */
489         static void LimitReachedCb(recorder_recording_limit_type_e type, void *pUserData);
490
491         /**
492         * Message callback function
493         *
494         * @param[in]    error                   Error reason
495         * @param[in]    state           Error state
496         * @param[in]    pUserData               User data
497          */
498         static void ErrorCb(recorder_error_e error, recorder_state_e state, void *pUserData);
499
500         /**
501         * Message callback function
502         *
503         * @param[in]    policy          The policy which occurs the interruption
504         * @param[in]    previous                Previous recorder state
505         * @param[in]    current         Current recorder state
506         * @param[in]    pUserData               User data
507          */
508         static void InterruptedCb(recorder_policy_e policy, recorder_state_e previous, recorder_state_e current, void *pUserData);
509
510         /**
511          * Function check fo this object is alive.
512          *
513          * @return              true if the object is alive, otherwise false.
514          */
515         static bool IsAlive(void);
516
517         /**
518          * Gets the Impl instance.
519          *
520          * @return              The pointer to %_AudioRecorderImpl
521          * @param[in]   pAudioRecorder          The %AudioRecorder pointer
522          */
523         static _AudioRecorderImpl* GetInstance(AudioRecorder *pAudioRecorder);
524
525         /**
526          * Gets the Impl instance.
527          *
528          * @return              The pointer to %_AudioRecorderImpl
529          * @param[in]   pAudioRecorder          The %AudioRecorder pointer
530          */
531         static const _AudioRecorderImpl* GetInstance(const AudioRecorder *pAudioRecorder);
532
533 private:
534         /**
535         * Converts the error from recorder to Result.
536         *
537         * @return       An error code
538         * @param[in]    err             recorder error
539         */
540         result ConvertResult(int err) const;
541
542         /**
543         * Transfer the state.
544         *
545         * @return       An error code
546         * @param[in]    mmDestState             recorder's destinationed state
547         * @param[in]    reason           state changed reason
548         * @remarks      This method makes the recorder's state change. @n
549         *                       Sometimes, acccording to this, Recorder's state is changed.
550         */
551         result ChangeStateTo(recorder_state_e mmDestState, _RecorderStateChangeReason reason);
552
553         /**
554         * Checks the operation is for completing.
555         *
556         * @return               The state change reason
557         * @remarks      If the Cancel() is called, this value is false, because the Record() is not completed.
558         */
559         _RecorderStateChangeReason GetStateChangeReason(void) const;
560
561         /**
562         * Re-load configuration.
563         *
564         * @return       An error code
565         * @param[in]    reload                  reload configuration field
566         * @exception    E_SUCCESS                               The method is successful.
567         * @exception    E_SYSTEM                                A system error has occurred.
568         * @remarks      Multiple configuration field can be set using reloadConf parameter appending.
569         */
570         result ReloadConfiguration(int reload);
571
572         _AudioRecorderImpl(const _AudioRecorderImpl&);
573         _AudioRecorderImpl& operator =(const _AudioRecorderImpl& _AudioRecorderImpl);
574
575         _AudioRecorderEvent* __pAudioRecorderEvent;
576         IAudioRecorderEventListener* __pAudioRecorderEventListener;
577         _RecorderManager* __pRecorderManager;
578         bool __isConstructed;
579         RecorderState __state;
580         long __recTime;
581         long __recSize;
582         long __maxTime;
583         AudioRecordingFormat __format;
584         CodecType __audioCodec;
585         MediaContainerType __container;
586         RecordingQuality __quality;
587         bool __mute;
588         _RecorderHandle __handle;
589         _RecorderStateChangeReason __stateChangeReason;
590         static bool __isUsed;
591 };
592
593 }}// Tizen::Media
594
595 #endif