/*
 * Copyright (c) 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:
 *
 */
package com.nokia.carbide.cpp.pi.export;

import java.util.List;

import org.eclipse.core.runtime.CoreException;
import org.eclipse.core.runtime.IPath;
import org.eclipse.core.runtime.IProgressMonitor;
import com.nokia.carbide.cpp.internal.pi.plugin.model.ITrace;

/**
 * Interface for binding external trace data providers for Performance
 * Investigator. Only a single trace data provider instance at a time is
 * supported. In case more that a single trace data providers are available the
 * selection among them is undeterministic.
 */
public interface ITraceProvider {

	public final static String DAT_FILE = "dat"; //$NON-NLS-1$
	public final static String BASE_FILE = "base64"; //$NON-NLS-1$
	public final static String BASE_CORRUPTED_FILE = "corrupted_base64"; //$NON-NLS-1$


	/**
	 * Get available list of the plug-ins from the device
	 * 
	 * @param traceClient instance of the ITraceClientNotificationsIf
	 * @param monitor
	 *            instance of the {@link IProgressMonitor}
	 * @return list of the available plug-ins
	 * @throws CoreException
	 */
	public List<ITrace> getAvailableSamplers(ITraceClientNotificationsIf traceClient, IProgressMonitor monitor)
			throws CoreException;


	/**
	 * Gets preference page ID for the user trace source.
	 * 
	 * @return preference page ID for the user trace source
	 */
	public String getTraceSourcePreferencePageId();

	/**
	 * Gets current connections display name.
	 * 
	 * @return current connections display name
	 */
	public String getDisplayNameForCurrentConnection(IProgressMonitor monitor)
			throws CoreException;
	
	/**
	 * Start to trace data from device
	 * 
	 * @param filePrefix profiler data file's prefix
	 * @param traceIds plug-in IDs to trace
	 * @param traceClient instance of the ITraceClientNotificationsIf
	 * @param monitor instance of the {@link IProgressMonitor}
	 * @throws CoreException
	 */
	public void startTrace(String filePrefix, int[] traceIds,
			ITraceClientNotificationsIf traceClient, IProgressMonitor monitor)
			throws CoreException;

	/**
	 * Stop the trace
	 * 
	 * @param forceStop do force stop
	 * @return location where the trace data file is located
	 * @throws CoreException
	 */
	public IPath stopTrace(boolean forceStop) throws CoreException;


	/**
	 * Check is listener activated
	 * 
	 * @return the listener activation status
	 */
	public boolean isListening();
}