Sharkysoft home

lava.riff
Interface IRiffInput

All Known Implementing Classes:
RiffInputFile, RiffInputStream

public interface IRiffInput

Riff input source.

Details: IRiffInput defines methods for accessing the individual BYTEs, WORDs, DWORDs, and chunks of a RIFF data source. Since this interface represents a generic byte input source, the underlying data source may or may not be file based. While IRiffInput is typically used for reading static RIFF files, it can also be used to access other data sources, such as streaming data sources or dynamically created "virtual files."

IRiffInput implementations maintain a "read offset," or a value that indicates the position of the next element to be read. Because this value is settable, it is possible that RIFF data consumers will request RIFF data in random order. (The read offset is similar to the "file pointer" concept used in java.io.RandomAccessFile). The offset of the first byte in an IRiffInput data source is 0.

Because IRiffInput allows clients to read byte sequences in random order, some implementations will need to buffer their underlying data sources if they do not support random access. To facilitate efficient memory usage, IRiffInput defines a free method which clients can use to give hints about segments that are no longer needed. Implementations should take advantage of these hints to produce efficient buffering, and clients should provide as many of these hints as possible.

Clip-source:

Since:
1999.09.24

Method Summary
 void close()
          Closes input source.
 void free(long offset, long amount)
          Unbuffers bytes.
 long getLength()
          Returns file length.
 long getPosition()
          Returns read offset.
 int read()
          Reads byte.
 int read(byte[] dest, int offset, int amount)
          Reads BYTEs.
 int read(int[] dest, int offset, int amount)
          Reads DWORDs.
 int read(short[] dest, int offset, int amount)
          Reads WORDs.
 void setPosition(long newpos)
          Sets read offset.
 

Method Detail

getLength

public long getLength()
               throws java.io.IOException
Returns file length.

Details: This method returns the length of the RIFF file, if it is known, or -1 otherwise.

Returns:
the length

getPosition

public long getPosition()
                 throws java.io.IOException
Returns read offset.

Details: This method returns the read offset, or the position of the next byte to be read. The position reported may be greater than the length of the stream if it was previously set to be so. (See setPosition.)

Returns:
the position

setPosition

public void setPosition(long newpos)
                 throws java.io.IOException
Sets read offset.

Details: This method sets the read offset, or the position of the next byte to be read, to newpos. Setting the position to a value greater than the length of the file is legal, and will not cause an error unless a read is subsequently attempted from that position.

Parameters:
newpos - the new position

read

public int read()
         throws java.io.IOException
Reads byte.

Details: This method reads and returns the next BYTE, i.e., the BYTE pointed to by the read offset. The read offset is automatically incremented by 1. The BYTE is zero-extended into an int before it is returned. If a BYTE could not be read because the end of the data source was reached, -1 is returned.

Returns:
the byte

read

public int read(byte[] dest,
                int offset,
                int amount)
         throws java.io.IOException
Reads BYTEs.

Details: This method reads a consecutive run of BYTEs from the data source, beginning with the BYTE at the current position. The BYTEs are stored in dest beginning at the given offset (offset). Up to amount BYTEs are read and stored, but the actual number of BYTEs read may be less if the end of the sequence is reached. If BYTEs are read, the number of BYTEs read is returned, but if no BYTEs can be read, -1 is returned. The read offset is automatically advanced by the number of BYTEs read.

Parameters:
dest - the destination array
offset - offset into dest
amount - number of bytes to read
Returns:
actual number of bytes read

read

public int read(short[] dest,
                int offset,
                int amount)
         throws java.io.IOException
Reads WORDs.

Details: This method reads a consecutive run of little-endian WORDs, or 16-bit integers, from the data source, beginning with the WORD at the current position. The WORDs are stored in dest beginning at the given offset (offset). Up to amount WORDs are read and stored, but the actual number of WORDs read may be less if the end of the sequence is reached. If WORDs are read, the number of WORDs read is returned, but if no WORDs can be read, -1 is returned. The read offset is automatically advanced by the number of BYTEs read.

Parameters:
dest - the destination array
offset - offset into dest
amount - number of bytes to read
Returns:
actual number of bytes read

read

public int read(int[] dest,
                int offset,
                int amount)
         throws java.io.IOException
Reads DWORDs.

Details: This method reads a consecutive run of little-endian DWORDs, or 32-bit integers, from the data source, beginning with the DWORD at the current position. The DWORDs are stored in dest beginning at the given offset (offset). Up to amount DWORDs are read and stored, but the actual number of DWORDs read may be less if the end of the sequence is reached. If DWORDs are read, the number of DWORDs read is returned, but if no DWORDs can be read, -1 is returned. The read offset is automatically advanced by the number of BYTEs read.

Parameters:
dest - the destination array
offset - offset into dest
amount - number of bytes to read
Returns:
actual number of bytes read

free

public void free(long offset,
                 long amount)
          throws java.io.IOException
Unbuffers bytes.

Details: This method advises this implementation that the given range of bytes can be unbuffered because the consumer has no need to read them again. Revisiting segments of this data source after they have been freed can cause an exception, return incorrect data, or simply cause undetected, unpredictable results.

Parameters:
offset - the position of the forgettable segment
amount - the length of the forgettable segment

close

public void close()
           throws java.io.IOException
Closes input source.

Details: close closes this data source and releases associated resources. Calling any of the other methods after close may produce unpredictable results or generate an exception.


Sharkysoft home