inc/FMediaPlayer.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                        FMediaPlayer.h
  20  * @brief                       This is the header file for the %Player class.
  21  *
  22  * This header file contains the declarations of the %Player class.
  23  */
  24
  25 #ifndef _FMEDIA_PLAYER_H_
  26 #define _FMEDIA_PLAYER_H_
  27
  28 #include <FBaseObject.h>
  29 #include <FBaseString.h>
  30 #include <FBaseUtilUri.h>
  31 #include <FBaseByteBuffer.h>
  32 #include <FBaseObject.h>
  33 #include <FBaseColIMap.h>
  34 #include <FGrpBufferInfo.h>
  35 #include <FGrpVideoTexture.h>
  36 #include <FMediaPlayerTypes.h>
  37 #include <FMediaAudioTypes.h>
  38 #include <FMediaMediaStreamInfo.h>
  39 #include <FMediaAudioManagerTypes.h>
  40 #include <FMediaIPlayerEventListener.h>
  41 #include <FMediaIPlayerVideoEventListener.h>
  42 #include <FMediaIPlayerProgressiveDownloadListener.h>
  43
  44 namespace Tizen { namespace Media
  45 {
  46
  47 /**
  48  * @class       Player
  49  * @brief       This class provides methods to play audio and video.
  50  *
  51  * @since               2.0
  52  *
  53  * The %Player class provides methods to play audio and video, including:
  54  * - Playing the audio or video content stored in the local storage (internal and external memory).
  55  * - Playing the audio or video content stream from the content server over RTSP or HTTP.
  56  * - Operating general controls for the audio or video content, such as play, pause, resume, and stop.
  57  * - Moving the audio or video content on the basis of time.
  58  * - Controlling the volume of the audio or video content.
  59  * - Looping the audio or video content.
  60  * - Getting the duration of an audio or the video content.
  61  * - Playing back multiple audio streams.
  62  *
  63  * The maximum count of the %Player instance is limited by Media::MediaCapability class.
  64  *
  65  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/media/playing_audio.htm">Playing Audio</a> and <a href="../org.tizen.native.appprogramming/html/guide/media/playing_video.htm">Playing Video</a>.
  66  *
  67  * The following example demonstrates how to use the %Player class to play an audio or video file.
  68  *
  69  * @code
  70  * #include <FBase.h>
  71  * #include <FGraphics.h>
  72  * #include <FUi.h>
  73  * #include <FApp.h>
  74  * #include <FMedia.h>
  75  *
  76  * using namespace Tizen::Base;
  77  * using namespace Tizen::Graphics;
  78  * using namespace Tizen::Ui;
  79  * using namespace Tizen::Ui::Controls;
  80  * using namespace Tizen::Media;
  81  *
  82  * class PlayerSample
  83  *     : public Tizen::Ui::Controls::Form
  84  *     , public Tizen::Media::IPlayerEventListener
  85  *     , public Tizen::Media::IPlayerVideoEventListener
  86  * {
  87  * public:
  88  *     result StartVideo(void);
  89  *     result StartAudio(void);
  90  *     result StartVideoWithVideoEventListener(void);
  91  *     void Stop(void);
  92  *
  93  * protected:
  94  *     // IPlayerEventListener
  95  *     virtual void OnPlayerOpened(result r) {}
  96  *     virtual void OnPlayerEndOfClip(void) {}
  97  *     virtual void OnPlayerBuffering(int percent) {}
  98  *     virtual void OnPlayerErrorOccurred(PlayerErrorReason r) {}
  99  *     virtual void OnPlayerInterrupted(void) {}
 100  *     virtual void OnPlayerReleased(void) {}
 101  *     virtual void OnPlayerSeekCompleted(result r) {}
 102  *     virtual void OnPlayerAudioFocusChanged (void) {}
 103  *
 104  *     // IPlayerVideoEventListener
 105  *     virtual void OnVideoFrameDecoded(Player &src, BitmapPixelFormat bitmapPixelFormat, const Dimension &dim,
 106  *                                      const byte *pBuffer, int sizeOfBuffer, result r);
 107  *
 108  * private:
 109  *     Player __player;
 110  *     OverlayRegion *__pOverlay;
 111  * };
 112  *
 113  * PlayerSample::PlayerSample(void)
 114  * {
 115  *     __pOverlay = null;
 116  * }
 117  *
 118  * result
 119  * PlayerSample::StartVideo(void)
 120  * {
 121  *     result r = E_SUCCESS;
 122  *     Rectangle rect(0, 0, 320, 240);
 123  *     BufferInfo bufferInfo;
 124  *     String filePath = Tizen::App::App::GetInstance()->GetAppRootPath() + L"data/test.mp4";
 125  *
 126  *     // Gets OverlayRegion from this Form
 127  *     __pOverlay = GetOverlayRegionN(rect, OVERLAY_REGION_TYPE_NORMAL);
 128  *     if (__pOverlay == null)
 129  *     {
 130  *         return GetLastResult();
 131  *     }
 132  *
 133  *     __pOverlay->GetBackgroundBufferInfo(bufferInfo);
 134  *
 135  *     r = __player.Construct(*this, &bufferInfo);
 136  *     if (IsFailed(r))
 137  *     {
 138  *         goto CATCH;
 139  *     }
 140  *
 141  *     // Opens file synchronously
 142  *     r = __player.OpenFile(filePath, false);
 143  *     if (IsFailed(r))
 144  *     {
 145  *         goto CATCH;
 146  *     }
 147  *
 148  *     __player.SetLooping(true);
 149  *     __player.SetVolume(80);
 150  *
 151  *     r = __player.Play();
 152  *     if (IsFailed(r))
 153  *     {
 154  *         goto CATCH;
 155  *     }
 156  *
 157  *     return E_SUCCESS;
 158  *
 159  * CATCH:
 160  *     delete __pOverlay;
 161  *     __pOverlay = null;
 162  *     return r;
 163  * }
 164  *
 165  * result
 166  * PlayerSample::StartAudio(void)
 167  * {
 168  *     result r = E_SUCCESS;
 169  *     String filePath = Tizen::App::App::GetInstance()->GetAppRootPath() + L"data/test.mp3";
 170  *
 171  *     r = __player.Construct(*this);
 172  *     if (IsFailed(r))
 173  *     {
 174  *         return r;
 175  *     }
 176  *
 177  *     // Opens file synchronously
 178  *     r = __player.OpenFile(filePath, false);
 179  *     if (IsFailed(r))
 180  *     {
 181  *         return r;
 182  *     }
 183  *
 184  *     __player.SetVolume(80);
 185  *
 186  *     r = __player.Play();
 187  *     if (IsFailed(r))
 188  *     {
 189  *         return r;
 190  *     }
 191  *
 192  *     return E_SUCCESS;
 193  * }
 194  *
 195  * void
 196  * PlayerSample::Stop(void)
 197  * {
 198  *     __player.Stop();
 199  *     __player.Close();
 200  *     if (__pOverlay)
 201  *     {
 202  *         delete __pOverlay;
 203  *         __pOverlay = null;
 204  *     }
 205  * }
 206  *
 207  *
 208  * result
 209  * PlayerSample::StartVideoWithVideoEventListener(void)
 210  * {
 211  *     result r = E_SUCCESS;
 212  *     Rectangle rect(0, 0, 320, 240);
 213  *     String filePath = Tizen::App::App::GetInstance()->GetAppRootPath() + L"data/test.mp4";
 214  *
 215  *     r = __player.Construct(*this, *this);
 216  *     if (IsFailed(r))
 217  *     {
 218  *         return r;
 219  *     }
 220  *
 221  *     r = __player.OpenFile(filePath);
 222  *     if (IsFailed(r))
 223  *     {
 224  *         return r;
 225  *     }
 226  *
 227  *     // Gets OverlayRegion from this Form
 228  *     __pOverlay = GetOverlayRegionN(rect, OVERLAY_REGION_TYPE_NORMAL);
 229  *     if (__pOverlay == null)
 230  *     {
 231  *         return GetLastResult();
 232  *     }
 233  *
 234  *     r = __player.Play();
 235  *     if (IsFailed(r))
 236  *     {
 237  *         goto CATCH;
 238  *     }
 239  *
 240  *     return E_SUCCESS;
 241  *
 242  * CATCH:
 243  *     if (__pOverlay)
 244  *     {
 245  *         delete __pOverlay;
 246  *         __pOverlay = null;
 247  *     }
 248  *     return r;
 249  *  }
 250  *
 251  * void
 252  * PlayerSample::OnVideoFrameDecoded(Player &src, BitmapPixelFormat bitmapPixelFormat, const Dimension &dim,
 253  *                                   const byte *pBuffer, int sizeOfBuffer, result r)
 254  * {
 255  *     ByteBuffer buf;
 256  *     OverlayRegionBufferPixelFormat overlayPixelFormat;
 257  *
 258  *     if (IsFailed(r))
 259  *     {
 260  *         return;
 261  *     }
 262  *
 263  *     if (__pOverlay == null)
 264  *     {
 265  *         return;
 266  *     }
 267  *
 268  *     if (bitmapPixelFormat == BITMAP_PIXEL_FORMAT_ARGB8888)
 269  *     {
 270  *         overlayPixelFormat = OVERLAY_REGION_BUFFER_PIXEL_FORMAT_ARGB8888;
 271  *     }
 272  *     else if (bitmapPixelFormat == BITMAP_PIXEL_FORMAT_RGB565)
 273  *     {
 274  *         overlayPixelFormat = OVERLAY_REGION_BUFFER_PIXEL_FORMAT_RGB565;
 275  *     }
 276  *     else // Unsupported pixel format
 277  *     {
 278  *         return;
 279  *     }
 280  *
 281  *     buf.Construct(pBuffer, 0, sizeOfBuffer, sizeOfBuffer);
 282  *     __pOverlay->SetInputBuffer(buf, dim, overlayPixelFormat);
 283  * }
 284  *
 285  * @endcode
 286  *
 287  */
 288
 289 class _OSP_EXPORT_ Player
 290         : public Tizen::Base::Object
 291 {
 292 public:
 293         /**
 294         * The object is not fully constructed after this constructor is called. For full construction, the Construct() method must be called right after calling this constructor.
 295         *
 296         * @since                2.0
 297         *
 298         * @remarks      After creating an instance of this class, the Construct() method must be called explicitly to
 299         *           initialize this instance.
 300         */
 301         Player(void);
 302
 303         /**
 304         * This destructor overrides Tizen::Base::Object::~Object(). @n
 305         * This method deallocates the resources. This method must be called in the same thread as the Construct()
 306         * method.
 307         *
 308         * @since                2.0
 309         *
 310         * @see          Construct()
 311         */
 312         virtual ~Player(void);
 313
 314 public:
 315         /**
 316         * Initializes this instance of %Player with the specified parameters.
 317         *
 318         * @since                2.0
 319         *
 320         * @return               An error code
 321         * @param[in]    listener                                        An instance of IPlayerEventListener
 322         * @param[in]    pBufferInfo                                     The buffer information to display the video  @n
 323         *                                                                                       This information is essential to play a video but not required for an audio content.
 324         * @exception    E_SUCCESS                                                                               The method is successful.
 325         * @exception    E_SYSTEM                                                                                        A system error has occurred.
 326         * @exception    E_OUT_OF_MEMORY                                 The memory is insufficient.
 327         * @exception    E_RESOURCE_UNAVAILABLE          The player's resources are unavailable.
 328         * @remarks      Multiple instances of %Player can be constructed.
 329         */
 330         result Construct(IPlayerEventListener& listener, const Tizen::Graphics::BufferInfo* pBufferInfo = null);
 331
 332         /**
 333         * Opens an audio or video file to be played. @n
 334         * The %OpenFile() method works synchronously, but when the second parameter, @c isAsync is set to @c true, this method works asynchronously.
 335         * Note that a method that works asynchronously must implement a listener.
 336         *
 337         * @if OSPCOMPAT
 338         * @brief <i> [Compatibility] </i>
 339         * @endif
 340         * @since                2.0
 341         * @if OSPCOMPAT
 342         * @compatibility        This method has compatibility issues with %Tizen API versions@n
 343         *                                       For more information, see @ref CompIoPathPage "here".
 344         * @endif
 345         *
 346         * @return               An error code
 347         * @param[in]    mediaLocalPath                  The local file path of the media source
 348         * @param[in]    isAsync                                 Set to @c true for the asynchronous mode, @n
 349         *                                                                                       else @c false for the synchronous mode
 350         * @exception    E_SUCCESS                                                       The method is successful.
 351         * @exception    E_INVALID_STATE                 This instance is in an invalid state for this method.
 352         * @exception    E_SYSTEM                                                                A system error has occurred.
 353         * @exception    E_FILE_NOT_FOUND                        The specified file cannot be found or accessed.
 354         * @exception    E_INVALID_DATA          The specified file contains invalid data.
 355         * @exception    E_OUT_OF_MEMORY                 The memory is insufficient.
 356         * @exception    E_UNSUPPORTED_FORMAT                            The given content format is not supported.
 357         * @exception    E_RIGHT_EXPIRED                                 The content right has expired.
 358         * @exception    E_RIGHT_NO_LICENSE                              The content has no license.
 359         * @exception    E_RIGHT_FUTURE_USE                              The content right is for future use.
 360         * @see                          Close()
 361         */
 362         result OpenFile(const Tizen::Base::String& mediaLocalPath, bool isAsync = false);
 363
 364         /**
 365         * Opens an audio or video streaming content to play through the specified URL. @n
 366         * The %OpenUrl() method works synchronously, but when the second parameter @c isAsync is set to @c true,
 367         * this method works asynchronously. Note that a method that works asynchronously must implement a listener.
 368         *
 369         * @since                2.0
 370         *
 371         * @return               An error code
 372         * @param[in]    mediaUri                                The URI of the media source
 373         * @param[in]    isAsync                                 Set to @c true for the asynchronous mode, @n
 374         *                                                                               else @c false for the synchronous mode
 375         * @exception    E_SUCCESS                                                                       The method is successful.
 376         * @exception    E_INVALID_STATE       This instance is in an invalid state for this method.
 377         * @exception    E_CONNECTION_FAILED                     The network connection has failed.
 378         * @exception    E_UNSUPPORTED_PROTOCOL  The protocol is not supported.
 379         * @exception    E_SYSTEM                                                                                A system error has occurred.
 380         * @exception    E_FILE_NOT_FOUND                                        The remote file cannot be found or accessed.
 381         * @exception    E_UNSUPPORTED_FORMAT                            The given content format is not supported.
 382         * @exception    E_RIGHT_EXPIRED                                 The content right has expired.
 383         * @exception    E_RIGHT_NO_LICENSE                              The content has no license.
 384         * @exception    E_RIGHT_FUTURE_USE                              The content right is for future use.
 385         * @remarks      This method is not thread-safe when @c isAsync is @c false.
 386         * @remarks      Input URL should be encoded if there are non-alphanumeric characters in URL.
 387         * @see                  Close()
 388         */
 389         result OpenUrl(const Tizen::Base::Utility::Uri& mediaUri, bool isAsync = false);
 390
 391         /**
 392         * Opens an audio or video content to play on the memory. @n
 393         * The %OpenBuffer() method works synchronously, but when the second parameter @c isAsync is set to @c true, this method works asynchronously.
 394         * Note that a method that works asynchronously must implement a listener.
 395         *
 396         * @since                2.0
 397         *
 398         * @return               An error code
 399         * @param[in]    mediaBuffer                             A pointer to the media source in the external memory
 400         * @param[in]    isAsync                                 Set to @c true for asynchronous mode, @n
 401         *                                                                                       else @c false for synchronous mode
 402         * @exception    E_SUCCESS                                                               The method is successful.
 403         * @exception    E_INVALID_STATE         This instance is in an invalid state for this method.
 404         * @exception    E_SYSTEM                                                                        A system error has occurred.
 405         * @exception    E_OBJ_NOT_FOUND                         The specified media buffer cannot be found.
 406         * @exception    E_INVALID_DATA                     The specified buffer contains invalid data.
 407         * @exception    E_OUT_OF_MEMORY                         The memory is insufficient.
 408         * @exception    E_UNSUPPORTED_FORMAT                            The given content format is not supported.
 409         * @exception    E_RIGHT_EXPIRED                                 The content right has expired.
 410         * @exception    E_RIGHT_NO_LICENSE                              The content has no license.
 411         * @exception    E_RIGHT_FUTURE_USE                              The content right is for future use.
 412         * @see                          Close()
 413         */
 414         result OpenBuffer(const Tizen::Base::ByteBuffer& mediaBuffer, bool isAsync = false);
 415
 416         /**
 417         * Closes the audio or video content. @n
 418         * The %Close() method works synchronously.
 419         *
 420         * @since                2.0
 421         *
 422         * @return               An error code
 423         * @exception    E_SUCCESS                                                       The method is successful.
 424         * @exception    E_INVALID_STATE         This instance is in an invalid state for this method.
 425         * @exception    E_SYSTEM                                                                A system error has occurred.
 426         * @see                  OpenFile()
 427         * @see                  OpenBuffer()
 428         * @see                  OpenUrl()
 429         */
 430         result Close(void);
 431
 432         /**
 433         * Plays the audio or video content. @n
 434         * The playback starts from the current position. In case of the ::PLAYER_STATE_ENDOFCLIP player state, the audio or video content
 435         * is played again.
 436         *
 437         * @since                2.0
 438         *
 439         * @return               An error code
 440         * @exception    E_SUCCESS                                                               The method is successful.
 441         * @exception    E_INVALID_STATE                         This instance is in an invalid state for this method.
 442         * @exception    E_DEVICE_BUSY           The device cannot be approached because of other operations.
 443         * @exception    E_UNSUPPORTED_FORMAT    The specified format is not supported.
 444         * @exception    E_UNSUPPORTED_CODEC             The specified codec is not supported.
 445         * @exception    E_SYSTEM                                                                        A system error has occurred. @n
 446         *                                                                       If playback has been paused, it resumes from the last position. @n
 447         *                                                                       E_SYSTEM is returned when unsupported format or codec media data are received during streaming. @n
 448         *                                    E_SYSTEM is returned when the unsupport resolution is set for rendering .
 449         * @remarks              When this method is called after the %Player instance is created with the Construct() method that accepts the IPlayVideoEventListener
 450         * interface as a parameter, it delivers every video frame of a video content continuously until the state is changed to @c PLAYER_STATE_ENDOFCLIP,
 451         * or the Stop() or Pause() method is called .
 452         * @see                  Stop()
 453         * @see                  Pause()
 454         * @see                  IPlayerVideoEventListener
 455         */
 456         result Play(void);
 457
 458         /**
 459         * Stops the playback of the audio or video content. @n
 460         * The %Stop() method works synchronously.
 461         *
 462         * @since                2.0
 463         *
 464         * @return               An error code
 465         * @exception    E_SUCCESS                                                       The method is successful.
 466         * @exception    E_INVALID_STATE         This instance is in an invalid state for this method.
 467         * @exception    E_SYSTEM                                                                A system error has occurred.
 468         * @remarks              In the Real Time Streaming Protocol (RTSP), this method stops the media stream and requests the termination of the network session.
 469         * @see                  Play()
 470         * @see                  Pause()
 471         */
 472         result Stop(void);
 473
 474         /**
 475         * Pauses the playback of the audio or video content. @n
 476         * To resume the playback, the Play() method must be called. The %Pause() method works synchronously.
 477         *
 478         * @since                2.0
 479         *
 480         * @return               An error code
 481         * @exception    E_SUCCESS                                                       The method is successful.
 482         * @exception    E_INVALID_STATE         This instance is in an invalid state for this method.
 483         * @exception    E_SYSTEM                                                                A system error has occurred.
 484         * @see                  Play()
 485         * @see                  Stop()
 486         */
 487         result Pause(void);
 488
 489         /**
 490         * Gets the state of an audio or video player.
 491         *
 492         * @since                2.0
 493         *
 494         * @return               The current state of the player
 495         * @see                  Close()
 496         * @see                  Play()
 497         * @see                  Stop()
 498         * @see                  Pause()
 499         * @see                  PlayerState
 500         */
 501         PlayerState GetState(void) const;
 502
 503         /**
 504         * Gets the time for the current playback position of the audio or video content. @n
 505         * Accuracy of the retrieved time is determined by the subsystem (for example, the time slice of the OS scheduler,
 506         * time resolution of the audio or video codec, or implementation of the audio or video player).
 507         * Note that it must not be assumed that the %GetPosition() method can reach the exact position mentioned by GetDuration().
 508         *
 509         * @since                2.0
 510         *
 511         * @return               The current position of the player in milliseconds
 512         * @exception    E_SUCCESS                                                       The method is successful.
 513         * @exception    E_INVALID_STATE                 This instance is in an invalid state for this method.
 514         * @remarks              The specific error code can be accessed using the GetLastResult() method.
 515         * @see                  SeekTo()
 516         */
 517         long GetPosition(void) const;
 518
 519         /**
 520         * Seeks the current playback position of the audio or video content to the specified time. @n
 521         * The %SeekTo() method works asynchronously. @n
 522         * Note that a method that works asynchronously must implement a listener. @n
 523         * This method only works for the @c PLAYER_STATE_PLAYING, @c PLAYER_STATE_PAUSED, and @c PLAYER_STATE_OPENED(local file/buffer playback only) states of the player. @n
 524         * This method changes the playback position as well as the time value. @n
 525         * In video, it may not change position accurately.
 526         *
 527         * @since                2.0
 528         *
 529         * @return               An error code
 530         * @param[in]    msTime                          The time in milliseconds to move to the current playback position @n
 531         *                                                                       @c 0 indicates the starting position.
 532         * @exception    E_SUCCESS                                                       The method is successful.
 533         * @exception    E_INVALID_STATE         This instance is in an invalid state for this method. @n
 534         *                                                       While playing live streaming, this operation returns E_INVALID_STATE. @n
 535         *                                                               This method returns E_INVALID_STATE, if this method is called again before
 536         *                                                                       IPlayerEventListener::OnPlayerSeekCompleted() is called.
 537         * @exception    E_OUT_OF_RANGE                          The specified time is out of range.
 538         * @exception    E_INVALID_DATA          The media data is inappropriate for seeking.
 539         * @exception    E_SYSTEM                                                                A system error has occurred.
 540         * @remarks              For video, this method delivers one video frame on the specified position through the video
 541         *                               event. Before calling this method, the %Player instance must be created with the Construct()
 542         *                               method has a parameter of the IPlayVideoEventListener interface .
 543         * @see                  GetPosition()
 544         * @see                  IPlayerVideoEventListener
 545         */
 546         result SeekTo(long msTime);
 547
 548         /**
 549         * Gets the total running time of the media source.
 550         *
 551         * @since                2.0
 552         *
 553         * @return                       The running time of the media source in milliseconds
 554         * @exception            E_SUCCESS                                               The method is successful.
 555         * @exception            E_INVALID_STATE         This instance is in an invalid state for this method.
 556         * @remarks              The specific error code can be accessed using the GetLastResult() method. @n
 557         *                               While playing live streaming, this operation returns @c 0.
 558         * @remarks           This method is valid in the @c PLAYER_STATE_OPENED @c PLAYER_STATE_PLAYING @c PLAYER_STATE_PAUSED @c PLAYER_STATE_STOPPED states of this instance.
 559         * @see                  GetPosition()
 560         */
 561         long GetDuration(void) const;
 562
 563         /**
 564         * Sets the specified value for the volume of an audio or video player.
 565         *
 566         * @since                2.0
 567         *
 568         * @return               An error code
 569         * @param[in]    volume                  The new value of volume @n
 570         *                                                               The range of this parameter is @c 0 to @c 100 and it is proportional to the current media sound volume level in setting.
 571         * @exception    E_SUCCESS                                       The method is successful.
 572         * @exception    E_OUT_OF_RANGE          The specified @c volume is out of range.
 573         * @exception    E_INVALID_STATE         This instance is in an invalid state for this method.
 574         * @see                  GetVolume()
 575         * @see                  IsMuted()
 576         * @see                  SetMute()
 577         */
 578         result SetVolume(int volume);
 579
 580         /**
 581         * Gets the current volume of an audio or video player.
 582         *
 583         * @since                2.0
 584         *
 585         * @return               The current volume level @n
 586         *                               The range of this return value is @c 0 to @c 100.
 587         * @see                  SetVolume()
 588         * @see                  IsMuted()
 589         * @see                  SetMute()
 590         */
 591         int GetVolume(void) const;
 592
 593         /**
 594         * Sets the mute status of an audio or video player.
 595         *
 596         * @since                2.0
 597         *
 598         * @return               An error code
 599         * @param[in]    mute                            Set to @c true to mute the audio or video player, @n
 600         *                                                                       else @c false
 601         * @exception    E_SUCCESS                                               The method is successful.
 602         * @exception    E_INVALID_STATE         This instance is in an invalid state for this method.
 603         * @see                  GetVolume()
 604         * @see                  SetVolume()
 605         * @see                  IsMuted()
 606         */
 607         result SetMute(bool mute);
 608
 609         /**
 610         * Checks the mute status of an audio or video player.
 611         *
 612         * @since                2.0
 613         *
 614         * @return               @c true if the audio or video player is muted, @n
 615         *                               else @c false
 616         * @see                  GetVolume()
 617         * @see                  SetVolume()
 618         * @see                  SetMute()
 619         */
 620         bool IsMuted(void) const;
 621
 622         /**
 623         * Sets an audio or video player to be in a loop. @n
 624         * Sets the looping to @c true to continuously play the audio or video content.
 625         *
 626         * @since                2.0
 627         *
 628         * @return               An error code
 629         * @param[in]    looping             Set to @c true to play the audio or video content in a loop, @n
 630         *                                                                       else @c false
 631         * @exception    E_SUCCESS                                               The method is successful.
 632         * @exception    E_INVALID_STATE         This instance is in an invalid state for this method.
 633         * @remarks              In streaming, this method throws @c E_INVALID_STATE for the cost of network.
 634         * @see          IsLooping()
 635         */
 636         result SetLooping(bool looping);
 637
 638         /**
 639         * Checks whether the audio or video player is in a loop.
 640         *
 641         * @since                2.0
 642         *
 643         * @return               @c true if the audio or video player is in a loop, @n
 644         *                               else @c false
 645         * @see          SetLooping()
 646         */
 647         bool IsLooping(void) const;
 648
 649         /**
 650         * Gets the current media stream information.
 651         *
 652         * @since                2.0
 653         *
 654         * @return       A pointer to the MediaStreamInfo instance containing metadata for the current media stream
 655         * @exception    E_SUCCESS                                                               The method is successful.
 656         * @exception    E_INVALID_STATE     This instance is in an invalid state for this method.
 657         * @exception    E_INVALID_CONTENT   The content is inappropriate to compose media stream information.
 658         * @exception    E_SYSTEM            A system error has occurred.
 659         * @remarks       This method returns a stream information of the media, which is currently being opened.
 660         *               The specific error code can be accessed using the GetLastResult() method.
 661         *               This method is valid in the @c PLAYER_STATE_OPENED @c PLAYER_STATE_PLAYING @c PLAYER_STATE_PAUSED @c PLAYER_STATE_STOPPED states of this instance.
 662         */
 663         MediaStreamInfo* GetCurrentMediaStreamInfoN(void) const;
 664
 665         /**
 666         * Sets the rendering buffer for the video playback.
 667         *
 668         * @since                2.0
 669         *
 670         * @return       An error code
 671         * @param[in]    bufferInfo                      The buffer information to display the video
 672         * @exception    E_SUCCESS                                               The method is successful.
 673         * @exception    E_INVALID_STATE         This instance is in an invalid state for this method.
 674         * @exception    E_INVALID_ARG                           The specified input parameter is invalid.
 675         * @exception    E_SYSTEM                                                        A system error has occurred. @n
 676         *                                   E_SYSTEM is returned when the unsupport resolution is set for rendering .
 677         * @remarks      This method works for the @c PLAYER_STATE_OPENED, @c PLAYER_STATE_ENDOFCLIP, @c PLAYER_STATE_STOPPED, @c PLAYER_STATE_PAUSED, and @c PLAYER_STATE_PLAYING states of the player.
 678         * @remarks              This method throws @c E_INVALID_STATE after the player instance is constructed with IPlayerVideoEventListener.
 679         */
 680         result SetRenderingBuffer(const Tizen::Graphics::BufferInfo& bufferInfo);
 681
 682         /**
 683         * Initializes this instance of %Player with the specified parameters.
 684         *
 685         * @since                2.0
 686         *
 687         * @return       An error code
 688         * @param[in]    listener                    An IPlayerEventListener instance
 689         * @param[in]    videoListener               An IPlayerVideoEventListener instance
 690         * @exception    E_SUCCESS                   The method is successful.
 691         * @exception    E_SYSTEM                    A system error has occurred.
 692         * @exception    E_RESOURCE_UNAVAILABLE      The player's resources are unavailable.
 693         * @exception    E_OUT_OF_MEMORY             The memory is insufficient.
 694         * @remarks      This method constructs the %Player instance to render the video content into the buffer of the video event listener.
 695         */
 696         result Construct(IPlayerEventListener& listener, IPlayerVideoEventListener& videoListener);
 697
 698         /**
 699         * Captures the video frame. @n
 700         * The %CaptureVideo() method delivers one video frame of a video content by using the IPlayVideoEventListener interface only once in the %Player instance. @n
 701         * This method works only for the @c PLAYER_STATE_OPENED state of the %Player instance, and the state of the %Player instance is changed to @c PLAYER_STATE_PAUSED from @c PLAYER_STATE_OPENED after calling this method.
 702         *
 703         * @since                2.0
 704         *
 705         * @return       An error code
 706         * @exception    E_SUCCESS                                                                       The method is successful.
 707         * @exception    E_INVALID_STATE                                 This instance is in an invalid state for this method. @n
 708         *                                                                               This method throws E_INVALID_STATE if the %Player instance is
 709         *                                                                               constructed without IPlayerVideoEventListener.
 710         * @exception    E_INVALID_OPERATION             This method is invalid for the current media content.
 711         * @exception    E_SYSTEM                                                                        A system error has occurred.
 712         * @remarks      In the Real Time Streaming Protocol (RTSP), this method does not work properly.
 713         */
 714         result CaptureVideo(void);
 715
 716         /**
 717         * Sets the audio stream type.
 718         *
 719         * @since                2.0
 720         *
 721         * @return                 An error code
 722         * @param[in]    type                                            An audio stream type
 723         * @exception    E_SUCCESS                                       The method is successful.
 724         * @exception    E_INVALID_ARG                           The specified input parameter is invalid.
 725         * @exception    E_INVALID_STATE                                 This instance is in an invalid state for this method.
 726         * @remarks      This method works for the @c PLAYER_STATE_INITIALIZED or @c PLAYER_STATE_CLOSED states of the %Player instance.
 727         *                                                                        In other states of %Player instance, this method returns @c E_SUCCESS, but the audio stream type is not changed properly.
 728         */
 729         result SetAudioStreamType(AudioStreamType type);
 730
 731         /**
 732         * Opens an audio or video streaming content to play through the specified URL with the HTTP header. @n
 733         * The %OpenUrlAsync() method works asynchronously, thus application can call further methods of %Player after IPlayerEventListener::OnPlayerOpened() is called.
 734         *
 735         * @since                2.0
 736         *
 737         * @return                                                               An error code
 738         * @param[in]    url                                             The URL of the media source
 739         * @param[in]    pHeader                                 The list of field and value pairs that will be added in HTTP request header. @n
 740         The types of field and value are described in the Programming Guide. If @c null, then default values will be set.
 741         *
 742         * @exception    E_SUCCESS                               The method is successful.
 743         * @exception    E_INVALID_STATE                 This instance is in an invalid state for this method.
 744         * @exception    E_UNSUPPORTED_PROTOCOL  The protocol is not supported.
 745         * @exception    E_INVALID_ARG                   A specified input parameter is invalid.
 746         * @exception    E_OUT_OF_MEMORY                 The memory is insufficient.
 747         * @remarks      See Programming Guide for the detail information of supported HTTP header fields.
 748         * @see                  Close()
 749         */
 750         result OpenUrlAsync(const Tizen::Base::String& url, const Tizen::Base::Collection::IMap* pHeader = null);
 751
 752         /**
 753         * Opens an audio or video streaming content to play through the specified HTTP URL with the HTTP header for the progressive download playback. @n
 754         * The %OpenUrlAsync() method works asynchronously, thus application can call further methods of %Player after IPlayerEventListener::OnPlayerOpened() is called.
 755         * The content information of the media source must be located at the beginning of the file for the progressive download playback. Otherwise, it does not guarantee to play and download media stream properly.
 756         *
 757         * @since                2.0
 758         *
 759         * @return                                                               An error code
 760         * @param[in]    url                                             The URL of the media source
 761         * @param[in]    filePath                                The file path on local file system where the downloaded content will be saved
 762         * @param[in]    listener                                The download listener
 763         * @param[in]    pHeader                                 The list of field and value pairs that will be added in HTTP request header @n
 764         * The types of field and value are described in the Programming Guide.
 765         *                                                                               If @c null, then default values will be set.
 766         * @exception    E_SUCCESS                               The method is successful.
 767         * @exception    E_INVALID_STATE                 This instance is in an invalid state for this method.
 768         * @exception    E_UNSUPPORTED_PROTOCOL  The protocol is not supported.
 769         * @exception    E_INVALID_ARG                   A specified input parameter is invalid.
 770         * @exception    E_OUT_OF_MEMORY                 The memory is insufficient.
 771         * @remarks      The download will start when Play() is called.
 772         * @remarks      If the specified file name already exists, then the old file will be overwritten with the new one.
 773         * @remarks      See Programming Guide for the detail information of supported HTTP header fields.
 774         * @see                  Close()
 775         */
 776         result OpenUrlAsync(const Tizen::Base::String& url, const Tizen::Base::String& filePath, IPlayerProgressiveDownloadListener& listener, const Tizen::Base::Collection::IMap* pHeader = null);
 777
 778
 779         /**
 780         * Sets the interval of calling the progress event.
 781         *
 782         * @since                2.0
 783         *
 784         * @param[in]    percent                                 The progress period interval as a percentage value
 785         * @remark               If the server does not provide the information about the content size, progress event will occur randomly.
 786         * @remarks              If the percentage value is not set, @c 10 will be set as a default value.
 787         * @see                  IPlayerProgressiveDownloadListener::OnPlayerProgressiveDownloadInProgress()
 788         */
 789         void SetProgressiveDownloadIntervalByPercent(int percent);
 790
 791         /**
 792         * Initializes this instance of %Player with the specified parameters.
 793         *
 794         * @since                2.0
 795         *
 796         * @return        An error code
 797         * @param[in]   listener                        An IPlayerEventListener instance
 798         * @param[in]   videoTexture                  An VideoTexture instance
 799         * @exception    E_SUCCESS                The method is successful.
 800         * @exception    E_INVALID_ARG      A specified input parameter is invalid.
 801         * @exception    E_RESOURCE_UNAVAILABLE  The player's resources are unavailable.
 802         * @remarks      This method constructs the %Player instance to render the video content into the video texture area.
 803         */
 804         result Construct(IPlayerEventListener& listener, Tizen::Graphics::Opengl::VideoTexture& videoTexture);
 805 private:
 806         /**
 807          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 808          *
 809          *  @since              2.0
 810          */
 811         Player(const Player& rhs);
 812
 813         /**
 814          *The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 815          *
 816          * @since               2.0
 817          */
 818         Player& operator =(const Player& rhs);
 819
 820         friend class _PlayerImpl;
 821         class _PlayerImpl* __pPlayerImpl;
 822 };
 823
 824
 825 }} // Tizen::Media
 826
 827 #endif