/*

 * Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies). 

 * All rights reserved.

 * This component and the accompanying materials are made available

 * under the terms of "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:

 *

 * Access point to TraceViewer API functions

 *

 */

package com.nokia.traceviewer.api;

import java.util.ArrayList;

import com.nokia.traceviewer.engine.TraceInformation;

import com.nokia.traceviewer.engine.TraceMetaData;

import com.nokia.traceviewer.engine.TraceViewerGlobals;

import com.nokia.traceviewer.engine.activation.TraceActivationComponentItem;

import com.nokia.traceviewer.engine.dataprocessor.DataProcessor;

/**

 * Access point to TraceViewer API functions

 */

public final class TraceViewerAPI {

	/**

	 * Enum indicating the error codes of TraceViewer API operations

	 */

	public enum TVAPIError {

		/**

		 * No error, operation succeeded.

		 */

		NONE,

		/**

		 * Not connected error. Is given when trying to operate with the

		 * connection when it is not open.

		 */

		NOT_CONNECTED,

		/**

		 * Disconnecting failed error.

		 */

		DISCONNECTING_FAILED,

		/**

		 * Invalid connection parameters error. Parameters are not what they

		 * should be for this connection method.

		 */

		INVALID_CONNECTION_PARAMETERS,

		/**

		 * Already connected error. Connection is already open.

		 */

		ALREADY_CONNECTED,

		/**

		 * Cannot open the connection port

		 */

		CANNOT_OPEN,

		/**

		 * Connection port already open

		 */

		ALREADY_OPEN,

		/**

		 * Invalid connection handle

		 */

		INVALID_CONNECTION_HANDLE,

		/**

		 * Timeout when connecting

		 */

		TIMEOUT,

		/**

		 * Tracefile is already open

		 */

		TRACEFILE_ALREADY_OPEN,

		/**

		 * Tracefile doesn't exist

		 */

		TRACEFILE_DOESNT_EXIST,

		/**

		 * No tracefile open where to write

		 */

		NO_TRACEFILE_OPEN,

		/**

		 * Cannot write to the tracefile

		 */

		CANNOT_WRITE_TO_TRACEFILE,

		/**

		 * Media seems not to be open

		 */

		MEDIA_NOT_OPEN,

		/**

		 * Invalid connection settings

		 */

		INVALID_CONNECTION_SETTINGS,

		/**

		 * Cannot find trace router application

		 */

		CANNOT_FIND_TRACEROUTER,

		/**

		 * Cannot create trace router process

		 */

		CANNOT_CREATE_TRACEROUTER,

		/**

		 * Media busy

		 */

		MEDIA_BUSY,

		/**

		 * User canceled connection

		 */

		USER_CANCELED,

		/**

		 * Unknown error

		 */

		UNKNOWN_ERROR,

		/**

		 * DataProcessor already added error. DataProcessor is already in the

		 * DataProcessor list.

		 */

		DATAPROCESSOR_ALREADY_ADDED,

		/**

		 * DataProcessor could not be found error. DataProcessor was not in the

		 * DataProcessor list.

		 */

		DATAPROCESSOR_NOT_FOUND,

		/**

		 * Decode Provider plugin is missing

		 */

		DECODE_PROVIDER_PLUGIN_MISSING,

		/**

		 * No Decode files loaded error.

		 */

		DECODE_FILE_NOT_LOADED,

		/**

		 * Some groups couldn't be found from the decode model. They are

		 * propably missing from the loaded decode files.

		 */

		SOME_GROUPS_NOT_FOUND_FROM_DECODE_MODEL,

		/**

		 * File doesn't exist

		 */

		FILE_DOES_NOT_EXIST,

		/**

		 * TraceViewer view not open

		 */

		TRACE_VIEW_NOT_OPEN;

	}

	/**

	 * TCP / IP connection method value

	 */

	public static final int TVAPI_CONNECTION_TCP = 1;

	/**

	 * USB Serial connection method value

	 */

	public static final int TVAPI_CONNECTION_USB_SERIAL = 2;

	/**

	 * DataProcessor adder object

	 */

	private static DataProcessorAdder dpAdder;

	/**

	 * Data sender object

	 */

	private static DataSender dataSender;

	/**

	 * Connection handler object

	 */

