/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You 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.
*/
/**
* @author Rustem V. Rafikov
* @version $Revision: 1.2 $
*/
package javax.imageio.stream;
import java.io.DataInput;
import java.io.IOException;
import java.nio.ByteOrder;
/**
* The ImageInputStream represents input stream interface that is used by
* ImageReaders.
*
* @since Android 1.0
*/
public interface ImageInputStream extends DataInput {
/**
* Sets the specified byte order for reading of data values from this
* stream.
*
* @param byteOrder
* the byte order.
*/
void setByteOrder(ByteOrder byteOrder);
/**
* Gets the byte order.
*
* @return the byte order.
*/
ByteOrder getByteOrder();
/**
* Reads a byte from the stream.
*
* @return the byte of the stream, or -1 for EOF indicating.
* @throws IOException
* if an I/O exception has occurred.
*/
int read() throws IOException;
/**
* Reads number of bytes which is equal to the specified array's length and
* stores a result to this array.
*
* @param b
* the byte array.
* @return the number of read bytes, or -1 indicated EOF.
* @throws IOException
* if an I/O exception has occurred.
*/
int read(byte[] b) throws IOException;
/**
* Reads the number of bytes specified by len parameter from the stream and
* stores a result to the specified array with the specified offset.
*
* @param b
* the byte array.
* @param off
* the offset.
* @param len
* the number of bytes to be read.
* @return the number of read bytes, or -1 indicated EOF.
* @throws IOException
* if an I/O exception has occurred.
*/
int read(byte[] b, int off, int len) throws IOException;
/**
* Reads the number of bytes specified by len parameter from the stream, and
* modifies the specified IIOByteBuffer with the byte array, offset, and
* length.
*
* @param buf
* the IIOByteBuffer.
* @param len
* the number of bytes to be read.
* @throws IOException
* if an I/O exception has occurred.
*/
void readBytes(IIOByteBuffer buf, int len) throws IOException;
/**
* Reads a byte from the stream and returns a boolean true value if it is
* non zero, false if it is zero.
*
* @return the boolean value for read byte.
* @throws IOException
* if an I/O exception has occurred.
*/
boolean readBoolean() throws IOException;
/**
* Reads a byte from the stream and returns its value as signed byte.
*
* @return the signed byte value for read byte.
* @throws IOException
* if an I/O exception has occurred.
*/
byte readByte() throws IOException;
/**
* Reads a byte from the stream and returns its value as an integer.
*
* @return the unsigned byte value for read byte as an integer.
* @throws IOException
* if an I/O exception has occurred.
*/
int readUnsignedByte() throws IOException;
/**
* Reads 2 bytes from the stream, and returns the result as a short.
*
* @return the signed short value from the stream.
* @throws IOException
* if an I/O exception has occurred.
*/
short readShort() throws IOException;
/**
* Reads 2 bytes from the stream and returns its value as an unsigned short.
*
* @return a unsigned short value coded in an integer.
* @throws IOException
* if an I/O exception has occurred.
*/
int readUnsignedShort() throws IOException;
/**
* Reads 2 bytes from the stream and returns their unsigned char value.
*
* @return the unsigned char value.
* @throws IOException
* if an I/O exception has occurred.
*/
char readChar() throws IOException;
/**
* Reads 4 bytes from the stream, and returns the result as an integer.
*
* @return the signed integer value from the stream.
* @throws IOException
* if an I/O exception has occurred.
*/
int readInt() throws IOException;
/**
* Reads 4 bytes from the stream and returns its value as long.
*
* @return the unsigned integer value as long.
* @throws IOException
* if an I/O exception has occurred.
*/
long readUnsignedInt() throws IOException;
/**
* Reads 8 bytes from the stream, and returns the result as a long.
*
* @return the long value from the stream.
* @throws IOException
* if an I/O exception has occurred.
*/
long readLong() throws IOException;
/**
* Reads 4 bytes from the stream, and returns the result as a float.
*
* @return the float value from the stream.
* @throws IOException
* if an I/O exception has occurred.
*/
float readFloat() throws IOException;
/**
* Reads 8 bytes from the stream, and returns the result as a double.
*
* @return the double value from the stream.
* @throws IOException
* if an I/O exception has occurred.
*/
double readDouble() throws IOException;
/**
* Reads a line from the stream.
*
* @return the string contained the line from the stream.
* @throws IOException
* if an I/O exception has occurred.
*/
String readLine() throws IOException;
/**
* Reads bytes from the stream in a string that has been encoded in a
* modified UTF-8 format.
*
* @return the string read from stream and modified UTF-8 format.
* @throws IOException
* if an I/O exception has occurred.
*/
String readUTF() throws IOException;
/**
* Reads the specified number of bytes from the stream, and stores the
* result into the specified array starting at the specified index offset.
*
* @param b
* the byte array.
* @param off
* the offset.
* @param len
* the number of bytes to be read.
* @throws IOException
* if an I/O exception has occurred.
*/
void readFully(byte[] b, int off, int len) throws IOException;
/**
* Reads number of bytes from the stream which is equal to the specified
* array's length, and stores them into this array.
*
* @param b
* the byte array.
* @throws IOException
* if an I/O exception has occurred.
*/
void readFully(byte[] b) throws IOException;
/**
* Reads the specified number of shorts from the stream, and stores the
* result into the specified array starting at the specified index offset.
*
* @param s
* the short array.
* @param off
* the offset.
* @param len
* the number of shorts to be read.
* @throws IOException
* if an I/O exception has occurred.
*/
void readFully(short[] s, int off, int len) throws IOException;
/**
* Reads the specified number of chars from the stream, and stores the
* result into the specified array starting at the specified index offset.
*
* @param c
* the char array.
* @param off
* the offset.
* @param len
* the number of chars to be read.
* @throws IOException
* if an I/O exception has occurred.
*/
void readFully(char[] c, int off, int len) throws IOException;
/**
* Reads the specified number of integer from the stream, and stores the
* result into the specified array starting at the specified index offset.
*
* @param i
* the integer array.
* @param off
* the offset.
* @param len
* the number of integer to be read.
* @throws IOException
* if an I/O exception has occurred.
*/
void readFully(int[] i, int off, int len) throws IOException;
/**
* Reads the specified number of longs from the stream, and stores the
* result into the specified array starting at the specified index offset.
*
* @param l
* the long array.
* @param off
* the offset.
* @param len
* the number of longs to be read.
* @throws IOException
* if an I/O exception has occurred.
*/
void readFully(long[] l, int off, int len) throws IOException;
/**
* Reads the specified number of floats from the stream, and stores the
* result into the specified array starting at the specified index offset.
*
* @param f
* the float array.
* @param off
* the offset.
* @param len
* the number of floats to be read.
* @throws IOException
* if an I/O exception has occurred.
*/
void readFully(float[] f, int off, int len) throws IOException;
/**
* Reads the specified number of doubles from the stream, and stores the
* result into the specified array starting at the specified index offset.
*
* @param d
* the double array.
* @param off
* the offset.
* @param len
* the number of doubles to be read.
* @throws IOException
* if an I/O exception has occurred.
*/
void readFully(double[] d, int off, int len) throws IOException;
/**
* Gets the stream position.
*
* @return the stream position.
* @throws IOException
* if an I/O exception has occurred.
*/
long getStreamPosition() throws IOException;
/**
* Gets the bit offset.
*
* @return the bit offset.
* @throws IOException
* if an I/O exception has occurred.
*/
int getBitOffset() throws IOException;
/**
* Sets the bit offset to an integer between 0 and 7.
*
* @param bitOffset
* the bit offset.
* @throws IOException
* if an I/O exception has occurred.
*/
void setBitOffset(int bitOffset) throws IOException;
/**
* Reads a bit from the stream and returns the value 0 or 1.
*
* @return the value of single bit: 0 or 1.
* @throws IOException
* if an I/O exception has occurred.
*/
int readBit() throws IOException;
/**
* Read the specified number of bits and returns their values as long.
*
* @param numBits
* the number of bits to be read.
* @return the bit string as a long.
* @throws IOException
* if an I/O exception has occurred.
*/
long readBits(int numBits) throws IOException;
/**
* Returns the length of the stream.
*
* @return the length of the stream, or -1 if unknown.
* @throws IOException
* if an I/O exception has occurred.
*/
long length() throws IOException;
/**
* Skips the specified number of bytes by moving stream position.
*
* @param n
* the number of bytes.
* @return the actual skipped number of bytes.
* @throws IOException
* if an I/O exception has occurred.
*/
int skipBytes(int n) throws IOException;
/**
* Skips the specified number of bytes by moving stream position.
*
* @param n
* the number of bytes.
* @return the actual skipped number of bytes.
* @throws IOException
* if an I/O exception has occurred.
*/
long skipBytes(long n) throws IOException;
/**
* Sets the current stream position to the specified location.
*
* @param pos
* a file pointer position.
* @throws IOException
* if an I/O exception has occurred.
*/
void seek(long pos) throws IOException;
/**
* Marks a position in the stream to be returned to by a subsequent call to
* reset.
*/
void mark();
/**
* Returns the file pointer to its previous position.
*
* @throws IOException
* if an I/O exception has occurred.
*/
void reset() throws IOException;
/**
* Flushes the initial position in this stream prior to the specified stream
* position.
*
* @param pos
* the position.
* @throws IOException
* if an I/O exception has occurred.
*/
void flushBefore(long pos) throws IOException;
/**
* Flushes the initial position in this stream prior to the current stream
* position.
*
* @throws IOException
* if an I/O exception has occurred.
*/
void flush() throws IOException;
/**
* Gets the flushed position.
*
* @return the flushed position.
*/
long getFlushedPosition();
/**
* Returns true if this ImageInputStream caches data in order to allow
* seeking backwards.
*
* @return true, if this ImageInputStream caches data in order to allow
* seeking backwards, false otherwise.
*/
boolean isCached();
/**
* Returns true if this ImageInputStream caches data in order to allow
* seeking backwards, and keeps it in memory.
*
* @return true, if this ImageInputStream caches data in order to allow
* seeking backwards, and keeps it in memory.
*/
boolean isCachedMemory();
/**
* Returns true if this ImageInputStream caches data in order to allow
* seeking backwards, and keeps it in a temporary file.
*
* @return true, if this ImageInputStream caches data in order to allow
* seeking backwards, and keeps it in a temporary file.
*/
boolean isCachedFile();
/**
* Closes this stream.
*
* @throws IOException
* if an I/O exception has occurred.
*/
void close() throws IOException;
}