/*******************************************************************************
 * Copyright (c) 2010 Nokia and others.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 *
 * Contributors:
 * Nokia - Initial API and implementation
 *******************************************************************************/
package org.eclipse.cdt.debug.edc.symbols;

import java.nio.ByteOrder;
import java.util.Collection;

import org.eclipse.cdt.core.IAddress;
import org.eclipse.cdt.debug.edc.internal.symbols.ISection;
import org.eclipse.core.runtime.IPath;

/**
 * Interface for handling different kinds of executables.  This manages
 * the mid-level access to different executable formats (ELF, PE-COFF, etc.). 
 */
public interface IExecutableSymbolicsReader {
	/**
	 * Dispose the reader and any files or memory it is holding
	 */
	void dispose();
	
	/**
	 * Get the file represented by this reader
	 */
	IPath getSymbolFile();
	
	/**
	 * Get the executable sections from the symbol file (names and buffers)
	 * @return unmodifiable list of sections
	 */
	Collection<IExecutableSection> getExecutableSections();

	/**
	 * Get a section with the given name
	 * @param sectionName
	 * @return {@link IExecutableSection} or <code>null</code>
	 */
	IExecutableSection findExecutableSection(String sectionName);
	
	/**
	 * Get the (low level) sections from the symbol file
	 * 
	 * @return unmodifiable list of sections
	 */
	Collection<ISection> getSections();

	/**
	 * Get the base image address generated by the linker
	 * 
	 * @return the base address, or null if unknown
	 */
	IAddress getBaseLinkAddress();

	/**
	 * Get the modification date of the symbol file when it was parsed. This is
	 * used for caching purposes.
	 * 
	 * @return the modification date (e.g. file.lastModified())
	 */
	long getModificationDate();
	
	/**
	 * Find symbol(s) with the given name.  If no exact
	 * matches are found, also search for a symbol whose
	 * undecorated variant matches the name (e.g. in Win32, "_main" -> "main",
	 * "__imp_foo@8" -> "foo"). 
	 * @param name name of the symbol
	 * @return collection of matching symbols, may be empty
	 */
	Collection<ISymbol> findSymbols(String name);

	/**
	 * Find symbol(s) with the given unmangled name.
	 * The name will be interpreted as if spaces are irrelevant.
	 * The name will be matched as if a fully qualified name (e.g.
     * leading "::" may be missing).
	 * If a symbol is a function and the name does not include
	 * arguments, any function with the same qualified name matches
     * (e.g. "foo(int)" for name="foo").
	 * @param name name of unmangled string (e.g. "Foo::Bar", "main", "::std::myfunc(int)")
	 * @return collection of matching symbols, may be empty
	 */
	Collection<ISymbol> findUnmangledSymbols(String name);

	/**
	 * Get the symbols from the symbol table
	 * 
	 * @return unmodifiable list of symbols
	 */
	Collection<ISymbol> getSymbols();


	/**
	 * Get the symbol that contains the given link address
	 * 
	 * @param linkAddress
	 *            the link address
	 * @return the symbol containing this address, or null if none found
	 * @see #getSymbolsAtAddress(IAddress) in many cases there may be more than
	 *      one such symbol and this will only return the first one
	 */
	ISymbol getSymbolAtAddress(IAddress linkAddress);

	/**
	 * Get the symbols that contains the given link address
	 * 
	 * @param linkAddress
	 *            the link address
	 * @return the symbols containing this address, or the empty collection if none found
	 * @since 3.0
	 */
	Collection<ISymbol> getSymbolsAtAddress(IAddress linkAddress);

	/**
	 * Get the byte order of data in the executable
	 * @return {@link ByteOrder}
	 */
	ByteOrder getByteOrder();
}