FakeExtractorInput

Artifact: androidx.media3:media3-test-utils

Kotlin |Java

@UnstableApi
class FakeExtractorInput : ExtractorInput

A fake ExtractorInput capable of simulating various scenarios.

Read, skip and peek errors can be simulated using setSimulateIOErrors. When enabled each read and skip will throw a SimulatedIOException unless one has already been thrown from the current position. Each peek will throw SimulatedIOException unless one has already been thrown from the current peek position. When a SimulatedIOException is thrown the read position is left unchanged and the peek position is reset back to the read position.

Partial reads and skips can be simulated using setSimulatePartialReads. When enabled, read and skip calls will only read or skip a single byte unless a partial read or skip has already been performed that had the same target position. For example, a first read request for 10 bytes will be partially satisfied by reading a single byte and advancing the position to 1. If the following read request attempts to read 9 bytes then it will be fully satisfied, since it has the same target position of 10.

Unknown data length can be simulated using setSimulateUnknownLength. When enabled getLength will return LENGTH_UNSET rather than the length of the data.

Summary

Nested types
`class FakeExtractorInput.Builder` Builder of `FakeExtractorInput` instances.
`class FakeExtractorInput.SimulatedIOException : IOException` Thrown when simulating an `IOException`.

Public functions
`Unit`	`advancePeekPosition(length: Int)` Advances the peek position by `length` bytes.
`Boolean`	`advancePeekPosition(length: Int, allowEndOfInput: Boolean)` Advances the peek position by `length` bytes.
`Long`	`getLength()` Returns the length of the source stream, or `LENGTH_UNSET` if it is unknown.
`Long`	`getPeekPosition()` Returns the current peek position (byte offset) in the stream.
`Long`	`getPosition()` Returns the current read position (byte offset) in the stream.
`Int`	`peek(target: ByteArray!, offset: Int, length: Int)` Peeks up to `length` bytes from the peek position.
`Unit`	`peekFully(target: ByteArray!, offset: Int, length: Int)` Equivalent to `peekFully(target, offset, length, false)`.
`Boolean`	`peekFully( target: ByteArray!, offset: Int, length: Int, allowEndOfInput: Boolean )` Like `peek`, but peeks the requested `length` in full.
`Int`	`read(buffer: ByteArray!, offset: Int, length: Int)` Reads up to `length` bytes from the input and resets the peek position.
`Unit`	`readFully(target: ByteArray!, offset: Int, length: Int)` Equivalent to `readFully(target, offset, length, false)`.
`Boolean`	`readFully( target: ByteArray!, offset: Int, length: Int, allowEndOfInput: Boolean )` Like `read`, but reads the requested `length` in full.
`Unit`	`reset()` Resets the input to its initial state.
`Unit`	`resetPeekPosition()` Resets the peek position to equal the current read position.
`Unit`	`setPosition(position: Int)` Sets the read and peek positions.
`Unit`	`<E : Throwable?> setRetryPosition(position: Long, e: E!)` Called when reading fails and the required retry position is different from the last position.
`Int`	`skip(length: Int)` Like `read`, except the data is skipped instead of read.
`Unit`	`skipFully(length: Int)` Like `readFully`, except the data is skipped instead of read.
`Boolean`	`skipFully(length: Int, allowEndOfInput: Boolean)` Like `readFully`, except the data is skipped instead of read.

Public functions

advancePeekPosition

fun advancePeekPosition(length: Int): Unit

Advances the peek position by length bytes. Like peekFully except the data is skipped instead of read.

Parameters
`length: Int`	The number of bytes to peek from the input.

Throws
`java.io.EOFException`	If the end of input was encountered.
`java.io.IOException`	If an error occurs peeking from the input.

advancePeekPosition

fun advancePeekPosition(length: Int, allowEndOfInput: Boolean): Boolean

Advances the peek position by length bytes. Like peekFully except the data is skipped instead of read.

