[ACR-1075] Add new APIs to set buffering size

Change-Id: I04485a0980a4b9113b9625caa77e0767d51b1ff5

diff --git a/include/player.h b/include/player.h
index a99ee0d..5228ecd 100644 (file)
--- a/include/player.h
+++ b/include/player.h
@@ -268,8 +268,8 @@ typedef void (*player_subtitle_updated_cb)(unsigned long duration, char *text, v
 
 /**
  * @brief Called when the media player is prepared.
- * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
  * @details It will be invoked when player has reached the begin of stream.
+ * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
  * @param[in]   user_data  The user data passed from the callback registration function
  * @pre player_prepare_async() will cause this callback.
  * @post The player state will be #PLAYER_STATE_READY.
@@ -279,8 +279,8 @@ typedef void (*player_prepared_cb)(void *user_data);
 
 /**
  * @brief Called when the media player is completed.
- * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
  * @details It will be invoked when player has reached the end of the stream.
+ * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
  * @param[in]   user_data  The user data passed from the callback registration function
  * @pre It will be invoked when the playback is completed if you register this callback using player_set_completed_cb().
  * @see player_set_completed_cb()
@@ -298,10 +298,10 @@ typedef void (*player_seek_completed_cb)(void *user_data);
 
 /**
  * @brief Called when the media player is interrupted.
- * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
  * @details If the code is #PLAYER_INTERRUPTED_BY_RESOURCE_CONFLICT, the player handle will be unprepared.
- * @param[in]  error_code      The interrupted error code
- * @param[in]  user_data       The user data passed from the callback registration function
+ * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
+ * @param[in] code        The interrupted error code
+ * @param[in] user_data   The user data passed from the callback registration function
  * @see player_set_interrupted_cb()
  * @see player_unset_interrupted_cb()
  */
@@ -332,8 +332,8 @@ typedef void (*player_error_cb)(int error_code, void *user_data);
 
 /**
  * @brief Called when the buffering percentage of the media playback is updated.
- * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
  * @details If the buffer is full, it will return 100%.
+ * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
  * @param[in]   percent        The percentage of buffering completed (0~100)
  * @param[in]   user_data      The user data passed from the callback registration function
  * @see player_set_buffering_cb()
@@ -390,9 +390,9 @@ typedef void (*player_media_stream_buffer_status_cb) (player_media_stream_buffer
 
 /**
  * @brief Called to notify the next push-buffer offset when seeking is occurred.
+ * @details The next push-buffer should produce buffers from the new offset.
  * @since_tizen @if WEARABLE 3.0 @else 2.4 @endif
  * @remarks This API is used for media stream playback only.
- * @details The next push-buffer should produce buffers from the new offset.
  * @param[in] offset The new byte position to seek
  * @param[in] user_data The user data passed from the callback registration function
  */
@@ -400,8 +400,8 @@ typedef void (*player_media_stream_seek_cb) (unsigned long long offset, void *us
 
 /**
  * @brief Called to notify the video stream changed.
- * @since_tizen @if WEARABLE 3.0 @else 2.4 @endif
  * @details The video stream changing is detected just before rendering operation.
+ * @since_tizen @if WEARABLE 3.0 @else 2.4 @endif
  * @param[in] width    The width of the captured image
  * @param[in] height The height of the captured image
  * @param[in] fps The frame per second of the video \n
@@ -415,9 +415,9 @@ typedef void (*player_video_stream_changed_cb) (int width, int height, int fps,
 
 /**
  * @brief Called to notify the streaming variant information.
- * @since_tizen 4.0
  * @details The adaptive streaming protocol(hls, mpeg dash) can support variant stream condition.
  *          All the streaming variant information can be shared by calling player_foreach_adaptive_variant().
+ * @since_tizen 4.0
  * @param[in] bandwidth The bandwidth of the stream can be supportable, this is mandatory parameter
  * @param[in] width The width of the stream, this is optional parameter
  * @param[in] height The height of the stream, this is optional parameter
@@ -435,6 +435,8 @@ typedef void (*player_adaptive_variant_cb) (int bandwidth, int width, int height
  *          audio or display device.
  *
  * @param[out]  player  A new handle to the media player
+ * @return @c 0 on success,
+ *         otherwise a negative error value
  * @retval #PLAYER_ERROR_NONE Successful
  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
  * @retval #PLAYER_ERROR_OUT_OF_MEMORY Out of memory
@@ -603,12 +605,11 @@ int player_get_state(player_h player, player_state_e *state);
 
 /**
  * @brief Sets the player's volume.
- * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
  * @details  Setting this volume adjusts the player's instance volume, not the system volume.
  *           The valid range is from 0 to 1.0, inclusive (1.0 = 100%). Default value is 1.0.
  *           To change system volume, use the @ref CAPI_MEDIA_SOUND_MANAGER_MODULE API.
  *           Finally, it does not support to set other value into each channel currently.
- *
+ * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
  * @param[in]   player The handle to the media player
  * @param[in]   left The left volume scalar
  * @param[in]   right The right volume scalar
@@ -623,11 +624,10 @@ int player_set_volume(player_h player, float left, float right);
 
 /**
  * @brief Gets the player's current volume factor.
- * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
  * @details The range of @a left and @a right is from @c 0 to @c 1.0, inclusive (1.0 = 100%).
  *          This function gets the player volume, not the system volume.
  *          To get the system volume, use the @ref CAPI_MEDIA_SOUND_MANAGER_MODULE API.
- *
+ * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
  * @param[in]   player The handle to the media player
  * @param[out]  left The current left volume scalar
  * @param[out]  right The current right volume scalar
@@ -738,11 +738,11 @@ int player_get_audio_latency_mode(player_h player, audio_latency_mode_e *latency
 
 /**
  * @brief Starts or resumes playback.
+ * @details Plays current media content, or resumes play if paused.
  * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
  * @remarks Sound can be mixed with other sounds if you don't control the stream focus in sound-manager module since 3.0.\n
  * You can refer to @ref CAPI_MEDIA_SOUND_MANAGER_MODULE.
  * @remarks Even if you don't set visible to true by calling player_set_display_visible, the video will be shown on #PLAYER_STATE_PLAYING state.
- * @details Plays current media content, or resumes play if paused.
  *
  * @param[in]   player The handle to the media player
  * @return @c 0 on success,
@@ -860,11 +860,10 @@ int player_get_play_position(player_h player, int *millisecond);
 
 /**
  * @brief Sets the player's mute status.
- * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
  * @details If the mute status is @c true, no sounds are played.
  *          If it is @c false, sounds are played at the previously set volume level.
  *          Until this function is called, by default the player is not muted.
- *
+ * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
  * @param[in]   player The handle to the media player
  * @param[in]   muted The new mute status: (@c true = mute, @c false = not muted)
  * @return @c 0 on success,
@@ -879,10 +878,9 @@ int player_set_mute(player_h player, bool muted);
 
 /**
  * @brief Gets the player's mute status.
- * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
  * @details If the mute status is @c true, no sounds are played.
  *          If it is @c false, sounds are played at the previously set volume level.
- *
+ * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
  * @param[in]   player The handle to the media player
  * @param[out]  muted  The current mute status: (@c true = mute, @c false = not muted)
  * @return @c 0 on success,
@@ -897,10 +895,9 @@ int player_is_muted(player_h player, bool *muted);
 
 /**
  * @brief Sets the player's looping status.
- * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
  * @details If the looping status is @c true, playback automatically restarts upon finishing.
  *          If it is @c false, it won't. The default value is @c false.
- *
+ * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
  * @param[in]   player The handle to the media player
  * @param[in]   looping The new looping status: (@c true = looping, @c false = non-looping )
  * @return @c 0 on success,
@@ -916,10 +913,9 @@ int player_set_looping(player_h player, bool looping);
 
 /**
  * @brief Gets the player's looping status.
- * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
  * @details If the looping status is @c true, playback automatically restarts upon finishing.
  *          If it is @c false, it won't.
- *
+ * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
  * @param[in]   player The handle to the media player
  * @param[out]  looping The looping status: (@c true = looping, @c false = non-looping )
  * @return @c 0 on success,
@@ -1289,9 +1285,9 @@ int player_is_display_visible(player_h player, bool* visible);
 
 /**
  * @brief Sets the rotation settings of the video surface display.
+ * @details Use this function to change the video orientation to portrait mode.
  * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
  * @remarks If no display is set, no operation is performed.
- * @details Use this function to change the video orientation to portrait mode.
  * @param[in] player   The handle to the media player
  * @param[in] rotation The rotation of the display
  * @return @c 0 on success,
@@ -1608,6 +1604,8 @@ int player_audio_effect_get_equalizer_band_frequency_range(player_h player, int
  * @brief Clears the equalizer effect.
  * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
  * @param[in] player The handle to the media player
+ * @return @c 0 on success,
+ *         otherwise a negative error value
  * @retval #PLAYER_ERROR_NONE Successful
  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
@@ -1625,6 +1623,8 @@ int player_audio_effect_equalizer_clear(player_h player);
  * @param[in] player The handle to the media player
  * @param[out] available If @c true the specified audio effect is available,
  *                       otherwise @c false
+ * @return @c 0 on success,
+ *         otherwise a negative error value
  * @retval #PLAYER_ERROR_NONE Successful
  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
@@ -1923,13 +1923,15 @@ int player_unset_progressive_download_message_cb(player_h player) TIZEN_DEPRECAT
 
 /**
  * @brief Sets the playback rate.
- * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
  * @details The default value is @c 1.0.
+ * @since_tizen @if WEARABLE 2.3.1 @else 2.3 @endif
  * @remarks #PLAYER_ERROR_INVALID_OPERATION occurs when streaming playback.
  * @remarks No operation is performed, if @a rate is @c 0.
  * @remarks The sound is muted, when playback rate is under @c 0.0 and over @c 2.0.
  * @param[in] player The handle to the media player
  * @param[in] rate The playback rate (-5.0x ~ 5.0x)
+ * @return @c 0 on success,
+ *         otherwise a negative error value
  * @retval #PLAYER_ERROR_NONE Successful
  * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
  * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation
@@ -2056,8 +2058,8 @@ int player_unset_video_stream_changed_cb(player_h player);
 
 /**
  * @brief Gets current track index.
- * @since_tizen @if WEARABLE 3.0 @else 2.4 @endif
  * @details Index starts from 0.
+ * @since_tizen @if WEARABLE 3.0 @else 2.4 @endif
  * @param[in] player The handle to the media player
  * @param[in] type The type of target stream which is PLAYER_STREAM_TYPE_AUDIO or PLAYER_STREAM_TYPE_TEXT
  * @param[out] index  The index of track
@@ -2183,8 +2185,8 @@ int player_get_max_adaptive_variant_limit(player_h player, int *bandwidth, int *
 
 /**
  * @brief Sets the audio only mode.
- * @since_tizen 4.0
  * @details This function is used to disable or enable video rendering during playback.
+ * @since_tizen 4.0
  * @param[in] player       The handle to the media player
  * @param[in] audio_only   The new audio only status: (@c true = enable audio only, @c false = disable audio only)
  * @return @c 0 on success,
@@ -2214,6 +2216,40 @@ int player_set_audio_only(player_h player, bool audio_only);
 int player_is_audio_only(player_h player, bool *audio_only);
 
 /**
+ * @brief Sets the streaming buffering time.
+ * @since_tizen 4.0
+ * @param[in] player       The handle to the media player
+ * @param[in] prebuffer_ms The buffer time to start playback
+ * @param[in] rebuffer_ms  The buffer time during playback if player enter pause state for buffering.
+ * @return @c 0 on success,
+ *         otherwise a negative error value
+ * @retval #PLAYER_ERROR_NONE Successful
+ * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #PLAYER_ERROR_INVALID_STATE Invalid state
+ * @if WEARABLE @retval #PLAYER_ERROR_FEATURE_NOT_SUPPORTED_ON_DEVICE Unsupported feature @endif
+ * @pre The player state must be #PLAYER_STATE_IDLE.
+ * @see player_get_streaming_buffering_time()
+ */
+int player_set_streaming_buffering_time(player_h player, int prebuffer_ms, int rebuffer_ms);
+
+/**
+ * @brief Gets the streaming buffering time.
+ * @since_tizen 4.0
+ * @param[in] player       The handle to the media player
+ * @param[in] prebuffer_ms The buffer time to start playback
+ * @param[in] rebuffer_ms  The buffer time during playback if player enter pause state for buffering.
+ * @return @c 0 on success,
+ *         otherwise a negative error value
+ * @retval #PLAYER_ERROR_NONE Successful
+ * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #PLAYER_ERROR_INVALID_STATE Invalid state
+ * @if WEARABLE @retval #PLAYER_ERROR_FEATURE_NOT_SUPPORTED_ON_DEVICE Unsupported feature @endif
+ * @pre The player state must be one of #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
+ * @see player_get_streaming_buffering_time()
+ */
+int player_get_streaming_buffering_time(player_h player, int *prebuffer_ms, int *rebuffer_ms);
+
+/**
  * @}
  */
 

diff --git a/include/player_internal.h b/include/player_internal.h
index fbfd7b9..02b4ed2 100644 (file)
--- a/include/player_internal.h
+++ b/include/player_internal.h
@@ -533,41 +533,6 @@ int player_get_media_packet_video_frame_pool_size(player_h player, int *size);
 int player_enable_media_packet_video_frame_decoded_cb(player_h player, bool enable);
 
 /**
- * @brief Sets the streaming buffering time
- * @since_tizen 4.0
- * @param[in] player       The handle to the media player
- * @param[in] buffer_ms    The buffer time to start playback
- * @param[in] rebuffer_ms  The buffer time during playback if player enter pause state for buffering.
- * @return @c 0 on success,
- *         otherwise a negative error value
- * @retval #PLAYER_ERROR_NONE Successful
- * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
- * @retval #PLAYER_ERROR_INVALID_STATE Invalid state
- * @if WEARABLE @retval #PLAYER_ERROR_FEATURE_NOT_SUPPORTED_ON_DEVICE Unsupported feature @endif
- * @pre The player state must be #PLAYER_STATE_IDLE.
- * @see        player_get_streaming_buffering_time()
- */
-int player_set_streaming_buffering_time(player_h player, int buffer_ms, int rebuffer_ms);
-
-/**
- * @brief Gets the streaming buffering time
- * @since_tizen 4.0
- * @remarks The player state have to be #PLAYER_STATE_IDLE to apply the buffer_ms.
- * @param[in] player       The handle to the media player
- * @param[in] buffer_ms    The buffer time to start playback
- * @param[in] rebuffer_ms  The buffer time during playback if player enter pause state for buffering.
- * @return @c 0 on success,
- *         otherwise a negative error value
- * @retval #PLAYER_ERROR_NONE Successful
- * @retval #PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
- * @retval #PLAYER_ERROR_INVALID_STATE Invalid state
- * @if WEARABLE @retval #PLAYER_ERROR_FEATURE_NOT_SUPPORTED_ON_DEVICE Unsupported feature @endif
- * @pre The player state must be one of #PLAYER_STATE_IDLE, #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
- * @see        player_get_streaming_buffering_time()
- */
-int player_get_streaming_buffering_time(player_h player, int *buffer_ms, int *rebuffer_ms);
-
-/**
  * @brief Enables 360 video mode
  * @since_tizen 4.0
  * @details If it is @c true, the content will be displayed with 360 video mode.