[MediaPlayer] Modify the range of parameter for buffering API (#748)

[platform/core/csapi/tizenfx.git] / src / Tizen.Multimedia.MediaPlayer / Player / Player.Properties.cs

diff --git a/src/Tizen.Multimedia.MediaPlayer/Player/Player.Properties.cs b/src/Tizen.Multimedia.MediaPlayer/Player/Player.Properties.cs
index 9ec8ac6..058f56a 100644 (file)
--- a/src/Tizen.Multimedia.MediaPlayer/Player/Player.Properties.cs
+++ b/src/Tizen.Multimedia.MediaPlayer/Player/Player.Properties.cs
@@ -25,7 +25,7 @@ using static Interop;
 namespace Tizen.Multimedia
 {
     /// <summary>
-    /// Represents properties for streaming buffering time
+    /// Represents properties for streaming buffering time.
     /// </summary>
     /// <since_tizen> 5 </since_tizen>
     public struct PlayerBufferingTime
@@ -34,17 +34,26 @@ namespace Tizen.Multimedia
         /// Initializes a new instance of the PlayerBufferingTime struct.
         /// </summary>
         /// <param name="preBufferMillisecond">A duration of buffering data that must be prerolled to start playback.</param>
-        /// <param name="reBufferMillisecond">A duration of buffering data that must be prerolled to resume playback
-        /// if player is paused for buffering internally.</param>
+        /// Except 0 and -1, setting at least 1000 milliseconds is recommended to ensure the normal buffering operation.
+        /// 0 : use platform default value which could be different depending on the streaming type and network status. (the initial value)
+        /// -1 : use current value. (since 5.5)
+        /// <param name="reBufferMillisecond">A duration of buffering data that must be prerolled to resume playback,
+        /// when player is internally paused for buffering.
+        /// Except 0 and -1, setting at least 1000 milliseconds is recommended to ensure the normal buffering operation.
+        /// 0 : use platform default value which could be different depending on the streaming type and network status. (the initial value)
+        /// -1 : use current value. (since 5.5)
+        /// <para>0 means platform default value which could be different depending on the streaming type and network status.
+        /// If the player state is <see cref="PlayerState.Playing"/> or <see cref="PlayerState.Paused"/>,
+        /// this function will return correct time value instead of 0. (since 5.5)</para></param>
         /// <since_tizen> 5 </since_tizen>
-        public PlayerBufferingTime(int preBufferMillisecond, int reBufferMillisecond)
+        public PlayerBufferingTime(int preBufferMillisecond = -1, int reBufferMillisecond = -1)
         {
             PreBufferMillisecond = preBufferMillisecond;
             ReBufferMillisecond = reBufferMillisecond;
         }
 
         /// <summary>
-        /// Gets or sets the duration of buffering data that must be prerolled to start playback
+        /// Gets or sets the duration of buffering data that must be prerolled to start playback.
         /// </summary>
         /// <since_tizen> 5 </since_tizen>
         public int PreBufferMillisecond
@@ -85,6 +94,7 @@ namespace Tizen.Multimedia
         #region Network configuration
         private string _cookie = "";
         private string _userAgent = "";
+        private const int MinBufferingTime = -1;
 
         /// <summary>
         /// Gets or sets the cookie for streaming playback.
@@ -153,10 +163,11 @@ namespace Tizen.Multimedia
         /// <exception cref="InvalidOperationException">The player is not in the valid state.</exception>
         /// <exception cref="ObjectDisposedException">The player has already been disposed of.</exception>
         /// <exception cref="ArgumentOutOfRangeException">
-        ///     <pramref name="PreBufferMillisecond"/> is less than 0.<br/>
+        ///     <pramref name="PreBufferMillisecond"/> is less than -1.<br/>
         ///     -or-<br/>
-        ///     <pramref name="ReBufferMillisecond"/> is less than 0.<br/>
+        ///     <pramref name="ReBufferMillisecond"/> is less than -1.<br/>
         /// </exception>
+        /// <exception cref="NotSupportedException">The required feature is not supported.</exception>
         /// <seealso cref="PlayerBufferingTime"/>
         /// <since_tizen> 5 </since_tizen>
         public PlayerBufferingTime BufferingTime
@@ -174,9 +185,10 @@ namespace Tizen.Multimedia
             {
                 ValidatePlayerState(PlayerState.Idle);
 
-                if (value.PreBufferMillisecond < 0 || value.ReBufferMillisecond < 0)
+                if (value.PreBufferMillisecond < MinBufferingTime || value.ReBufferMillisecond < MinBufferingTime)
                 {
-                    throw new ArgumentOutOfRangeException("invalid range");
+                    throw new ArgumentOutOfRangeException(nameof(value), value,
+                        $"invalid range, got { value.PreBufferMillisecond }, { value.ReBufferMillisecond }.");
                 }
 
                 NativePlayer.SetStreamingBufferingTime(Handle, value.PreBufferMillisecond, value.ReBufferMillisecond).
@@ -527,7 +539,7 @@ namespace Tizen.Multimedia
         /// Gets or sets the player's replaygain state.
         /// </summary>
         /// <value>If the replaygain status is true, replaygain is applied (if contents has a replaygain tag);
-        /// otherwise, the replaygain isn't affected by tag and properties.</value>
+        /// otherwise, the replaygain is not affected by tag and properties.</value>
         /// <exception cref="ObjectDisposedException">The player has already been disposed of.</exception>
         /// <exception cref="InvalidOperationException">The player is not in the valid state.</exception>
         /// <since_tizen> 5 </since_tizen>