inc/FMediaITonePlayerEventListener.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                FMediaITonePlayerEventListener.h
  20  * @brief               This is the header file for the %ITonePlayerEventListener interface.
  21  *
  22  * This header file contains the declarations of the %ITonePlayerEventListener interface.
  23  */
  24
  25 #ifndef _FMEDIA_ITONE_PLAYER_EVENT_LISTENER_H_
  26 #define _FMEDIA_ITONE_PLAYER_EVENT_LISTENER_H_
  27
  28 #include <FBaseRtIEventListener.h>
  29 #include <FMediaTonePlayer.h>
  30
  31 namespace Tizen { namespace Media
  32 {
  33 class TonePlayer;
  34 /**
  35  * @interface   ITonePlayerEventListener
  36  * @brief               This interface provides a listener for the tone player events.
  37  *
  38  * @since               2.0
  39  *
  40  * @remarks                     The OnTonePlayerInterrupted() method is called when an application is interrupted by another application, and the OnTonePlayerReleased() method is called at the end of this interruption.
  41  * The OnTonePlayerAudioFocusChanged() method is called when an application is interrupted by another application, but the end of this interruption is not be notified.
  42  * So, an application must accordingly handle both the events when audio switching occurs between various applications.
  43  *
  44  * The %ITonePlayerEventListener interface specifies the methods used to notify the status of the tone player.
  45  */
  46
  47 class _OSP_EXPORT_ ITonePlayerEventListener
  48         : virtual public Tizen::Base::Runtime::IEventListener
  49 {
  50 public:
  51         /**
  52         * 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.
  53         *
  54         * @since                2.0
  55         */
  56         virtual ~ITonePlayerEventListener(void) {}
  57
  58         /**
  59         *       Called when the tone player reaches the end of the tone or the end of the list of tones.
  60         *
  61         *     @since            2.0
  62         *
  63         *       @param[in]      src             An instance of TonePlayer that fires the event
  64         *
  65         */
  66         virtual void OnTonePlayerEndOfTone(Tizen::Media::TonePlayer& src) = 0;
  67
  68         /**
  69         *       Called when the tone player is interrupted by a task of higher priority than the tone player.
  70         *
  71         *     @since            2.0
  72         *
  73         *       @param[in]      src             An instance of TonePlayer that fires the event
  74         *
  75         */
  76         virtual void OnTonePlayerInterrupted(Tizen::Media::TonePlayer& src) = 0;
  77
  78         /**
  79         *       Called when the interrupted tone player is released.
  80         *
  81         *     @since            2.0
  82         *
  83         *       @param[in]      src             An instance of TonePlayer that fires the event
  84         *
  85         */
  86         virtual void OnTonePlayerReleased(Tizen::Media::TonePlayer& src) = 0;
  87
  88         /**
  89         *       Called to notify an application that an error has occurred while the tone is played.
  90         *
  91         *   @since              2.0
  92         *
  93         *       @param[in]      src                                                                     An instance of TonePlayer that fires the event
  94         *       @param[in]      r                                                                       The cause of the error
  95         *       @exception      E_SYSTEM                                                        A system error has occurred.
  96         */
  97         virtual void OnTonePlayerErrorOccurred(Tizen::Media::TonePlayer& src, result r) = 0;
  98
  99         /**
 100         *       Called when an audio playback focus is changed to another application.
 101         *
 102         *       @since          2.0
 103         *
 104         *       @param[in]              src             An instance of TonePlayer that fires the event
 105         *       @remarks
 106         *                                       - After the audio focus is being changed, the playback is paused and the state of this instance is changed to ::TONE_PLAYER_STATE_PAUSED.
 107         *                                       - User interaction with the device is required for an application in @c TONE_PLAYER_STATE_PAUSED state to resume playing.
 108         *                                       This is to avoid the occurrence of a race condition among applications that try to play without user interaction.
 109         *                                       - An application cannot start playback again even in the state of @c TONE_PLAYER_STATE_PAUSED due to other applications which have a higher priority.
 110         */
 111         virtual void OnTonePlayerAudioFocusChanged(Tizen::Media::TonePlayer& src) {}
 112
 113 protected:
 114         //
 115         // This method is for internal use only. Using this method can cause behavioral, security-related, and consistency-related issues in the application.
 116         //
 117         // This method is reserved and may change its name at any time without prior notice.
 118         //
 119         // @since               2.0
 120         //
 121         virtual void ITonePlayerEventListener_Reserved1(void) {}
 122
 123         //
 124         // This method is for internal use only. Using this method can cause behavioral, security-related, and consistency-related issues in the application.
 125         //
 126         // This method is reserved and may change its name at any time without prior notice.
 127         //
 128         // @since               2.0
 129         //
 130         virtual void ITonePlayerEventListener_Reserved2(void) {}
 131
 132         //
 133         // This method is for internal use only. Using this method can cause behavioral, security-related, and consistency-related issues in the application.
 134         //
 135         // This method is reserved and may change its name at any time without prior notice.
 136         //
 137         // @since               2.0
 138         //
 139         virtual void ITonePlayerEventListener_Reserved3(void) {}
 140
 141 };
 142
 143 }}// Tizen::Media
 144
 145 #endif