/*******************************************************************************
 *  Copyright 2017-2018 Centre for Development of Advanced Computing(C-DAC), Pune
 *  
 * Licensed 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.
 *******************************************************************************/
package cdac.medinfo.sdk.dcm30_04.commoninterface;

import java.io.IOException;

/**
 * This interface needs to be implemented by all classes which implements the necessary functionality for the Dicom Stream. 
 */
public interface IDicomStream
{
	/**
	 * Retrieves the stream.
	 * @return int - integer value of stream type.
	 */
	int getStream();

	/**
	 * Writes the data to the buffer.
	 * @param arrbyte Byte array containing data.
	 * @param iOffset integer value shows offset.
	 * @param iLength integer value shows length.
	 * @return boolean - shows status as success or failure.
	 * @throws IOException if Input/Output operation fails.
	 */
	boolean writeBuffer(byte[] arrbyte,int iOffset,int iLength) throws IOException;

	/**
	 * Writes a byte to the stream
	 * @param bVar Byte value.
	 * @return int - shows status as success or failure.
	 * @throws IOException if Input/Output operation fails.
	 */
	int writeByte(byte bVar) throws IOException;

	/**
	 * Writes a short value on to the stream
	 * @param shtVar short value to write.
	 * @return int - integer value shows success.
	 * @throws IOException If IO operation fails.
	 */
	int writeShort(short shtVar) throws IOException;

	/**
	 * Writes a double value to the stream
	 * @param dVar Shows double value to write.
	 * @return int - integer value shows success.
	 * @throws IOException If IO operation fails.
	 */
	int writeDouble(double dVar) throws IOException;

	/**
	 * Writes a float value to the stream
	 * @param fVar Shows float value to write.
	 * @return int - integer value shows success.
	 * @throws IOException If IO operation fails.
	 */
	int writeFloat(float fVar) throws IOException;

	/**
	 * Writes an int value to the stream
	 * @param nVar integer value to write.
	 * @return int - integer value shows success.
	 * @throws IOException If IO operation fails.
	 */
	int writeInt(int nVar) throws IOException;

	/**
	 * Writes an Long value to the stream
	 * @param iVar integer value to write.
	 * @return int - integer value shows success.
	 * @throws IOException If IO operation fails.
	 */
	int writeLong(int iVar) throws IOException;

	/**
	 * Writes an String value to the stream
	 * @param s String value to write.
	 * @return int - integer value shows success.
	 * @throws IOException If IO operation fails.
	 */
	int writeString(String s) throws IOException;

	/**
	 * Writes array of charactors to the stream
	 * @param arrChar Array of charactors value to write.
	 * @return int - integer value shows success.
	 * @throws IOException If IO operation fails.
	 */
	int writeChars(byte[] arrChar) throws IOException;

	/**
	 * Writes a word to the stream
	 * @param byteVal Array of Byte value to write.
	 * @return int - integer value shows success.
	 * @throws IOException If IO operation fails.
	 */
	int writeWord(byte[] byteVal) throws IOException;

	/**
	 * Reads a long from stream.
	 * In Java, long is of 8 bytes, but in Dicom Standard long data type length is expected as 4 bytes. So here it reads only 4 bytes from stream.
	 * @return long - Next read long value.
	 * @throws IOException If IO operation fails.
	 */
	long readLong() throws IOException;

	/**
	 * Reads an integer from the stream
	 * @return int - Next read integer value.
	 * @throws IOException If IO operation fails.
	 */
	int readInt() throws IOException;

	/**
	 * Reads a float from the stream
	 * @return float - Next read float value.
	 * @throws IOException If IO operation fails.
	 */
	float readFloat() throws IOException;

	/**
	 * Reads a double from the stream
	 * @return double - Next read double value.
	 * @throws IOException If IO operation fails.
	 */
	double readDouble() throws IOException;

	/**
	 * Reads a single byte from the stream
	 * @return byte - Next read byte value.
	 * @throws IOException If IO operation fails.
	 */
	byte readByte() throws IOException;

	/**
	 * Reads a short from the stream
	 * @return short - Next read short value.
	 * @throws IOException If IO operation fails.
	 */
	short readShort() throws IOException;

	/**
	 * Reads a string from the stream with specified length
	 * @param intVar Integer value shows length of string to read.
	 * @return String - Read string value of specified length.
	 * @throws IOException If IO operation fails.
	 */
	String readString(int intVar) throws IOException;

	/**
	 * Reads specified number of characters from the stream
	 * @param iLength integer value shows no. of characters to read.
	 * @return byte[] - Byte array of next read characters.
	 * @throws IOException If IO operation fails.
	 */
	byte[] readChars(int iLength) throws IOException;

	/**
	 * Reads reads buffer byte per byte from stream
	 * @param arrbyte Byte array populated by stream.
	 * @return int -Returns the integer number of bytes actually read from input stream .
	 * If no byte is available because the stream is at end of file, the value -1 is returned.
	 * @throws IOException If IO operation fails.
	 */
	int readBuffer(byte[] arrbyte) throws IOException;

	/**
	 * Reads a word from stream
	 * @return byte[] - Returns the byte array which contains the word read from stream.
	 * @throws IOException If IO operation fails.
	 */
	byte[] readWord() throws IOException;

	/**
	 * Shows the beginning of receiving process.
	 * @return boolean - shows status. 
	 */
	boolean startReceive();

	/**
	 * Shows the end of sending process.
	 * @return boolean - shows status as success or failure.
	 * @throws IOException Exception if IO operation fails.
	 */
	boolean endSend() throws IOException;

	/**
	 * Sets the endianess of the steam [BIG_ENDIAN/LITTLE_ENDIAN]
	 * Endianness  defines the byte ordering used to store values as bytes in computer memory.
	 * @param iEndianNess Integer value shows endianNess.
	 * @return int - Integer value shows success.
	 */
	int setEndianNess(int iEndianNess);

	/**
	 * Retrieves the endianNess of the stream.
	 * Endianness  defines the byte ordering used to store values as bytes in computer memory.
	 * @return int - Integer value shows the endianNess.
	 */
	int getEndianNess();

	/**
	 * Keeps track of how much bytes are read from the stream
	 * @return int - Integer value of number of bytes read.
	 */
	int getReadBytes();

	/**
	 * Skips the specified number of bytes.
	 * @param iNumBytes Integer value shows no. of bytes to skip.
	 * @return int - Integer value shows success.
	 * @throws IOException Exception if IO operation fails.
	 */
	int skip(int iNumBytes) throws IOException;

	/**
	 * Marks the stream for further resetting with specified limit.
	 * @param iReadAheadLimit integer number of bytes to mark.
	 * @return int - Integer value shows success.
	 */
	int mark(int iReadAheadLimit);

	/**
	 * Resets the stream to a specific marked position.
	 * @return int - Integer value shows success.
	 * @throws IOException Exception if IO operation fails.
	 */
	int reset() throws IOException;

	/**
	 * Returns the number of bytes available on the stream
	 * @return int - Integer value of available bytes.
	 * @throws IOException Exception if IO operation fails.
	 */
	int available()  throws IOException;

	/**
	 * Closes the stream.
	 * @return int - integer value shows success.
	 * @throws IOException  Exception if IO operation fails.
	 */
	int close() throws IOException;	
}
