From: Eunhae Choi <eunhae1.choi@samsung.com>
Date: Mon, 28 Jan 2019 06:40:15 +0000 (+0900)
Subject: [ACR-1347] Modify the parameter value range of buffering function
X-Git-Tag: submit/tizen/20190222.014721^2
X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=95b0a57a8fd067a51c5946a6f83328bc0b5eab4f;p=platform%2Fcore%2Fapi%2Fplayer.git

[ACR-1347] Modify the parameter value range of buffering function

- Allow '-1' value to keep previous setting.
- Add missed error code : PLAYER_ERROR_INVALID_OPERATION
- Modify API reference

Change-Id: I03beabed7d10ee0de810f1555dd0159180c69bee
---

diff --git a/include/player.h b/include/player.h
index 81beb3f..38e7426 100644
--- a/include/player.h
+++ b/include/player.h
@@ -2349,17 +2349,40 @@ int player_get_video_roi_area(player_h player, double *x_scale, double *y_scale,
  * @brief Sets the streaming buffering time.
  * @since_tizen 4.0
  * @param[in] player        The handle to the media player
- * @param[in] prebuffer_ms  The time duration of buffering data that must be prerolled to start playback
+ * @param[in] prebuffer_ms  The time duration of buffering data that must be prerolled to start playback. \n
+ *                          At least 1000 milliseconds is recommended to ensure the normal buffering operation except 0 or -1. \n
+ *                           0 : use platform default value which could be different depending on the streaming type and network status (default) \n
+ *                          -1 : use current value (since 5.5) \n
  * @param[in] rebuffer_ms   The time duration of buffering data that must be prerolled to resume playback
- *                          if player is paused for buffering internally.
+ *                          if player is paused for buffering internally. \n
+ *                          At least 1000 milliseconds is recommended to ensure the normal buffering operation except 0 or -1. \n
+ *                           0 : use platform default value which could be different depending on the streaming type and network status (default) \n
+ *                          -1 : use current value (since 5.5)\n
  * @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
+ * @retval #PLAYER_ERROR_INVALID_OPERATION Invalid operation (since 5.5)
  * @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()
+ * @par Example
+ * @code
+   #include <player.h>
+   bool set_buffering_time(player_h p)
+   {
+       int err = PLAYER_ERROR_NONE;
+
+       // sets the prebuffer_ms to 5000 milliseconds but does not change the rebuffer_ms
+       err =  player_set_streaming_buffering_time(p, 5000, -1);
+       if (err != PLAYER_ERROR_NONE) {
+          printf("Fail to set buffering time = %x\n", err);
+          return false;
+       }
+       return true;
+   }
+ * @endcode
  */
 int player_set_streaming_buffering_time(player_h player, int prebuffer_ms, int rebuffer_ms);
 
@@ -2369,7 +2392,10 @@ int player_set_streaming_buffering_time(player_h player, int prebuffer_ms, int r
  * @param[in]  player        The handle to the media player
  * @param[out] prebuffer_ms  The time duration of buffering data that must be prerolled to start playback
  * @param[out] rebuffer_ms   The time duration of buffering data that must be prerolled to resume playback
- *                           if player enters pause state for buffering.
+ *                           if player is paused for buffering internally. \n
+ *                           @c 0 means platform default value which could be different depending on the streaming type and network status.
+ *                           If the player state is #PLAYER_STATE_PLAYING or #PLAYER_STATE_PAUSED,
+ *                           this function will return correct time value instead of @c 0. (since 5.5)
  * @return @c 0 on success,
  *         otherwise a negative error value
  * @retval #PLAYER_ERROR_NONE Successful
diff --git a/src/player.c b/src/player.c
index 5f3169f..7edc018 100644
--- a/src/player.c
+++ b/src/player.c
@@ -4763,9 +4763,10 @@ int player_is_audio_only(player_h player, bool *paudio_only)
 
 int player_set_streaming_buffering_time(player_h player, int prebuffer_ms, int rebuffer_ms)
 {
+#define MIN_BUFFER_TIME -1
 	int ret = PLAYER_ERROR_NONE;
 	PLAYER_INSTANCE_CHECK(player);
-	PLAYER_CHECK_CONDITION(prebuffer_ms >= 0 && rebuffer_ms >= 0, PLAYER_ERROR_INVALID_PARAMETER, "PLAYER_ERROR_INVALID_PARAMETER");
+	PLAYER_CHECK_CONDITION(prebuffer_ms >= MIN_BUFFER_TIME && rebuffer_ms >= MIN_BUFFER_TIME, PLAYER_ERROR_INVALID_PARAMETER, "PLAYER_ERROR_INVALID_PARAMETER");
 
 	player_cli_s *pc = (player_cli_s *)player;
 	muse_player_api_e api = MUSE_PLAYER_API_SET_STREAMING_BUFFERING_TIME;