Package ghidra.debug.api.tracermi

Interface RemoteMethod

public interface RemoteMethod
A remote method registered by the back-end debugger.

Remote methods must describe the parameters names and types at a minimum. They should also provide a display name and description for the method itself and each of its parameters. These methods should not return a result. Instead, any "result" should be recorded into a trace. The invocation can result in an error, which is communicated by an exception that can carry only a message string. Choice few methods should return a result, for example, the execute method with output capture. That output generally does not belong in a trace, so the only way to communicate it back to the front end is to return it.

  • Method Details

    • name

      String name()
      The name of the method.
      Returns:
      the name

    • action

      ActionName action()
      A string that hints at the UI action this method achieves.
      Returns:
      the action

    • display

      String display()
      A title to display in the UI for this action.
      Returns:
      the title

    • icon

      Icon icon()
      The icon to display in menu's and in the prompt dialog.
      Returns:
      the icon

    • okText

      String okText()
      Text to display in the OK button of any prompt dialog.
      Returns:
      the text

    • description

      String description()
      A description of the method.

      This is the text for tooltips or other information presented by actions whose purpose is to invoke this method. If the back-end command name is well known to its users, this text should include that name.

      Returns:
      the description

    • parameters

      Map<String,RemoteParameter> parameters()
      The methods parameters.

      Parameters are all keyword-style parameters. This returns a map of names to parameter descriptions.

      Returns:
      the parameter map

    • retType

      TraceObjectSchema.SchemaName retType()
      Get the schema for the return type. NOTE: Most methods should return void, i.e., either they succeed, or they throw/raise an error message. One notable exception is "execute," which may return the console output from executing a command. In most cases, the method should only cause an update to the trace database. That effect is its result.
      Returns:
      the schema name for the method's return type.

    • checkType

      static void checkType(String paramName, TraceObjectSchema.SchemaName schName, TraceObjectSchema sch, Object arg)
      Check the type of an argument.

      This is a hack, because TraceObjectSchema expects TraceObject, or a primitive. We instead need TraceObject. I'd add the method to the schema, except that trace stuff is not in its dependencies.

      Parameters:
      paramName - the name of the parameter
      schName - the name of the parameter's schema
      sch - the type of the parameter
      arg - the argument

    • validate

      default Trace validate(Map<String,Object> arguments)
      Validate the given argument.

      This method is for checking parameter sanity before they are marshalled to the back-end. This is called automatically during invocation. Clients can use this method to pre-test or validate in the UI, when invocation is not yet desired.

      Parameters:
      arguments - the arguments
      Returns:
      the trace if any object arguments were given, or null
      Throws:
      IllegalArgumentException - if the arguments are not valid

    • invokeAsync

      RemoteAsyncResult invokeAsync(Map<String,Object> arguments)
      Invoke the remote method, getting a future result.

      This invokes the method asynchronously. The returned objects is a CompletableFuture, whose getters are overridden to prevent blocking the Swing thread for more than 1 second. Use of this method is not recommended, if it can be avoided; however, you should not create a thread whose sole purpose is to invoke this method. UI actions that need to invoke a remote method should do so using this method, but they must be sure to handle errors using, e.g., using CompletableFuture.exceptionally(Function), lest the actions fail silently.

      Parameters:
      arguments - the keyword arguments to the remote method
      Returns:
      the future result
      Throws:
      IllegalArgumentException - if the arguments are not valid

    • invoke

      default Object invoke(Map<String,Object> arguments)
      Invoke the remote method and wait for its completion.

      This method cannot be invoked from the Swing thread. This is to avoid locking up the user interface. If you are on the Swing thread, consider invokeAsync(Map) instead. You can chain the follow-up actions and then schedule any UI updates on the Swing thread using AsyncUtils.SWING_EXECUTOR.

      Parameters:
      arguments - the keyword arguments to the remote method
      Returns:
      the returned value
      Throws:
      IllegalArgumentException - if the arguments are not valid