Skip to content

Ghidra is a software reverse engineering (SRE) framework

21.8 KB
Raw Blame
/* ###
 * IP: GHIDRA
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package docking.help;

import java.awt.*;
import java.io.IOException;
import java.io.InputStream;
import java.net.*;
import java.util.*;
import java.util.List;
import java.util.Map;
import java.util.Map.Entry;

import javax.help.*;
import javax.help.Map.ID;
import javax.swing.JButton;

import docking.ComponentProvider;
import docking.action.DockingActionIf;
import generic.concurrent.GThreadPool;
import generic.util.WindowUtilities;
import ghidra.util.*;
import ghidra.util.exception.AssertException;
import ghidra.util.exception.CancelledException;
import ghidra.util.task.TaskMonitor;
import help.*;
import resources.ResourceManager;
import utilities.util.reflection.ReflectionUtilities;

/**
 * Class that uses JavaHelp browser to show context sensitive help.
 *
 * <p>Note: this manager will validate all registered help when in development mode.  In order
 * to catch items that have not registered help at all, we rely on those items to register a
 * default {@link HelpLocation} that will get flagged as invalid.  Examples of this usage are
 * the {@link DockingActionIf} and the {@link ComponentProvider} base classes.
 */
public class HelpManager implements HelpService {

	/**
	 * The hardcoded value to use for all HelpSet 'home id' values.  Subclasses may change this 
	 * value by overriding {@link #getHomeId()}.
	 */
	private static final String HOME_ID = "Misc_Help_Contents";

	public static final String SHOW_AID_KEY = "SHOW.HELP.NAVIGATION.AID";
	private static final String TABLE_OF_CONTENTS_FILENAME_KEY = "data";

	private final static URL HELP_NOT_FOUND_PAGE_URL =
		ResourceManager.getResource("help/empty.htm");

	private static final String TABLE_OF_CONTENTS_VIEW_NAME = "TOC";

	private static final String GHIDRA_HELP_TITLE = "Ghidra Help";

	private GHelpSet mainHS;
	private HelpBroker mainHB;

	private HashMap<URL, HelpSet> urlToHelpSets = new HashMap<>();
	private Map<Object, HelpLocation> helpLocations = new WeakHashMap<>();
	private Map<Object, DynamicHelpLocation> dynamicHelp = new WeakHashMap<>();

	private List<HelpSet> helpSetsPendingMerge = new ArrayList<>();
	private boolean hasMergedHelpSets;

	/** If the help is not built, then this will be false */
	private boolean isValidHelp;
	private boolean hasBeenDisplayed;

	private Set<Object> excludedFromHelp = Collections.newSetFromMap(new WeakHashMap<>());

	/**
	 * Constructor.
	 *
	 * @param url url for the main HelpSet file for the application.
	 * @throws HelpSetException if HelpSet could not be created
	 */
	protected HelpManager(URL url) throws HelpSetException {
		mainHS = new DockingHelpSet(new GHelpClassLoader(null), url);
		mainHS.setHomeID(getHomeId());
		mainHB = mainHS.createHelpBroker();
		mainHS.setTitle(GHIDRA_HELP_TITLE);

		isValidHelp = isValidHelp();
	}

	protected void registerHelp() {
		mergePendingHelpSets();
		Help.installHelpService(this);
	}

	@Override
	public boolean isShowing() {
		return mainHB.isDisplayed();
	}

	@Override
	public boolean helpExists() {
		return isValidHelp && hasMergedHelpSets;
	}

	/**
	 * Add the help set for the given URL.
	 *
	 * @param url url for the HelpSet (.hs) file
	 * @param classLoader the help classloader that knows how to find help modules in the classpath
	 * @throws HelpSetException if the help set could not be created from the given URL.
	 */
	public void addHelpSet(URL url, GHelpClassLoader classLoader) throws HelpSetException {
		HelpSet hs = createHelpSet(url, classLoader);
		if (hs == null) {
			return;
		}

		if (hasMergedHelpSets) {
			mainHS.add(hs);
		}
		else {
			helpSetsPendingMerge.add(hs);
		}
	}

