/*

* Copyright (c) 2009-2010 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.

*

*/

package com.nokia.carbide.cpp.sdk.core;

import java.util.Set;

import org.eclipse.core.runtime.IPath;

import org.osgi.framework.Version;

/**

 * This interface provides details on a single Symbian OS SDK.

 * 

 * Notes on return values for unknown/undefined items:

 *  - String value are empty ""

 *  - IPath and IFile objects are null

 *  - containers have zero size

 *  

 *  @noimplement This interface is not intended to be implemented by clients.

 */

public interface ISymbianSDK {

	/**

	 * Value given for an SDK that is created when a build configuration

	 * references an non-existent SDK.

	 * @since 3.0

	 */

	public static String BAD_EPOCROOT = "/BAD_SDK_ROOT";

	/**

	 * Returns build info for a particular builder.

	 * @param builderId id string of a builder (ISymbianBuilderID constant)

	 * @return ISDKBuildInfo - may be null if the builderId is deprecated.

	 * @since 3.0

	 * @see {@link ISymbianBuilderID}

	 */

	ISDKBuildInfo getBuildInfo(String builderId);

	/**

	 * Returns the absolute path to the epoc32 directory of this SDK. This method is guaranteed to

	 * return the path with a trailing File.separator.

	 *

	 * @return the absolute path to the epoc32 directory.

	 */

	String getEPOCROOT();

	/**

	 * Returns an IPath for the epoc32\include directory of a SDK.

	 * @return an IPath for the epoc32\include directory, or <code>null</code>.

	 */

	IPath getIncludePath();

	/**

	 * Returns the OS version string of this SDK.

	 *

	 * @return the OS Version object. If the version cannot be determined it will be "9.5".

	 * @deprecated - use ISymbianSDK{@link #getSupportedFeatures()} to figure out the properties of an SDK

	 */

	Version getOSVersion();

//	/**

//	 * Returns the prefix file for a particular builder.

//	 * @param builderId id string of a builder

//	 * @return the File object for the prefix file, or

//	 * <code>null</code> if there isn't one for the SDK.

//	 */

//	File getPrefixFile(String builderId);

	/**

	 * Returns an IPath for the epoc32\release directory of a SDK.

	 * @return an IPath for the epoc32\release directory, or <code>null</code>.

	 */

	IPath getReleaseRoot();

	/**

	 * Returns a set of features supported by the SDK. 

	 * Feature IDs are defined in ISymbianSDKFeatures.

	 * @return set of features

	 * @since 3.0

	 */

	@SuppressWarnings("rawtypes")

	Set getSupportedFeatures();

	/**

	 * Returns an IPath for the epoc32\tools directory of a SDK.

	 * @return an IPath for the epoc32\tools directory, or <code>null</code>.

	 */

	IPath getToolsPath();

	/**

	 * Returns the unique id of this SDK. This is the devices.xml 'id' attribute.

	 *

	 * @return the id string of this SDK.

	 */

	String getUniqueId();

	/**

	 * Returns true if the SDK is enabled, false otherwise.

	 *

	 * @return <code>true</code> if the SDK is enabled, and

	 *   <code>false</code> otherwise

	 */

	boolean isEnabled();

	/**

	 * Scans/Rescans the SDK for info such as prefix file, variant macros, manifest.xml, etc.

	 */

	void scanSDK();

}