Keeping PlatSim internal only.
/*
* 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();
}