|
Sharkysoft home | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
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.
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 |
public long getLength() throws java.io.IOException
Details: This method returns the length of the RIFF file, if it is known, or -1 otherwise.
public long getPosition() throws java.io.IOException
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
public void setPosition(long newpos) throws java.io.IOException
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.
newpos
- the new positionpublic int read() throws java.io.IOException
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-int
before it is returned. If a BYTE could not be read because the end of the data source was reached, -1 is returned.
public int read(byte[] dest, int offset, int amount) throws java.io.IOException
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.
dest
- the destination arrayoffset
- offset into destamount
- number of bytes to readpublic int read(short[] dest, int offset, int amount) throws java.io.IOException
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.
dest
- the destination arrayoffset
- offset into destamount
- number of bytes to readpublic int read(int[] dest, int offset, int amount) throws java.io.IOException
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.
dest
- the destination arrayoffset
- offset into destamount
- number of bytes to readpublic void free(long offset, long amount) throws java.io.IOException
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 free
d can cause an exception, return incorrect data, or simply cause undetected, unpredictable results.
offset
- the position of the forgettable segmentamount
- the length of the forgettable segmentpublic void close() throws java.io.IOException
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 | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |