/*

* 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.IStatus;

/**

 * This is the main API class and must be instantiated by the client. 

 * The implementation can be created by using the TCFClassFactory.

 */

public interface ITCAPIConnection {

	/** 

	 * Adds an error listener - multiple error listeners can be used

	 * by one client

	 *  

	 * @param inErrorListener

	 * @return

	 */

	public IStatus addErrorListener(ITCErrorListener inErrorListener);

	/**

	 * Remove an error listener from the list for this client

	 * 

	 * @param inErrorListener

	 * @return

	 */

	public IStatus removeErrorListener(ITCErrorListener inErrorListener);

	/**

	 * Connect using a specified connection type and settings. If this

	 * connection is already open, the inConnection settings is ignored.

	 * 

	 * @param inConnection

	 * @param inMessageOptions

	 * @param inMessageIds

	 * @return IStatus

	 */

	public IStatus connect(ITCConnection inConnection, ITCMessageOptions inMessageOptions, ITCMessageIds inMessageIds);

	/**

	 * Connect using an already open connection. If no connections or multiple

	 * connections are open, then this returns an error.

	 * 

	 * Use getConnections to get a list of open connections.

	 * 

	 * @param inMessageOptions

	 * @param inMessageIds

	 * @return IStatus

	 */

	public IStatus connect(ITCMessageOptions inMessageOptions, ITCMessageIds inMessageIds);

	/**

	 * Disconnect from the target. If this client is not connected this is

	 * ignored.

	 * 

	 * @return IStatus

	 */

	public IStatus disconnect();

	/**

	 * Get all the open connection settings. This will work whether or not

	 * this client is connected. If no connections exist null is returned.

	 * 

	 * @return ITCConnecion[]

	 */

	public ITCConnection[] getConnections();

	/**

	 * Get a reference to the input stream for this client. This can only be

	 * done if a successful {@link #connect} has been done.

	 * 

	 * This is an alternate form of storage for messages to that of the message file.

	 * 

	 * If a connection does not exist, null is returned.

	 * 

	 * @return ITCMessageInputStream

	 */

	public ITCMessageInputStream getInputStream();

	/**

	 * Get the versions of connection components for an open connection.

	 * 

	 * If a connection does not exist, null is returned.

	 * 

	 * If a connection exists, at least 2 versions will be returned:

	 * [0] = version of TCFClient.dll

	 * [1] = version of TCFServer.exe

	 * If the connection version can be obtained, [2] will contain that version.

	 * 

	 * @return ITCVersion[]

	 */

	public ITCVersion[] getVersions();

	/**

	 * Send a message to the target.

	 * 

	 * If a connection does not exist, an error is returned.

	 * 

	 * @param inMessage

	 * @return IStatus

	 */

	public IStatus sendMessage(ITCMessage inMessage);

	/**

	 * Resets the message Ids to process for this client. Processing must

	 * be stopped to change this. If this client is not connected, an error

	 * is returned.

	 * 

	 * @param inMessageIds

	 */

	public IStatus setTCMessageIds(ITCMessageIds inMessageIds);

	/**

	 * Start (or restart) processing messages. A successful {@link #connect} does an automatic

	 * start, so a separate call to this is unnecessary, unless a {@link #stop} has

	 * been done.

	 * 

	 * If processing is already started, this will be ignored. 

	 * If a connection does not exist, an error is returned.

	 * 

	 * @return IStatus

	 */

	public IStatus start();

	/**

	 * Stop processing messages without disconnecting. Use {@link #start} to restart.

	 * 

	 * If processing is already stopped, this is ignored.

	 * If a connection does not exist, an error is returned.

	 * 

	 * @return IStatus

	 */

	public IStatus stop();

	/**

	 * Test this client's connection.

	 * 

	 * If a connection does not exist, an error is returned.

	 * 

	 * @return IStatus

	 */

	public IStatus testConnection();

	/**

	 * Test the specified connection. It this matches a currently open connection, it

	 * returns the status of that connection and leaves that connection open. If this

	 * connection is not yet open, it opens this new connection, returns the status, and

	 * closes the connection.

	 * 

	 * @param inConnection

	 * @return

	 */

	public IStatus testConnection(ITCConnection inConnection);

	/**

	 * Clears the current client's message output file. If no file is in use (closed or never opened)

	 * this method does nothing.

	 * 

	 * Otherwise, it tells the TCF to stop processing for this client, closes and re-opens the message file.

	 * 

	 * @return IStatus - if I/O Exception occurs

	 */

	public IStatus clearMessageFile();

}