org.niffty
Class RIFF

java.lang.Object
  |
  +--org.niffty.RIFF

public class RIFF

extends java.lang.Object

Class for reading RIFF files.

Constructor Summary

RIFF(java.io.InputStream input, java.lang.String formID)
Start reading a new RIFF stream as a RIFF form, requiring the chunkID to be "RIFX" and the form ID to be formID.

RIFF(RIFF parent)
Begin reading a new RIFF chunk or list which is part of a parent chunk or list.

RIFF(RIFF parent, java.lang.String chunkID)
Begin reading a new RIFF chunk or list which is part of a parent chunk or list, requiring the chunkID to be chunkID.

Method Summary

int	getBytesRemaining() Return the bytes remaining in this chunk or list.
java.lang.String	getChunkID() Return the chunk ID which was read in the constructor.
int[]	getTagData() Returns the tag data from the most recent call to readTag.
int	getTagID() Returns the tag ID from the most recent call to readTag.
int	peekFirstChunkBYTE() First, read four bytes from input stream (the chunk ID) and ignore them.
java.lang.String	peekFOURCC() Read four bytes from input and return as a string, and restore the input stream to before the bytes were read.
java.lang.String	peekListID() First, read four bytes from input stream.
int	readBYTE() Read one byte from _input as a BYTE (unsigned one-byte) and return as an int.
int	readDWORD() Read four bytes from _input as a DWORD (unsigned, most significant byte first) and return as an int.
java.lang.String	readFOURCC() Read four bytes from input and return as a string.
int	readSHORT() Read two bytes from _input as a SHORT (signed, most significant byte first) and return as an int.
int	readSIGNEDBYTE() Read one byte from _input as a SIGNEDBYTE (signed one-byte) and return as an int.
int	readTag() Read a tag from the input stream and return the tag ID.
void	requireFOURCC(java.lang.String value) Read four bytes from input as a FOURCC and check against value, and if not equal, throw a RIFFFormatException.
void	skipChunk() Skip past the next chunk in the input stream.
void	skipRemaining() Skip over and discard the remaining bytes in this chunk or list.
int	tagByteAt(int index) Interpret tagData[index] as a one-byte unsigned integer, and return as an int.
java.lang.String	tagDataString() Returns the tag data from the most recent call to readTag as a String.
int	tagLongAt(int index) Interpret tagData[index] through tagData[index+3] as a four-byte signed integer, most significant byte first and return as an int.
int	tagShortAt(int index) Interpret tagData[index] and tagData[index+1] as a two-byte signed integer, most significant byte first and return as an int.
int	tagSignedByteAt(int index) Interpret tagData[index] as a one-byte signed integer, and return as an int.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

RIFF

public RIFF(java.io.InputStream input,
            java.lang.String formID)
     throws java.io.IOException,
            RIFFFormatException

Start reading a new RIFF stream as a RIFF form, requiring the chunkID to be "RIFX" and the form ID to be formID. Upon return, the input file is ready to read the content.

Parameters:

input - the RIFF input stream

formID - the expected form ID

Throws:

java.io.IOException - if an I/O error occurs

RIFFFormatException - if the chunk ID is not "RIFX"

See Also:

requireFOURCC(java.lang.String)

RIFF

public RIFF(RIFF parent)
     throws java.io.IOException

Begin reading a new RIFF chunk or list which is part of a parent chunk or list. Upon return, the input file is ready to read the content. The chunk ID can be checked with getChunkID(). If this is a list, you can read the list ID with readFOURCC(). This will update the bytesRemaining for this and parent RIFF objects.

Parameters:

parent - the parent RIFF object

Throws:

java.io.IOException - if an I/O error occurs

See Also:

getChunkID(), readFOURCC()

RIFF

public RIFF(RIFF parent,
            java.lang.String chunkID)
     throws java.io.IOException,
            RIFFFormatException

Begin reading a new RIFF chunk or list which is part of a parent chunk or list, requiring the chunkID to be chunkID. To begin a list, use "LIST" for chunkID. Upon return, the input file is ready to read the content. To check the list ID, call requireFOURCC. This will update the bytesRemaining for this and parent RIFF objects.

Parameters:

parent - the parent RIFF object

chunkID - the required chunk ID

Throws:

java.io.IOException - if an I/O error occurs

RIFFFormatException - if the chunk ID read is not chunkID

See Also:

requireFOURCC(java.lang.String)

Method Detail

getChunkID

public java.lang.String getChunkID()

Return the chunk ID which was read in the constructor.

getBytesRemaining

public int getBytesRemaining()

Return the bytes remaining in this chunk or list. This value is automatically decremented as this or any child objects reads from the input stream.

readBYTE

public int readBYTE()
             throws java.io.IOException

Read one byte from _input as a BYTE (unsigned one-byte) and return as an int. This decrements bytesRemaining for this and all parents.

java.io.IOException

readDWORD

public int readDWORD()
              throws java.io.IOException

Read four bytes from _input as a DWORD (unsigned, most significant byte first) and return as an int. This decrements bytesRemaining for this and all parents.