	/**
	 * Returns the 'home id' to be used by all help sets in the system (as opposed to allowing each
	 * help set to define its own home id.
	 * @return the home id
	 */
	protected String getHomeId() {
		return HOME_ID;
	}

	/**
	 * Returns the master help set (the one into which all other help sets are merged).
	 * @return the help set
	 */
	public GHelpSet getMasterHelpSet() {
		return mainHS;
	}

	@Override
	public void excludeFromHelp(Object helpObject) {
		excludedFromHelp.add(helpObject);
		helpLocations.remove(helpObject);
	}

	@Override
	public boolean isExcludedFromHelp(Object helpObject) {
		return excludedFromHelp.contains(helpObject);
	}

	@Override
	public void clearHelp(Object helpObject) {
		helpLocations.remove(helpObject);
	}

	@Override
	public void registerDynamicHelp(Object helpObject, DynamicHelpLocation helpLocation) {
		dynamicHelp.put(helpObject, helpLocation);
	}

	@Override
	public void registerHelp(Object helpObject, HelpLocation location) {

		if (helpObject == null) {
			Throwable t = ReflectionUtilities.createJavaFilteredThrowable();
			Msg.debug(this, "Incorrect use of registerHelp() - 'helpObject' cannot be null\n", t);
			return;
		}

		if (location == null) {
			Throwable t = ReflectionUtilities.createJavaFilteredThrowable();
			Msg.debug(this, "Deprecated use of registerHelp() - use excludeFromHelp()\n", t);
			excludeFromHelp(helpObject);
			return;
		}

		if (helpObject instanceof Window) {
			// we do not allow this, as it causes unintended behavior when searching for help
			Msg.error(this, "Cannot register help for a top-level window", new AssertException());
			return;
		}

		if (isExcluded(helpObject)) {
			return;
		}

		// Implementation Note: the same object can have different help registered.  For example,
		//                      DockingActions do this as part of their construction process.
		//                      These actions will register a default help location and then
		//                      subclasses may change that location.  We always use the most
		//                      recently registered action.
		helpLocations.put(helpObject, location);
	}

	private boolean isExcluded(Object helpee) {
		if (excludedFromHelp.contains(helpee)) {
			return true;
		}

		return false;
	}

	@Override
	public HelpLocation getHelpLocation(Object helpObj) {
		return doGetHelpLocation(helpObj);
	}

	private HelpLocation doGetHelpLocation(Object helpObj) {

		DynamicHelpLocation dynamicLocation = dynamicHelp.get(helpObj);
		if (dynamicLocation != null) {
			HelpLocation hl = dynamicLocation.getActiveHelpLocation();
			if (hl != null) {
				return hl;
			}
		}

		return helpLocations.get(helpObj);
	}

	private HelpLocation findHelpLocation(Object helpObj) {
		if (helpObj instanceof HelpDescriptor) {
			HelpDescriptor helpDescriptor = (HelpDescriptor) helpObj;
			Object descriptorHelpObj = helpDescriptor.getHelpObject();
			return doGetHelpLocation(descriptorHelpObj);
		}
		return doGetHelpLocation(helpObj);
	}

	@Override
	public void reload() {

		if (!(mainHB instanceof GHelpBroker)) {
			// not our broker installed; can't force a reload
			return;
		}

		GHelpBroker gHelpBroker = (GHelpBroker) mainHB;
		gHelpBroker.reload();
	}

	@Override
	public void showHelp(URL url) {
		if (!isValidHelp) {
			Msg.warn(this, "Help is not in a valid state.  " +
				"This can happen when help has not been built.");
			return;
		}

		Window window = getBestParent(null);
		displayHelp(url, window);
	}

	@Override
	public void showHelp(HelpLocation loc) {
		if (!isValidHelp) {
			Msg.warn(this, "Help is not in a valid state.  " +
				"This can happen when help has not been built.");
			return;
		}

		Window window = getBestParent(null);
		showHelpLocation(loc, window);
	}

	@Override
	public void showHelp(Object helpObj, boolean infoOnly, Component owner) {

		if (!isValidHelp && !infoOnly) {
			Msg.warn(this, "Help is not in a valid state.  " +
				"This can happen when help has not been built.");
			return;
		}

		Window window = getBestParent(owner);
		HelpLocation loc = findHelpLocation(helpObj);

		if (infoOnly) {
			displayHelpInfo(helpObj, loc, window);
		}
		else {
			showHelpLocation(loc, window);
		}
	}

	private void showHelpLocation(HelpLocation loc, Window window) {
		if (loc == null) {
			showDefaultHelpPage(window);
			return;
		}

		URL url = loc.getHelpURL();
		if (url != null) {
			displayHelp(url, window);
			return;
		}

		String helpId = loc.getHelpId();
		if (helpId == null) {
			showDefaultHelpPage(window);
			return;
		}

		try {
			displayHelp(createHelpID(helpId), window);
		}
		catch (BadIDException e) {
			Msg.info(this,
				"Could not find help for ID: \"" + helpId + "\" from HelpLocation: " + loc);
			displayHelp(HELP_NOT_FOUND_PAGE_URL, window);
		}
	}

	private void showDefaultHelpPage(Window w) {
		displayHelp(mainHS.getHomeID(), w);
	}

	private Window getBestParent(Component c) {

		if (c == null) {
			KeyboardFocusManager keyboardFocusManager =
				KeyboardFocusManager.getCurrentKeyboardFocusManager();
			c = keyboardFocusManager.getActiveWindow();
		}

		while (c != null && !(c instanceof Window)) {
			c = c.getParent();
		}

		Window window = (Window) c;
		Dialog modalDialog = WindowUtilities.findModalestDialog();
		if (modalDialog != null) {
			window = modalDialog;
		}
		return window;
	}

	private ID createHelpID(String helpIDString) {
		BadIDException helpException = null;

		try {
			return ID.create(helpIDString, mainHS);
		}
		catch (BadIDException bide) {
			helpException = bide; // save in case we need later
		}

		// We get here on an exception; let's try to our alternative help lookup.
		// To do this, try making a URL out of the help string and doing a reverse lookup
		URL URL = null;
		try {
			URL = URI.create(helpIDString).toURL();
		}
		catch (IllegalArgumentException | MalformedURLException e) {
			// nothing we can do, fall through the method to the previous exception
		}

		if (URL != null) {
			javax.help.Map combinedMap = mainHS.getCombinedMap();
			ID ID = combinedMap.getIDFromURL(URL);
			if (ID != null) {
				return ID;
			}
		}

		throw helpException;
	}

	private String getFilenameForHelpLocation(HelpLocation helpLocation) {
		URL helpFileURL = getURLForHelpLocation(helpLocation);
		if (helpFileURL == null) {
			return null;
		}

		String file = helpFileURL.getFile();
		int filenameStart = file.lastIndexOf('/') + 1; // filename start within full path string
		int anchorIndex = file.indexOf('#'); // help topic anchor
		int filenameEnd = (anchorIndex == -1) ? file.length() : anchorIndex;
		return file.substring(filenameStart, filenameEnd);
	}

	private URL getURLForHelpLocation(HelpLocation helpLocation) {
		String helpId = helpLocation.getHelpId();
		ID id = null;
		try {
			id = createHelpID(helpId);
		}
		catch (BadIDException e) {
			return null;
		}

		// this can happen when the HelpLocation has a null helpId value
		if (id == null) {
			return helpLocation.getHelpURL();
		}

		HelpSet hs = id.hs;
		try {
			return hs.getCombinedMap().getURLFromID(id);
		}
		catch (MalformedURLException e) {
			// we return null
		}
		return null;
	}

	private boolean hasValidHelp(Object helpee, HelpLocation location) {
		if (isKeybindingOnly(helpee)) {
			// no help for keybindings, as they do not have GUI widgets
			return true;
		}

		if (location == null) {
			return false;
		}

		return isValidHelpLocation(location);
	}

