/*
 * Copyright (C) 2016 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package androidx.media3.extractor;

import androidx.media3.common.C;
import androidx.media3.common.DataReader;
import androidx.media3.common.util.UnstableApi;
import java.io.EOFException;
import java.io.IOException;
import java.io.InputStream;

/**
 * Provides data to be consumed by an {@link Extractor}.
 *
 * <p>This interface provides two modes of accessing the underlying input. See the subheadings below
 * for more info about each mode.
 *
 * <ul>
 *   <li>The {@code read()/peek()} and {@code skip()} methods provide {@link InputStream}-like
 *       byte-level access operations.
 *   <li>The {@code read/skip/peekFully()} and {@code advancePeekPosition()} methods assume the user
 *       wants to read an entire block/frame/header of known length.
 * </ul>
 *
 * <h2>{@link InputStream}-like methods</h2>
 *
 * <p>The {@code read()/peek()} and {@code skip()} methods provide {@link InputStream}-like
 * byte-level access operations. The {@code length} parameter is a maximum, and each method returns
 * the number of bytes actually processed. This may be less than {@code length} because the end of
 * the input was reached, or the method was interrupted, or the operation was aborted early for
 * another reason.
 *
 * <h2>Block-based methods</h2>
 *
 * <p>The {@code read/skip/peekFully()} and {@code advancePeekPosition()} methods assume the user
 * wants to read an entire block/frame/header of known length.
 *
 * <p>These methods all have a variant that takes a boolean {@code allowEndOfInput} parameter. This
 * parameter is intended to be set to true when the caller believes the input might be fully
 * exhausted before the call is made (i.e. they've previously read/skipped/peeked the final
 * block/frame/header). It's <b>not</b> intended to allow a partial read (i.e. greater than 0 bytes,
 * but less than {@code length}) to succeed - this will always throw an {@link EOFException} from
 * these methods (a partial read is assumed to indicate a malformed block/frame/header - and
 * therefore a malformed file).
 *
 * <p>The expected behaviour of the block-based methods is therefore:
 *
 * <ul>
 *   <li>Already at end-of-input and {@code allowEndOfInput=false}: Throw {@link EOFException}.
 *   <li>Already at end-of-input and {@code allowEndOfInput=true}: Return {@code false}.
 *   <li>Encounter end-of-input during read/skip/peek/advance: Throw {@link EOFException}
 *       (regardless of {@code allowEndOfInput}).
 * </ul>
 */
@UnstableApi
public interface ExtractorInput extends DataReader {

  /**
   * Reads up to {@code length} bytes from the input and resets the peek position.
   *
   * <p>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.
   *
   * @param buffer A target array into which data should be written.
   * @param offset The offset into the target array at which to write.
   * @param length The maximum number of bytes to read from the input.
   * @return The number of bytes read, or {@link C#RESULT_END_OF_INPUT} if the input has ended.
   * @throws IOException If an error occurs reading from the input.
   */
  @Override
  int read(byte[] buffer, int offset, int length) throws IOException;

  /**
   * Like {@link #read(byte[], int, int)}, but reads the requested {@code length} in full.
   *
   * @param target A target array into which data should be written.
   * @param offset The offset into the target array at which to write.
   * @param length The number of bytes to read from the input.
   * @param allowEndOfInput True if encountering the end of the input having read no data is
   *     allowed, and should result in {@code false} being returned. False if it should be
   *     considered an error, causing an {@link EOFException} to be thrown. See note in class
   *     Javadoc.
   * @return True if the read was successful. False if {@code allowEndOfInput=true} and the end of
   *     the input was encountered having read no data.
   * @throws EOFException If the end of input was encountered having partially satisfied the read
   *     (i.e. having read at least one byte, but fewer than {@code length}), or if no bytes were
   *     read and {@code allowEndOfInput} is false.
   * @throws IOException If an error occurs reading from the input.
   */
  boolean readFully(byte[] target, int offset, int length, boolean allowEndOfInput)
      throws IOException;

  /**
   * Equivalent to {@link #readFully(byte[], int, int, boolean) readFully(target, offset, length,
   * false)}.
   *
   * @param target A target array into which data should be written.
   * @param offset The offset into the target array at which to write.
   * @param length The number of bytes to read from the input.
   * @throws EOFException If the end of input was encountered.
   * @throws IOException If an error occurs reading from the input.
   */
  void readFully(byte[] target, int offset, int length) throws IOException;

  /**
   * Like {@link #read(byte[], int, int)}, except the data is skipped instead of read.
   *
   * @param length The maximum number of bytes to skip from the input.
   * @return The number of bytes skipped, or {@link C#RESULT_END_OF_INPUT} if the input has ended.
   * @throws IOException If an error occurs reading from the input.
   */
  int skip(int length) throws IOException;

  /**
   * Like {@link #readFully(byte[], int, int, boolean)}, except the data is skipped instead of read.
   *
   * @param length The number of bytes to skip from the input.
   * @param allowEndOfInput True if encountering the end of the input having skipped no data is
   *     allowed, and should result in {@code false} being returned. False if it should be
   *     considered an error, causing an {@link EOFException} to be thrown. See note in class
   *     Javadoc.
   * @return True if the skip was successful. False if {@code allowEndOfInput=true} and the end of
   *     the input was encountered having skipped no data.
   * @throws EOFException If the end of input was encountered having partially satisfied the skip
   *     (i.e. having skipped at least one byte, but fewer than {@code length}), or if no bytes were
   *     skipped and {@code allowEndOfInput} is false.
   * @throws IOException If an error occurs reading from the input.
   */
  boolean skipFully(int length, boolean allowEndOfInput) throws IOException;