	private static ConnectionHandler connectionHandler;

	/**

	 * Decode handler object

	 */

	private static DecodeHandler decodeHandler;

	/**

	 * View handler object

	 */

	private static ViewHandler viewHandler;

	/**

	 * Log handler object

	 */

	private static LogHandler logHandler;

	/**

	 * Activates traces using group ID's

	 * 

	 * @param componentId

	 *            component ID

	 * @param groupIds

	 *            array of group IDs

	 * @param activate

	 *            if true, activate. If false, deactivate.

	 * @return error code from TraceViewerAPI

	 */

	public static TVAPIError activateTraces(int componentId, int[] groupIds,

			boolean activate) {

		// Create the sender if it doesn't exist

		if (dataSender == null) {

			dataSender = new DataSender();

		}

		// Send the data and check error status

		TVAPIError errorCode = dataSender.activateTraces(componentId, groupIds,

				activate);

		return errorCode;

	}

	/**

	 * Activates traces using group names

	 * 

	 * @param componentId

	 *            component ID

	 * @param groupNames

	 *            array of group names

	 * @param activate

	 *            if true, activate. If false, deactivate.

	 * @return error code from TraceViewerAPI

	 */

	public static TVAPIError activateTraces(int componentId,

			String[] groupNames, boolean activate) {

		// Create the sender if it doesn't exist

		if (dataSender == null) {

			dataSender = new DataSender();

		}

		// Send the data and check error status

		TVAPIError errorCode = dataSender.activateTraces(componentId,

				groupNames, activate);

		return errorCode;

	}

	/**

	 * Adds own DataProcessor to a specific location in dataprocessor list.

	 * DataProcessors registered through this method will receive all traces

	 * that are coming from the device.

	 * 

	 * @param dataProcessor

	 *            the dataprocessor to be added

	 * @param location

	 *            location in the list

	 * @param priority

	 *            priority of the dataprocessor. If two dataprocessors are in

	 *            the same location in the dataprocessor list, the one with

	 *            higher priority will be run first

	 * @return error code from TraceViewerAPI

	 */

	public static TVAPIError addDataProcessor(DataProcessor dataProcessor,

			DPLocation location, int priority) {

		// Create the adder if it doesn't exist

		if (dpAdder == null) {

			dpAdder = new DataProcessorAdder();

		}

		// Add the processor and check error status

		TVAPIError errorCode = dpAdder.addDataProcessor(dataProcessor,

				location, priority);

		return errorCode;

	}

	/**

	 * Connect using current settings defined in TraceViewer's preferences

	 * 

	 * @return error code from TraceViewerAPI

	 */

	public static TVAPIError connect() {

		// Create the connection handler if it doesn't exist

		if (connectionHandler == null) {

			connectionHandler = new ConnectionHandler();

		}

		// Try to connect

		TVAPIError errorCode = connectionHandler.connect();

		return errorCode;

	}

	/**

	 * Connect using given parameters. Possible connection methods can be found

	 * from TraceViewerAPI constants. Parameters should be given in this order:

	 * When using TCP connection, parameters are IP address port number and

	 * channel number in this order. When using USB serial connection, the only

	 * parameter is the COM port number. This function will also set given

	 * parameters to TraceViewer's connection preferences if the connecting

	 * succeeds.

	 * 

	 * @param connectionMethod

	 *            the connection method to use

	 * @param parameters

	 *            array of parameters

	 * @return error code from TraceViewerAPI

	 */

	public static TVAPIError connect(int connectionMethod, String[] parameters) {

		// Create the connection handler if it doesn't exist

		if (connectionHandler == null) {

			connectionHandler = new ConnectionHandler();

		}

		// Try to connect

		TVAPIError errorCode = connectionHandler.connect(connectionMethod,

				parameters);

		return errorCode;

	}

	/**

	 * Disconnects from the target

	 * 

	 * @return error code from TraceViewerAPI

	 */

	public static TVAPIError disconnect() {

		// Create the connection handler if it doesn't exist

		if (connectionHandler == null) {

			connectionHandler = new ConnectionHandler();

		}

		// Try to disconnect

		TVAPIError errorCode = connectionHandler.disconnect();

		return errorCode;

	}