Parameters
`length: Int`	The number of bytes by which to advance the peek position.
`allowEndOfInput: Boolean`	True if encountering the end of the input before advancing is allowed, and should result in `false` being returned. False if it should be considered an error, causing an `EOFException` to be thrown. See note in class Javadoc.

Returns
`Boolean`	True if advancing the peek position was successful. False if `allowEndOfInput=true` and the end of the input was encountered before advancing over any data.

Throws
`java.io.EOFException`	If the end of input was encountered having partially advanced (i.e. having advanced by at least one byte, but fewer than `length`), or if the end of input was encountered before advancing and `allowEndOfInput` is false.
`java.io.IOException`	If an error occurs advancing the peek position.

getLength

fun getLength(): Long

Returns the length of the source stream, or LENGTH_UNSET if it is unknown.

Returns
`Long`	The length of the source stream, or `LENGTH_UNSET`.

getPeekPosition

fun getPeekPosition(): Long

Returns the current peek position (byte offset) in the stream.

Returns
`Long`	The peek position (byte offset) in the stream.

getPosition

fun getPosition(): Long

Returns the current read position (byte offset) in the stream.

Returns
`Long`	The read position (byte offset) in the stream.

peek

fun peek(target: ByteArray!, offset: Int, length: Int): Int

Peeks up to length bytes from the peek position. The current read position is left unchanged.

This method blocks until at least one byte of data can be peeked, the end of the input is detected, or an exception is thrown.

Calling resetPeekPosition resets the peek position to equal the current read position, so the caller can peek the same data again. Reading or skipping also resets the peek position.

Parameters
`target: ByteArray!`	A target array into which data should be written.
`offset: Int`	The offset into the target array at which to write.
`length: Int`	The maximum number of bytes to peek from the input.

Returns
`Int`	The number of bytes peeked, or `RESULT_END_OF_INPUT` if the input has ended.

Throws
`java.io.IOException`	If an error occurs peeking from the input.

peekFully

fun peekFully(target: ByteArray!, offset: Int, length: Int): Unit

Equivalent to peekFully(target, offset, length, false).

Parameters
`target: ByteArray!`	A target array into which data should be written.
`offset: Int`	The offset into the target array at which to write.
`length: Int`	The number of bytes to peek from the input.

Throws
`java.io.EOFException`	If the end of input was encountered.
`java.io.IOException`	If an error occurs peeking from the input.

peekFully

fun peekFully(
    target: ByteArray!,
    offset: Int,
    length: Int,
    allowEndOfInput: Boolean
): Boolean

Like peek, but peeks the requested length in full.

Parameters
`target: ByteArray!`	A target array into which data should be written.
`offset: Int`	The offset into the target array at which to write.
`length: Int`	The number of bytes to peek from the input.
`allowEndOfInput: Boolean`	True if encountering the end of the input having peeked no data is allowed, and should result in `false` being returned. False if it should be considered an error, causing an `EOFException` to be thrown. See note in class Javadoc.

Returns
`Boolean`	True if the peek was successful. False if `allowEndOfInput=true` and the end of the input was encountered having peeked no data.

Throws
`java.io.EOFException`	If the end of input was encountered having partially satisfied the peek (i.e. having peeked at least one byte, but fewer than `length`), or if no bytes were peeked and `allowEndOfInput` is false.
`java.io.IOException`	If an error occurs peeking from the input.

read

fun read(buffer: ByteArray!, offset: Int, length: Int): Int

Reads up to length bytes from the input and resets the peek position.

This method blocks until at least one byte of data can be read, the end of the input is detected, or an exception is thrown.

Parameters
`buffer: ByteArray!`	A target array into which data should be written.
`offset: Int`	The offset into the target array at which to write.
`length: Int`	The maximum number of bytes to read from the input.

Returns
`Int`	The number of bytes read, or `RESULT_END_OF_INPUT` if the input has ended.

Throws
`java.io.IOException`	If an error occurs reading from the input.

readFully

