2 // Open Service Platform
3 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
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
9 // http://www.apache.org/licenses/LICENSE-2.0
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.
19 * @file FMediaIPlayerEventListener.h
20 * @brief This is the header file for the %IPlayerEventListener interface.
22 * This header file contains the declarations of the %IPlayerEventListener interface.
25 #ifndef _FMEDIA_IPLAYER_EVENT_LISTENER_H_
26 #define _FMEDIA_IPLAYER_EVENT_LISTENER_H_
28 #include <FBaseRtIEventListener.h>
29 #include <FMediaPlayerTypes.h>
31 namespace Tizen { namespace Media
35 * @interface IPlayerEventListener
36 * @brief This interface provides a listener for media playing events.
40 * @remarks OnPlayerInterrupted() is called when the application is interrupted by another application and OnPlayerReleased() event can be called at the end of interruption.
41 * OnPlayerAudioFocusChanged() is called when the application is interrupted by another application but the end of interruption is not notified.
42 * So, the application should handle both events to work properly on various sound scenarios between applications.
44 * The %IPlayerEventListener interface specifies the methods used to notify the status of the media player during the media playing events.
45 * The player engine works asynchronously. Therefore, it is important to implement this listener to ensure that the player flows correctly.
46 * When each operation of the Player is completed, an event is generated, and a method from this class is called.
48 * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/media/playing_audio.htm">Playing Audio</a> and
49 <a href="../org.tizen.native.appprogramming/html/guide/media/playing_video.htm">Playing Video</a>.
52 class _OSP_EXPORT_ IPlayerEventListener
53 : virtual public Tizen::Base::Runtime::IEventListener
58 * 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.
62 virtual ~IPlayerEventListener(void) {}
65 * Called when an audio/video content is opened asynchronously.
69 * @param[in] r The cause of the error
70 * @exception E_SUCCESS The method is successful.
71 * @exception E_SYSTEM A system error has occurred.
72 * @exception E_CONNECTION_FAILED The network connection has failed.
73 * @exception E_FILE_NOT_FOUND The file cannot be found or accessed.
74 * @exception E_UNSUPPORTED_FORMAT The specified format is not supported.
75 * @exception E_UNSUPPORTED_CODEC The specified codec is not supported.
76 * @exception E_OUT_OF_MEMORY The memory is insufficient.
77 * @exception E_RIGHT_EXPIRED The content right has expired.
78 * @exception E_RIGHT_NO_LICENSE The content has no license.
79 * @exception E_RIGHT_FUTURE_USE The content right is for future use.
80 * @exception E_DISPLAY_RIGHT_VIOLATED The display right is not valid for the specific output device. @b Since: @b 2.1
81 * @see Player::OpenFile()
82 * @see Player::OpenUrl()
83 * @see Player::OpenBuffer()
85 virtual void OnPlayerOpened(result r) = 0;
88 * Called when the Player reaches the end of the clip.
92 virtual void OnPlayerEndOfClip(void) = 0;
95 * Called when the position of the audio/video content moves asynchronously.
99 * @param[in] r The cause of the error
100 * @exception E_SUCCESS The method is successful.
101 * @exception E_SYSTEM A system error has occurred.
102 * @see Player::SeekTo()
105 virtual void OnPlayerSeekCompleted(result r){};
109 * Called when the streaming data is being buffered.
113 * @param[in] percent The percentage of buffering is completed
114 * @see Player::OpenUrl()
116 virtual void OnPlayerBuffering(int percent) = 0;
119 * Called when an error has occurred while the Player is working.
123 * @param[in] r A player error reason of type ::PlayerErrorReason
125 * - While playing streaming media, the player might throw an error like ::PLAYER_ERROR_CONNECTION_LOST,
126 * ::PLAYER_ERROR_STREAMING_TIMEOUT, ::PLAYER_ERROR_TRANSPORT, or ::PLAYER_ERROR_SERVER.
127 * - If the content includes invalid data, ::PLAYER_ERROR_INVALID_DATA may occur.
128 * @see PlayerErrorReason
130 virtual void OnPlayerErrorOccurred(Tizen::Media::PlayerErrorReason r) = 0;
134 * Called when the Player is being interrupted by a task of higher priority than the %Player.
138 virtual void OnPlayerInterrupted(void) = 0;
141 * Called when the interrupting Player has been released.
145 virtual void OnPlayerReleased(void) = 0;
147 * Called when an audio playback focus is changed to another application.
151 * - After the audio focus is being changed, the playback is paused or stopped and the state of this instance is changed to ::PLAYER_STATE_PAUSED or ::PLAYER_STATE_CLOSED.
152 * - User interaction with the device is required for an application in @c PLAYER_STATE_PAUSED state to resume playing.
153 * This is to avoid the occurrence of a race condition among applications that try to play without user interaction.
154 * - An application can not play again even in the state of @c PLAYER_STATE_PAUSED due to the application which has a higher priority.
156 virtual void OnPlayerAudioFocusChanged(void) {}
159 // This method is for internal use only. Using this method can cause behavioral, security-related, and consistency-related issues in the application.
161 // This method is reserved and may change its name at any time without prior notice.
165 virtual void IPlayerEventListener_Reserved1(void) {}
168 // This method is for internal use only. Using this method can cause behavioral, security-related, and consistency-related issues in the application.
170 // This method is reserved and may change its name at any time without prior notice.
174 virtual void IPlayerEventListener_Reserved2(void) {}