	private boolean isValidHelpLocation(HelpLocation helpLoc) {
		if (helpLoc.getHelpURL() != null) {
			return true; // URL always assumed to be good
		}

		String helpId = helpLoc.getHelpId();
		ID id = null;
		try {
			id = createHelpID(helpId);
		}
		catch (BadIDException e) {
			// just return false
		}
		if (id == null) {
			return false;
		}

		HelpSet helpSet = id.getHelpSet();
		javax.help.Map combinedMap = helpSet.getCombinedMap();
		try {
			URL url = combinedMap.getURLFromID(id);
			if (url == null) {
				// not sure when this can happen, log it for now
				Msg.debug(this, "Unable to find help for ID: " + id);
				return false;
			}

			return isURLValid(url);
		}
		catch (MalformedURLException e) {
			return false;
		}
	}

	private void displayHelp(final Object help, final Window owner) {
		if (help == null) {
			return;
		}

		boolean wasDisplayed = mainHB.isDisplayed();
		if (mainHB instanceof DefaultHelpBroker) {
			((DefaultHelpBroker) mainHB).setActivationWindow(owner);
		}

		// make sure we are visible before we set data (prevents bugs in JavaHelp)
		mainHB.setDisplayed(true);

		if (!wasDisplayed) {
			//
			// Unusual Code Alert!: The initial load of the UI will use a SwingWorker to reload
			//                      the help model.  If it finishes after we set our desired
			// 				        help value, then the TOC item is not properly selected.  Using
			//		                an invokeLater() will work as long as the model loading is
			//                      relatively quick.
			//
			Swing.runLater(() -> displayHelp(help, owner));
			return;
		}

		mergePendingHelpSets();

		URL helpURL = null;
		if (help instanceof ID) {
			helpURL = getURLForID((ID) help);
		}
		else if (help instanceof URL) {
			helpURL = (URL) help;
		}

		displayHelpUrl(help, helpURL);

		printBadHelp();

		hasBeenDisplayed = true;
	}

	private void printBadHelp() {

		if (!SystemUtilities.isInDevelopmentMode()) {
			return;
		}

		if (hasBeenDisplayed) {
			// only show this once
			return;
		}

		GThreadPool.runAsync(Swing.GSWING_THREAD_POOL_NAME, this::doPrintBadHelp);
	}

	private void doPrintBadHelp() {

		Map<Object, HelpLocation> badHelp;
		try {
			badHelp = getInvalidHelpLocations(TaskMonitor.DUMMY);
			if (badHelp.isEmpty()) {
				return;
			}
		}
		catch (CancelledException e) {
			return; // user cancelled
		}

		StringBuilder buffy = new StringBuilder();
		buffy.append("Found the following invalid help locations:\n");
		for (HelpLocation loc : badHelp.values()) {
			buffy.append('\t').append(loc.toString()).append('\n');
			buffy.append("                ").append(loc.getInceptionInformation()).append('\n');
		}

		new Throwable("Bad Help Locations Found!\n" + buffy.toString()).printStackTrace();
	}

	public Map<Object, HelpLocation> getInvalidHelpLocations(TaskMonitor monitor)
			throws CancelledException {

		Set<String> alreadySeen = new HashSet<>();
		Map<Object, HelpLocation> map = new WeakHashMap<>();
		Map<Object, HelpLocation> helpLocationsCopy = copyHelpLocations();
		monitor.initialize(helpLocationsCopy.size());
		Set<Entry<Object, HelpLocation>> entries = helpLocationsCopy.entrySet();
		for (Entry<Object, HelpLocation> entry : entries) {
			monitor.increment();

			Object helpee = entry.getKey();
			HelpLocation location = entry.getValue();
			monitor.setMessage("Checking " + helpee);
			if (hasValidHelp(helpee, location)) {
				continue;
			}

			String inception = location.getInceptionInformation();
			if (alreadySeen.contains(inception)) {
				continue; // don't show repeated errors for same line of code
			}

			alreadySeen.add(inception);
			map.put(helpee, location);
		}
		return map;
	}