	/**

	 * Gets components from all loaded Dictionaries

	 * 

	 * @return list of components from all loaded Dictionaries. List can be

	 *         empty.

	 */

	public static ArrayList<TraceActivationComponentItem> getDictionaryComponents() {

		// Create the decode handler if it doesn't exist

		if (decodeHandler == null) {

			decodeHandler = new DecodeHandler();

		}

		// Get the component list

		ArrayList<TraceActivationComponentItem> components = decodeHandler

				.getDictionaryComponents();

		return components;

	}

	/**

	 * Gets trace component name from the Decode model with a component ID

	 * 

	 * @param componentId

	 *            component ID

	 * @return component name or null if not found or no Decode files are loaded

	 */

	public static String getTraceComponentName(int componentId) {

		// Create the decode handler if it doesn't exist

		if (decodeHandler == null) {

			decodeHandler = new DecodeHandler();

		}

		// Get the component name

		String componentName = decodeHandler.getTraceComponentName(componentId);

		return componentName;

	}

	/**

	 * Gets trace group ID from the Decode model with a group name

	 * 

	 * @param componentId

	 *            component ID

	 * @param groupName

	 *            the group name

	 * @return trace group ID or -1 if group ID not found or -2 if no Decode

	 *         files are loaded

	 */

	public static int getTraceGroupId(int componentId, String groupName) {

		// Create the decode handler if it doesn't exist

		if (decodeHandler == null) {

			decodeHandler = new DecodeHandler();

		}

		// Get the group ID

		int groupId = decodeHandler.getTraceGroupId(componentId, groupName);

		return groupId;

	}

	/**

	 * Gets trace group name from the Decode model with a component and group

	 * IDs

	 * 

	 * @param componentId

	 *            component ID

	 * @param groupId

	 *            group ID

	 * @return group name or null if not found or no Decode files are loaded

	 */

	public static String getTraceGroupName(int componentId, int groupId) {

		// Create the decode handler if it doesn't exist

		if (decodeHandler == null) {

			decodeHandler = new DecodeHandler();

		}

		// Get the group name

		String groupName = decodeHandler

				.getTraceGroupName(componentId, groupId);

		return groupName;

	}

	/**

	 * Gets trace name from the Decode model with a component, group and trace

	 * IDs

	 * 

	 * @param componentId

	 *            component ID

	 * @param groupId

	 *            group ID

	 * @param traceId

	 *            trace ID

	 * @return trace name or null if not found or no Decode files are loaded

	 */

	public static String getTraceName(int componentId, int groupId, int traceId) {

		// Create the decode handler if it doesn't exist

		if (decodeHandler == null) {

			decodeHandler = new DecodeHandler();

		}

		// Get the trace name

		String traceName = decodeHandler.getTraceName(componentId, groupId,

				traceId);

		return traceName;

	}

	/**

	 * Gets trace metadata

	 * 

	 * @param information

	 *            TraceInformation to be used when finding correct metadata

	 * @return trace metadata or null if nothing is found

	 */

	public static TraceMetaData getTraceMetaData(TraceInformation information) {

		TraceMetaData metaData = null;

		if (information != null && information.isDefined()

				&& TraceViewerGlobals.getDecodeProvider() != null) {

			metaData = TraceViewerGlobals.getDecodeProvider().getTraceMetaData(

					information);

		}

		return metaData;

	}

	/**

	 * Loads decode file to the decode model. User must remember that loading

	 * the decode file can take some time and this function will block until the

	 * model is loaded or a maximum of 5 seconds.

	 * 

	 * @param decodeFilePath

	 *            absolute path to the decode file. Path must be in correct

	 *            format for any operating system (Windows, Linux)

	 * @param deleteExistingModel

	 *            if true, old decode model is removed before this decode file

	 *            is loaded

	 * @return error code from TraceViewerAPI

	 */

	public static TVAPIError loadDecodeFile(String decodeFilePath,

			boolean deleteExistingModel) {

		// Create the decode handler if it doesn't exist

		if (decodeHandler == null) {

			decodeHandler = new DecodeHandler();

		}

		// Load the decode file

		TVAPIError errorCode = decodeHandler.loadDecodeFile(decodeFilePath,

				deleteExistingModel);

		return errorCode;

	}

	/**

	 * Opens log file to TraceViewer. If filePath is null and TraceViewer view