  /**
   * Like {@link #readFully(byte[], int, int)}, except the data is skipped instead of read.
   *
   * <p>Encountering the end of input is always considered an error, and will result in an {@link
   * EOFException} being thrown.
   *
   * @param length The number of bytes to skip from the input.
   * @throws EOFException If the end of input was encountered.
   * @throws IOException If an error occurs reading from the input.
   */
  void skipFully(int length) throws IOException;

  /**
   * Peeks up to {@code length} bytes from the peek position. The current read position is left
   * unchanged.
   *
   * <p>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.
   *
   * <p>Calling {@link #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.
   *
   * @param target A target array into which data should be written.
   * @param offset The offset into the target array at which to write.
   * @param length The maximum number of bytes to peek from the input.
   * @return The number of bytes peeked, or {@link C#RESULT_END_OF_INPUT} if the input has ended.
   * @throws IOException If an error occurs peeking from the input.
   */
  int peek(byte[] target, int offset, int length) throws IOException;

  /**
   * Like {@link #peek(byte[], int, int)}, but peeks the requested {@code length} in full.
   *
   * @param target A target array into which data should be written.
   * @param offset The offset into the target array at which to write.
   * @param length The number of bytes to peek from the input.
   * @param allowEndOfInput True if encountering the end of the input having peeked no data is
   *     allowed, and should result in {@code false} being returned. False if it should be
   *     considered an error, causing an {@link EOFException} to be thrown. See note in class
   *     Javadoc.
   * @return True if the peek was successful. False if {@code allowEndOfInput=true} and the end of
   *     the input was encountered having peeked no data.
   * @throws EOFException If the end of input was encountered having partially satisfied the peek
   *     (i.e. having peeked at least one byte, but fewer than {@code length}), or if no bytes were
   *     peeked and {@code allowEndOfInput} is false.
   * @throws IOException If an error occurs peeking from the input.
   */
  boolean peekFully(byte[] target, int offset, int length, boolean allowEndOfInput)
      throws IOException;

  /**
   * Equivalent to {@link #peekFully(byte[], int, int, boolean) peekFully(target, offset, length,
   * false)}.
   *
   * @param target A target array into which data should be written.
   * @param offset The offset into the target array at which to write.
   * @param length The number of bytes to peek from the input.
   * @throws EOFException If the end of input was encountered.
   * @throws IOException If an error occurs peeking from the input.
   */
  void peekFully(byte[] target, int offset, int length) throws IOException;

  /**
   * Advances the peek position by {@code length} bytes. Like {@link #peekFully(byte[], int, int,
   * boolean)} except the data is skipped instead of read.
   *
   * @param length The number of bytes by which to advance the peek position.
   * @param allowEndOfInput True if encountering the end of the input before advancing is allowed,
   *     and should result in {@code false} being returned. False if it should be considered an
   *     error, causing an {@link EOFException} to be thrown. See note in class Javadoc.
   * @return True if advancing the peek position was successful. False if {@code
   *     allowEndOfInput=true} and the end of the input was encountered before advancing over any
   *     data.
   * @throws EOFException If the end of input was encountered having partially advanced (i.e. having
   *     advanced by at least one byte, but fewer than {@code length}), or if the end of input was
   *     encountered before advancing and {@code allowEndOfInput} is false.
   * @throws IOException If an error occurs advancing the peek position.
   */
  boolean advancePeekPosition(int length, boolean allowEndOfInput) throws IOException;

  /**
   * Advances the peek position by {@code length} bytes. Like {@link #peekFully(byte[], int, int)}
   * except the data is skipped instead of read.
   *
   * @param length The number of bytes to peek from the input.
   * @throws EOFException If the end of input was encountered.
   * @throws IOException If an error occurs peeking from the input.
   */
  void advancePeekPosition(int length) throws IOException;

  /** Resets the peek position to equal the current read position. */
  void resetPeekPosition();

  /**
   * Returns the current peek position (byte offset) in the stream.
   *
   * @return The peek position (byte offset) in the stream.
   */
  long getPeekPosition();

  /**
   * Returns the current read position (byte offset) in the stream.
   *
   * @return The read position (byte offset) in the stream.
   */
  long getPosition();

  /**
   * Returns the length of the source stream, or {@link C#LENGTH_UNSET} if it is unknown.
   *
   * @return The length of the source stream, or {@link C#LENGTH_UNSET}.
   */
  long getLength();

  /**
   * Called when reading fails and the required retry position is different from the last position.
   * After setting the retry position it throws the given {@link Throwable}.
   *
   * @param <E> Type of {@link Throwable} to be thrown.
   * @param position The required retry position.
   * @param e {@link Throwable} to be thrown.
   * @throws E The given {@link Throwable} object.
   */
  <E extends Throwable> void setRetryPosition(long position, E e) throws E;
}