fun readFully(target: ByteArray!, offset: Int, length: Int): Unit

Equivalent to readFully(target, offset, length, false).

Parameters
`target: ByteArray!`	A target array into which data should be written.
`offset: Int`	The offset into the target array at which to write.
`length: Int`	The number of bytes to read from the input.

Throws
`java.io.EOFException`	If the end of input was encountered.
`java.io.IOException`	If an error occurs reading from the input.

readFully

fun readFully(
    target: ByteArray!,
    offset: Int,
    length: Int,
    allowEndOfInput: Boolean
): Boolean

Like read, but reads the requested length in full.

Parameters
`target: ByteArray!`	A target array into which data should be written.
`offset: Int`	The offset into the target array at which to write.
`length: Int`	The number of bytes to read from the input.
`allowEndOfInput: Boolean`	True if encountering the end of the input having read no data is allowed, and should result in `false` being returned. False if it should be considered an error, causing an `EOFException` to be thrown. See note in class Javadoc.

Returns
`Boolean`	True if the read was successful. False if `allowEndOfInput=true` and the end of the input was encountered having read no data.

Throws
`java.io.EOFException`	If the end of input was encountered having partially satisfied the read (i.e. having read at least one byte, but fewer than `length`), or if no bytes were read and `allowEndOfInput` is false.
`java.io.IOException`	If an error occurs reading from the input.

reset

fun reset(): Unit

Resets the input to its initial state.

resetPeekPosition

fun resetPeekPosition(): Unit

Resets the peek position to equal the current read position.

setPosition

fun setPosition(position: Int): Unit

Sets the read and peek positions.

Parameters
`position: Int`	The position to set.

setRetryPosition

fun <E : Throwable?> setRetryPosition(position: Long, e: E!): Unit

Called when reading fails and the required retry position is different from the last position. After setting the retry position it throws the given Throwable.

Parameters
`<E : Throwable?>`	Type of `Throwable` to be thrown.
`position: Long`	The required retry position.
`e: E!`	`Throwable` to be thrown.

Throws
`E`	The given `Throwable` object.
`androidx.media3.test.utils.FakeExtractorInput`

skip

fun skip(length: Int): Int

Like read, except the data is skipped instead of read.

Parameters
`length: Int`	The maximum number of bytes to skip from the input.

Returns
`Int`	The number of bytes skipped, or `RESULT_END_OF_INPUT` if the input has ended.

Throws
`java.io.IOException`	If an error occurs reading from the input.

skipFully

fun skipFully(length: Int): Unit

Like readFully, except the data is skipped instead of read.

Encountering the end of input is always considered an error, and will result in an being thrown.

Parameters
`length: Int`	The number of bytes to skip from the input.

Throws
`java.io.EOFException`	If the end of input was encountered.
`java.io.IOException`	If an error occurs reading from the input.

skipFully

fun skipFully(length: Int, allowEndOfInput: Boolean): Boolean

Like readFully, except the data is skipped instead of read.

Parameters
`length: Int`	The number of bytes to skip from the input.
`allowEndOfInput: Boolean`	True if encountering the end of the input having skipped no data is allowed, and should result in `false` being returned. False if it should be considered an error, causing an `EOFException` to be thrown. See note in class Javadoc.

Returns
`Boolean`	True if the skip was successful. False if `allowEndOfInput=true` and the end of the input was encountered having skipped no data.

Throws
`java.io.EOFException`	If the end of input was encountered having partially satisfied the skip (i.e. having skipped at least one byte, but fewer than `length`), or if no bytes were skipped and `allowEndOfInput` is false.
`java.io.IOException`	If an error occurs reading from the input.

FakeExtractorInput

Summary

Nested types

Public functions

Public functions

advancePeekPosition

advancePeekPosition

getLength

getPeekPosition

getPosition

peek

peekFully

peekFully

read

readFully

readFully

reset

resetPeekPosition

setPosition

setRetryPosition

skip

skipFully

skipFully