java.io.IOException

readSIGNEDBYTE

public int readSIGNEDBYTE()
                   throws java.io.IOException

Read one byte from _input as a SIGNEDBYTE (signed one-byte) and return as an int. This decrements bytesRemaining for this and all parents.

java.io.IOException

readSHORT

public int readSHORT()
              throws java.io.IOException

Read two bytes from _input as a SHORT (signed, most significant byte first) and return as an int. This decrements bytesRemaining for this and all parents.

java.io.IOException

readFOURCC

public java.lang.String readFOURCC()
                            throws java.io.IOException

Read four bytes from input and return as a string. This decrements bytesRemaining for this and all parents.

java.io.IOException

peekFOURCC

public java.lang.String peekFOURCC()
                            throws java.io.IOException

Read four bytes from input and return as a string, and restore the input stream to before the bytes were read. This does not change bytesRemaining.

java.io.IOException

peekListID

public java.lang.String peekListID()
                            throws java.io.IOException

First, read four bytes from input stream. If it is not "LIST" then return "". Otherwise, skip four chunk length bytes are read the next four bytes, returning them as a String. Finally, restore the input stream to before the bytes were read. This does not change bytesRemaining.

Returns:

the list ID or "" if the chunkID is not "LIST"

java.io.IOException

peekFirstChunkBYTE

public int peekFirstChunkBYTE()
                       throws java.io.IOException

First, read four bytes from input stream (the chunk ID) and ignore them. Next, skip four chunk length bytes are return the first BYTE (unsigned one-byte) of the chunk data. Finally, restore the input stream to before the bytes were read. Although not very general (it can only get the first BYTE, not any other byte), this is useful if the first byte of the chunk has important identifying information. This does not change bytesRemaining.

Returns:

the the first BYTE of the chunk body.

java.io.IOException

requireFOURCC

public void requireFOURCC(java.lang.String value)
                   throws java.io.IOException,
                          RIFFFormatException

Read four bytes from input as a FOURCC and check against value, and if not equal, throw a RIFFFormatException. For success, simply return. This decrements bytesRemaining for this and all parents.

Parameters:

value - the expected FOURCC value

Throws:

java.io.IOException - if an I/O error occurs

RIFFFormatException - if the chunk ID is not "RIFX"

skipChunk

public void skipChunk()
               throws java.io.IOException

Skip past the next chunk in the input stream.

java.io.IOException

skipRemaining

public void skipRemaining()
                   throws java.io.IOException

Skip over and discard the remaining bytes in this chunk or list. This also skips past a possible pad byte at the end of the chunk.

java.io.IOException

readTag

public int readTag()
            throws java.io.IOException

Read a tag from the input stream and return the tag ID. A tag has a one byte tag ID, a one byte tag size and data of the given size. On return, call getTagData() to get the tag data. The tag data is an array of int where each int is between 0 and 255. The data length is getTagData().length . This decrements bytesRemaining for this and all parents. Even though getTagData() does not include the possible pad byte, this will advance the input stream past the pad byte.

Returns:

the tag ID (also available from getTagID())

java.io.IOException

See Also:

getTagData(), getTagID()

getTagID

public int getTagID()

Returns the tag ID from the most recent call to readTag.

See Also:

readTag()

getTagData

public int[] getTagData()

Returns the tag data from the most recent call to readTag. The tagData is an array of int where each int is between 0 and 255.

See Also:

readTag()

tagDataString

public java.lang.String tagDataString()

Returns the tag data from the most recent call to readTag as a String. This first converts the tagData() to an array of byte and then uses the String constructor String(bytes).

See Also:

readTag()

tagShortAt

public int tagShortAt(int index)
               throws RIFFFormatException

Interpret tagData[index] and tagData[index+1] as a two-byte signed integer, most significant byte first and return as an int.

Parameters:

index - the position in tagData of the first byte of the SHORT

Returns:

the two-byte integer starting at tagData[index]

Throws:

RIFFFormatException - if the SHORT at index extends beyond the length of tagData.

tagLongAt

public int tagLongAt(int index)
              throws RIFFFormatException

Interpret tagData[index] through tagData[index+3] as a four-byte signed integer, most significant byte first and return as an int.

Parameters:

index - the position in tagData of the first byte of the LONG

Returns:

the four-byte integer starting at tagData[index]

Throws:

RIFFFormatException - if the LONG at index extends beyond the length of tagData.

tagByteAt

public int tagByteAt(int index)
              throws RIFFFormatException

Interpret tagData[index] as a one-byte unsigned integer, and return as an int.

Parameters:

index - the position in tagData of the BYTE

Returns:

the one-byte integer at tagData[index]

Throws:

RIFFFormatException - if the index is beyond the length of tagData.

tagSignedByteAt

public int tagSignedByteAt(int index)
                    throws RIFFFormatException

Interpret tagData[index] as a one-byte signed integer, and return as an int.

Parameters:

index - the position in tagData of the SIGNEDBYTE

Returns:

the one-byte integer at tagData[index]

Throws:

RIFFFormatException - if the index is beyond the length of tagData.