From: Eunhae Choi <eunhae1.choi@samsung.com>
Date: Tue, 17 Jul 2018 10:47:25 +0000 (+0900)
Subject: [ACR-1262] Modified the pre condition of _start()
X-Git-Tag: submit/tizen/20180730.025527^0
X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=0e07f2ca6511fb63e52bae0e7a9acd5e3920fbd0;p=platform%2Fcore%2Fapi%2Fplayer.git

[ACR-1262] Modified the pre condition of _start()

- added PLAYING state at pre condition of player_start()
  for resuming during buffering.
- fixed doxygen error about post state of player_pause()
- modified the param description of player_set_streaming_buffering_time()
  not to be confused with player state.

Change-Id: I87272507f46818a74b5894a3f49f62096900c396
---

diff --git a/include/player.h b/include/player.h
index 47d6c1a..15ef504 100644
--- a/include/player.h
+++ b/include/player.h
@@ -754,12 +754,16 @@ 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.
+ * @details Plays current media content, or resumes playback if the player is paused or buffering during HTTP streaming play.
  * @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.
- *
+ * @remarks Since 3.0: \n
+ *          Sound can be mixed with other sounds, if you don't control the stream focus in sound-manager module.\n
+ *          You can refer to @ref CAPI_MEDIA_SOUND_MANAGER_MODULE.
+ * @remarks Since 5.0: \n
+ *          In case of HTTP streaming playback, the player could be internally paused for buffering.
+ *          If the application calls this function during the buffering, the playback will be resumed by force
+ *          and the buffering message posting by player_buffering_cb() will be stopped.
  * @param[in]   player The handle to the media player
  * @return @c 0 on success,
  *         otherwise a negative error value
@@ -769,8 +773,8 @@ int player_get_audio_latency_mode(player_h player, audio_latency_mode_e *latency
  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
  * @retval #PLAYER_ERROR_CONNECTION_FAILED Network connection failed
  * @retval #PLAYER_ERROR_SOUND_POLICY Sound policy error
- * @pre player_prepare() must be called before calling this function.
- * @pre The player state must be set to #PLAYER_STATE_READY by calling player_prepare() or set to #PLAYER_STATE_PAUSED by calling player_pause().
+ * @pre Before 5.0: The player state must be #PLAYER_STATE_READY or #PLAYER_STATE_PAUSED. \n
+ * @pre Since 5.0: The player state must be one of #PLAYER_STATE_READY, #PLAYER_STATE_PLAYING, or #PLAYER_STATE_PAUSED.
  * @post The player state will be #PLAYER_STATE_PLAYING.
  * @post It invokes player_completed_cb() when playback completes, if you set a callback with player_set_completed_cb().
  * @see player_prepare()
@@ -780,6 +784,8 @@ int player_get_audio_latency_mode(player_h player, audio_latency_mode_e *latency
  * @see player_set_completed_cb()
  * @see player_completed_cb()
  * @see player_set_display_visible()
+ * @see player_set_buffering_cb()
+ * @see player_buffering_cb()
  */
 int player_start(player_h player);
 
@@ -816,7 +822,7 @@ int player_stop(player_h player);
  * @retval #PLAYER_ERROR_INVALID_STATE Invalid player state
  * @retval #PLAYER_ERROR_SOUND_POLICY Sound policy error
  * @pre The player state must be set to #PLAYER_STATE_PLAYING.
- * @post The player state will be #PLAYER_STATE_READY.
+ * @post The player state will be #PLAYER_STATE_PAUSED.
  * @see player_start()
  */
 int player_pause(player_h player);
@@ -2375,7 +2381,7 @@ int player_is_replaygain_enabled(player_h player, bool *enabled);
  * @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] 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.
  * @return @c 0 on success,
  *         otherwise a negative error value
  * @retval #PLAYER_ERROR_NONE Successful