inc/FMediaTonePlayer.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                        FMediaTonePlayer.h
  20  * @brief                       This is the header file for the %TonePlayer class.
  21  *
  22  * This header file contains the declarations of the %TonePlayer class.
  23  */
  24
  25 #ifndef _FMEDIA_TONE_PLAYER_H_
  26 #define _FMEDIA_TONE_PLAYER_H_
  27
  28 #include <FBaseColIList.h>
  29 #include <FMediaAudioTypes.h>
  30 #include <FMediaTone.h>
  31 #include <FMediaAudioManagerTypes.h>
  32 #include <FMediaITonePlayerEventListener.h>
  33
  34 namespace Tizen { namespace Media
  35 {
  36 class _TonePlayerImpl;
  37 /**
  38  * @class               TonePlayer
  39  * @brief               This class plays the tone(s).
  40  *
  41  * @since               2.0
  42  *
  43  * @remarks
  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.
  45  *
  46  * The %TonePlayer class provides methods for:
  47  * - Playing the tone(s)
  48  * - Controlling a tone player instance
  49  *
  50  * The following example demonstrates how to use the %TonePlayer class for playing a single tone and a list of tones.
  51  *
  52  * @code
  53  *
  54  * #include <FBase.h>
  55  * #include <FMedia.h>
  56  *
  57  * using namespace Tizen::Base;
  58  * using namespace Tizen::Base::Collection;
  59  * using namespace Tizen::Media;
  60  *
  61  * class TonePlayerSample
  62  *       : public ITonePlayerEventListener
  63  * {
  64  * public:
  65  *       result PlayTone(void);
  66  *       result PlayToneList(void);
  67  *       void Stop(void);
  68  *
  69  * protected:
  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) {}
  75  *
  76  * private:
  77  *       TonePlayer __player;
  78  *       LinkedList __toneList;
  79  * };
  80  *
  81  * result
  82  * TonePlayerSample::PlayTone(void)
  83  * {
  84  *       result r = E_SUCCESS;
  85  *       Tone *pTone = null;
  86  *
  87  *       pTone = new Tone(DTMF_PRESET_S, 2000);
  88  *
  89  *       __toneList.Add(*pTone);
  90  *
  91  *       // Constructs the TonePlayer
  92  *       __player.Construct(*this);
  93  *
  94  *       // Opens TonePlayer with a single tone
  95  *       __player.Open(*pTone, 5);
  96  *       r = __player.Play();
  97  *       if (IsFailed(r))
  98  *       {
  99  *               goto CATCH;
 100  *       }
 101  *
 102  *       return E_SUCCESS;
 103  *
 104  * CATCH:
 105  *       __toneList.RemoveAll(true);
 106  *       return r;
 107  * }
 108  *
 109  * result
 110  * TonePlayerSample::PlayToneList(void)
 111  * {
 112  *       result r = E_SUCCESS;
 113  *
 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)));
 120  *
 121  *       __player.Construct(*this);
 122  *
 123  *       // Opens TonePlayer with a tone list
 124  *       __player.Open(__toneList, 2);
 125  *
 126  *       r = __player.Play();
 127  *       if (IsFailed(r))
 128  *       {
 129  *               goto CATCH;
 130  *       }
 131  *
 132  *       return E_SUCCESS;
 133  *
 134  * CATCH:
 135  *       __toneList.RemoveAll(true);
 136  *       return r;
 137  * }
 138  *
 139  * void
 140  * TonePlayerSample::Stop(void)
 141  * {
 142  *       __player.Stop();
 143  *       __player.Close();
 144  *       __toneList.RemoveAll(true);
 145  * }
 146  *
 147  * @endcode
 148  */
 149
 150 class _OSP_EXPORT_ TonePlayer
 151         : public Tizen::Base::Object
 152 {
 153 public:
 154         /**
 155          * This is the default constructor for this class.
 156          *
 157          * @since               2.0
 158          *
 159          * @remarks             After creating an instance of this class, the Construct() method must be
 160          *                              called explicitly to initialize this instance
 161          * @see                 Construct()
 162          */
 163         TonePlayer(void);
 164
 165         /**
 166          * This is the destructor for this class. @n
 167          * All the allocated resources are released by this method. @n
 168          * This method must be called in the same thread as the Construct() method.
 169          *
 170          * @since               2.0
 171          *
 172          * @see                 Construct()
 173          */
 174         virtual ~TonePlayer(void);
 175
 176         /**
 177         * Initializes this instance of %TonePlayer with the specified listener.
 178         *
 179         * @since                2.0
 180         *
 181         * @return               An error code
 182         * @param[in]    listener                                                                                An instance of ITonePlayerEventListener
 183         * @exception    E_SUCCESS                                                                       The method is successful.
 184         * @exception    E_RESOURCE_UNAVAILABLE  The tone player's resources are unavailable.
 185         * @exception    E_OUT_OF_MEMORY         The memory is insufficient.
 186         * @exception    E_SYSTEM                                                                                A system error has occurred.
 187         */
 188         result Construct(Tizen::Media::ITonePlayerEventListener& listener);
 189
 190         /**
 191         * Opens the specified list of tones.
 192         *
 193         * @since                2.0
 194         *
 195         * @return               An error code
 196         * @param[in]    toneList                        A list of Tone instances
 197         * @param[in]    repeatCount                     The number of times the list of tones should be played @n
 198         *                                                                       This number is greater than or equal to @c 1.
 199         * @exception    E_SUCCESS                                               The method is successful.
 200         * @exception    E_INVALID_STATE         This instance is in an invalid state for this method.
 201         * @exception    E_OBJ_NOT_FOUND         The specified tone instance cannot be found in the list.
 202         * @exception    E_OUT_OF_MEMORY         The memory is insufficient.
 203         * @exception    E_OUT_OF_RANGE                  The count is out of range.
 204         * @exception    E_SYSTEM                                                        A system error has occurred.
 205         * @remarks              The item(s) of the specified @c toneList should be an instance(s) of Tone.
 206         * @see                  Close()
 207         */
 208         result Open(const Tizen::Base::Collection::IList& toneList, int repeatCount = 1);
 209
 210         /**
 211         * Opens the specified tone.
 212         *
 213         * @since                2.0
 214         *
 215         * @return               An error code
 216         * @param[in]    tone                            The tone instance
 217         * @param[in]    repeatCount                     The number of times a tone should be played @n
 218         *                                                                       This number is greater than or equal to @c 1.
 219         * @exception    E_SUCCESS                                               The method is successful.
 220         * @exception    E_INVALID_STATE         This instance is in an invalid state for this method.
 221         * @exception    E_OUT_OF_MEMORY         The memory is insufficient.
 222         * @exception    E_OUT_OF_RANGE                  The count is out of range.
 223         * @exception    E_SYSTEM                                                        A system error has occurred.
 224         * @see                  Close()
 225         */
 226         result Open(const Tizen::Media::Tone& tone, int repeatCount = 1);
 227
 228         /**
 229         * Plays the playback or resumes the playback if Pause() has been called. @n
 230         * In case of the TONE_PLAYER_STATE_END_OF_TONE state, the tone(s) can be played again.
 231         *
 232         * @since                2.0
 233         *
 234         * @return               An error code
 235         * @exception    E_SUCCESS                                               The method is successful.
 236         * @exception    E_INVALID_STATE         This instance is in an invalid state for this method.
 237         * @exception    E_DEVICE_BUSY                           The device is busy for other operations.
 238         * @exception    E_SYSTEM                                                        A system error has occurred.
 239         * @remarks              The playback starts from the current position. If playback is paused, playback restarts from
 240         *                               the last position.
 241         * @see                  Stop(), Pause()
 242         */
 243         result Play(void);
 244
 245         /**
 246         * Stops the playback.
 247         *
 248         * @since                2.0
 249         *
 250         * @return               An error code
 251         * @exception    E_SUCCESS                                               The method is successful.
 252         * @exception    E_INVALID_STATE         This instance is in an invalid state for this method.
 253         * @exception    E_SYSTEM                                                        A system error has occurred.
 254         * @see                  Play(), Pause()
 255         */
 256         result Stop(void);
 257
 258         /**
 259         * Pauses the playback. @n
 260         * To resume the paused playback, call Play().
 261         *
 262         * @since                2.0
 263         *
 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.
 268         * @see                  Play(), Stop()
 269         */
 270         result Pause(void);
 271
 272
 273         /**
 274         * Sets the volume level.
 275         *
 276         * @since                2.0
 277         *
 278         * @return               An error code
 279         * @param[in]    volume                          The new value for 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.
 284         * @see                  GetVolume()
 285         */
 286         result SetVolume(int volume);
 287
 288         /**
 289         * Gets the current volume level
 290         *
 291         * @since                2.0
 292         *
 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.
 296         * @see                  SetVolume()
 297         */
 298         int GetVolume(void) const;
 299
 300         /**
 301         * Closes the tone player.
 302         *
 303         * @since                2.0
 304         *
 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.
 309         * @see                  Open()
 310         */
 311         result Close(void);
 312
 313         /**
 314         * Gets the current state of the tone player instance.
 315         *
 316         * @since                2.0
 317         *
 318         * @return               The current state of the tone player
 319         */
 320         TonePlayerState GetState(void) const;
 321
 322         /**
 323         * Sets audio stream type for tone playback
 324         *
 325         * @since                2.0
 326         *
 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                           A specified input parameter is invalid.
 332         * @remarks      This method should be called before Open().
 333         */
 334         result SetAudioStreamType(AudioStreamType type);
 335
 336 private:
 337         TonePlayer(const TonePlayer& rhs);
 338         TonePlayer& operator =(const TonePlayer& rhs);
 339
 340         friend class _TonePlayerImpl;
 341         _TonePlayerImpl* __pTonePlayerImpl;
 342 };
 343
 344 }} // Tizen::Media
 345
 346 #endif