FCL/sftools/ana/dynaanaapps: comparison trace/traceviewer/com.nokia.traceviewer/src/com/nokia/traceviewer/api/TraceViewerAPI.java

equal deleted inserted replaced

-:ed1c9f64298a
+:5b9d4d8641ce
+/*
+* 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
+	 * is not open, error will be returned.
+	 *
+	 * @param filePath
+	 *            file path to open. If file path ends with .txt, file is opened
+	 *            as ASCII log. If filePath is null and TraceViewer view is
+	 *            open, a file selection dialog is opened.
+	 * @return error code from TraceViewerAPI
+	 */
+	public static TVAPIError openLogFile(String filePath) {
+		// Create the handler if it doesn't exist
+		if (logHandler == null) {
+			logHandler = new LogHandler();
+		}
+		// Save current traces to a log file
+		TVAPIError errorCode = logHandler.openLogFile(filePath);
+		return errorCode;
+	}
+	/**
+	 * Removes this DataProcessor from the list of DataProcessors.
+	 *
+	 * @param dataProcessor
+	 *            the DataProcessor to be removed
+	 * @return error code from TraceViewerAPI
+	 */
+	public static TVAPIError removeDataProcessor(DataProcessor dataProcessor) {
+		// Create the adder if it doesn't exist
+		if (dpAdder == null) {
+			dpAdder = new DataProcessorAdder();
+		}
+		// Remove the Data Processor
+		TVAPIError errorCode = dpAdder.removeDataProcessor(dataProcessor);
+		return errorCode;
+	}
+	/**
+	 * Saves current traces shown in TraceViewer view to a Binary log. If
+	 * TraceViewer view is visible, a progress bar about the saving will be
+	 * shown for the user. If TraceViewer view is not visible, saving the file
+	 * will be done with the calling thread. Note that saving the file can take
+	 * a long time!
+	 *
+	 * @param filePath
+	 *            file path where to save the log. If null and TraceViewer view
+	 *            is visible, a file selection dialog is shown
+	 * @return error code from TraceViewerAPI
+	 */
+	public static TVAPIError saveCurrentTracesToLog(String filePath) {
+		// Create the handler if it doesn't exist
+		if (logHandler == null) {
+			logHandler = new LogHandler();
+		}
+		// Save current traces to a log file
+		TVAPIError errorCode = logHandler.saveCurrentTracesToLog(filePath);
+		return errorCode;
+	}
+	/**
+	 * Sends raw data to the device with header
+	 *
+	 * @param msg
+	 *            byte array to be sent
+	 * @param changeMediaType
+	 *            If true, changes media type to the header when sending the
+	 *            message. Otherwise leaves the message as it is.
+	 * @return error code from TraceViewerAPI
+	 */
+	public static TVAPIError sendDataToDeviceWithHeader(byte[] msg,
+			boolean changeMediaType) {
+		// Create the sender if it doesn't exist
+		if (dataSender == null) {
+			dataSender = new DataSender();
+		}
+		// Send the data and check error status
+		byte b = 0x00;
+		TVAPIError errorCode = dataSender.sendRawData(msg, false, b,
+				changeMediaType);
+		return errorCode;
+	}
+	/**
+	 * Sends raw data to the device without header
+	 *
+	 * @param msg
+	 *            byte array to be sent
+	 * @param messageId
+	 *            messageID to add to the header. Might not be needed, depends
+	 *            on the protocol.
+	 * @return error code from TraceViewerAPI
+	 */
+	public static TVAPIError sendDataToDeviceWithoutHeader(byte[] msg,
+			byte messageId) {
+		// Create the sender if it doesn't exist
+		if (dataSender == null) {
+			dataSender = new DataSender();
+		}
+		// Send the data and check error status
+		TVAPIError errorCode = dataSender.sendRawData(msg, true, messageId,
+				false);
+		return errorCode;
+	}
+	/**
+	 * Stops or restarts the TraceViewer view update
+	 *
+	 * @param stop
+	 *            if true, stops the view update. If false, restarts the update.
+	 */
+	public static void stopViewUpdate(boolean stop) {
+		// Create the handler if it doesn't exist
+		if (viewHandler == null) {
+			viewHandler = new ViewHandler();
+		}
+		// Ask handler to stop / restart view update
+		viewHandler.stopViewUpdate(stop);
+	}
+	/**
+	 * Syncs to timestamp in the TraceViewer view. If both start and end
+	 * timestamps are given, the range is selected. This function assumes that
+	 * the traces in the TraceViewer view are in chronological order. Also,
+	 * endTimestamp must always be "bigger" than startTimestamp
+	 *
+	 * @param startTimestamp
+	 *            start timestamp in the format of hh:mm:ss.SSS
+	 * @param endTimestamp
+	 *            end timestamp in the format of hh:mm:ss.SSS or null if only
+	 *            start timestamp is searched for
+	 * @return error code from TraceViewerAPI
+	 */
+	public static TVAPIError syncToTimestamp(String startTimestamp,
+			String endTimestamp) {
+		// Create the handler if it doesn't exist
+		if (viewHandler == null) {
+			viewHandler = new ViewHandler();
+		}
+		// Try to sync and check error status
+		TVAPIError errorCode = viewHandler.syncToTimestamp(startTimestamp,
+				endTimestamp);
+		return errorCode;
+	}
+	/**
+	 * Syncs to trace in the TraceViewer view
+	 *
+	 * @param startTrace
+	 *            start trace number
+	 * @param endTrace
+	 *            end trace number of 0 if only start trace is searched for
+	 * @return error code from TraceViewerAPI
+	 */
+	public static TVAPIError syncToTrace(int startTrace, int endTrace) {
+		// Create the handler if it doesn't exist
+		if (viewHandler == null) {
+			viewHandler = new ViewHandler();
+		}
+		// Try to sync and check error status
+		TVAPIError errorCode = viewHandler.syncToTrace(startTrace, endTrace);
+		return errorCode;
+	}
+}