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