@UnstableApi
class DataSpec


Defines a region of data in a resource.

Summary

Nested types

Builds DataSpec instances.

@Documented
@Retention(value = RetentionPolicy.SOURCE)
@Target(value = TYPE_USE)
@IntDef(flag = true, value = )
annotation DataSpec.Flags

The flags that apply to any request for data.

@Documented
@Retention(value = RetentionPolicy.SOURCE)
@Target(value = TYPE_USE)
@IntDef(value = )
annotation DataSpec.HttpMethod

HTTP methods supported by ExoPlayer HttpDataSources.

Constants

const Int

Allows fragmentation of this request into multiple cache files, meaning a cache eviction policy will be able to evict individual fragments of the data.

const Int

Allows an underlying network stack to request that the server use gzip compression.

const Int

Prevents caching if the length cannot be resolved when the DataSource is opened.

const Int

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).

const Int

HTTP GET method.

const Int

HTTP HEAD method.

const Int

HTTP POST method.

Public constructors

DataSpec(uri: Uri!)

Constructs an instance.

DataSpec(uri: Uri!, position: Long, length: Long)

Constructs an instance.

DataSpec(uri: Uri!, position: Long, length: Long, key: String?)

This function is deprecated.

Use Builder.

Public functions

DataSpec.Builder!

Returns a DataSpec.Builder initialized with the values of this instance.

String!

Returns the uppercase HTTP method name (e.g., "GET", "POST", "HEAD") corresponding to the httpMethod.

java-static String!

Returns an uppercase HTTP method name (e.g., "GET", "POST", "HEAD") corresponding to the given HttpMethod.

Boolean

Returns whether the given flag is set.

DataSpec!
subrange(offset: Long)

Returns a data spec that represents a subrange of the data defined by this DataSpec.

DataSpec!
subrange(offset: Long, length: Long)

Returns a data spec that represents a subrange of the data defined by this DataSpec.

String!
DataSpec!
withAdditionalHeaders(
    additionalHttpRequestHeaders: (Mutable)Map<String!, String!>!
)

Returns a copy this data spec with additional HTTP request headers.

DataSpec!
withRequestHeaders(httpRequestHeaders: (Mutable)Map<String!, String!>!)

Returns a copy of this data spec with the specified HTTP request headers.

DataSpec!
withUri(uri: Uri!)

Returns a copy of this data spec with the specified Uri.

Public properties

Long

This property is deprecated.

Use position except for specific use cases where the absolute position within the resource is required within a DataSource chain.

Any?

Application specific data.

Int

Request flags.

ByteArray<Byte>?

The HTTP request body, null otherwise.

Int

The HTTP method to use when requesting the data.

(Mutable)Map<String!, String!>!

Additional HTTP headers to use when requesting the data.

String?

A key that uniquely identifies the resource.

Long

The length of the data, or LENGTH_UNSET.

Long

The position of the data when read from uri.

Uri!

A Uri from which data belonging to the resource can be read.

Long

The offset of the data located at uri within the resource.

Constants

FLAG_ALLOW_CACHE_FRAGMENTATION

const val FLAG_ALLOW_CACHE_FRAGMENTATION = 4: Int

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).

FLAG_ALLOW_GZIP

const val FLAG_ALLOW_GZIP = 1: Int

Allows an underlying network stack to request that the server use gzip compression.

Should not typically be set if the data being requested is already compressed (e.g. most audio and video requests). May be set when requesting other data.

When a DataSource is used to request data with this flag set, and if the does make a network request, then the value returned from open will typically be LENGTH_UNSET. The data read from read will be the decompressed data.

FLAG_DONT_CACHE_IF_LENGTH_UNKNOWN

const val FLAG_DONT_CACHE_IF_LENGTH_UNKNOWN = 2: Int

Prevents caching if the length cannot be resolved when the DataSource is opened.

FLAG_MIGHT_NOT_USE_FULL_NETWORK_SPEED

const val FLAG_MIGHT_NOT_USE_FULL_NETWORK_SPEED = 8: Int

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).

HTTP_METHOD_GET

const val HTTP_METHOD_GET = 1: Int

HTTP GET method.

HTTP_METHOD_HEAD

const val HTTP_METHOD_HEAD = 3: Int

HTTP HEAD method.

HTTP_METHOD_POST

const val HTTP_METHOD_POST = 2: Int

HTTP POST method.

Public constructors

DataSpec

DataSpec(uri: Uri!)

Constructs an instance.

Parameters
uri: Uri!

uri.

DataSpec

DataSpec(uri: Uri!, position: Long, length: Long)

Constructs an instance.

Parameters
uri: Uri!

uri.

position: Long

position.

