Add flag to DataSpec that allows to indicate throttled transfer speed.

This may happen for example when trying to load unfinished live media
chunks that can only be loaded at real-time playback speed.

The flag can be used by the sources to indicate that network transfer
will knowingly be throttled, such that transfer listeners like the
bandwidth meter can take this information into account.

PiperOrigin-RevId: 285397100

library/core/src/main/java/com/google/android/exoplayer2/upstream/DataSpec.java

@@ -35,14 +35,19 @@ public final class DataSpec {
 
   /**
    * The flags that apply to any request for data. Possible flag values are {@link
-   * #FLAG_ALLOW_GZIP}, {@link #FLAG_DONT_CACHE_IF_LENGTH_UNKNOWN} and {@link
-   * #FLAG_ALLOW_CACHE_FRAGMENTATION}.
+   * #FLAG_ALLOW_GZIP}, {@link #FLAG_DONT_CACHE_IF_LENGTH_UNKNOWN}, {@link
+   * #FLAG_ALLOW_CACHE_FRAGMENTATION}, and {@link #FLAG_MIGHT_NOT_USE_FULL_NETWORK_SPEED}.
    */
   @Documented
   @Retention(RetentionPolicy.SOURCE)
   @IntDef(
       flag = true,
-      value = {FLAG_ALLOW_GZIP, FLAG_DONT_CACHE_IF_LENGTH_UNKNOWN, FLAG_ALLOW_CACHE_FRAGMENTATION})
+      value = {
+        FLAG_ALLOW_GZIP,
+        FLAG_DONT_CACHE_IF_LENGTH_UNKNOWN,
+        FLAG_ALLOW_CACHE_FRAGMENTATION,
+        FLAG_MIGHT_NOT_USE_FULL_NETWORK_SPEED
+      })
   public @interface Flags {}
   /**
    * Allows an underlying network stack to request that the server use gzip compression.
@@ -57,14 +62,19 @@ public final class DataSpec {
    */
   public static final int FLAG_ALLOW_GZIP = 1;
   /** Prevents caching if the length cannot be resolved when the {@link DataSource} is opened. */
-  public static final int FLAG_DONT_CACHE_IF_LENGTH_UNKNOWN = 1 << 1; // 2
+  public static final int FLAG_DONT_CACHE_IF_LENGTH_UNKNOWN = 1 << 1;
   /**
    * Allows fragmentation of this request into multiple cache files, meaning a cache eviction policy
    * will be able to evict individual fragments of the data. Depending on the cache implementation,
    * setting this flag may also enable more concurrent access to the data (e.g. reading one fragment
    * whilst writing another).
    */
-  public static final int FLAG_ALLOW_CACHE_FRAGMENTATION = 1 << 2; // 4
+  public static final int FLAG_ALLOW_CACHE_FRAGMENTATION = 1 << 2;
+  /**
+   * Indicates there are known external factors that might prevent the data from being loaded at
+   * full network speed (e.g. server throttling or unfinished live media chunks).
+   */
+  public static final int FLAG_MIGHT_NOT_USE_FULL_NETWORK_SPEED = 1 << 3;
 
   /**
    * The set of HTTP methods that are supported by ExoPlayer {@link HttpDataSource}s. One of {@link