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 FMediaTonePlayer.h
20 * @brief This is the header file for the %TonePlayer class.
22 * This header file contains the declarations of the %TonePlayer class.
25 #ifndef _FMEDIA_TONE_PLAYER_H_
26 #define _FMEDIA_TONE_PLAYER_H_
28 #include <FBaseColIList.h>
29 #include <FMediaAudioTypes.h>
30 #include <FMediaTone.h>
31 #include <FMediaAudioManagerTypes.h>
32 #include <FMediaITonePlayerEventListener.h>
34 namespace Tizen { namespace Media
36 class _TonePlayerImpl;
39 * @brief This class plays the tone(s).
44 * The maximum number of the %TonePlayer instance is limited by Media::MediaCapability class. This number is a system wide count so that the application should not be able to construct instances more than the maximum number.
46 * The %TonePlayer class provides methods for:
47 * - Playing the tone(s)
48 * - Controlling a tone player instance
50 * The following example demonstrates how to use the %TonePlayer class for playing a single tone and a list of tones.
57 * using namespace Tizen::Base;
58 * using namespace Tizen::Base::Collection;
59 * using namespace Tizen::Media;
61 * class TonePlayerSample
62 * : public ITonePlayerEventListener
65 * result PlayTone(void);
66 * result PlayToneList(void);
70 * virtual void OnTonePlayerAudioFocusChanged (Tizen::Media::TonePlayer &src) {}
71 * virtual void OnTonePlayerEndOfTone(TonePlayer& src) {}
72 * virtual void OnTonePlayerInterrupted(TonePlayer& src) {}
73 * virtual void OnTonePlayerReleased(TonePlayer& src) {}
74 * virtual void OnTonePlayerErrorOccurred(TonePlayer& src, result r) {}
77 * TonePlayer __player;
78 * LinkedList __toneList;
82 * TonePlayerSample::PlayTone(void)
84 * result r = E_SUCCESS;
87 * pTone = new Tone(DTMF_PRESET_S, 2000);
89 * __toneList.Add(*pTone);
91 * // Constructs the TonePlayer
92 * __player.Construct(*this);
94 * // Opens TonePlayer with a single tone
95 * __player.Open(*pTone, 5);
96 * r = __player.Play();
105 * __toneList.RemoveAll(true);
110 * TonePlayerSample::PlayToneList(void)
112 * result r = E_SUCCESS;
114 * // Adds some tones to the tone list
115 * __toneList.Add(*(new Tone(DTMF_PRESET_1, 2000)));
116 * __toneList.Add(*(new Tone(2000, 5000, 3000)));
117 * __toneList.Add(*(new Tone(DTMF_PRESET_8, 500)));
118 * __toneList.Add(*(new Tone(0, 0, 1500))); // Silence
119 * __toneList.Add(*(new Tone(10000, 14000, 2500)));
121 * __player.Construct(*this);
123 * // Opens TonePlayer with a tone list
124 * __player.Open(__toneList, 2);
126 * r = __player.Play();
135 * __toneList.RemoveAll(true);
140 * TonePlayerSample::Stop(void)
144 * __toneList.RemoveAll(true);
150 class _OSP_EXPORT_ TonePlayer
151 : public Tizen::Base::Object
155 * This is the default constructor for this class.
159 * @remarks After creating an instance of this class, the Construct() method must be
160 * called explicitly to initialize this instance
165 * This is the destructor for this class. @n
166 * All the allocated resources are released by this method. @n
167 * This method must be called in the same thread as the Construct() method.
172 virtual ~TonePlayer(void);
175 * Initializes this instance of %TonePlayer with the specified listener.
179 * @return An error code
180 * @param[in] listener An instance of ITonePlayerEventListener
181 * @exception E_SUCCESS The method is successful.
182 * @exception E_RESOURCE_UNAVAILABLE The tone player's resources are unavailable.
183 * @exception E_OUT_OF_MEMORY The memory is insufficient.
184 * @exception E_SYSTEM A system error has occurred.
186 result Construct(Tizen::Media::ITonePlayerEventListener& listener);
189 * Opens the specified list of tones.
193 * @return An error code
194 * @param[in] toneList A list of Tone instances
195 * @param[in] repeatCount The number of times the list of tones should be played @n
196 * This number is greater than or equal to @c 1.
197 * @exception E_SUCCESS The method is successful.
198 * @exception E_INVALID_STATE This instance is in an invalid state for this method.
199 * @exception E_OBJ_NOT_FOUND The specified tone instance cannot be found in the list.
200 * @exception E_OUT_OF_MEMORY The memory is insufficient.
201 * @exception E_OUT_OF_RANGE The count is out of range.
202 * @exception E_SYSTEM A system error has occurred.
203 * @remarks The item(s) of the specified @c toneList must be an instance(s) of Tone.
206 result Open(const Tizen::Base::Collection::IList& toneList, int repeatCount = 1);
209 * Opens the specified tone.
213 * @return An error code
214 * @param[in] tone The tone instance
215 * @param[in] repeatCount The number of times a tone should be played @n
216 * This number is greater than or equal to @c 1.
217 * @exception E_SUCCESS The method is successful.
218 * @exception E_INVALID_STATE This instance is in an invalid state for this method.
219 * @exception E_OUT_OF_MEMORY The memory is insufficient.
220 * @exception E_OUT_OF_RANGE The count is out of range.
221 * @exception E_SYSTEM A system error has occurred.
224 result Open(const Tizen::Media::Tone& tone, int repeatCount = 1);
227 * Plays the playback or resumes the playback if Pause() has been called. @n
228 * In case of the @c TONEPLAYER_STATE_ENDOFTONE state, the tone(s) can be played again.
232 * @return An error code
233 * @exception E_SUCCESS The method is successful.
234 * @exception E_INVALID_STATE This instance is in an invalid state for this method.
235 * @exception E_DEVICE_BUSY The device is busy for other operations.
236 * @exception E_SYSTEM A system error has occurred.
237 * @remarks The playback starts from the current position. If playback is paused, playback restarts from
245 * Stops the playback.
249 * @return An error code
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_SYSTEM A system error has occurred.
259 * Pauses the playback. @n
260 * To resume the paused playback, call Play().
264 * @return An error code
265 * @exception E_SUCCESS The method is successful.
266 * @exception E_INVALID_STATE This instance is in an invalid state for this method.
267 * @exception E_SYSTEM A system error has occurred.
274 * Sets the volume level.
278 * @return An error code
279 * @param[in] volume The new value for @c volume @n
280 * The range of this parameter is @c 0 to @c 100 and it is proportional to the current media sound volume level in setting.
281 * @exception E_SUCCESS The method is successful.
282 * @exception E_OUT_OF_RANGE The specified @c volume parameter is out of range.
283 * @exception E_INVALID_STATE This instance is in an invalid state for this method.
286 result SetVolume(int volume);
289 * Gets the current volume level.
293 * @return The current volume level @n
294 * The range of this return value is @c 0 to @c 100.
295 * @remarks If the @c volume is not set, the default volume @c 50 is returned.
298 int GetVolume(void) const;
301 * Closes the tone player.
305 * @return An error code
306 * @exception E_SUCCESS The method is successful.
307 * @exception E_INVALID_STATE This instance is in an invalid state for this method.
308 * @exception E_SYSTEM A system error has occurred.
314 * Gets the current state of the tone player instance.
318 * @return The current state of the tone player
320 TonePlayerState GetState(void) const;
323 * Sets an audio stream type for tone playback.
327 * @return An error code
328 * @param[in] type An audio stream type
329 * @exception E_SUCCESS The method is successful.
330 * @exception E_INVALID_STATE This instance is in an invalid state for this method.
331 * @exception E_INVALID_ARG The specified input parameter is invalid.
332 * @remarks This method should be called before Open().
334 result SetAudioStreamType(AudioStreamType type);
337 TonePlayer(const TonePlayer& rhs);
338 TonePlayer& operator =(const TonePlayer& rhs);
340 friend class _TonePlayerImpl;
341 _TonePlayerImpl* __pTonePlayerImpl;