/*
* Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).
* All rights reserved.
* This component and the accompanying materials are made available
* under the terms of the License "Eclipse Public License v1.0"
* which accompanies this distribution, and is available
* at the URL "http://www.eclipse.org/legal/epl-v10.html".
*
* Initial Contributors:
* Nokia Corporation - initial contribution.
*
* Contributors:
*
* Description: 
*
*/
package com.nokia.tcf.api;

import org.eclipse.core.runtime.IPath;
import org.eclipse.core.runtime.IStatus;

/**
 * 
 * This interface specifies the message handling options for this client.
 * Use the TCFClassFactory to instantiate a copy of the implementation class.
 */
public interface ITCMessageOptions {

	/**
	 * Message destination options
	 */
	public final long DESTINATION_INPUTSTREAM = 0;
	public final long DESTINATION_CLIENTFILE = 1;
	public final long DEFAULT_DESTINATION = DESTINATION_INPUTSTREAM;
	
	/**
	 * Default Input Stream buffer size
	 */
//	public final long DEFAULT_BUFFER_SIZE = (128*1024);	
	public final long DEFAULT_BUFFER_SIZE = (20*1024*1024); // changed to 20M for 2.0

	/**
	 * Incoming message unwrap options
	 */
	public final long UNWRAP_LEAVE_HEADERS = 0;
	public final long UNWRAP_DELETE_HEADERS = 1;
	public final long DEFAULT_UNWRAP_OPTION = UNWRAP_LEAVE_HEADERS;

	/**
	 * Outgoing message encoding
	 * This option only requests the TCF to encode this client's messages or use them as-is.
	 * The protocol format used is specified by ITCConnection.
	 */
	public final long ENCODE_NO_FORMAT = 0;
	public final long ENCODE_FORMAT = 1;
	public final long ENCODE_TRK_FORMAT = 2;
	public final long DEFAULT_ENCODE_FORMAT = ENCODE_NO_FORMAT;
	/**
	 * Default OST Version to use on outgoing messages if encoding format is on and 
	 * protocol specified in ITCConnection is OST.
	 */
	public final byte DEFAULT_OST_VERSION = 0x01;

	/**
	 * Returns setting of message destination (file or input stream).
	 * @see ITCMessageOptions#setMessageDestination(long)
	 * 
	 * @return
	 */
	public long getMessageDestination();
	
	/**
	 * If destination option is file, then this returns the path to the message file selected.
	 * @see ITCMessageOptions#setMessageFile(String)
	 * @return file - the current full path to the client's file
	 */
	public IPath getMessageFile();
		
	/**
	 * Return Input Stream buffer size.
	 * @see ITCMessageOptions#setInputStreamSize(long)
	 * @return outBufferSize - the current size of the buffer
	 */
	public long getInputStreamSize();
	
	/**
	 * Returns which message format to encode on outgoing messages:
	 * @see ITCMessageOptions#setMessageEncodeFormat(long)
	 * <p>
	 * Note: The protocol format is specified as part of the 
	 * {@link com.nokia.tcf.ITCConnection} interface.
	 * 
	 * @return
	 */
	public long getMessageEncodeFormat();
	/**
	 * Return OST Version to use on outgoing messages.
	 * @see ITCMessageOptions#setOSTVersion(byte)
	 * @return outOSTVersion - the OST version selected
	 */
	public byte getOSTVersion();
	
	/**
	 * Returns incoming message formatting
	 * @see ITCMessageOptions#setUnWrapFormat(long) 
	 * @return
	 */
	public long getUnWrapFormat();

	/**
	 * Specify the destination of messages (file or input stream)
	 * <li>{@link ITCMessageOptions#DESTINATION_INPUTSTREAM}: messages are written to input stream (client must then poll this stream) (default).
	 * <li>{@link ITCMessageOptions#DESTINATION_CLIENTFILE}: messages are written directly to a client specified file.
	 * <p>
	 * If destination is file, use {@link ITCMessageOptions#setMessageFile(String)} to specify the file.
	 * Currently this is work-in-progress. Only Input Stream is allowed at this time.
	 * 
	 * @param inDestination 
	 * @return
	 */
	public IStatus setMessageDestination(long inDestination);

	/**
	 * If message destination is file, then this specifies the path to the message file.
	 * Refer to {@link ITCMessageOptions#setMessageDestination(long)} for more explanation.
	 * 
	 * @param inFile - full path to the client's file to write
	 * @return
	 */
	public IStatus setMessageFile(IPath inFile);
	
	/**
	 * Specify the maximum size of the Input Stream buffer.
	 * Default is currently 20MB
	 * 
	 * @param inBufferSize
	 */
	public IStatus setInputStreamSize(long inBufferSize);
	/**
	 * Specify which message format to encode on outgoing messages:
	 * {@link ITCMessageOptions#ENCODE_NO_FORMAT}: do not encode outgoing messages (client must format the protocol) (default).
	 * {@link ITCMessageOptions#ENCODE_FORMAT}: format the message for protocol.
	 * {@link ITCMessageOptions#ENCODE_TRK_FORMAT}: outgoing messages for TRK need special processing with certain protocols.
	 * 
	 * Note: The protocol type is specified in the ITCConnection interface.
	 * 
	 * @param inMessageEncodeFormat
	 */
	public IStatus setMessageEncodeFormat(long inMessageEncodeFormat);
	
	/**
	 * Specify which OST version to encode in outgoing messages.
	 * If encoding option is different, this is ignored.
	 * Default is 0x01.
	 * 
	 * @param inOSTVersion
	 */
	public IStatus setOSTVersion(byte inOSTVersion);
	/**
	 * Specify whether to delete headers from incoming messages
	 * <li>{@link ITCMessageOptions#UNRAP_LEAVE_HEADERS}: protocol headers are left as-is (default).
	 * <li>{@link ITCMessageOptions#UNWRAP_DELETE_HEADERS}: protocol headers are deleted before passing to client.
	 * 
	 * @param inUnWrapFormat
	 */
	public IStatus setUnWrapFormat(long inUnWrapFormat);
	
}