include/esplusplayer_capi/esplusplayer_capi.h

   1 /**
   2  * @file           esplusplayer_capi.h
   3  * @brief          EsPlusPlayer api c version
   4  * @interfacetype  Platform
   5  * @privlevel      None-privilege
   6  * @privilege      None
   7  * @product        TV, AV, B2B
   8  * @version        2.0
   9  * @SDK_Support    N
  10  * @remark         This is esplusplayer api header implemented as C style to
  11  *                 avoid binary compatibility issues.
  12  *
  13  * Copyright (c) 2020 Samsung Electronics Co., Ltd All Rights Reserved
  14  * PROPRIETARY/CONFIDENTIAL
  15  * This software is the confidential and proprietary
  16  * information of SAMSUNG ELECTRONICS ("Confidential Information"). You shall
  17  * not disclose such Confidential Information and shall use it only in
  18  * accordance with the terms of the license agreement you entered into with
  19  * SAMSUNG ELECTRONICS. SAMSUNG make no representations or warranties about the
  20  * suitability of the software, either express or implied, including but not
  21  * limited to the implied warranties of merchantability, fitness for a
  22  * particular purpose, or non-infringement. SAMSUNG shall not be liable for any
  23  * damages suffered by licensee as a result of using, modifying or distributing
  24  * this software or its derivatives.
  25  */
  26
  27 #ifndef __PLUSPLAYER_ESPLUSPLAYER_CAPI_ESPLUSPLAYER_CAPI_H__
  28 #define __PLUSPLAYER_ESPLUSPLAYER_CAPI_ESPLUSPLAYER_CAPI_H__
  29
  30 #include "esplusplayer_capi/buffer.h"
  31 #include "esplusplayer_capi/display.h"
  32 #include "esplusplayer_capi/drm.h"
  33 #include "esplusplayer_capi/error.h"
  34 #include "esplusplayer_capi/espacket.h"
  35 #include "esplusplayer_capi/event.h"
  36 #include "esplusplayer_capi/state.h"
  37 #include "esplusplayer_capi/stream.h"
  38 #include "esplusplayer_capi/submitdatatype.h"
  39 #include "esplusplayer_capi/submitstatus.h"
  40
  41 #ifdef __cplusplus
  42 extern "C" {
  43 #endif
  44
  45 #include <stdint.h>
  46
  47 typedef void (*esplusplayer_error_cb)(const esplusplayer_error_type, void*);
  48 typedef void (*esplusplayer_buffer_status_cb)(const esplusplayer_stream_type,
  49                                               const esplusplayer_buffer_status,
  50                                               void*);
  51 typedef void (*esplusplayer_buffer_byte_status_cb)(
  52     const esplusplayer_stream_type, const esplusplayer_buffer_status, uint64_t,
  53     void*);
  54 typedef void (*esplusplayer_buffer_time_status_cb)(
  55     const esplusplayer_stream_type, const esplusplayer_buffer_status, uint64_t,
  56     void*);
  57 typedef void (*esplusplayer_resource_conflicted_cb)(void*);
  58 typedef void (*esplusplayer_eos_cb)(void*);
  59 typedef void (*esplusplayer_ready_to_prepare_cb)(const esplusplayer_stream_type,
  60                                                  void*);
  61 typedef void (*esplusplayer_prepare_async_done_cb)(bool, void*);
  62 typedef void (*esplusplayer_seek_done_cb)(void*);
  63 typedef void (*esplusplayer_ready_to_seek_cb)(const esplusplayer_stream_type,
  64                                               const uint64_t, void*);
  65 typedef void (*esplusplayer_media_packet_video_decoded_cb)(
  66     const esplusplayer_decoded_video_packet*, void*);
  67 typedef void (*esplusplayer_closed_caption_cb)(const char* data, const int size,
  68                                                void* userdata);
  69 typedef void (*esplusplayer_flush_done_cb)(void*);
  70 typedef void (*esplusplayer_event_cb)(const esplusplayer_event_type,
  71                                       const esplusplayer_event_msg, void*);
  72
  73 typedef void* esplusplayer_handle;
  74
  75 /**
  76  * @brief  Enumerations for the Adaptive info type
  77  */
  78 typedef enum {
  79   ESPLUSPLAYER_ADAPT_INFO_TYPE_NONE,
  80   ESPLUSPLAYER_ADAPT_INFO_TYPE_DROPPED_FRAMES,
  81   ESPLUSPLAYER_ADAPT_INFO_TYPE_DROPPED_VIDEO_FRAMES_FOR_CATCHUP,
  82   ESPLUSPLAYER_ADAPT_INFO_TYPE_DROPPED_AUDIO_FRAMES_FOR_CATCHUP,
  83 } esplusplayer_adaptive_info_type;
  84
  85 /**
  86  * @brief   Enumerations for low latency mode
  87  * @remark  Public supports #ESPLUSPLAYER_LOW_LATENCY_MODE_DISABLE_PREROLL only.
  88  */
  89 typedef enum {
  90   ESPLUSPLAYER_LOW_LATENCY_MODE_NONE = 0x0000,
  91   /**
  92    * @description   to support audio fast decoding/rendering
  93    */
  94   ESPLUSPLAYER_LOW_LATENCY_MODE_AUDIO = 0x0001,
  95   /**
  96    * @description   to support video fast decoding/rendering
  97    *                Video stream should be composed only of P and I frames.
  98    *                The mode support seamless resolution change since tizen 6.5
  99    */
 100   ESPLUSPLAYER_LOW_LATENCY_MODE_VIDEO = 0x0010,
 101   /**
 102    * @description   to support video fast decoding/rendering and video
 103    *                distortion concealment.
 104    *                Video stream should be composed only of P and I frames.
 105    *                For applications using the UDP protocol, packet loss can
 106    *                occur. when video distortion by video packet loss is
 107    *                detected, it is a function to conceal distortion by showing
 108    *                previous video frame. It is supported only in h.264 codec &
 109    *                FHD or lower resolution.
 110    */
 111   ESPLUSPLAYER_LOW_LATENCY_MODE_VIDEO_DISTORTION_CONCEALMENT =
 112       ESPLUSPLAYER_LOW_LATENCY_MODE_VIDEO | 0x0020,
 113   /**
 114    * @description   to disable clock sync and a/v sync when rendering. it
 115    *                includes #ESPLUSPLAYER_LOW_LATENCY_MODE_DISABLE_PREROLL.
 116    */
 117   ESPLUSPLAYER_LOW_LATENCY_MODE_DISABLE_SYNC = 0x0100,
 118   /**
 119    * @description   to disable preroll which means player doesn't wait for
 120    *                first buffer when state is changed to
 121    *                #ESPLUSPLAYER_STATE_READY from #ESPLUSPLAYER_STATE_IDLE.
 122    *                It changes the state immediately.
 123    *                It's usually used for sparse stream. (e.g. video packet
 124    *                arrives but audio packet doesn't yet.)
 125    */
 126   ESPLUSPLAYER_LOW_LATENCY_MODE_DISABLE_PREROLL = 0x0200,
 127   /**
 128    * @deprecated    Deprecated since tizen 6.5
 129    * @description   to set lower video quality
 130    *                If set this value, it can use original game_mode.
 131    *                This value will be deprecated from 2022TV.
 132    *                Please use ESPLUSPLAYER_LOW_LATENCY_MODE_ENABLE_GAME_MODE.
 133    */
 134   ESPLUSPLAYER_LOW_LATENCY_MODE_DISABLE_VIDEO_QUALITY = 0x1000,
 135   /**
 136    * @description   to set game mode for minimum latency
 137    *                Video stream should be composed only of P and I frames.
 138    *                It must not be used together with
 139    *                #ESPLUSPLAYER_LOW_LATENCY_MODE_DISABLE_VIDEO_QUALITY.
 140    *                If use this value, It can expect better latency performance
 141    *                than #ESPLUSPLAYER_LOW_LATENCY_MODE_DISABLE_VIDEO_QUALITY.
 142    *                The mode support seamless resolution change.
 143    *                The mode use lower video quality.
 144    */
 145   ESPLUSPLAYER_LOW_LATENCY_MODE_ENABLE_GAME_MODE =
 146       ESPLUSPLAYER_LOW_LATENCY_MODE_AUDIO |
 147       ESPLUSPLAYER_LOW_LATENCY_MODE_VIDEO | 0x2000,
 148   /**
 149    * @description   to set game mode for latency
 150    *                Video stream should be composed only of P and I frames.
 151    *                Video stream must use fixed resolution.
 152    *                It must not be used together with
 153    *                #ESPLUSPLAYER_LOW_LATENCY_MODE_DISABLE_VIDEO_QUALITY.
 154    *                If use this value, It can expect better latency
 155    *                performance than
 156    *                #ESPLUSPLAYER_LOW_LATENCY_MODE_DISABLE_VIDEO_QUALITY and
 157    *                #ESPLUSPLAYER_LOW_LATENCY_MODE_ENABLE_GAME_MODE
 158    *                The mode use lower video quality.
 159    */
 160   ESPLUSPLAYER_LOW_LATENCY_MODE_ENABLE_GAME_MODE_WITH_FIXED_RESOLUTION =
 161       ESPLUSPLAYER_LOW_LATENCY_MODE_ENABLE_GAME_MODE | 0x4000,
 162 } esplusplayer_low_latency_mode;
 163
 164 /**
 165  * @brief   Enumerations for esplusplayer audio codec type
 166  */
 167 typedef enum {
 168   /**
 169    * @description   hardware codec can only be selected, default type
 170    */
 171   ESPLUSPLAYER_AUDIO_CODEC_TYPE_HW,
 172   /**
 173    * @description   software codec can only be selected
 174    */
 175   ESPLUSPLAYER_AUDIO_CODEC_TYPE_SW,
 176   ESPLUSPLAYER_AUDIO_CODEC_TYPE_MAX
 177 } esplusplayer_audio_codec_type;
 178
 179 /**
 180  * @brief   Enumerations for esplusplayer video codec type
 181  */
 182 typedef enum {
 183   /**
 184    * @description   hardware codec can only be selected, default type
 185    */
 186   ESPLUSPLAYER_VIDEO_CODEC_TYPE_HW,
 187   /**
 188    * @description   software codec can only be selected
 189    */
 190   ESPLUSPLAYER_VIDEO_CODEC_TYPE_SW,
 191   /**
 192   * @description   hardware codec using n-decoding mode can only be selected.
 193                    It must set display type to mixer type by display setting
 194   api.
 195                    esplusplayer_set_display()
 196   */
 197   ESPLUSPLAYER_VIDEO_CODEC_TYPE_HW_N_DECODING,
 198   ESPLUSPLAYER_VIDEO_CODEC_TYPE_MAX
 199
 200 } esplusplayer_video_codec_type;
 201 /**
 202  * @brief   Enumerations for esplusplayer audio easing type
 203  * @version 3.0
 204  */
 205 typedef enum {
 206   /**
 207    * @description audio easing function type is linear
 208    */
 209   ESPLUSPLAYER_AUDIO_EASING_LINEAR,
 210   /**
 211    * @description audio easing function type is incubic
 212    */
 213   ESPLUSPLAYER_AUDIO_EASING_INCUBIC,
 214   /**
 215    * @description audio easing function type is outcubic
 216    */
 217   ESPLUSPLAYER_AUDIO_EASING_OUTCUBIC,
 218   /**
 219    * @description audio easing function type is none
 220    */
 221   ESPLUSPLAYER_AUDIO_EASING_NONE
 222 } esplusplayer_audio_easing_type;
 223
 224 /**
 225  * @brief   Enumerations for esplusplayer resource type
 226  * @version 3.0
 227  */
 228 typedef enum {
 229   /**
 230    * @description video renderer type
 231    */
 232   ESPLUSPLAYER_RSC_TYPE_VIDEO_RENDERER
 233 } esplusplayer_rsc_type;
 234
 235 /**
 236  * @brief   Enumerations for advanced video quality type
 237  * @version 3.1
 238  */
 239 typedef enum {
 240   /**
 241    * @description advanced picture quality for video call
 242    */
 243   ESPLUSPLAYER_ADVANCED_PICTURE_QUALITY_VIDEO_CALL,
 244   /**
 245    * @description advanced picture quality for usb camera
 246    */
 247   ESPLUSPLAYER_ADVANCED_PICTURE_QUALITY_USB_CAMERA
 248 } esplusplayer_advanced_picture_quality_type;
 249
 250 typedef struct {
 251   /**
 252    * @description   the minimum frame number in case of mid latency
 253    */
 254   int mid_latency_threshold;
 255   /**
 256    * @description   the minimum frame number in case of high latency
 257    */
 258   int high_latency_threshold;
 259 } esplusplayer_latency_threshold;
 260
 261 /**
 262  * @brief  rational number numerator/denominator
 263  */
 264 typedef struct {
 265   /**
 266    * @description   the numerator value
 267    */
 268   int num;
 269   /**
 270    * @description   the denominator value
 271    */
 272   int den;
 273 } esplusplayer_rational;
 274
 275 /**
 276  * @brief  resource allocate policy
 277  */
 278 typedef enum {
 279   /**
 280    * @description exclusive policy, RM will return the requested resources,
 281    * default policy
 282    */
 283   ESPLUSPLAYER_RSC_ALLOC_EXCLUSIVE = 0,
 284   /**
 285    * @description conditional policy, when trying to allocate resources and
 286    * available resources are not left, RM will return fail.
 287    */
 288   ESPLUSPLAYER_RSC_ALLOC_EXCLUSIVE_CONDITIONAL
 289 } esplusplayer_rsc_alloc_policy;
 290
 291 /**
 292  * @brief Enumerations for the status of getting decoded video frame
 293  * @version 4.0
 294  */
 295 typedef enum {
 296   /** @brief successfully decoded video frame acquired. */
 297   ESPLUSPLAYER_GET_DECVIDEOFRAME_STATUS_SUCCESS,
 298   /** @brief  it means app has to return the video before getting decoded
 299    * video frame frame.
 300    */
 301   ESPLUSPLAYER_GET_DECVIDEOFRAME_STATUS_NO_REMAINING_BUFFER,
 302   /**
 303    * @brief  there is no filled video frame yet.
 304    */
 305   ESPLUSPLAYER_GET_DECVIDEOFRAME_STATUS_NO_FILLED_BUFFER,
 306   /**
 307    * @brief  internal error
 308    */
 309   ESPLUSPLAYER_GET_DECVIDEOFRAME_STATUS_UNKNOWN
 310 } esplusplayer_get_decoded_video_frame_status_type;
 311
 312 /**
 313  * @brief     Create a esplusplayer handle.
 314  * @param     None
 315  * @return    return esplusplayer handle pointer.
 316  * @code
 317  *            esplusplayer_handle esplayer = esplusplayer_create();
 318  *            // ... your codes ...
 319  *            esplusplayer_destroy(esplayer);
 320  * @endcode
 321  * @pre       None
 322  * @post      The player state will be #ESPLUSPLAYER_STATE_NONE.
 323  * @exception None
 324  */
 325 esplusplayer_handle esplusplayer_create();
 326
 327 /**
 328  * @brief     Open esplusplayer handle.
 329  * @param     [in] handle : esplusplayer handle
 330  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of esplusplayer_error_type
 331  *            values will be returned.
 332  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
 333  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
 334  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation failed
 335  * @code
 336  *            esplusplayer_handle esplayer = esplusplayer_create();
 337  *            esplusplayer_open(esplayer);
 338  *            // ... your codes ...
 339  *            esplusplayer_close(esplayer);
 340  *            esplusplayer_destroy(esplayer);
 341  * @endcode
 342  * @pre       The player state must be #ESPLUSPLAYER_STATE_NONE.
 343  * @post      The player state will be #ESPLUSPLAYER_STATE_IDLE.
 344  * @exception None
 345  * @see       esplusplayer_close()
 346  */
 347 int esplusplayer_open(esplusplayer_handle handle);
 348
 349 /**
 350  * @brief     Release all the player resources and all setting except callback
 351  *            functions.
 352  * @param     [in] handle : esplusplayer handle.
 353  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of esplusplayer_error_type
 354  *            values will be returned.
 355  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
 356  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
 357  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation failed
 358  * @pre       The player state must be all of #esplusplayer_state except
 359  *            #ESPLUSPLAYER_STATE_NONE.
 360  * @post      The player state will be #ESPLUSPLAYER_STATE_NONE.
 361  * @exception None
 362  * @see       esplusplayer_open()
 363  */
 364 int esplusplayer_close(esplusplayer_handle handle);
 365
 366 /**
 367  * @brief     Release player handle.
 368  * @param     [in] handle : esplusplayer handle.
 369  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of esplusplayer_error_type
 370  *            values will be returned.
 371  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
 372  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
 373  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation failed
 374  * @code
 375  *            refer to the sample code of esplusplayer_create()
 376  * @endcode
 377  * @pre       The player state must be #ESPLUSPLAYER_STATE_NONE
 378  * @post      player handle will be removed.
 379  * @exception None
 380  * @see       esplusplayer_create()
 381  */
 382 int esplusplayer_destroy(esplusplayer_handle handle);
 383
 384 /**
 385  * @brief     Flush the specific buffered stream data and release TV resource
 386  *            to change stream.
 387  * @remark    To activate, the stream must be set again.
 388  * @param     [in] handle : esplusplayer handle.
 389  * @param     [in] type : stream type which user want to deactivate.
 390  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of esplusplayer_error_type
 391  *            values will be returned.
 392  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
 393  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
 394  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation failed
 395  * @code
 396               refer to the sample code of esplusplayer_activate()
 397  * @endcode
 398  * @pre       The player state must be at least #ESPLUSPLAYER_STATE_READY
 399  * @post      The player state is same as before calling
 400  *            esplusplayer_deactivate(). The deactivated stream will stop
 401  *            rendering and release the decoder, renderer resources.
 402  * @exception None
 403  * @see       esplusplayer_activate
 404  */
 405 int esplusplayer_deactivate(esplusplayer_handle handle,
 406                             esplusplayer_stream_type type);
 407
 408 /**
 409  * @brief     Reprepare for the specific stream playback.
 410  * @remark    There must be active stream to prepare playback.
 411  * @param     [in] handle : esplusplayer handle.
 412  * @param     [in] type : stream type which user want to activate.
 413  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of esplusplayer_error_type
 414  *            values will be returned.
 415  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
 416  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
 417  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation failed
 418  * @code
 419  *            prepare esplayer done
 420  *            // ... your codes ...
 421  *            esplusplayer_deactivate(esplayer, ESPLUSPLAYER_STREAM_TYPE_VIDEO);
 422  *            esplusplayer_video_stream_info stream;
 423  *            stream.width = 640;
 424  *            stream.height = 352;
 425  *            stream.mime_type = ESPLUSPLAYER_VIDEO_MIME_TYPE_H264;
 426  *            stream.framerate_num = 30;
 427  *            stream.framerate_den = 1;
 428  *            esplusplayer_set_video_stream_info(esplayer, &stream);
 429  *            esplusplayer_activate(esplayer, ESPLUSPLAYER_STREAM_TYPE_VIDEO);
 430  *            // ... your codes ...
 431  *            esplusplayer_close(esplayer);
 432  *            esplusplayer_destroy(esplayer);
 433  * @endcode
 434  * @pre       The player state must be at least #ESPLUSPLAYER_STATE_READY
 435  * @post      The player state is same as before calling
 436  *            esplusplayer_activate(). Rebuild pipeline to render the stream.
 437  * @exception None
 438  * @see       esplusplayer_prepare_async()
 439  */
 440 int esplusplayer_activate(esplusplayer_handle handle,
 441                           esplusplayer_stream_type type);
 442
 443 /**
 444  * @brief     Prepare the player for playback, asynchronously.
 445  * @param     [in] handle : esplusplayer handle.
 446  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of esplusplayer_error_type
 447  *            values will be returned.
 448  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
 449  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
 450  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation failed
 451  * @code
 452  *            static void OnPrepareDone(bool ret, void* userdata) {
 453  *                //Something you want to do when prepare done, but, we strongly
 454  *                //recommend DO NOT CALL PLAYER APIs in this callback
 455  *                printf("OnPrepareDone\n");
 456  *            }
 457  *            esplusplayer_handle esplayer = esplusplayer_create();
 458  *            esplusplayer_set_prepare_async_done_cb(esplayer, OnPrepareDone,nullptr);
 459  *            esplusplayer_open(esplayer);
 460  *            esplusplayer_prepare_async(esplayer);
 461  *            // ... your codes ...
 462  *            esplusplayer_close(esplayer);
 463  *            esplusplayer_destroy(esplayer);
 464  * @endcode
 465  * @pre       The player state must be #ESPLUSPLAYER_STATE_IDLE. \n
 466  *            Call at least one of esplusplayer_set_video_stream_info() or
 467  *            esplusplayer_set_audio_stream_info(). \n
 468  * @post      It invokes esplusplayer_prepare_async_done_cb() when prepare is
 469  *            finished. \n
 470  *            Prepare result can be succeeded or not at this moment. \n
 471  *            If the result is succeeded, the player state will be
 472  *            #ESPLUSPLAYER_STATE_READY and one frame will be displayed
 473  *            unless esplusplayer_set_display_visible() is set to @c false.
 474  * @exception None
 475  * @remark    esplusplayer_prepare_async_done_cb() can be invoked only when as
 476  *            many es packets as at least one decoded frame is submitted. \n
 477  *            The player can receive es packets after
 478  *            esplusplayer_ready_to_seek_cb() is called.
 479  * @see       esplusplayer_open() \n
 480  *            esplusplayer_stop() \n
 481  *            esplusplayer_submit_packet() \n
 482  *            esplusplayer_ready_to_prepare_cb() \n
 483  *            esplusplayer_close()
 484  */
 485 int esplusplayer_prepare_async(esplusplayer_handle handle);
 486
 487 /**
 488  * @brief     Start playback.
 489  * @param     [in] handle : esplusplayer handle.
 490  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of esplusplayer_error_type
 491  *            values will be returned.
 492  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
 493  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
 494  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation failed
 495  * @code
 496  *            prepare esplayer done
 497  *            esplusplayer_start(esplayer);
 498  *            // ... your codes ...
 499  *            esplusplayer_stop(esplayer);
 500  * @endcode
 501  * @pre       The player state should be #ESPLUSPLAYER_STATE_READY.
 502  * @post      The player state will be #ESPLUSPLAYER_STATE_PLAYING.
 503  * @exception None
 504  * @see       esplusplayer_open() \n
 505  *            esplusplayer_prepare_async() \n
 506  *            esplusplayer_stop() \n
 507  *            esplusplayer_close()
 508  */
 509 int esplusplayer_start(esplusplayer_handle handle);
 510
 511 /**
 512  * @brief     Stop playing media content.
 513  * @param     [in] handle : esplusplayer handle.
 514  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of esplusplayer_error_type
 515  *            values will be returned.
 516  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
 517  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
 518  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation failed
 519  * @code
 520  *            prepare esplayer done
 521  *            // ... your codes ...
 522  *            esplusplayer_stop(esplayer);
 523  *             // ... your codes ...
 524  *            esplusplayer_close(esplayer);
 525  * @endcode
 526  * @pre       The player state must be all of #esplusplayer_state except
 527  *            #ESPLUSPLAYER_STATE_NONE.
 528  * @post      The player state will be #ESPLUSPLAYER_STATE_IDLE.
 529  * @exception None
 530  * @remark    esplusplayer_close() must be called once after player is stopped
 531  * @see       esplusplayer_open() \n
 532  *            esplusplayer_prepare_async() \n
 533  *            esplusplayer_start() \n
 534  *            esplusplayer_pause() \n
 535  *            esplusplayer_resume() \n
 536  *            esplusplayer_close()
 537  */
 538 int esplusplayer_stop(esplusplayer_handle handle);
 539
 540 /**
 541  * @brief     Pause playing media content.
 542  * @param     [in] handle : esplusplayer handle.
 543  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of esplusplayer_error_type
 544  *            values will be returned.
 545  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
 546  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
 547  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation failed
 548  * @code
 549  *            prepare esplayer done
 550  *            // ... your codes ...
 551  *            esplusplayer_pause(esplayer);
 552  *            // ... your codes ...
 553  *            esplusplayer_stop(esplayer);
 554  * @endcode
 555  * @pre       The player state must be one of #ESPLUSPLAYER_STATE_READY or
 556  *            #ESPLUSPLAYER_STATE_PAUSED or #ESPLUSPLAYER_STATE_PLAYING.
 557  * @post      The player state will be #ESPLUSPLAYER_STATE_PAUSE.
 558  * @exception None
 559  * @see       esplusplayer_start() \n
 560  *            esplusplayer_resume() \n
 561  *            esplusplayer_prepare_async()
 562  */
 563 int esplusplayer_pause(esplusplayer_handle handle);
 564
 565 /**
 566  * @brief     Resume playing media content.
 567  * @param     [in] handle : esplusplayer handle.
 568  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of esplusplayer_error_type
 569  *            values will be returned.
 570  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
 571  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
 572  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation failed
 573  * @code
 574  *            prepare esplayer done
 575  *            // ... your codes ...
 576  *            esplusplayer_pause(esplayer);
 577  *            // ... your codes ...
 578  *            esplusplayer_resume(esplayer);
 579  *            // ... your codes ...
 580  *            esplusplayer_stop(esplayer);
 581  * @endcode
 582  * @pre       The player state must be one of #ESPLUSPLAYER_STATE_PAUSED or
 583  *            #ESPLUSPLAYER_STATE_PLAYING.
 584  * @post      The player state will be #ESPLUSPLAYER_STATE_PLAYING.
 585  * @exception None
 586  * @see       esplusplayer_start() \n
 587  *            esplusplayer_pause() \n
 588  *            esplusplayer_prepare_async()
 589  */
 590 int esplusplayer_resume(esplusplayer_handle handle);
 591
 592 /**
 593  * @brief     Set playback rate.
 594  * @param     [in] handle : esplusplayer handle.
 595  * @param     [in] playback_rate :  the playback rate from 0.0 to 2.0.
 596  * @param     [in] audio_mute :  the audio is mute on/off, true: mute on, false:
 597  * mute off.
 598  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of esplusplayer_error_type
 599  *            values will be returned.
 600  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
 601  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
 602  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation failed
 603  * @code
 604  *            prepare esplayer done
 605  *            // ... your codes ...
 606  *            esplusplayer_set_playback_rate(esplayer,2,true);
 607  *            // ... your codes ...
 608  *            esplusplayer_stop(esplayer);
 609  * @endcode
 610  * @pre       The player state must be one of #ESPLUSPLAYER_STATE_READY or
 611  *            #ESPLUSPLAYER_STATE_PAUSED or #ESPLUSPLAYER_STATE_PLAYING. \n
 612  *            User has to push the data as fast as playback rate.
 613  * @post      None
 614  * @exception None
 615  * @see       esplusplayer_prepare_async()
 616  */
 617 int esplusplayer_set_playback_rate(esplusplayer_handle handle,
 618                                    const double playback_rate,
 619                                    const bool audio_mute);
 620
 621 /**
 622  * @brief     Seek for playback, asynchronously.
 623  * @param     [in] handle : esplusplayer handle.
 624  * @param     [in] time_ms : seek time in milliseconds
 625  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of esplusplayer_error_type
 626  *            values will be returned.
 627  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
 628  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
 629  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation failed
 630  * @code
 631  *            prepare esplayer done
 632  *            // ... your codes ...
 633  *            const uint64_t ms_to_seek = 0;
 634  *            esplusplayer_seek(esplayer,ms_to_seek);
 635  *            // ... your codes ...
 636  *            esplusplayer_stop(esplayer);
 637  * @endcode
 638  * @pre       The player state must be one of #ESPLUSPLAYER_STATE_READY or
 639  *            #ESPLUSPLAYER_STATE_PAUSED or #ESPLUSPLAYER_STATE_PLAYING.
 640  *            In ESPLUSPLAYER_STATE_IDLE, this api can be called exceptionally
 641  *            between esplusplayer_open() and esplusplayer_prepare_async().
 642  *            the start time of playback can be set explicitly when starting
 643  *            first playback. In this case, esplusplayer_set_seek_done_cb is not
 644  *            called.
 645  * @post      None
 646  * @exception None
 647  * @remark    esplusplayer_set_seek_done_cb() will be invoked if seek operation
 648  *            is finished. \n
 649  *            Seek result can be succeeded or not at this moment. \n
 650  *            esplusplayer_set_seek_done_cb() can be invoked only when as many
 651  *            es packets as at least one decoded frame is submitted. \n
 652  *            The player can receive es packets from seek time after
 653  *            esplusplayer_ready_to_seek_cb() is invoked.
 654  * @see       esplusplayer_ready_to_seek_cb() \n
 655  *            esplusplayer_prepare_async()
 656  */
 657 int esplusplayer_seek(esplusplayer_handle handle, uint64_t time_ms);
 658
 659 /**
 660  * @brief     Set the video display.
 661  * @param     [in] handle : esplusplayer handle.
 662  * @param     [in] type : display type.
 663  * @param     [in] window : the handle to display window.
 664  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of esplusplayer_error_type
 665  *            values will be returned.
 666  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
 667  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
 668  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation failed
 669  * @code
 670  *            esplusplayer_open(esplayer);
 671  *            esplusplayer_set_display(esplayer,ESPLUSPLAYER_DISPLAY_TYPE_OVERLAY,window);
 672  *            // ... your codes ...
 673  *            esplusplayer_close(esplayer);
 674  * @endcode
 675  * @pre       The player state must be #ESPLUSPLAYER_STATE_IDLE.
 676  * @post      None
 677  * @exception None
 678  * @remark    Esplusplayer is not supporting changing display. \n
 679  *            This API have to be called before calling
 680  *            esplusplayer_prepare_async() to reflect the display type.
 681  * @see       esplusplayer_open() \n
 682  *            esplusplayer_set_display_mode() \n
 683  *            esplusplayer_set_display_roi() \n
 684  *            esplusplayer_set_display_visible()
 685  */
 686 int esplusplayer_set_display(esplusplayer_handle handle,
 687                              esplusplayer_display_type type, void* window);
 688
 689 #ifdef TIZEN_FEATURE_TV
 690 /**
 691  * @brief     Set the video display.
 692  * @param     [in] handle : esplusplayer handle.
 693  * @param     [in] type : display type.
 694  * @param     [in] subsurface : the ecore wayland subsurface handle.
 695  * @param     [in] x : the x coordinate of subsurface.
 696  * @param     [in] y : the y coordinate of subsurface.
 697  * @param     [in] width : the width of subsurface.
 698  * @param     [in] height : the height of subsurface.
 699  * @return    @c one of esplusplayer_error_type values will be returned.
 700  * @pre       The player state must be #ESPLUSPLAYER_STATE_IDLE.
 701  * @post      None
 702  * @exception   None
 703  * @version   3.1
 704  * @see       esplusplayer_set_display_mode() \n
 705  *            esplusplayer_set_display_roi() \n
 706  *            esplusplayer_set_display_visible()
 707  */
 708 int esplusplayer_set_display_ecore_subsurface(esplusplayer_handle handle,
 709                                               esplusplayer_display_type type,
 710                                               void* subsurface, int x, int y,
 711                                               int width, int height);
 712 #endif
 713
 714 /**
 715  * @brief     Set the video display mode.
 716  * @param     [in] handle : esplusplayer handle.
 717  * @param     [in] mode : display mode.
 718  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of esplusplayer_error_type
 719  *            values will be returned.
 720  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
 721  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
 722  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation failed
 723  * @code
 724  *            esplusplayer_open(esplayer);
 725  *            esplusplayer_set_display_mode(esplayer,ESPLUSPLAYER_DISPLAY_MODE_DST_ROI);
 726  *            // ... your codes ...
 727  *            esplusplayer_close(esplayer);
 728  * @endcode
 729  * @pre       The player state can be all of #esplusplayer_state except
 730  *            #ESPLUSPLAYER_STATE_NONE.
 731  * @post      None
 732  * @exception None
 733  * @remark    If no display is set, no operation is performed.
 734  * @see       esplusplayer_open() \n
 735  *            esplusplayer_set_display_mode() \n
 736  *            esplusplayer_set_display_roi() \n
 737  *            esplusplayer_set_display_visible()
 738  */
 739 int esplusplayer_set_display_mode(esplusplayer_handle handle,
 740                                   esplusplayer_display_mode mode);
 741
 742 /**
 743  * @brief     Set the ROI(Region Of Interest) area of display.
 744  * @param     [in] handle : esplusplayer handle.
 745  * @param     [in] x : var startPointX in src video area.
 746  * @param     [in] y : var startPointY in src video area.
 747  * @param     [in] width : width of display in src video area.
 748  * @param     [in] height : height of display in src video area.
 749  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of esplusplayer_error_type
 750  *            values will be returned.
 751  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
 752  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
 753  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation failed
 754  * @code
 755  *            esplusplayer_open(esplayer);
 756  *            esplusplayer_set_display(esplayer,ESPLUSPLAYER_DISPLAY_TYPE_OVERLAY,window);
 757  *            esplusplayer_set_display_mode(esplayer,ESPLUSPLAYER_DISPLAY_MODE_DST_ROI);
 758  *            esplusplayer_set_display_roi(esplayer,0,0,600,500);
 759  *            // ... your codes ...
 760  *            esplusplayer_close(esplayer);
 761  * @endcode
 762  * @pre       The player state can be all of #esplusplayer_state except
 763  *            #ESPLUSPLAYER_STATE_NONE. \n
 764  *            Before set display ROI, #ESPLUSPLAYER_DISPLAY_MODE_DST_ROI
 765  *            must be set with esplusplayer_set_display_mode().
 766  * @post      None
 767  * @exception None
 768  * @remark    The minimum value of width and height are 1.
 769  * @see       esplusplayer_open() \n
 770  *            esplusplayer_set_display() \n
 771  *            esplusplayer_set_display_mode() \n
 772  *            esplusplayer_set_display_visible()
 773  */
 774 int esplusplayer_set_display_roi(esplusplayer_handle handle, int x, int y,
 775                                  int width, int height);
 776
 777 /**
 778  * @brief     Set the Crop Area(Region Of Src ratio) area of display.
 779  * @param     [in] handle : esplusplayer handle.
 780  * @param     [in] scale_x: x label ratio in src video area.
 781  * @param     [in] scale_y: y label ratio in src video area.
 782  * @param     [in] scale_w: width ratio in src video area.
 783  * @param     [in] scale_h: height ratio in src video area.
 784  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of esplusplayer_error_type
 785  *            values will be returned.
 786  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
 787  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
 788  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation failed
 789  * @code
 790  *            esplusplayer_open(esplayer);
 791  *            esplusplayer_set_display(esplayer,ESPLUSPLAYER_DISPLAY_TYPE_OVERLAY,window);
 792  *            esplusplayer_set_video_roi(esplayer,0,0,0.5,0.5);
 793  *            // ... your codes ...
 794  *            esplusplayer_close(esplayer);
 795  * @endcode
 796  * @pre       The player state can be all of #esplusplayer_state except
 797  *            #ESPLUSPLAYER_STATE_NONE. \n
 798  * @post      None
 799  * @exception None
 800  * @remark    The minimum value of input are 0,maximum value is 1.
 801  * @see       esplusplayer_open() \n
 802  *            esplusplayer_set_display() \n
 803  *            esplusplayer_set_display_visible()
 804  */
 805 int esplusplayer_set_video_roi(esplusplayer_handle handle, double scale_x,
 806                                double scale_y, double scale_w, double scale_h);
 807
 808 /**
 809  * @brief     Set the visibility of the video display.
 810  * @param     [in] handle : esplusplayer handle.
 811  * @param     [in] visible : the visibility of the display.
 812  *            (@c true = visible, @c false = non-visible)
 813  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of esplusplayer_error_type
 814  *            values will be returned.
 815  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
 816  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
 817  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation failed
 818  * @code
 819  *            esplusplayer_open(esplayer);
 820  *            esplusplayer_set_display(esplayer,ESPLUSPLAYER_DISPLAY_TYPE_OVERLAY,window);
 821  *            esplusplayer_set_display_visible(esplayer,false);
 822  *            // ... your codes ...
 823  *            esplusplayer_close(esplayer);
 824  * @endcode
 825  * @pre       The player state can be all of #esplusplayer_state except
 826  *            #ESPLUSPLAYER_STATE_NONE.
 827  * @post      None
 828  * @exception   None
 829  * @see       esplusplayer_open() \n
 830  *            esplusplayer_set_display()
 831  */
 832 int esplusplayer_set_display_visible(esplusplayer_handle handle, bool visible);
 833
 834 /**
 835  * @brief     Set the rotate angle of the video display.
 836  * @param     [in] handle : esplusplayer handle.
 837  * @param     [in] rotation : the rotate angle of the display.
 838  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of esplusplayer_error_type
 839  *            values will be returned.
 840  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
 841  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
 842  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation failed
 843  * @code
 844  *            esplusplayer_open(esplayer);
 845  *            esplusplayer_set_display(esplayer,ESPLUSPLAYER_DISPLAY_TYPE_OVERLAY,window);
 846  *            esplusplayer_set_display_rotation(esplayer_,ESPLUSPLAYER_DISPLAY_ROTATION_TYPE_90);
 847  *            // ... your codes ...
 848  *            esplusplayer_close(esplayer);
 849  * @endcode
 850  * @pre       The player state can be all of #esplusplayer_state except
 851  *            #ESPLUSPLAYER_STATE_NONE.
 852  * @post      this API worked only when video sink created.
 853  * @exception None
 854  * @see       esplusplayer_open() \n
 855  *            esplusplayer_set_display()
 856  */
 857 int esplusplayer_set_display_rotation(
 858     esplusplayer_handle handle, esplusplayer_display_rotation_type rotation);
 859
 860 /**
 861  * @brief     Get the rotate angle of the video display.
 862  * @param     [in] handle : esplusplayer handle.
 863  * @param     [out] rotation : the rotate angle of the display which want to
 864  * get.
 865  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of esplusplayer_error_type
 866  *            values will be returned.
 867  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
 868  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
 869  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation failed
 870  * @code
 871  *            esplusplayer_open(esplayer);
 872  *            esplusplayer_set_display_rotation(esplayer,ESPLUSPLAYER_DISPLAY_ROTATION_TYPE_90);
 873  *            esplusplayer_display_rotation_type rotation_get = ESPLUSPLAYER_DISPLAY_ROTATION_TYPE_NONE;
 874  *            // ... your codes ...
 875  *            esplusplayer_get_display_rotation(esplayer,&rotation_get);
 876  *            // ... your codes ...
 877  *            esplusplayer_close(esplayer);
 878  * @endcode
 879  * @pre       The player state can be all of #esplusplayer_state except
 880  *            #ESPLUSPLAYER_STATE_NONE.
 881  * @post      this API worked only when video sink created.
 882  * @exception None
 883  * @see       esplusplayer_open() \n
 884  *            esplusplayer_set_display_rotation()
 885  */
 886 int esplusplayer_get_display_rotation(
 887     esplusplayer_handle handle, esplusplayer_display_rotation_type* rotation);
 888
 889 /**
 890  * @brief     Set whether to send decrypted es packets in the trust zone or
 891  *            encrypted es packets.
 892  * @param     [in] handle : esplusplayer handle.
 893  * @param     [in] type : whether to use trust zone memory or encrypted data
 894  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of esplusplayer_error_type
 895  *            values will be returned.
 896  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
 897  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
 898  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation failed
 899  * @code
 900  *            esplusplayer_open(esplayer);
 901  *            esplusplayer_set_submit_data_type(esplayer,ESPLUSPLAYER_SUBMIT_DATA_TYPE_CLEAN_DATA);
 902  *            // ... your codes ...
 903  *            esplusplayer_close(esplayer);
 904  * @endcode
 905  * @pre       The player state must be set to #ESPLUSPLAYER_STATE_IDLE.
 906  * @post      None
 907  * @exception None
 908  * @remark    This API have to be called before calling
 909  *            esplusplayer_prepare_async(). \n
 910  *            If type is ESPLUSPLAYER_SUBMIT_DATA_TYPE_CLEAN_DATA use
 911  *            esplusplayer_submit_packet() to send clean packets. \n
 912  *            If type is ESPLUSPLAYER_SUBMIT_DATA_TYPE_ENCRYPTED_DATA, use
 913  *            esplusplayer_submit_encrypted_packet() to send encrypted packets.
 914  * @see       esplusplayer_open() \n
 915  *            esplusplayer_submit_encrypted_packet() \n
 916  *            esplusplayer_submit_data_type
 917  */
 918 int esplusplayer_set_submit_data_type(esplusplayer_handle handle,
 919                                       esplusplayer_submit_data_type type);
 920
 921 /**
 922  * @brief     Set on mute of the audio sound.
 923  * @param     [in] handle : esplusplayer handle.
 924  * @param     [in] mute : on mute of the sound.
 925  *            (@c true = mute, @c false = non-mute)
 926  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success, otherwise @c one of esplusplayer_error_type
 927  *            values will be returned.
 928  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
 929  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
 930  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation failed
 931  * @code
 932  *            esplusplayer_open(esplayer);
 933  *            esplusplayer_set_audio_mute(esplayer, true);
 934  *            // ... your codes ...
 935  *            esplusplayer_close(esplayer);
 936  * @endcode
 937  * @pre       The player state can be all of #esplusplayer_state except
 938  *            #ESPLUSPLAYER_STATE_NONE.
 939  * @post      None
 940  * @exception None
 941  * @see       esplusplayer_open()
 942  */
 943 int esplusplayer_set_audio_mute(esplusplayer_handle handle, bool mute);
 944
 945 /**
 946  * @brief     Get current state of player.
 947  * @param     [in] handle : esplusplayer handle.
 948  * @return    current #esplusplayer_state of player.
 949  * @code
 950  *            esplusplayer_handle esplayer = esplusplayer_create();
 951  *            // ... your codes ...
 952  *            esplusplayer_state ret = esplusplayer_get_state(esplayer);
 953  *            // ... your codes ...
 954  *            esplusplayer_destroy(esplayer);
 955  * @endcode
 956  * @pre       None
 957  * @post      None
 958  * @exception None
 959  */
 960 esplusplayer_state esplusplayer_get_state(esplusplayer_handle handle);
 961
 962 /**
 963  * @brief     Submit es packet to decode audio or video.
 964  * @param     [in] handle : esplusplayer handle.
 965  * @param     [in] packet : es packet pointer.
 966  * @return    @c ESPLUSPLAYER_SUBMIT_STATUS_SUCCESS : succeed to submit es
 967  *            packet,
 968  *            otherwise @c : fail to submit es packet.
 969  * @code
 970  *            static void OnPrepareDone(bool ret, void* userdata) {
 971  *                // ... your codes ...
 972  *                printf ("OnPrepareDone\n");
 973  *            }
 974  *            static void OnReadyToPrepare(const esplusplayer_stream_type type,void* userdata) {
 975  *                if (type == ESPLUSPLAYER_STREAM_TYPE_VIDEO) {
 976  *                    //Something you want to do when feed es video stream is allowed
 977  *                } else {
 978  *                    //Something you want to do when feed es audio stream is allowed
 979  *                }
 980  *                //Something you want to do when OnReadyToPrepare
 981  *                printf ("OnReadyToPrepare\n");
 982  *            }
 983  *            static void OnBufferByteStatus(const esplusplayer_stream_type type,
 984  *                                           const esplusplayer_buffer_status status,
 985  *                                           uint64_t byte_size, void* userdata) {
 986  *                if (type == ESPLUSPLAYER_STREAM_TYPE_VIDEO) {
 987  *                    if (status == ESPLUSPLAYER_BUFFER_STATUS_UNDERRUN) {
 988  *                        //Something you want to do when es video buffer is enough
 989  *                    } else {
 990  *                        //Something you want to do when es video buffer is not enough
 991  *                    }
 992  *                } else {
 993  *                    if (status == ESPLUSPLAYER_BUFFER_STATUS_UNDERRUN) {
 994  *                        //Something you want to do when es audio buffer is enough
 995  *                    } else {
 996  *                        //Something you want to do when es audio buffer is not enough
 997  *                    }
 998  *                }
 999  *                //Something you want to do when OnBufferByteStatus
1000  *                printf ("OnBufferByteStatus\n");
1001  *            }
1002  *            static void OnBufferTimeStatus(const esplusplayer_stream_type type,
1003  *                                           const esplusplayer_buffer_status status,
1004  *                                           uint64_t time_size,void* userdata) {
1005  *                if (type == ESPLUSPLAYER_STREAM_TYPE_VIDEO) {
1006  *                    if (status == ESPLUSPLAYER_BUFFER_STATUS_UNDERRUN) {
1007  *                        //Something you want to do when es video buffer is enough
1008  *                    } else {
1009  *                        //Something you want to do when es video buffer is not enough
1010  *                    }
1011  *                } else {
1012  *                    if (status == ESPLUSPLAYER_BUFFER_STATUS_UNDERRUN) {
1013  *                        //Something you want to do when es audio buffer is enough
1014  *                    } else {
1015  *                        //Something you want to do when es audio buffer is not enough
1016  *                    }
1017  *                }
1018  *                //Something you want to do when OnBufferTimeStatus
1019  *                printf ("OnBufferTimeStatus\n");
1020  *            }
1021  *            void FeedEsPacket(esplusplayer_handle player,esplusplayer_es_packet pkt) {
1022  *               // ... your codes ...
1023  *               if(feed is allowed && buffer is enough) {
1024  *                   esplusplayer_submit_packet(player, &pkt);
1025  *               }
1026  *               // ... your codes ...
1027  *           )
1028  *            esplusplayer_handle esplayer = esplusplayer_create();
1029  *            esplusplayer_set_prepare_async_done_cb(esplayer,OnPrepareDone,&esplayer);
1030  *            esplusplayer_set_ready_to_prepare_cb(esplayer,OnReadyToPrepare,&esplayer);
1031  *            esplusplayer_set_buffer_byte_status_cb(esplayer,OnBufferByteStatus,&esplayer);
1032  *            esplusplayer_set_buffer_time_status_cb(esplayer,OnBufferTimeStatus,&esplayer);
1033  *            esplusplayer_open(esplayer);
1034  *            esplusplayer_prepare_async(esplayer);
1035  *            // ... your codes ...
1036  *            //FeedEsPacket()(call a new thread to do this)
1037  *            // ... your codes ...
1038  *            esplusplayer_close(esplayer);
1039  *            esplusplayer_destroy(esplayer);
1040  * @endcode
1041  * @pre       User can submit es packets after
1042  *            esplusplayer_ready_to_prepare_cb() or
1043  *            esplusplayer_ready_to_seek_cb() is called.
1044  * @post      None
1045  * @exception None
1046  * @remark    Amount of packets for at least one decoded frame must be submitted
1047  *            after calling esplusplayer_prepare_async() or esplusplayer_seek()
1048  *            for invoking esplusplayer_prepare_async_done_cb() or
1049  *            esplusplayer_seek_done_cb() \n
1050  *            This api must be called from a different thread than other apis.
1051  * @see       esplusplayer_set_submit_data_type() \n
1052  *            esplusplayer_es_packet \n
1053  *            esplusplayer_buffer_status_cb() \n
1054  *            esplusplayer_ready_to_prepare_cb() \n
1055  *            esplusplayer_ready_to_seek_cb()
1056  */
1057 esplusplayer_submit_status esplusplayer_submit_packet(
1058     esplusplayer_handle handle, esplusplayer_es_packet* packet);
1059
1060 #ifdef TIZEN_FEATURE_TV
1061 /**
1062  * @brief     Submit encrypted es packet to decode and decrypt audio or video.
1063  * @param     [in] handle : esplusplayer handle.
1064  * @param     [in] packet : es packet pointer.
1065  * @param     [in] drm_info : information to decrypt es packet.
1066  *                            esplusplayer doesn't take ownership. user should
1067  *                            free it. if you deliver it as (null), this api
1068  *                            works as esplusplayer_submit_packet().
1069  * @return    @c ESPLUSPLAYER_SUBMIT_STATUS_SUCCESS : succeed to submit es
1070  *            packet,
1071  *            otherwise @c : fail to submit es packet.
1072  * @code
1073  *            refer to the sample code of esplusplayer_submit_packet();
1074  * @endcode
1075  * @pre       User can submit es packets after
1076  *            esplusplayer_ready_to_prepare_cb() or
1077  *            esplusplayer_ready_to_seek_cb() is called.
1078  * @post      None
1079  * @exception None
1080  * @remark    Amount of packets for at least one decoded frame must be submitted
1081  *            after calling esplusplayer_prepare_async() or esplusplayer_seek()
1082  *            for invoking esplusplayer_prepare_async_done_cb() or
1083  *            esplusplayer_seek_done_cb(). \n
1084  *            To use this api, Must set
1085  * ESPLUSPLAYER_SUBMIT_DATA_TYPE_ENCRYPTED_DATA using
1086  * esplusplayer_set_submit_data_type() \n This api must be called from a
1087  * different thread than other apis.
1088  * @see       esplusplayer_es_packet \n
1089  *            esplusplayer_drm_info \n
1090  *            esplusplayer_buffer_status_cb() \n
1091  *            esplusplayer_ready_to_prepare_cb() \n
1092  *            esplusplayer_ready_to_seek_cb() \n
1093  *            esplusplayer_submit_packet()
1094  */
1095 esplusplayer_submit_status esplusplayer_submit_encrypted_packet(
1096     esplusplayer_handle handle, esplusplayer_es_packet* packet,
1097     esplusplayer_drm_info* drm_info);
1098 #endif
1099
1100 /**
1101  * @brief     Generate EOS(End Of Stream) packet explicitly and submit it to the
1102  *            player.
1103  * @param     [in] handle : esplusplayer handle.
1104  * @param     [in] type : stream type which reaches eos.
1105  * @return    @c ESPLUSPLAYER_SUBMIT_STATUS_SUCCESS : succeed to submit EOS
1106  * packet,
1107  *            otherwise @c : fail to submit EOS packet.
1108  * @code
1109  *            esplusplayer_handle esplayer = esplusplayer_create();
1110  *            // ... your codes ...
1111  *            esplusplayer_submit_eos_packet(esplayer,ESPLUSPLAYER_STREAM_TYPE_VIDEO);
1112  *            // ... your codes ...
1113  * @endcode
1114  * @pre       None
1115  * @post      None
1116  * @exception None
1117  */
1118 esplusplayer_submit_status esplusplayer_submit_eos_packet(
1119     esplusplayer_handle handle, esplusplayer_stream_type type);
1120
1121 /**
1122  * @brief     Set audio stream to have contents information.
1123  * @param     [in] handle : esplusplayer handle.
1124  * @param     [in] stream : audio stream pointer.
1125  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of esplusplayer_error_type
1126  *            values will be returned.
1127  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
1128  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
1129  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation failed
1130  * @code
1131  *            esplusplayer_open(esplayer);
1132  *            esplusplayer_audio_stream_info audio_stream;
1133  *            audio_stream.codec_data = nullptr;
1134  *            audio_stream.codec_data_length = 0;
1135  *            esplusplayer_set_audio_stream_info(esplayer, &audio_stream);
1136  *            // ... your codes ...
1137  *            esplusplayer_close(esplayer);
1138  * @endcode
1139  * @pre       The player state must be set to #ESPLUSPLAYER_STATE_IDLE except
1140  *            audio stream is deactivated.
1141  * @post      None
1142  * @exception None
1143  * @remark    This API have to be called before calling the
1144  *            esplusplayer_prepare_async().
1145  * @see       esplusplayer_open() \n
1146  *            esplusplayer_audio_stream_info
1147  */
1148 int esplusplayer_set_audio_stream_info(esplusplayer_handle handle,
1149                                        esplusplayer_audio_stream_info* stream);
1150
1151 /**
1152  * @brief     Set video stream to have contents information.
1153  * @param     [in] handle : esplusplayer handle.
1154  * @param     [in] stream : video stream pointer.
1155  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of esplusplayer_error_type
1156  *            values will be returned.
1157  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
1158  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
1159  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation failed
1160  * @pre       The player state must be set to #ESPLUSPLAYER_STATE_IDLE except
1161  *            video stream is deactivated.
1162  * @post      None
1163  * @exception None
1164  * @remark    This API have to be called before calling the
1165  *            esplusplayer_prepare_async().
1166  * @see       esplusplayer_audio_stream_info
1167  *            esplusplayer_activate
1168  */
1169 int esplusplayer_set_video_stream_info(esplusplayer_handle handle,
1170                                        esplusplayer_video_stream_info* stream);
1171
1172 /**
1173  * @brief     Get the current playing time of the associated media.
1174  * @param     [in] handle : esplusplayer handle.
1175  * @param     [out] ms : current playing time in milliseconds.
1176  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of esplusplayer_error_type
1177  *            values will be returned.
1178  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
1179  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
1180  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation failed
1181  * @code
1182  *            prepare esplayer done
1183  *            esplusplayer_start(esplayer);
1184  *            // ... your codes ...
1185  *            uint64_t cur_time = 0;
1186  *            esplusplayer_get_playing_time(esplayer, &cur_time);
1187  *            // ... your codes ...
1188  *            esplusplayer_stop(esplayer);
1189  * @endcode
1190  * @pre       The player must be one of #ESPLUSPLAYER_STATE_PAUSE or
1191  *            #ESPLUSPLAYER_STATE_PLAYING.
1192  * @post      None
1193  * @exception None
1194  * @see       esplusplayer_prepare_async()
1195  */
1196 int esplusplayer_get_playing_time(esplusplayer_handle handle, uint64_t* ms);
1197
1198 /**
1199  * @brief     Get dropped frame counts in videosink.
1200  * @param     [in] handle : esplusplayer handle.
1201  * @param     [out] padaptive_info : dropped frame counts.
1202  * @param     [in] adaptive_type : type of adaptive info which APP want to get.
1203  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of esplusplayer_error_type
1204  *            values will be returned.
1205  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
1206  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
1207  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation failed
1208  * @code
1209  *            prepare esplayer done
1210  *            // ... your codes ...
1211  *            uint64_t count = 0;
1212  *            esplusplayer_get_adaptive_info(esplayer,
1213  *                static_cast<void*>(&count),ESPLUSPLAYER_ADAPT_INFO_TYPE_DROPPED_FRAMES);
1214  *            // ... your codes ...
1215  *            esplusplayer_stop(esplayer);
1216  * @endcode
1217  * @pre       The player must be one of #ESPLUSPLAYER_STATE_READY,
1218  *                    #ESPLUSPLAYER_STATE_PAUSE or #ESPLUSPLAYER_STATE_PLAYING.
1219  * @post      None
1220  * @exception None
1221  * @see       esplusplayer_prepare_async()
1222  */
1223 int esplusplayer_get_adaptive_info(
1224     esplusplayer_handle handle, void* padaptive_info,
1225     esplusplayer_adaptive_info_type adaptive_type);
1226
1227 /**
1228  * @brief     Set volume to player
1229  * @param     [in] handle : esplusplayer handle.
1230  * @param     [in] volume : volume level(0 ~ 100).
1231  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of esplusplayer_error_type
1232  *            values will be returned.
1233  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
1234  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
1235  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation failed
1236  * @code
1237  *            esplusplayer_open(esplayer);
1238  *            int vol = 80;
1239  *            esplusplayer_set_volume(esplayer, vol)
1240  *            // ... your codes ...
1241  *            esplusplayer_close(esplayer);
1242  * @endcode
1243  * @pre       The player state must be not #ESPLUSPLAYER_STATE_NONE.
1244  * @post      None
1245  * @exception None
1246  * @see       esplusplayer_open()
1247  */
1248 int esplusplayer_set_volume(esplusplayer_handle handle, const int volume);
1249
1250 /**
1251  * @brief     Get volume from player
1252  * @param     [in] handle : esplusplayer handle.
1253  * @param     [out] volume : volume ptr.
1254  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of esplusplayer_error_type
1255  *            values will be returned.
1256  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
1257  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
1258  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation failed
1259  * @code
1260  *            esplusplayer_open(esplayer);
1261  *            // ... your codes ...
1262  *            int vol = 0;
1263  *            esplusplayer_get_volume(esplayer, &vol)
1264  *            // ... your codes ...
1265  *            esplusplayer_close(esplayer);
1266  * @endcode
1267  * @pre       The player state must be not #ESPLUSPLAYER_STATE_NONE.
1268  * @post      None
1269  * @exception None
1270  * @see       esplusplayer_open()
1271  */
1272 int esplusplayer_get_volume(esplusplayer_handle handle, int* volume);
1273
1274 /**
1275  * @brief     Set decoded video frame buffer type.
1276  * @param     [in] handle : esplusplayer handle.
1277  * @param     [in] type : one of the video decoded buffer type to set .
1278  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of esplusplayer_error_type
1279  *            values will be returned.
1280  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
1281  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
1282  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation failed
1283  * @code
1284  *            esplusplayer_open(esplayer);
1285  *            esplusplayer_set_video_frame_buffer_type(esplayer,
1286  *                ESPLUSPLAYER_DECODED_VIDEO_FRAME_BUFFER_TYPE_NONE);
1287  *            // ... your codes ...
1288  *            esplusplayer_close(esplayer);
1289  * @endcode
1290  * @pre       The player state must be set to #ESPLUSPLAYER_STATE_IDLE when type
1291               is not equal to be
1292  ESPLUSPLAYER_DECODED_VIDEO_FRAME_BUFFER_TYPE_SCALE
1293               The player state must be not #ESPLUSPLAYER_STATE_NONE when
1294               type is equal to be
1295  ESPLUSPLAYER_DECODED_VIDEO_FRAME_BUFFER_TYPE_SCALE
1296  * @post      None
1297  * @exception None
1298  * @remark    reference can't support sw codec type.
1299  *            esplusplayer_set_media_packet_video_decoded_cb()
1300  *            esplusplayer_set_video_codec_type()
1301  *            when type is SCALE, the target scale resolution can be set by
1302  *            esplusplayer_set_video_frame_buffer_scale_resolution()
1303  * @see       esplusplayer_open()
1304  */
1305 int esplusplayer_set_video_frame_buffer_type(
1306     esplusplayer_handle handle,
1307     esplusplayer_decoded_video_frame_buffer_type type);
1308
1309 /**
1310  * @brief     Flush buffers for a player.
1311  * @param     [in] handle : esplusplayer handle ptr.
1312  * @param     [in] type : choose which stream data need to be
1313  *            flush,audio/video,if need flush all pipeline can call this API
1314  * twice.
1315  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of esplusplayer_error_type
1316  *            values will be returned.
1317  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
1318  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
1319  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation failed
1320  * @code
1321  *            prepare esplayer done
1322  *            // ... your codes ...
1323  *            esplusplayer_flush(esplayer, ESPLUSPLAYER_STREAM_TYPE_VIDEO);
1324  *            // ... your codes ...
1325  *            esplusplayer_stop(esplayer);
1326  * @endcode
1327  * @pre       The player state should greater than #ESPLUSPLAYER_STATE_IDLE
1328  * @post      None
1329  * @exception None
1330  * @see       esplusplayer_prepare_async()
1331  */
1332 int esplusplayer_flush(esplusplayer_handle handle,
1333                        esplusplayer_stream_type type);
1334
1335 /**
1336  * @brief     Convert the esplusplayer error type to a string.
1337  * @param     [in] type : esplusplayer error type
1338  * @return    @c not nullptr  the converted error string otherwise @c failed to
1339  *            convert the error.
1340  * @code
1341  *            // ... your codes ...
1342  *            const char* error;
1343  *            error = esplusplayer_get_error_string(ESPLUSPLAYER_ERROR_TYPE_NOT_SUPPORTED_FILE);
1344  *            // ... your codes ...
1345  * @endcode
1346  * @pre       None
1347  * @post      None
1348  * @exception None
1349  */
1350 const char* esplusplayer_get_error_string(esplusplayer_error_type type);
1351
1352 /**
1353  * @brief     Sets a callback function to be invoked when an error occurs.
1354  * @param     [in] handle : esplusplayer handle.
1355  * @param     [in] error_cb : the error callback function to register.
1356  * @param     [in] userdata : userdata of esplusplayer_error_cb()
1357  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of esplusplayer_error_type
1358  *            values will be returned.
1359  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
1360  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
1361  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation failed
1362  * @code
1363  *            static void OnError(const esplusplayer_error_type err_code, void*
1364  *                userdata) {
1365  *                //Something you want to do when error occur
1366  *                printf ("OnError\n");
1367  *            }
1368  *            esplusplayer_handle esplayer = esplusplayer_create();
1369  *            esplusplayer_set_error_cb(esplayer, OnError, nullptr);
1370  *            // ... your codes ...
1371  *            esplusplayer_destroy(esplayer);
1372  * @endcode
1373  * @pre       The player state must be set to #ESPLUSPLAYER_STATE_NONE
1374  *            or #ESPLUSPLAYER_STATE_IDLE.
1375  * @post      esplusplayer_error_cb() will be invoked.
1376  * @exception None
1377  * @remark    esplusplayer_error_cb()
1378  *            if error_cb is set to null, esplusplayer_error_cb() will not be
1379  *            invoked anymore.
1380  */
1381 int esplusplayer_set_error_cb(esplusplayer_handle handle,
1382                               esplusplayer_error_cb error_cb, void* userdata);
1383
1384 /**
1385  * @brief     Set a callback function to be invoked when buffer underrun or
1386  *            overflow is occurred.
1387  * @param     [in] handle : esplusplayer handle.
1388  * @param     [in] buffer_status_cb : the buffer status callback function to
1389  * register.
1390  * @param     [in] userdata : userdata of esplusplayer_buffer_status_cb()
1391  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of esplusplayer_error_type
1392  *            values will be returned.
1393  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
1394  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
1395  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation failed
1396  * @code
1397  *            refer to the sample code of esplusplayer_set_error_cb();
1398  * @endcode
1399  * @pre       The player state must be set to #ESPLUSPLAYER_STATE_NONE
1400  *            or #ESPLUSPLAYER_STATE_IDLE.
1401  * @post      esplusplayer_buffer_status_cb() will be invoked.
1402  * @exception None
1403  * @remark    esplusplayer_buffer_status_cb()
1404  *            if buffer_status_cb is set to null,
1405  *            esplusplayer_buffer_status_cb() will not be invoked anymore.
1406  */
1407 int esplusplayer_set_buffer_status_cb(
1408     esplusplayer_handle handle, esplusplayer_buffer_status_cb buffer_status_cb,
1409     void* userdata);
1410
1411 /**
1412  * @brief     Set a callback function to be invoked when buffer underrun or
1413  *            overflow is occurred and buffer size in byte will be passed.
1414  * @param     [in] handle : esplusplayer handle.
1415  * @param     [in] buffer_status_cb : the buffer byte status callback function
1416  *            to register.
1417  * @param     [in] userdata : userdata of esplusplayer_buffer_byte_status_cb()
1418  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of esplusplayer_error_type
1419  *            values will be returned.
1420  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
1421  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
1422  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation failed
1423  * @code
1424  *            refer to the sample code of esplusplayer_submit_packet();
1425  * @endcode
1426  * @pre       The player state must be set to #ESPLUSPLAYER_STATE_NONE
1427  *            or #ESPLUSPLAYER_STATE_IDLE.
1428  * @post      esplusplayer_buffer_byte_status_cb() will be invoked.
1429  * @exception None
1430  * @remark    esplusplayer_buffer_byte_status_cb()
1431  */
1432 int esplusplayer_set_buffer_byte_status_cb(
1433     esplusplayer_handle handle,
1434     esplusplayer_buffer_byte_status_cb buffer_status_cb, void* userdata);
1435
1436 /**
1437  * @brief     Set a callback function to be invoked when buffer underrun or
1438  *            overflow is occurred and buffer size in time will be passed.
1439  * @param     [in] handle : esplusplayer handle.
1440  * @param     [in] buffer_status_cb : the buffer time status callback function
1441  *            to register.
1442  * @param     [in] userdata : userdata of esplusplayer_buffer_time_status_cb()
1443  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of esplusplayer_error_type
1444  *            values will be returned.
1445  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
1446  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
1447  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation failed
1448  * @code
1449               refer to the sample code of esplusplayer_submit_packet();
1450  * @endcode
1451  * @pre       The player state must be set to #ESPLUSPLAYER_STATE_NONE
1452  *            or #ESPLUSPLAYER_STATE_IDLE.
1453  * @post      esplusplayer_buffer_time_status_cb() will be invoked.
1454  * @exception None
1455  * @remark    esplusplayer_buffer_time_status_cb(),
1456  *            esplusplayer_buffer_time_status_cb() will be invoked only
1457  *            when the duration value of espacket is set.
1458  *            if buffer_status_cb is set to null,
1459  *            esplusplayer_buffer_time_status_cb() will not be invoked anymore.
1460  */
1461 int esplusplayer_set_buffer_time_status_cb(
1462     esplusplayer_handle handle,
1463     esplusplayer_buffer_time_status_cb buffer_status_cb, void* userdata);
1464
1465 /**
1466  * @brief     Set buffer size with different option
1467  * @param     [in] handle : esplusplayer handle.
1468  * @param     [in] option : the option of buffer size.
1469  * @param     [in] size : size of selected buffer option.
1470  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of esplusplayer_error_type
1471  *            values will be returned.
1472  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
1473  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
1474  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation failed
1475  * @code
1476  *            esplusplayer_open(esplayer);
1477  *            esplusplayer_set_buffer_size(esplayer,ESPLUSPLAYER_BUFFER_AUDIO_MAX_BYTE_SIZE,10240)
1478  *            // ... your codes ...
1479  *            esplusplayer_close(esplayer);
1480  * @endcode
1481  * @pre       The player state must be set to #ESPLUSPLAYER_STATE_IDLE.
1482  * @post      None
1483  * @exception None
1484  * @remark    esplusplayer_buffer_option
1485  * @see       esplusplayer_open()
1486  */
1487 int esplusplayer_set_buffer_size(esplusplayer_handle handle,
1488                                  esplusplayer_buffer_option option,
1489                                  uint64_t size);
1490 /**
1491  * @brief     Set a callback function to be invoked when resource confliction is
1492  * occurred.
1493  * @param     [in] handle : esplusplayer handle.
1494  * @param     [in] resource_conflicted_cb : the resource conflicted callback
1495  *            function to register.
1496  * @param     [in] userdata : userdata of resource_conflicted_cb()
1497  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of esplusplayer_error_type
1498  *            values will be returned.
1499  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
1500  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
1501  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation failed
1502  * @code
1503  *            refer to the sample code of esplusplayer_set_error_cb();
1504  * @endcode
1505  * @pre       The player state must be set to #ESPLUSPLAYER_STATE_NONE
1506  *            or #ESPLUSPLAYER_STATE_IDLE.
1507  * @post      esplusplayer_resource_conflicted_cb() will be invoked.
1508  * @exception None
1509  * @remark    esplusplayer_resource_conflicted_cb()
1510  *            if resource_conflicted_cb is set to null,
1511  *            esplusplayer_resource_conflicted_cb() will not be invoked
1512  *            anymore.
1513  */
1514 int esplusplayer_set_resource_conflicted_cb(
1515     esplusplayer_handle handle,
1516     esplusplayer_resource_conflicted_cb resource_conflicted_cb, void* userdata);
1517
1518 /**
1519  * @brief     Set a callback function to be invoked when player has reached the
1520  *            end of stream.
1521  * @param     [in] handle : esplusplayer handle.
1522  * @param     [in] eos_cb : the eos callback function to register.
1523  * @param     [in] userdata : userdata of esplusplayer_eos_cb()
1524  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of esplusplayer_error_type
1525  *            values will be returned.
1526  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
1527  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
1528  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation failed
1529  * @code
1530  *            refer to the sample code of esplusplayer_set_error_cb();
1531  * @endcode
1532  * @pre       The player state must be set to #ESPLUSPLAYER_STATE_NONE
1533  *            or #ESPLUSPLAYER_STATE_IDLE.
1534  * @post      esplusplayer_eos_cb() will be invoked.
1535  * @exception None
1536  * @remark    esplusplayer_eos_cb()
1537  *            if eos_cb is set to null, esplusplayer_eos_cb() will not be
1538  *            invoked anymore.
1539  */
1540 int esplusplayer_set_eos_cb(esplusplayer_handle handle,
1541                             esplusplayer_eos_cb eos_cb, void* userdata);
1542
1543 /**
1544  * @brief     Set a callback function to be invoked when player is prepared to
1545  *            receive es packets after calling esplusplayer_prepare_async().
1546  * @param     [in] handle : esplusplayer handle.
1547  * @param     [in] ready_to_prepare_cb : the ready to prepare callback function
1548  *            to register.
1549  * @param     [in] userdata : userdata of ready_to_prepare_cb()
1550  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of esplusplayer_error_type
1551  *            values will be returned.
1552  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
1553  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
1554  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation failed
1555  * @code
1556  *            refer to the sample code of esplusplayer_submit_packet();
1557  * @endcode
1558  * @pre       The player state must be set to #ESPLUSPLAYER_STATE_NONE
1559  *            or #ESPLUSPLAYER_STATE_IDLE.
1560  * @post      None
1561  * @exception None
1562  * @remark    esplusplayer_prepare_async()
1563  *            if ready_to_prepare_cb is set to null,
1564  *            esplusplayer_ready_to_prepare_cb() will not be invoked anymore.
1565  */
1566 int esplusplayer_set_ready_to_prepare_cb(
1567     esplusplayer_handle handle,
1568     esplusplayer_ready_to_prepare_cb ready_to_prepare_cb, void* userdata);
1569
1570 /**
1571  * @brief     Set a callback function to be invoked when player is prepared to
1572  *            be started.
1573  * @param     [in] handle : esplusplayer handle.
1574  * @param     [in] prepare_async_done_cb : the prepare async done callback
1575  * function to register.
1576  * @param     [in] userdata : userdata of prepare_async_done_cb()
1577  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of esplusplayer_error_type
1578  *            values will be returned.
1579  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
1580  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
1581  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation failed
1582  * @code
1583  *            refer to the sample code of plusplayer_prepare_async();
1584  * @endcode
1585  * @pre       The player state must be set to #ESPLUSPLAYER_STATE_NONE
1586  *            or #ESPLUSPLAYER_STATE_IDLE.
1587  * @post      esplusplayer_prepare_async_done_cb() will be invoked.
1588  * @exception It is prohibited to call any player APIs at
1589  *            esplusplayer_prepare_async_done_cb callback.
1590  * @remark    esplusplayer_prepare_async_done_cb()
1591  *            if prepare_async_done_cb is set to null,
1592  *            esplusplayer_prepare_async_done_cb() will not be
1593  *            invoked anymore.
1594  * @see       plusplayer_prepare_async
1595  */
1596 int esplusplayer_set_prepare_async_done_cb(
1597     esplusplayer_handle handle,
1598     esplusplayer_prepare_async_done_cb prepare_async_done_cb, void* userdata);
1599
1600 /**
1601  * @brief     Set a callback function to be invoked when player is prepared to
1602  *            be started.
1603  * @param     [in] handle : esplusplayer handle.
1604  * @param     [in] seek_done_cb : the seek done callback function to register.
1605  * @param     [in] userdata : userdata of esplusplayer_seek_done_cb()
1606  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of esplusplayer_error_type
1607  *            values will be returned.
1608  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
1609  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
1610  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation failed
1611  * @code
1612  *            refer to the sample code of esplusplayer_set_error_cb();
1613  * @endcode
1614  * @pre       The player state must be set to #ESPLUSPLAYER_STATE_NONE
1615  *            or #ESPLUSPLAYER_STATE_IDLE.
1616  * @post      esplusplayer_seek_done_cb() will be invoked.
1617  *            if seek_done_cb is set to null, esplusplayer_seek_done_cb() will
1618  *            not be invoked anymore.
1619  * @exception None
1620  */
1621 int esplusplayer_set_seek_done_cb(esplusplayer_handle handle,
1622                                   esplusplayer_seek_done_cb seek_done_cb,
1623                                   void* userdata);
1624
1625 /**
1626  * @brief     Set a callback function to be invoked when player is prepared to
1627  *            receive es packets after flushing all submitted es packets for
1628  *            seek.
1629  * @param     [in] handle : esplusplayer handle.
1630  * @param     [in] ready_to_seek_cb : the ready to seek callback function to
1631  *            register.
1632  * @param     [in] userdata : userdata of esplusplayer_ready_to_seek_cb()
1633  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of esplusplayer_error_type
1634  *            values will be returned.
1635  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
1636  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
1637  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation failed
1638  * @code
1639  *            refer to the sample code of esplusplayer_set_error_cb();
1640  * @endcode
1641  * @pre       The player state must be set to #ESPLUSPLAYER_STATE_NONE
1642  *            or #ESPLUSPLAYER_STATE_IDLE.
1643  * @post      None
1644  * @exception None
1645  * @remark    esplusplayer_seek()
1646  *            if ready_to_seek_cb is set to null, esplusplayer_ready_to_seek_cb()
1647  *            will not be invoked anymore.
1648  */
1649 int esplusplayer_set_ready_to_seek_cb(
1650     esplusplayer_handle handle, esplusplayer_ready_to_seek_cb ready_to_seek_cb,
1651     void* userdata);
1652
1653 /**
1654  * @brief     Set a callback function to be invoked when player decoded video
1655  *            frame. A video frame can be retrieved using a registered callback.
1656  * @param     [in] handle : esplusplayer handle.
1657  * @param     [in] media_packet_video_decoded_cb : the media packet video
1658  * decoded callback function to register.
1659  * @param     [in] userdata : userdata of
1660  * esplusplayer_set_media_packet_video_decoded_cb()
1661  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of esplusplayer_error_type
1662  *            values will be returned.
1663  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
1664  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
1665  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation failed
1666  * @code
1667  *            refer to the sample code of esplusplayer_set_error_cb();
1668  * @endcode
1669  * @pre       The player state must be set to #ESPLUSPLAYER_STATE_NONE
1670  *            or #ESPLUSPLAYER_STATE_IDLE.
1671  * @post      None
1672  * @exception None
1673  * @remark    esplusplayer_set_video_frame_buffer_type()
1674  *            if media_packet_video_decoded_cb is set to null,
1675  *            esplusplayer_error_cb() will not be invoked anymore.
1676  *            media packets have to be released by calling
1677  *            esplusplayer_decoded_buffer_destroy().
1678  * @see       esplusplayer_set_video_frame_buffer_scale_resolution
1679  */
1680 int esplusplayer_set_media_packet_video_decoded_cb(
1681     esplusplayer_handle handle,
1682     esplusplayer_media_packet_video_decoded_cb media_packet_video_decoded_cb,
1683     void* userdata);
1684
1685 /**
1686  * @brief     Set closed caption callback function.
1687  * @description   In this function set closed caption callback to handle the
1688  *            closed caption. If there is closed caption to display,
1689  *            esplusplayer_closed_caption_cb will be called to notify there
1690  *            is closed caption to display.
1691  * @param     [in] handle : esplusplayer handle ptr.
1692  * @param     [in] closed_caption_cb :  the closed caption callback  function to
1693  * register.
1694  * @param     [in] userdata : userdata of esplusplayer_closed_caption_cb
1695  *            callback function.
1696  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of esplusplayer_error_type
1697  *            values will be returned.
1698  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
1699  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
1700  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation failed
1701  * @code
1702  *            refer to the sample code of esplusplayer_set_error_cb();
1703  * @endcode
1704  * @pre       The player state must be set to #ESPLUSPLAYER_STATE_NONE
1705  *            or #ESPLUSPLAYER_STATE_IDLE.
1706  * @post      When there is closed caption data, call
1707  *            esplusplayer_closed_caption_cb to notify that there is closed
1708  *            caption needed to be displayed.
1709  * @exception None
1710  * @remark    esplusplayer_closed_caption_cb \n
1711  *            [in] data : closed caption data \n
1712  *            [in] size : length of closed caption data \n
1713  *            [in] userdata : userdata of esplusplayer_closed_caption_cb
1714  *            callback function.
1715  *            if closed_caption_cb is set to null, esplusplayer_closed_caption_cb()
1716  *            will not be invoked anymore.
1717  */
1718 int esplusplayer_set_closed_caption_cb(
1719     esplusplayer_handle handle,
1720     esplusplayer_closed_caption_cb closed_caption_cb, void* userdata);
1721
1722 /**
1723  * @brief     Set a callback function to be invoked when the flush operation is
1724  *            done.
1725  * @param     [in] handle : esplusplayer handle.
1726  * @param     [in] flush_done_cb : the flush done callback function to register.
1727  * @param     [in] userdata : userdata of esplusplayer_flush_done_cb()
1728  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of esplusplayer_error_type
1729  *            values will be returned.
1730  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
1731  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
1732  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation failed
1733  * @code
1734  *            refer to the sample code of esplusplayer_set_error_cb();
1735  * @endcode
1736  * @pre       This api should be called before esplusplayer_flush() is called
1737  * @post      esplusplayer_flush_done_cb() will be invoked.
1738  * @exception None
1739  * @remark    called before esplusplayer_flush().
1740  *            if flush_done_cb is set to null, esplusplayer_error_cb() will
1741  *            not be invoked anymore.
1742  */
1743 int esplusplayer_set_flush_done_cb(esplusplayer_handle handle,
1744                                    esplusplayer_flush_done_cb flush_done_cb,
1745                                    void* userdata);
1746 /**
1747  * @brief     Set a callback function to be invoked when a specific event
1748  *            occurs.
1749  * @param     [in] handle : esplusplayer handle.
1750  * @param     [in] event_cb : the callback function to register.
1751  * @param     [in] userdata : userdata of esplusplayer_event_cb()
1752  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of esplusplayer_error_type
1753  *            values will be returned.
1754  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
1755  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
1756  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation failed
1757  * @code
1758  *            refer to the sample code of esplusplayer_set_error_cb();
1759  * @endcode
1760  * @pre       The player state must be set to #ESPLUSPLAYER_STATE_NONE
1761  *            or #ESPLUSPLAYER_STATE_IDLE.
1762  * @post      esplusplayer_event_cb() will be invoked.
1763  * @exception None
1764  * @remark    esplusplayer_set_event_cb()
1765  *            if event_cb is set to null, esplusplayer_event_cb() will not be
1766  *            invoked anymore.
1767  */
1768 int esplusplayer_set_event_cb(esplusplayer_handle handle,
1769                               esplusplayer_event_cb event_cb, void* userdata);
1770 /**
1771  * @brief     Provided api for destroying decoded buffer.
1772  * @param     [in] handle : esplusplayer handle.
1773  * @param     [in] packet : the decoded buffer.
1774  * @return    @c one of esplusplayer_error_type values will be returned.
1775  * @pre       The player state can be greater than #ESPLUSPLAYER_STATE_IDLE.
1776  * @post      esplusplayer_decoded_buffer_destroy will be invoked for video
1777  *            texturing
1778  * @exception None
1779  * @remark    esplusplayer_decoded_buffer_destroy().
1780  */
1781 int esplusplayer_decoded_buffer_destroy(
1782     esplusplayer_handle handle, esplusplayer_decoded_video_packet* packet);
1783
1784 /**
1785  * @brief     Provided api for setting low latency mode, multiple modes can be
1786  *            set to duplicate.
1787  * @param     [in] handle : esplusplayer handle.
1788  * @param     [in] mode : one of the low latency mode to set.
1789  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of esplusplayer_error_type
1790  *            values will be returned.
1791  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
1792  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
1793  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation failed
1794  * @code
1795  *            esplusplayer_open(esplayer);
1796  *            esplusplayer_set_low_latency_mode(esplayer, ESPLUSPLAYER_LOW_LATENCY_MODE_NONE);
1797  *            // ... your codes ...
1798  *            esplusplayer_close(esplayer);
1799  * @endcode
1800  * @pre       The player state must be set to #ESPLUSPLAYER_STATE_IDLE.
1801  * @post      None
1802  * @exception None
1803  * @remark    Public supports #ESPLUSPLAYER_LOW_LATENCY_MODE_DISABLE_PREROLL only.
1804  *            No operation is performed and #ESPLUSPLAYER_ERROR_TYPE_NONE will be returned,
1805  *            if @a mode is not #ESPLUSPLAYER_LOW_LATENCY_MODE_DISABLE_PREROLL to make compatible with TV API.
1806  * @see       esplusplayer_open()
1807  */
1808 int esplusplayer_set_low_latency_mode(esplusplayer_handle handle,
1809                                       esplusplayer_low_latency_mode mode);
1810
1811 /**
1812  * @brief     Provided api for setting unlimited max buffer mode, the player
1813  *            does not limit es packet transmission although in buffer overrun
1814  * status
1815  * @param     [in] handle : esplusplayer handle.
1816  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of esplusplayer_error_type
1817  *            values will be returned.
1818  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
1819  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
1820  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation failed
1821  * @code
1822  *            esplusplayer_open(esplayer);
1823  *            esplusplayer_set_unlimited_max_buffer_mode(esplayer);
1824  *            // ... your codes ...
1825  *            esplusplayer_close(esplayer);
1826  * @endcode
1827  * @pre       The player state must be set to #ESPLUSPLAYER_STATE_IDLE.
1828  * @post      None
1829  * @exception None
1830  * @remark    esplusplayer_set_unlimited_max_buffer_mode().
1831  *            esplusplayer_buffer_status_cb() will be invoked in
1832  *            overrun/underrun buffer status. but
1833  *            esplusplayer_submit_packet() /
1834  *            esplusplayer_submit_encrypted_packet()
1835  *            does not return ESPLUSPLAYER_SUBMIT_STATUS_FULL
1836  * @see       esplusplayer_open() \n
1837  *            esplusplayer_submit_packet() \n
1838  *            esplusplayer_submit_encrypted_packet()
1839  */
1840 int esplusplayer_set_unlimited_max_buffer_mode(esplusplayer_handle handle);
1841
1842 /**
1843  * @brief     Provided api for setting audio codec type for playback.
1844  * @param     [in] handle : esplusplayer handle.
1845  * @param     [in] type : codec type(hardware/software).
1846  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of esplusplayer_error_type
1847  *            values will be returned.
1848  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
1849  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
1850  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation failed
1851  * @code
1852  *            esplusplayer_open(esplayer);
1853  *            esplusplayer_set_audio_codec_type(esplayer,ESPLUSPLAYER_AUDIO_CODEC_TYPE_SW);
1854  *            // ... your codes ...
1855  *            esplusplayer_close(esplayer);
1856  * @endcode
1857  * @pre       The player state must be set to #ESPLUSPLAYER_STATE_IDLE.
1858               When the audio stream is not set or deactivated, it can be set
1859               in #ESPLUSPLAYER_STATE_READY, #ESPLUSPLAYER_STATE_PAUSED and
1860               #ESPLUSPLAYER_STATE_PLAYING. The set codec type will be
1861               applied when esplusplayer_activate() is called.
1862  * @post      None
1863  * @exception None
1864  * @see       esplusplayer_open() \n
1865  *            esplusplayer_deactivate() \n
1866               esplusplayer_activate() \n
1867               esplusplayer_set_audio_stream_info()
1868  */
1869 int esplusplayer_set_audio_codec_type(esplusplayer_handle handle,
1870                                       esplusplayer_audio_codec_type type);
1871 /**
1872  * @brief     Provided api for setting video codec type for playback.
1873  * @param     [in] handle : esplusplayer handle.
1874  * @param     [in] type : codec type(hardware/software).
1875  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of esplusplayer_error_type
1876  *            values will be returned.
1877  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
1878  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
1879  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation failed
1880  * @code
1881  *            esplusplayer_open(esplayer);
1882  *            esplusplayer_set_video_codec_type(esplayer,ESPLUSPLAYER_VIDEO_CODEC_TYPE_SW);
1883  *            // ... your codes ...
1884  *            esplusplayer_close(esplayer);
1885  * @endcode
1886  * @pre       The player state must be set to #ESPLUSPLAYER_STATE_IDLE.
1887               When the video stream is not set or deactivated, it can be set
1888               in #ESPLUSPLAYER_STATE_READY, #ESPLUSPLAYER_STATE_PAUSED and
1889               #ESPLUSPLAYER_STATE_PLAYING. The set codec type will be
1890               applied when esplusplayer_activate() is called.
1891  * @post      None
1892  * @exception None
1893  * @see       esplusplayer_open() \n
1894  *            esplusplayer_deactivate() \n
1895               esplusplayer_activate() \n
1896               esplusplayer_set_video_stream_info()
1897  */
1898 int esplusplayer_set_video_codec_type(esplusplayer_handle handle,
1899                                       esplusplayer_video_codec_type type);
1900 /**
1901  * @brief     Provided api for setting render time offset
1902  * @param     [in] handle : esplusplayer handle ptr.
1903  * @param     [in] type : stream type
1904  * @param     [in] offset : offset (in milliseconds).
1905  *                          G_MININT64 <= offset * 1000000 <= G_MAXINT64
1906  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of esplusplayer_error_type
1907  *            values will be returned.
1908  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
1909  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
1910  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation failed
1911  * @code
1912  *            esplusplayer_open(esplayer);
1913  *            esplusplayer_set_low_latency_mode(esplayer,ESPLUSPLAYER_LOW_LATENCY_MODE_NONE);
1914  *            prepare esplayer
1915  *            // ... your codes ...
1916  *            int64_t set_offset = 10;
1917  *            esplusplayer_set_render_time_offset(esplayer,ESPLUSPLAYER_STREAM_TYPE_VIDEO,
1918  *                                                set_offset);
1919  *            int64_t get_offset = 0;
1920  *            esplusplayer_get_render_time_offset(esplayer_,ESPLUSPLAYER_STREAM_TYPE_VIDEO,
1921  *                                                &get_offset);
1922  *            // ... your codes ...
1923  *            esplusplayer_close(esplayer);
1924  * @endcode
1925  * @pre       The player state must be set to #ESPLUSPLAYER_STATE_READY,
1926  *            #ESPLUSPLAYER_STATE_PAUSED or #ESPLUSPLAYER_STATE_PLAYING.
1927  *            It have to be set to low latency mode. (all mode except
1928  *            # ESPLUSPLAYER_LOW_LATENCY_MODE_DISABLE_SYNC)
1929  * @remark    esplusplayer_set_low_latency_mode().
1930  * @post      None
1931  * @exception None
1932  * @see       esplusplayer_open()
1933  *            esplusplayer_get_render_time_offset()
1934  */
1935 int esplusplayer_set_render_time_offset(esplusplayer_handle handle,
1936                                         esplusplayer_stream_type type,
1937                                         int64_t offset);
1938 /**
1939  * @brief     Provided api for getting render time offset
1940  * @param     [in] handle : esplusplayer handle ptr.
1941  * @param     [in] type : stream type
1942  * @param     [in] offset : offset ptr (in milliseconds).
1943  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success,otherwise @c one of esplusplayer_error_type
1944  *            values will be returned.
1945  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
1946  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
1947  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation failed
1948  * @pre       The player state must be set to #ESPLUSPLAYER_STATE_READY,
1949  *            #ESPLUSPLAYER_STATE_PAUSED or #ESPLUSPLAYER_STATE_PLAYING.
1950  *            It have to be set to low latency mode.
1951  * @remark    esplusplayer_set_low_latency_mode().
1952  * @post      None
1953  * @exception None
1954  * see        esplusplayer_set_render_time_offset()
1955  */
1956 int esplusplayer_get_render_time_offset(esplusplayer_handle handle,
1957                                         esplusplayer_stream_type type,
1958                                         int64_t* offset);
1959 /**
1960  * @brief     Requests decoded video frame packet to acquire it. it works only
1961  *            with #ESPLUSPLAYER_DECODED_VIDEO_FRAME_BUFFER_TYPE_MANUAL_COPY
1962  *            mode
1963  * @param     [in] handle : esplusplayer handle.
1964  * @param     [out] packet : the decoded buffer.
1965  * @param     [out] status : (nullable) the result of video frame requested
1966  * @pre       The player state must be one of #ESPLUSPLAYER_STATE_READY or
1967  *            #ESPLUSPLAYER_STATE_PAUSED or #ESPLUSPLAYER_STATE_PLAYING.
1968  * @post      None
1969  * @return    #ESPLUSPLAYER_ERROR_TYPE_NONE on success, otherwise one of
1970  *            esplusplayer_error_type values will be returned.
1971  * @exception None
1972  * @version   4.0
1973  * @see       esplusplayer_set_video_frame_buffer_type()
1974  * @see       esplusplayer_decoded_buffer_destroy()
1975  * @see       esplusplayer_decoded_video_frame_buffer_type
1976  * @code
1977  * ...
1978  * esplusplayer_set_video_frame_buffer_type(handle,
1979  * ESPLUSPLAYER_DECODED_VIDEO_FRAME_BUFFER_TYPE_MANUAL_COPY);
1980  * ...
1981  * esplusplayer_prepare_async(handle);
1982  * ...
1983  * // after prepared
1984  * esplusplayer_decoded_video_packet packet;
1985  * esplusplayer_get_decoded_video_frame_status_type state;
1986  * int retval = esplusplayer_get_decoded_video_packet(handle, &packet, &state);
1987  * if (state == ESPLUSPLAYER_GET_DECVIDEOFRAME_STATUS_SUCCESS) {
1988  *   // successful case.
1989  *   // in this case, retval will be ESPLUSPLAYER_ERROR_TYPE_NONE
1990  *   // you have to call esplusplayer_decoded_buffer_destroy() after using the
1991  *   // packet
1992  *   ...
1993  *   esplusplayer_decoded_buffer_destroy(handle, &packet);
1994  * } else if (state ==
1995  * ESPLUSPLAYER_GET_DECVIDEOFRAME_STATUS_NO_REMAINING_BUFFER) {
1996  *   // app has to call esplusplayer_decoded_buffer_destroy() with previous
1997  *   // video packet.
1998  *   // it means player couldn't draw the video frame into a buffer due to no
1999  * buffer.
2000  *   // in this case ,retval will be ESPLUSPLAYER_ERROR_TYPE_NONE
2001  * } else if (state ==
2002  * ESPLUSPLAYER_GET_DECVIDEOFRAME_STATUS_NO_FILLED_BUFFER) {
2003  *   // it means app should retry to get decoded video packet.
2004  *   // in most case, there were no buffers drawn in the timing you called this
2005  *   // api.
2006  *   // in this case, retval will be ESPLUSPLAYER_ERROR_TYPE_NONE
2007  * } else if (state == ESPLUSPLAYER_GET_DECVIDEOFRAME_STATUS_UNKNOWN) {
2008  *   // internal error happened
2009  *   // in this case, retval will be ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION
2010  * }
2011  * ...
2012  * @endcode
2013  */
2014 int esplusplayer_get_decoded_video_packet(
2015     esplusplayer_handle handle, esplusplayer_decoded_video_packet* packet,
2016     esplusplayer_get_decoded_video_frame_status_type* status);
2017
2018 /**
2019  * @brief     Provided api for enabling video hole.
2020  * @param     [in] handle : esplusplayer handle.
2021  * @param     [in] value : the value of video hole.
2022  *            (@c true = video hole enabled, @c false = video hole disabled)
2023  * @return    @c ESPLUSPLAYER_ERROR_TYPE_NONE on success, otherwise @c one of esplusplayer_error_type
2024  *            values will be returned.
2025  * @retval    #ESPLUSPLAYER_ERROR_TYPE_NONE Successful
2026  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_PARAMETER Invalid parameter
2027  * @retval    #ESPLUSPLAYER_ERROR_TYPE_INVALID_OPERATION Internal operation failed
2028  * @code
2029  *            esplusplayer_open(esplayer);
2030  *            esplusplayer_enable_video_hole(esplayer, false);
2031  *            // ... your codes ...
2032  *            esplusplayer_close(esplayer);
2033  * @endcode
2034  * @pre       The player state must not be #ESPLUSPLAYER_STATE_NONE.
2035  * @remark    To disable video hole, esplusplayer_decoded_video_frame_buffer_type() must
2036  *            not be set to #ESPLUSPLAYER_DECODED_VIDEO_FRAME_BUFFER_TYPE_NONE.
2037  *            To enable video hole, esplusplayer_set_display() must be set to #ESPLUSPLAYER_DISPLAY_TYPE_OVERLAY
2038  * @post      None
2039  * @exception None
2040  * @see       esplusplayer_set_video_frame_buffer_type()
2041  *            esplusplayer_set_media_packet_video_decoded_cb()
2042  */
2043 int esplusplayer_enable_video_hole(esplusplayer_handle handle, const bool value);
2044
2045 #ifdef __cplusplus
2046 }
2047 #endif
2048
2049 #endif  // __PLUSPLAYER_ESPLUSPLAYER_CAPI_ESPLUSPLAYER_CAPI_H__