	private Map<Object, HelpLocation> copyHelpLocations() {
		// we must copy the help locations, since we are in a background thread and the
		// locations map is frequently updated by the Swing thread
		return Swing.runNow(() -> new HashMap<>(helpLocations));
	}

	//
	// 				Warning!
	// This code has timing implications.  DockingActions register themselves with the help
	// system as part of their construction.  At that point, they are not usually fully
	// constructed, as most clients will use the newly constructed action to set the various
	// toolbar/menu/popup data elements.  For us to know if the action is really only for
	// keybinding purposes, we have to do this check after the action is fully constructed.
	//
	private boolean isKeybindingOnly(Object helpee) {
		if (!(helpee instanceof DockingActionIf)) {
			return false;
		}

		DockingActionIf action = (DockingActionIf) helpee;
		if (action.getToolBarData() != null) {
			return false;
		}
		if (action.getMenuBarData() != null) {
			return false;
		}
		if (action.getPopupMenuData() != null) {
			return false;
		}
		return true;
	}

	private void displayHelpUrl(Object help, URL helpUrl) {
		if (helpUrl == null) {
			Msg.debug(this, "Unable to find help for object: " + help);
		}

		helpUrl = validateUrl(helpUrl);

		if (hasBeenDisplayed && helpUrl.equals(mainHB.getCurrentURL())) {
			reloadPage(helpUrl);
			return;
		}

		mainHB.setCurrentURL(helpUrl);
	}

	/** This forces page to be redisplayed when location has not changed */
	private void reloadPage(URL helpURL) {

		if (!(mainHB instanceof DockingHelpBroker)) {
			// not our broker installed; can't force a reload
			return;
		}

		// Let the URL dictate where the page scrolls to.  If we do not do this, then there is an
		// odd effect of having the page load and then jump to a previous location.
		boolean preserveLocation = false;
		((DockingHelpBroker) mainHB).reloadHelpPage(validateUrl(helpURL), preserveLocation);
	}

	private URL getURLForID(ID ID) {
		javax.help.Map map = mainHS.getCombinedMap();
		try {
			return map.getURLFromID(ID);
		}
		catch (MalformedURLException e) {
			return null;
		}
	}

	private URL validateUrl(URL url) {
		if (url == null) {
			return HELP_NOT_FOUND_PAGE_URL;
		}

		try {
			InputStream inputStream = url.openStream();
			inputStream.close();
			return url;
		}
		catch (IOException e) {
			// handled below
		}

		return HELP_NOT_FOUND_PAGE_URL;
	}

	/** Make sure we can find the help resources that Ghidra will use */
	private boolean isValidHelp() {
		NavigatorView TOCView = mainHS.getNavigatorView(TABLE_OF_CONTENTS_VIEW_NAME);
		Hashtable<?, ?> parametersTable = TOCView.getParameters();
		String filename = (String) parametersTable.get(TABLE_OF_CONTENTS_FILENAME_KEY);
		ClassLoader loader = mainHS.getLoader();
		URL testResource = loader.getResource(filename);
		if (testResource == null) {
			return false;
		}
		return isURLValid(testResource);
	}

	private boolean isURLValid(URL url) {
		InputStream testStream = null;
		try {
			testStream = url.openStream();
			return true; // if the above didn't fail, then the resource can be accessed
		}
		catch (MalformedURLException e) {
			return false; // shouldn't happen as the URL should be valid
		}
		catch (IOException e) {
			return false; // this happens if the resource doesn't exit
		}
		finally {
			if (testStream != null) {
				try {
					testStream.close();
				}
				catch (IOException e) {
					// don't care, we tried to close it
				}
			}
		}
	}

