inc/FMediaIAudioOutEventListener.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                        FMediaIAudioOutEventListener.h
  20  * @brief                       This is the header file for the %IAudioOutEventListener interface.
  21  *
  22  * This header file contains the declarations of the %IAudioOutEventListener interface.
  23  */
  24
  25 #ifndef _FMEDIA_IAUDIO_OUT_EVENT_LISTENER_H_
  26 #define _FMEDIA_IAUDIO_OUT_EVENT_LISTENER_H_
  27
  28 #include <FBaseRtIEventListener.h>
  29
  30 namespace Tizen { namespace Media
  31 {
  32 class AudioOut;
  33 /**
  34  * @interface   IAudioOutEventListener
  35  * @brief                       This interface represents a listener that receives the AudioOut related events.
  36  *
  37  * @since               2.0
  38  *
  39  * @remarks                     OnAudioOutInterrupted() is called when the application is interrupted by another application and OnAudioOutReleased() event can be called at the end of interruption.
  40  *                      OnAudioOutAudioFocusChanged() is called when the application is interrupted by another application but the end of interruption is not notified.
  41  *                      So, the application should handle both events to work properly on various sound scenarios between applications.
  42  *
  43  *  The %IAudioOutEventListener interface represents a listener that receives the AudioOut related events. The %AudioOut class works in asynchronous mode, and when the application plays audio data with the %AudioOut class,
  44  *  the caller must implement this interface to receive an event from %AudioOut.
  45  *
  46  *  For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/media/playing_pcm_audio.htm">Playing PCM Audio</a>.
  47  */
  48
  49 class _OSP_EXPORT_ IAudioOutEventListener
  50         : virtual public Tizen::Base::Runtime::IEventListener
  51 {
  52
  53 public:
  54         /**
  55         * This polymorphic destructor should be overridden if required. This way, the destructors of the derived classes are called when the destructor of this interface is called.
  56         *
  57         * @since                2.0
  58         */
  59         virtual ~IAudioOutEventListener(void) {}
  60
  61         /**
  62         *       Called when the device has written a buffer completely.
  63         *
  64         * @since                2.0
  65         *
  66         *       @param[in]      src     An instance of AudioOut that fires the event
  67         */
  68         virtual void OnAudioOutBufferEndReached(Tizen::Media::AudioOut& src) = 0;
  69
  70         /**
  71          *      Called when the output device is interrupted by a task of higher priority than AudioOut.
  72          *
  73          * @since               2.0
  74          *
  75          *      @param[in]      src                                                     An instance of AudioOut that fires the event
  76          */
  77         virtual void OnAudioOutInterrupted(Tizen::Media::AudioOut& src) = 0;
  78
  79         /**
  80          *      Called when the interrupted output device is released.
  81          *
  82          * @since               2.0
  83          *
  84          *      @param[in]      src                                                     An instance of AudioOut that fires the event
  85          */
  86         virtual void OnAudioOutReleased(Tizen::Media::AudioOut& src) = 0;
  87
  88         /**
  89         *   Called when an audio playback focus is changed to another application.
  90         *
  91         *  @since               2.0
  92         *
  93         *  @param[in]   src             An instance of AudioOut that fires the event
  94         *  @remarks
  95         *                               - After the audio focus is being changed, the playback is stopped and the state of this instance is changed to ::AUDIOOUT_STATE_STOPPED.
  96         *                               - User interaction with the device is required for an application in @c AUDIOOUT_STATE_STOPPED state to resume playing.
  97         *                               This is to avoid the occurrence of a race condition among applications that try to start without user interaction.
  98         *                               - An application cannot start playback again even in the state of @c AUDIOOUT_STATE_STOPPED due to other applications which have a higher priority.
  99         */
 100         virtual void OnAudioOutAudioFocusChanged(Tizen::Media::AudioOut& src) {}
 101 protected:
 102         //
 103         // This method is for internal use only. Using this method can cause behavioral, security-related, and consistency-related issues in the application.
 104         //
 105         // This method is reserved and may change its name at any time without prior notice.
 106         //
 107         // @since               2.0
 108         //
 109         virtual void IAudioOutEventListener_Reserved1(void){}
 110
 111         //
 112         // This method is for internal use only. Using this method can cause behavioral, security-related, and consistency-related issues in the application.
 113         //
 114         // This method is reserved and may change its name at any time without prior notice.
 115         //
 116         // @since               2.0
 117         //
 118         virtual void IAudioOutEventListener_Reserved2(void){}
 119
 120 };
 121
 122 }} // Tizen::Media
 123
 124 #endif