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         * @see          Construct()
 301         */
 302         Player(void);
 303
 304         /**
 305         * This destructor overrides Tizen::Base::Object::~Object().
 306         * This method deallocates the resources. This method must be called in the same thread as the Construct()
 307         * method.
 308         *
 309         * @since                2.0
 310         *
 311         * @see          Construct()
 312         */
 313         virtual ~Player(void);
 314
 315 public:
 316         /**
 317         * Initializes this instance of %Player with the specified parameters.
 318         *
 319         * @since                2.0
 320         *
 321         * @return               An error code
 322         * @param[in]    listener                                        An instance of IPlayerEventListener
 323         * @param[in]    pBufferInfo                                     The buffer information to display the video  @n
 324         *                                                                                       This information is essential to play a video but not required for an audio content.
 325         * @exception    E_SUCCESS                                                                               The method is successful.
 326         * @exception    E_SYSTEM                                                                                        A system error has occurred.
 327         * @exception    E_OUT_OF_MEMORY                                 The memory is insufficient.
 328         * @exception    E_RESOURCE_UNAVAILABLE          The player's resources are unavailable.
 329         * @remarks      Multiple instances of %Player can be constructed.
 330         */
 331         result Construct(IPlayerEventListener& listener, const Tizen::Graphics::BufferInfo* pBufferInfo = null);
 332
 333         /**
 334         * Opens an audio or video file to be played. @n
 335         * This method works synchronously, but when the second parameter, @c isAsync is set to @c true, this method works asynchronously.
 336         * Note that a method that works asynchronously must implement a listener.
 337         *
 338         * @if OSPCOMPAT
 339         * @brief <i> [Compatibility] </i>
 340         * @endif
 341         * @since                2.0
 342         * @if OSPCOMPAT
 343         * @compatibility        This method has compatibility issues with OSP compatible applications. @n
 344         *                                       For more information, see @ref CompIoPathPage "here".
 345         * @endif
 346         *
 347         * @return                       An error code
 348         * @param[in]            mediaLocalPath                  The local file path of the media source
 349         * @param[in]            isAsync                                 Set to @c true for the asynchronous mode, @n
 350         *                                                                                       else @c false for the synchronous mode
 351         * @exception            E_SUCCESS                                                       The method is successful.
 352         * @exception            E_INVALID_STATE                 This instance is in an invalid state for this method.
 353         * @exception            E_SYSTEM                                                                A system error has occurred.
 354         * @exception            E_FILE_NOT_FOUND                        The specified file cannot be found or accessed.
 355         * @exception   E_INVALID_DATA           The specified file contains invalid data.
 356         * @exception            E_OUT_OF_MEMORY                 The memory is insufficient.
 357         * @see                          Close()
 358         */
 359         result OpenFile(const Tizen::Base::String& mediaLocalPath, bool isAsync = false);
 360
 361         /**
 362         * Opens an audio or video streaming content to play through the specified URL. @n
 363         * This method works synchronously, but when the second parameter @c isAsync is set to @c true,
 364         * this method works asynchronously. Note that a method that works asynchronously must implement a listener.
 365         *
 366         * @since                2.0
 367         *
 368         * @return               An error code
 369         * @param[in]    mediaUri                                The URL of the media source
 370         * @param[in]    isAsync                                 Set to @c true for the asynchronous mode, @n
 371         *                                                                               else @c false for the synchronous mode
 372         * @exception    E_SUCCESS                                                                       The method is successful.
 373         * @exception    E_INVALID_STATE       This instance is in an invalid state for this method.
 374         * @exception    E_CONNECTION_FAILED                     The network connection has failed.
 375         * @exception    E_UNSUPPORTED_PROTOCOL  The protocol is not supported.
 376         * @exception    E_SYSTEM                                                                                A system error has occurred.
 377         * @remarks      This method is not thread-safe when @c isAsync is @c false.
 378         * @remarks      Input URL should be encoded if there are non-alphanumeric characters in URL.
 379         * @see                  Close()
 380         */
 381         result OpenUrl(const Tizen::Base::Utility::Uri& mediaUri, bool isAsync = false);
 382
 383         /**
 384         * Opens an audio or video content to play on the memory. @n
 385         * This method works synchronously, but when the second parameter @c isAsync is set to @c true, this method works asynchronously.
 386         * Note that a method that works asynchronously must implement a listener.
 387         *
 388         * @since                2.0
 389         *
 390         * @return                       An error code
 391         * @param[in]            mediaBuffer                             A pointer to the media source in the external memory
 392         * @param[in]            isAsync                                 Set to @c true for asynchronous mode, @n
 393         *                                                                                       else @c false for synchronous mode
 394         * @exception            E_SUCCESS                                                               The method is successful.
 395         * @exception            E_INVALID_STATE         This instance is in an invalid state for this method.
 396         * @exception            E_SYSTEM                                                                        A system error has occurred.
 397         * @exception            E_OBJ_NOT_FOUND                         The specified media buffer cannot be found.
 398         * @exception   E_INVALID_DATA              The specified buffer contains invalid data.
 399         * @exception            E_OUT_OF_MEMORY                         The memory is insufficient.
 400         * @see                          Close()
 401         */
 402         result OpenBuffer(const Tizen::Base::ByteBuffer& mediaBuffer, bool isAsync = false);
 403
 404         /**
 405         * Closes the audio or video content. @n
 406         * This method works synchronously.
 407         *
 408         * @since                2.0
 409         *
 410         * @return               An error code
 411         * @exception    E_SUCCESS                                                       The method is successful.
 412         * @exception    E_INVALID_STATE         This instance is in an invalid state for this method.
 413         * @exception    E_SYSTEM                                                                A system error has occurred.
 414         * @see                  OpenFile(), OpenBuffer(), OpenUrl()
 415         */
 416         result Close(void);
 417
 418         /**
 419         * Plays the audio or video content. @n
 420         * The playback starts from the current position. In case of the ::PLAYER_STATE_ENDOFCLIP player state, the audio or video content
 421         * is played again.
 422         *
 423         * @since                2.0
 424         *
 425         * @return               An error code
 426         * @exception    E_SUCCESS                                                               The method is successful.
 427         * @exception    E_INVALID_STATE                         This instance is in an invalid state for this method.
 428         * @exception    E_DEVICE_BUSY                                           The device cannot be approached because of other applications which have a higher priority.
 429         * @exception    E_UNSUPPORTED_FORMAT    The specified format is not supported.
 430         * @exception    E_UNSUPPORTED_CODEC             The specified codec is not supported.
 431         * @exception    E_SYSTEM                                                                        A system error has occurred. @n
 432         *                                                                       If playback has been paused, it resumes from the last position. @n
 433         *                                                                       E_SYSTEM is returned when unsupported format or codec media data are received during streaming. @n
 434         *                                    E_SYSTEM is returned when the unsupport resolution is set for rendering .
 435         * @remarks              When this method is called after the %Player instance is created with the Construct() method that accepts the IPlayVideoEventListener
 436         * interface as a parameter, it delivers every video frame of a video content continuously until the state is changed to PLAYER_STATE_ENDOFCLIP,
 437         * or the Stop() or Pause() method is called .
 438         * @see                  Stop(), Pause(), IPlayerVideoEventListener
 439         */
 440         result Play(void);
 441
 442         /**
 443         * Stops the playback of the audio or video content. This method works synchronously.
 444         *
 445         * @since                2.0
 446         *
 447         * @return               An error code
 448         * @exception    E_SUCCESS                                                       The method is successful.
 449         * @exception    E_INVALID_STATE         This instance is in an invalid state for this method.
 450         * @exception    E_SYSTEM                                                                A system error has occurred.
 451         * @remarks              In the Real Time Streaming Protocol (RTSP), this method stops the media stream and requests the termination of the network session.
 452         * @see                  Play(), Pause()
 453         */
 454         result Stop(void);
 455
 456         /**
 457         * Pauses the playback of the audio or video content. @n
 458         * To resume the playback, the Play() method must be called. This method works synchronously.
 459         *
 460         * @since                2.0
 461         *
 462         * @return               An error code
 463         * @exception    E_SUCCESS                                                       The method is successful.
 464         * @exception    E_INVALID_STATE         This instance is in an invalid state for this method.
 465         * @exception    E_SYSTEM                                                                A system error has occurred.
 466         * @see                  Play(), Stop()
 467         */
 468         result Pause(void);
 469
 470         /**
 471         * Gets the state of an audio or video player.
 472         *
 473         * @since                2.0
 474         *
 475         * @return               The current state of the player
 476         * @see                  Close(), Play(), Stop(), Pause(), PlayerState
 477         */
 478         PlayerState GetState(void) const;
 479
 480         /**
 481         * Gets the time for the current playback position of the audio or video content. @n
 482         * Accuracy of the retrieved time is determined by the subsystem (for example, the time slice of the OS scheduler,
 483         * time resolution of the audio or video codec, or implementation of the audio or video player).
 484         * Note that it must not be assumed that this method can reach the exact position mentioned by GetDuration().
 485         *
 486         * @since                2.0
 487         *
 488         * @return               The current position of the player in milliseconds
 489         * @exception    E_SUCCESS                                                       The method is successful.
 490         * @exception    E_INVALID_STATE                 This instance is in an invalid state for this method.
 491         * @remarks              The specific error code can be accessed using the GetLastResult() method.
 492         * @see                  SeekTo()
 493         */
 494         long GetPosition(void) const;
 495
 496         /**
 497         * Seeks the current playback position of the audio or video content to the specified time. @n
 498         * This method works asynchronously. @n
 499         * Note that a method that works asynchronously must implement a listener. @n
 500         * This method only works for the PLAYER_STATE_PLAYING, PLAYER_STATE_PAUSED and PLAYER_STATE_OPENED(local file/buffer playback only) states of the player. @n
 501         * This method changes the playback position as well as the time value. @n
 502         * In video, it may not change position accurately.
 503         *
 504         * @since                2.0
 505         *
 506         * @return               An error code
 507         * @param[in]    msTime                          The time in milliseconds to move to the current playback position @n
 508         *                                                                       @c 0 indicates the starting position.
 509         * @exception    E_SUCCESS                                                       The method is successful.
 510         * @exception    E_INVALID_STATE         This instance is in an invalid state for this method. @n
 511         *                                                       While playing live streaming, this operation returns E_INVALID_STATE. @n
 512         *                                                               This method returns E_INVALID_STATE, if this method is called again before
 513         *                                                                       IPlayerEventListener::OnPlayerSeekCompleted() is called.
 514         * @exception    E_OUT_OF_RANGE                          The specified time is out of range.
 515         * @exception    E_INVALID_DATA          The media data is inappropriate for seeking.
 516         * @exception    E_SYSTEM                                                                A system error has occurred.
 517         * @remarks              For video, this method delivers one video frame on the specified position through the video
 518         *                               event. Before calling this method, the %Player instance must be created with the Construct()
 519         *                               method has a parameter of the IPlayVideoEventListener interface .
 520         * @see                  GetPosition(),  IPlayerVideoEventListener
 521         */
 522         result SeekTo(long msTime);
 523
 524         /**
 525         * Gets the total running time of the media source.
 526         *
 527         * @since                2.0
 528         *
 529         * @return                       The running time of the media source in milliseconds
 530         * @exception            E_SUCCESS                                               The method is successful.
 531         * @exception            E_INVALID_STATE         This instance is in an invalid state for this method.
 532         * @remarks              The specific error code can be accessed using the GetLastResult() method. @n
 533         *                               While playing live streaming, this operation returns @c 0.
 534         * @remarks           This method is valid in the playing and paused state of this instance.
 535         * @see                  GetPosition()
 536         */
 537         long GetDuration(void) const;
 538
 539         /**
 540         * Sets the specified value for the volume of an audio or video player.
 541         *
 542         * @since                2.0
 543         *
 544         * @return               An error code
 545         * @param[in]    volume                  The new value of volume @n
 546         *                                                               The range of this parameter is @c 0 to @c 100 and it is proportional to the current media sound volume level in setting.
 547         * @exception    E_SUCCESS                                       The method is successful.
 548         * @exception    E_OUT_OF_RANGE          The specified volume is out of range.
 549         * @exception    E_INVALID_STATE         This instance is in an invalid state for this method.
 550         * @see                  GetVolume(), IsMuted(), SetMute()
 551         */
 552         result SetVolume(int volume);
 553
 554         /**
 555         * Gets the current volume of an audio or video player.
 556         *
 557         * @since                2.0
 558         *
 559         * @return               The current volume level @n
 560         *                               The range of this return value is @c 0 to @c 100.
 561         * @see                  SetVolume(), IsMuted(), SetMute()
 562         */
 563         int GetVolume(void) const;
 564
 565         /**
 566         * Sets the mute status of an audio or video player.
 567         *
 568         * @since                2.0
 569         *
 570         * @return               An error code
 571         * @param[in]    mute                            Set to @c true to mute the audio or video player, @n
 572         *                                                                       else @c false
 573         * @exception    E_SUCCESS                                               The method is successful.
 574         * @exception    E_INVALID_STATE         This instance is in an invalid state for this method.
 575         * @see          GetVolume(), SetVolume(), IsMuted()
 576         */
 577         result SetMute(bool mute);
 578
 579         /**
 580         * Checks the mute status of an audio or video player.
 581         *
 582         * @since                2.0
 583         *
 584         * @return               @c true if the audio or video player is muted, @n
 585         *                               else @c false
 586         * @see          GetVolume(), SetVolume(), SetMute()
 587         */
 588         bool IsMuted(void) const;
 589
 590         /**
 591         * Sets an audio or video player to be in a loop. @n
 592         * Set the looping to @c true to continuously play the audio or video content.
 593         *
 594         * @since                2.0
 595         *
 596         * @return               An error code
 597         * @param[in]    looping             Set to @c true to play the audio or video content in a loop, @n
 598         *                                                                       else @c false
 599         * @exception    E_SUCCESS                                               The method is successful.
 600         * @exception    E_INVALID_STATE         This instance is in an invalid state for this method.
 601         * @remarks              In streaming, this method throws E_INVALID_STATE for the cost of network.
 602         * @see          IsLooping()
 603         */
 604         result SetLooping(bool looping);
 605
 606         /**
 607         * Checks whether the audio or video player is in a loop.
 608         *
 609         * @since                2.0
 610         *
 611         * @return               @c true if the audio or video player is in a loop, @n
 612         *                               else @c false
 613         * @see          SetLooping()
 614         */
 615         bool IsLooping(void) const;
 616
 617         /**
 618         * Gets the current media stream information.
 619         *
 620         * @since                2.0
 621         *
 622         * @return       A pointer to the MediaStreamInfo instance containing metadata for the current media stream
 623         * @exception    E_SUCCESS                                                               The method is successful.
 624         * @exception    E_INVALID_STATE     This instance is in an invalid state for this method.
 625         * @exception    E_INVALID_CONTENT   The content is inappropriate to compose media stream information.
 626         * @exception    E_SYSTEM            A system error has occurred.
 627         * @remarks       This method returns a stream information of the media, which is currently being played.
 628         *               The specific error code can be accessed using the GetLastResult() method.
 629         *               This method must be called after Play() to get the correct data.
 630         * @see          MediaStreamInfo
 631         */
 632         MediaStreamInfo* GetCurrentMediaStreamInfoN(void) const;
 633
 634         /**
 635         * Sets the rendering buffer for the video playback.
 636         *
 637         * @since                2.0
 638         *
 639         * @return       An error code
 640         * @param[in]    bufferInfo                      The buffer information to display the video
 641         * @exception    E_SUCCESS                                               The method is successful.
 642         * @exception    E_INVALID_STATE         This instance is in an invalid state for this method.
 643         * @exception    E_INVALID_ARG                           The specified input parameter is invalid.
 644         * @exception    E_SYSTEM                                                        A system error has occurred. @n
 645         *                                   E_SYSTEM is returned when the unsupport resolution is set for rendering .
 646         * @remarks      This method works for the PLAYER_STATE_OPENED, PLAYER_STATE_ENDOFCLIP, PLAYER_STATE_STOPPED, PLAYER_STATE_PAUSED, and PLAYER_STATE_PLAYING states of the player.
 647         * @remarks              This method throws E_INVALID_STATE after the player instance is constructed with IPlayerVideoEventListener.
 648         */
 649         result SetRenderingBuffer(const Tizen::Graphics::BufferInfo& bufferInfo);
 650
 651         /**
 652         * Initializes this instance of %Player with the specified parameters.
 653         *
 654         * @since                2.0
 655         *
 656         * @return       An error code
 657         * @param[in]    listener                    An IPlayerEventListener instance
 658         * @param[in]    videoListener               An IPlayerVideoEventListener instance
 659         * @exception    E_SUCCESS                   The method is successful.
 660         * @exception    E_SYSTEM                    A system error has occurred.
 661         * @exception    E_RESOURCE_UNAVAILABLE      The player's resources are unavailable.
 662         * @exception    E_OUT_OF_MEMORY             The memory is insufficient.
 663         * @remarks      This method constructs the %Player instance to render the video content into the buffer of the video event listener.
 664         * @see          IPlayerVideoEventListener
 665         */
 666         result Construct(IPlayerEventListener& listener, IPlayerVideoEventListener& videoListener);
 667
 668         /**
 669         * Captures the video frame. @n
 670         * This method delivers one video frame of a video content by using the IPlayVideoEventListener interface only once in the %Player instance. @n
 671         * This method works only for the PLAYER_STATE_OPENED state of the %Player instance, and the state of the %Player instance is changed to PLAYER_STATE_PAUSED from PLAYER_STATE_OPENED after calling this method.
 672         *
 673         * @since                2.0
 674         *
 675         * @return       An error code
 676         * @exception    E_SUCCESS                                                                       The method is successful.
 677         * @exception    E_INVALID_STATE                                 This instance is in an invalid state for this method. @n
 678         *                                                                               This method throws E_INVALID_STATE if the %Player instance is
 679         *                                                                               constructed without IPlayerVideoEventListener.
 680         * @exception    E_INVALID_OPERATION             This method is invalid for the current media content.
 681         * @exception    E_SYSTEM                                                                        A system error has occurred.
 682         * @remarks      In the Real Time Streaming Protocol (RTSP), this method does not work properly.
 683         * @see          IPlayerVideoEventListener
 684         */
 685         result CaptureVideo(void);
 686
 687         /**
 688         * Sets audio stream type
 689         *
 690         * @since                2.0
 691         *
 692         * @return                 An error code
 693         * @param[in]    type                                            An audio stream type
 694         * @exception    E_SUCCESS                                       The method is successful.
 695         * @exception    E_INVALID_ARG                           A specified input parameter is invalid.
 696         */
 697         result SetAudioStreamType(AudioStreamType type);
 698
 699         /**
 700         * Opens an audio or video streaming content to play through the specified URL with the HTTP header.@n
 701         * This method works asynchronously, thus application can call further APIs of %Player after IPlayerEventListener::OnPlayerOpened() is called.
 702         *
 703         * @since                2.0
 704         *
 705         * @return                                                               An error code
 706         * @param[in]    url                                             The URL of the media source
 707         * @param[in]    pHeader                                 The list of field and value pairs that will be added in HTTP request header. @n
 708         The types of field and value are described in the Programming Guide. If @c null, then default values will be set
 709         *
 710         * @exception    E_SUCCESS                               The method is successful.
 711         * @exception    E_INVALID_STATE                 This instance is in an invalid state for this method.
 712         * @exception    E_UNSUPPORTED_PROTOCOL  The protocol is not supported.
 713         * @exception    E_INVALID_ARG                   The specified input parameter is invalid.
 714         * @exception    E_OUT_OF_MEMORY                 The memory is insufficient.
 715         * @remarks      See Programming Guide for the detail information of supported HTTP header fields.
 716         * @remarks      Input URL should be encoded if there are non-alphanumeric characters in URL.
 717         * @see                  Close()
 718         */
 719         result OpenUrlAsync(const Tizen::Base::String& url, const Tizen::Base::Collection::IMap* pHeader = null);
 720
 721         /**
 722         * Opens an audio or video streaming content to play through the specified HTTP URL with the HTTP header for the progressive download playback. @n
 723         * This method works asynchronously, thus application can call further APIs of %Player after IPlayerEventListener::OnPlayerOpened() is called.
 724         * The content information of the media source should 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.
 725         *
 726         * @since                2.0
 727         *
 728         * @return                                                               An error code
 729         * @param[in]    url                                             The URL of the media source
 730         * @param[in]    filePath                                The file path on local file system that the downloaded content will be saved.
 731         * @param[in]    listener                                The download listener
 732         * @param[in]    pHeader                                 The list of field and value pairs that will be added in HTTP request header. @n
 733         The types of field and value are described in the Programming Guide.
 734                                                                                         If @c null, then default values will be set..
 735         * @exception    E_SUCCESS                               The method is successful.
 736         * @exception    E_INVALID_STATE                 This instance is in an invalid state for this method.
 737         * @exception    E_UNSUPPORTED_PROTOCOL  The protocol is not supported.
 738         * @exception    E_INVALID_ARG                   The specified input parameter is invalid.
 739         * @exception    E_OUT_OF_MEMORY                 The memory is insufficient.
 740         * @remarks      Download will start when Play() is called.
 741         * @remarks      If the specified file name already exists, then the old file will be overwritten with the new one.
 742         * @remarks      See Programming Guide for the detail information of supported HTTP header fields.
 743         * @remarks      Input URL should be encoded if there are non-alphanumeric characters in URL.
 744         * @see                  Close(), Play()
 745         */
 746         result OpenUrlAsync(const Tizen::Base::String& url, const Tizen::Base::String& filePath, IPlayerProgressiveDownloadListener& listener, const Tizen::Base::Collection::IMap* pHeader = null);
 747
 748
 749         /**
 750         * Sets the interval of calling the progress event
 751         *
 752         * @since                2.0
 753         *
 754         * @param[in]    percent                                 The progress period interval as a percentage value.
 755         * @remark               If the server does not provide the information about the content size, progress event will occur randomly.
 756         * @remarks              If the percentage value is not set, @c 10 will be set as a default value.
 757         * @see                  OnPlayerProgressiveDownloadInProgress(), IPlayerProgressiveDownloadListener
 758         */
 759         void SetProgressiveDownloadIntervalByPercent(int percent);
 760
 761         /**
 762         * Initializes this instance of %Player with the specified parameters.
 763         *
 764         * @since                2.0
 765         *
 766         * @return        An error code
 767         * @param[in]   listener                        An IPlayerEventListener instance
 768         * @param[in]   videoTexture                  An VideoTexture instance
 769         * @exception    E_SUCCESS                The method is successful.
 770         * @exception    E_INVALID_ARG      A specified input parameter is invalid.
 771         * @exception    E_RESOURCE_UNAVAILABLE  The player's resources are unavailable.
 772         * @remarks      This method constructs the %Player instance to render the video content into the video texture area.
 773         */
 774         result Construct(IPlayerEventListener& listener, Tizen::Graphics::Opengl::VideoTexture& videoTexture);
 775 private:
 776         /**
 777          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 778          *
 779          *  @since              2.0
 780          */
 781         Player(const Player& rhs);
 782
 783         /**
 784          *The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 785          *
 786          * @since               2.0
 787          */
 788         Player& operator =(const Player& rhs);
 789
 790         friend class _PlayerImpl;
 791         class _PlayerImpl* __pPlayerImpl;
 792 };
 793
 794
 795 }} // Tizen::Media
 796
 797 #endif