	protected void mergePendingHelpSets() {
		for (HelpSet helpSet : helpSetsPendingMerge) {
			try {
				if (isExcludedHelpSet(helpSet)) {
					continue;
				}

				mainHS.add(helpSet);
			}
			catch (Exception e) {
				Msg.warn(this,
					"Unable to load HelpSet: " + helpSet.getHelpSetURL().toExternalForm(), e);
			}
		}

		// Note: not sure if we ever need to merge again after the initial load.  If so, then
		//       this flag doesn't make sense.  However, as of this writing, we do not discover
		//       new help sets on the fly.
		hasMergedHelpSets = true;
		helpSetsPendingMerge.clear();
	}

	boolean hasMergedHelpSets() {
		return hasMergedHelpSets;
	}

	private boolean isExcludedHelpSet(HelpSet helpSet) {
		if (mainHS.getHelpSetURL().equals(helpSet.getHelpSetURL())) {
			return true; // don't add the main help set to itself
		}

		URL URL = helpSet.getHelpSetURL();
		String URLString = URL.toString();
		if (URLString.endsWith(DUMMY_HELP_SET_NAME)) {
			return true;
		}

		return false;
	}

	/**
	 * Create a new help set for the given url, if one does
	 * not already exist.
	 * @param classLoader the class loader
	 */
	private HelpSet createHelpSet(URL url, GHelpClassLoader classLoader) throws HelpSetException {
		if (!urlToHelpSets.containsKey(url)) {
			GHelpSet hs = new GHelpSet(classLoader, url);
			hs.setHomeID(getHomeId());
			urlToHelpSets.put(url, hs);
			return hs;
		}
		return null;
	}

	private void displayHelpInfo(Object helpObj, HelpLocation loc, Window parent) {
		String msg = getHelpInfo(helpObj, loc);
		Msg.showInfo(this, parent, "Help Info", msg);
	}

	private String getHelpInfo(Object helpObj, HelpLocation helpLoc) {
		if (helpObj == null) {
			return "Help Object is null";
		}

		boolean isHelpDescriptor = false;
		StringBuilder buffy = new StringBuilder();
		buffy.append("HELP OBJECT: " + helpObj.getClass().getName());
		buffy.append("\n");
		if (helpObj instanceof HelpDescriptor) {
			HelpDescriptor helpDescriptor = (HelpDescriptor) helpObj;
			buffy.append(helpDescriptor.getHelpInfo());
			isHelpDescriptor = true;
		}
		else if (helpObj instanceof JButton) {
			JButton button = (JButton) helpObj;
			buffy.append("   BUTTON: " + button.getText());
			buffy.append("\n");
			Component c = button;
			while (c != null && !(c instanceof Window)) {
				c = c.getParent();
			}
			if (c instanceof Dialog) {
				buffy.append("   DIALOG: " + ((Dialog) c).getTitle());
				buffy.append("\n");
			}
			if (c instanceof Frame) {
				buffy.append("   FRAME: " + ((Frame) c).getTitle());
				buffy.append("\n");
			}
		}
		buffy.append("\nHELP-LOCATION-> ");
		if (helpLoc != null) {
			buffy.append(helpLoc.toString());
			String str = helpLoc.getTopic();
			if (str != null) {
				buffy.append("\n   TOPIC:       ");
				buffy.append(str);
			}

			String filename = getFilenameForHelpLocation(helpLoc);
			if (filename != null) { // should never be null
				buffy.append("\n   FILENAME: ");
				buffy.append(filename);
			}

			str = helpLoc.getAnchor();
			if (str != null) {
				buffy.append("\n   ANCHOR:   ");
				buffy.append(str);
			}

			if (!isHelpDescriptor) { // don't put the info in twice
				String inception = helpLoc.getInceptionInformation();
				if (inception != null) {
					buffy.append("\n   \n");
					buffy.append("   CREATED AT: " + inception);
					buffy.append("\n   ");
				}
			}
		}
		else {
			if (isExcludedFromHelp(helpObj)) {
				buffy.append("<EXCLUDED FROM HELP>");
			}
			else {
				buffy.append("<NO HELP AVAILABLE>");
			}
		}

		return buffy.toString();
	}
}