package com.millistream.www;

/**
 * This interface provides the call back function used in
 * <code>Mdf.consume()</code>.
 * 
 * @author Liang Qu
 * @version 0.1, 03/25/10
 * @see com.millistream.www.Mdf
 */
public interface Callback {
	/**
	 * Defines the various connection states
	 */
	public enum StatusCode {
		/**
		 * Performing DNS lookup of the host name
		 */
		LOOKUP,

		/**
		 * Trying to connect with the server
		*/
		CONNECTING,

		/**
		 * Connected with the server, establishing a secure channel
		 */
		CONNECTED,

		/**
		 * Disconnected from the server
		 */
		DISCONNECTED,

		/**
		 * The secure channel with the server is established and you can now send the logon message
		 */
		READYTOLOGON,

		/**
		 * Client sent a Heartbeat request to the server
		 */
		SND_HB_REQ,

		/**
		 * Client received a Heartbeat request from the server
		 */
		RCV_HB_REQ,

		/**
		 * Client received a Hearbeat response from the server
		 */
		RCV_HB_RES
	};

	/**
	 * This function is automatically called by the <code>consume()</code>
	 * function of <code>Mdf</code> class if the <code>setConsumeDataCallback()</code> method have been used to register a consumeData callback.
	 * 
	 * @param mdf
	 *            <code>Mdf</code> object that receives data from the mdf server
	 */
	public void consumeData(Mdf mdf);

	/**
	 * This function is automatically called by the <code>consume()</code>
	 * function of <code>Mdf</code> class when the current connection status changes and if the
	 * <code>setStatusChangeCallback()</code> method have been used to register a statusChange callback.
	 * 
	 * @param status the new connection status
	 * @param host the server host name we are connecting / trying to connect to. For <code>RCV_HB_RES</code> the string contains the nanoseconds epoch timestamp of when the API received the heartbeat.
	 * @param ip the ip address of the host if available (can be null if not translated yet). For <code>RCV_HB_RES</code> the string contains the nanoseconds epoch timestamp of when the server sent the heartbeat.
	 */
	public void statusChange(StatusCode status, String host, String ip);
}
