RIFFChunk (Media Authoring with Java API)
Date: 2016-02-05

tv.amwa.maj.model

## Interface RIFFChunk

- All Superinterfaces:
    InterchangeObject, MediaEntity, MetadataObject
  All Known Implementing Classes:
    RIFFChunkImpl

      public interface RIFFChunk
      extends InterchangeObject

  Specifies a chunk of resource interchange file format (RIFF) data, identified by a 4-byte tag and variable size field.

  See the description of the RIFF file format on Wikipedia.

  See Also:
    `BWFImportDescriptor.getUnknownBWFChunks()`, `TypeDefinitions.RIFFChunkStrongReference`, `TypeDefinitions.RIFFChunkStrongReferenceVector`

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `RIFFChunk` | `clone()` Create a cloned copy of this RIFF chunk.
    `Stream` | `getChunkData()` Returns the complete data of this RIFF chunk.
    `int` | `getChunkID()` Returns the chunk id of this RIFF chunk, which is a 4-byte tag that identifies this tag.
    `int` | `getLength()` Returns the total size of this RIFF chunk measured in bytes.
    `long` | `getPosition()` Returns the current position for reading or writing the RIFF chunk data.
    `ByteBuffer` | `read(int numberOfBytes)` Read the requested number of bytes from the RIFF chunk at the current position.
    `void` | `setChunkData(Stream chunkData)` Sets the complete data of this RIFF chunk and initializes the position to zero.
    `void` | `setChunkID(int chunkId)` Sets the chunk id of this RIFF chunk, which is a 4-byte tag that identifies this tag.
    `void` | `setPosition(long offset)` Sets the position for reading or writing this RIFF chunk data.
    `void` | `write(ByteBuffer bytes)` Writes the given bytes to this RIFF chunk data at the current position.

    - ### Methods inherited from interface tv.amwa.maj.model.InterchangeObject

      `addApplicationPlugin, clearApplicationPlugins, containsApplicationPlugin, containsApplicationPlugin, countApplicationPlugins, deepEquals, disableGenerationTracking, enableGenerationTracking, equals, getApplicationPlugins, getGeneration, getLinkedGenerationID, getObjectClass, isGenerationTracked, removeApplicationPlugin, removeApplicationPlugin, setLinkedGenerationID, setObjectClass, toString`

    - ### Methods inherited from interface tv.amwa.maj.industry.MediaEntity

      `getPersistentID, setPersistentIndex`

- - ### Method Detail

    - #### setChunkID

          void setChunkID(@UInt32
                          int chunkId)

      Sets the chunk id of this RIFF chunk, which is a 4-byte tag that identifies this tag.

      Note that in the representation of this tag, care needs to be taken to ensure that the sign bit is not confused with an 8-bit character code. Negative values are accepted by this method.

      Parameters:
        `chunkId` - Chunk identifier for this RIFF chunk.

    - #### getChunkID

          @UInt32
          int getChunkID()

      Returns the chunk id of this RIFF chunk, which is a 4-byte tag that identifies this tag.

      Note that in the representation of this tag, care needs to be taken to ensure that the sign bit is not confused with an 8-bit character code. Negative values are accepted by this method.

      Returns:
        Chunk identifier for this RIFF chunk.

    - #### read

          @DataBuffer
          ByteBuffer read(@UInt32
                                      int numberOfBytes)
                               throws IllegalArgumentException,
                                      EndOfDataException,
                                      IOException

      Read the requested number of bytes from the RIFF chunk at the current position. The position is advanced by the number of bytes read.

      Parameters:
        `numberOfBytes` - Number of bytes to read from the RIFF chunk.
      Returns:
        Bytes read from the RIFF chunk at the current position.
      Throws:
        `IllegalArgumentException` - Cannot read a negative number of bytes.
        `EndOfDataException` - The number of bytes requested are not available in the RIFF chunk relative to the current position.
        `IOException` - Error occurred when trying to read from the underlying stream.
      See Also:
        `getPosition()`

    - #### write

          void write(@DataBuffer
                     ByteBuffer bytes)
              throws NullPointerException,
                     EndOfDataException,
                     IOException

      Writes the given bytes to this RIFF chunk data at the current position. The position is advanced by the number of bytes written. Any data beyond the new position is lost by truncating the buffer.

      Parameters:
        `bytes` - Bytes to write to the RIFF chunk data.
      Throws:
        `NullPointerException` - The given array of bytes is `null`.
        `EndOfDataException` - The size of the RIFF chunk is less than the number of bytes to write relative to the current position.
        `IOException` - Error occurred when trying to write to the underlying stream.
      See Also:
        `getPosition()`

    - #### setPosition

          void setPosition(@PositionType
                           long offset)
                    throws PositionOutOfRangeException,
                           IOException

      Sets the position for reading or writing this RIFF chunk data.

      Parameters:
        `offset` - Position offset to set for reading or writing RIFF chunk data.
      Throws:
        `PositionOutOfRangeException` - The given offset is outside the acceptable range for this RIFF chunk data, which is between 0 and the length of the data.
        `IOException` - Error occurred when trying to set the position for the underlying stream.
      See Also:
        `getLength()`

    - #### getPosition

          @PositionType
          long getPosition()
                                  throws IOException

      Returns the current position for reading or writing the RIFF chunk data.

      Returns:
        Current position for reading or writing the RIFF chunk data.
      Throws:
        `IOException` - Error occurred when trying to set the position for the underlying stream.

    - #### getLength

          @UInt32
          int getLength()

      Returns the total size of this RIFF chunk measured in bytes. The length is initially 0 until `setChunkData(Stream)` has been called.

      Returns:
        Total size size of this RIFF chunk measured in bytes.

    - #### getChunkData

          @DataBuffer
          Stream getChunkData()

      Returns the complete data of this RIFF chunk.

      Returns:
        Actual data of this RIFF chunk.

    - #### setChunkData

          void setChunkData(Stream chunkData)
                     throws NullPointerException

      Sets the complete data of this RIFF chunk and initializes the position to zero. The length property of this RIFF chunk will be set to the length of the given chunk data.

      Parameters:
        `chunkData` - Actual data for this RIFF chunk.
      Throws:
        `NullPointerException` - The chunk data argument is `null.`

    - #### clone

          RIFFChunk clone()

      Create a cloned copy of this RIFF chunk.

      Specified by:
        `clone` in interface `InterchangeObject`
      Specified by:
        `clone` in interface `MediaEntity`
      Returns:
        Cloned copy of this RIFF chunk.

(c)2007-2016 Richard Cartwright, all rights reserved. Licensed under Apache 2 license and subject to the AMWA IPR policy.