package org.etsi.its.network;

import java.io.IOException;
import java.net.SocketException;
import java.net.UnknownHostException;

/**
 * This interface provides mandatory methods to implement an UDP client/server
 */
public interface IUdpImpl {

	/**
	 * Initialises the new instance
	 * 
	 * @param address The IPv4 address
	 * @param remotePort The remote port to send datas packets
	 * @param localPort The listener port to receive datas packets
	 * @throws UnknownHostException Thrown to indicate that the IP address of a host could not be determined
	 * @throws SocketException Thrown to indicate that there is an error in the underlying protocol, such as a TCP error
	 */
	public void initialize(final String address, final int remotePort, final int localPort) throws UnknownHostException, SocketException;

	/**
	 * Initialise the new instance
	 * 
	 * @param address The IPv4 address
	 * @param remotePort The remote port to send datas packets
	 * @param localPort The listener port to receive datas packets
	 * @param asyncReceive A reference to an object implementing the callback <code>onReceive</code>, used for asynchronous receive operations
	 * @throws UnknownHostException Thrown to indicate that the IP address of a host could not be determined
	 * @throws SocketException Thrown to indicate that there is an error in the underlying protocol, such as a TCP error
	 * 
	 * @see IUdpImplEvent
	 */
	public void initialize(final String address, final int remotePort, final int localPort, final IUdpImplEvent asyncReceive) throws UnknownHostException, SocketException;

	/**
	 * Un-initialises the current instance
	 */
	public void uninitialize();

	/**
	 * Sends datas
	 * @param buffer The datas packet to be sent
	 * @throws IOException Signals that an I/O exception of some sort has occurred
	 * @throws RuntimeException Signals that method is called in asynchronous mode, it shall not
	 */
	public void send(final byte[] buffer) throws IOException;

	/**
	 * Receives datas in synchronous mode
	 * 
	 * note that this method cannot be called if asynchronous receive mode is used
	 * @return The datas packet on success, null otherwise
	 * @throws IOException Signals that an I/O exception of some sort has occurred
	 */
	public byte[] receive() throws IOException;

} // End of interface IUdpImpl
