/**

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

*

* Contributors:

*

* Description: 

*

*/

package com.nokia.carbide.remoteconnections.internal.api;

import java.net.URL;

import org.eclipse.core.runtime.CoreException;

/**

 * An interface to a device discovery agent

 * @since 2.5

 */

public interface IDeviceDiscoveryAgent {

	/**

	 * An interface for discovery agents to implement that the manager uses

	 * before loading the agent to get errors about required components.

	 * <p>

	 * Every discovery agent must implement this interface.

	 */

	public interface IPrerequisiteStatus {

		/**

		 * Is the status OK?

		 * @return boolean 

		 */

		boolean isOK();

		/**

		 * If status is not OK, return error message text.

		 * @return String

		 */

		String getErrorText();

		/**

		 * Optionally return a URL for user to browse to for more information on error.

		 * @return URL

		 */

		URL getURL();

	}

	/**

	 * Starts agent. Once started, runs until stopped.

	 * @throws CoreException

	 */

	void start() throws CoreException;

	/**

	 * Stops agent.

	 * @throws CoreException

	 */

	void stop() throws CoreException;

	/**

	 * Returns a URL to specific information about this discovery mechanism,

	 * troubleshooting, etc.

	 * @return URL

	 */

	URL getInformation();

	/**

	 * Returns a display name for the particular discovery agent in case we need to

	 * let the user know errors from the agents.

	 * @return String

	 */

	String getDisplayName();

	/**

	 * Manager will call this to get any status of prerequisites not satisfied before

	 * the manager calls start(). The agent should check its prerequisites at this time.

	 * <p>

	 * If the agent has no prerequisites return a status of OK.

	 * @return IPrerequisiteStatus

	 */

	IPrerequisiteStatus getPrerequisiteStatus();

	/**

	 * Return whether this discovery agent is running

	 * @return boolean

	 */

	boolean isRunning();

	/**

	 * The unique id for this agent

	 * @return String

	 */

	String getId();

	// In addition, there may need to be an additional API to do a deeper form of discovery for

	// connection mechanisms that require pairing (like BT or Wifi). In these cases, normal discovery

	// will probably be for already paired devices, however, the user will want to discover all 

	// potential devices from some UI in order to set up a paired device.

	// A method for doing this will need to be added.

}