length: Long

length.

DataSpec

DataSpec(uri: Uri!, position: Long, length: Long, key: String?)

Constructs an instance.

Parameters
uri: Uri!

uri.

position: Long

position.

length: Long

length.

key: String?

key.

Public functions

buildUpon

fun buildUpon(): DataSpec.Builder!

Returns a DataSpec.Builder initialized with the values of this instance.

getHttpMethodString

fun getHttpMethodString(): String!

Returns the uppercase HTTP method name (e.g., "GET", "POST", "HEAD") corresponding to the httpMethod.

getStringForHttpMethod

java-static fun getStringForHttpMethod(@DataSpec.HttpMethod httpMethod: Int): String!

Returns an uppercase HTTP method name (e.g., "GET", "POST", "HEAD") corresponding to the given HttpMethod.

isFlagSet

fun isFlagSet(@DataSpec.Flags flag: Int): Boolean

Returns whether the given flag is set.

Parameters
@DataSpec.Flags flag: Int

Flag to be checked if it is set.

subrange

fun subrange(offset: Long): DataSpec!

Returns a data spec that represents a subrange of the data defined by this DataSpec. The subrange includes data from the offset up to the end of this DataSpec.

Parameters
offset: Long

The offset of the subrange.

Returns
DataSpec!

A data spec that represents a subrange of the data defined by this DataSpec.

subrange

fun subrange(offset: Long, length: Long): DataSpec!

Returns a data spec that represents a subrange of the data defined by this DataSpec.

Parameters
offset: Long

The offset of the subrange.

length: Long

The length of the subrange.

Returns
DataSpec!

A data spec that represents a subrange of the data defined by this DataSpec.

toString

fun toString(): String!

withAdditionalHeaders

fun withAdditionalHeaders(
    additionalHttpRequestHeaders: (Mutable)Map<String!, String!>!
): DataSpec!

Returns a copy this data spec with additional HTTP request headers. Headers in additionalHttpRequestHeaders will overwrite any headers already in the data spec that have the same keys.

Parameters
additionalHttpRequestHeaders: (Mutable)Map<String!, String!>!

The additional HTTP request headers.

Returns
DataSpec!

The copied data spec with the additional HTTP request headers.

withRequestHeaders

fun withRequestHeaders(httpRequestHeaders: (Mutable)Map<String!, String!>!): DataSpec!

Returns a copy of this data spec with the specified HTTP request headers. Headers already in the data spec are not copied to the new instance.

Parameters
httpRequestHeaders: (Mutable)Map<String!, String!>!

The HTTP request headers.

Returns
DataSpec!

The copied data spec with the specified HTTP request headers.

withUri

fun withUri(uri: Uri!): DataSpec!

Returns a copy of this data spec with the specified Uri.

Parameters
uri: Uri!

The new source Uri.

Returns
DataSpec!

The copied data spec with the specified Uri.

Public properties

absoluteStreamPosition

val absoluteStreamPositionLong

The absolute position of the data in the resource.

customData

val customDataAny?

Application specific data.

This field is intended for advanced use cases in which applications require the ability to attach custom data to DataSpec instances. The custom data should be immutable.

flags

@DataSpec.Flags
val flagsInt

Request flags.

httpBody

val httpBodyByteArray<Byte>?

The HTTP request body, null otherwise. If the body is non-null, then httpBody.length will be non-zero.

httpMethod

@DataSpec.HttpMethod
val httpMethodInt

The HTTP method to use when requesting the data. This value will be ignored by non-HTTP implementations.

httpRequestHeaders

val httpRequestHeaders: (Mutable)Map<String!, String!>!

Additional HTTP headers to use when requesting the data.

Note: This map is for additional headers specific to the data being requested. It does not include headers that are set directly by HttpDataSource implementations. In particular, this means the following headers are not included:

key

val keyString?

A key that uniquely identifies the resource. Used for cache indexing. May be null if the data spec is not intended to be used in conjunction with a cache.

length

val lengthLong

The length of the data, or LENGTH_UNSET.

position

val positionLong

The position of the data when read from uri.

uri

val uriUri!

A Uri from which data belonging to the resource can be read.

uriPositionOffset

val uriPositionOffsetLong

The offset of the data located at uri within the resource.

Equal to 0 unless uri provides access to a subset of the resource. As an example, consider a resource that can be requested over the network and is 1000 bytes long. If uri points to a local file that contains just bytes [200-300], then this field will be set to 200.

This field can be ignored except for in specific circumstances where the absolute position in the resource is required in a DataSource chain. One example is when a needs to decrypt the content as it's read. In this case the absolute position in the resource is typically needed to correctly initialize the decryption algorithm.