Package ghidra.app.services

# Interface TraceRmiService

All Known Subinterfaces:
  `InternalTraceRmiService`

public interface TraceRmiService
A service (both in the Ghidra framework sense, and in the network sense) for connecting Trace RMI-based back-end debuggers.

This service connects to back-end debuggers, and/or allows back-end debuggers to connect to it. Either way, Ghidra becomes the front-end, acting as the Trace RMI server, and the back-end debugger acts as the Trace RMI client. The Ghidra front-end may also send control commands to the back-end, e.g., to step, resume, or suspend the target.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `TraceRmiAcceptor`
  `acceptOne(SocketAddress address)`
  Prepare to accept a single connection by listening on the given address.
  `void`
  `addTraceServiceListener(TraceRmiServiceListener listener)`
  Add a listener for events on the Trace RMI service
  `TraceRmiConnection`
  `connect(SocketAddress address)`
  Assuming a back-end debugger is listening, connect to it.
  `Collection<TraceRmiAcceptor>`
  `getAllAcceptors()`
  Get all of the acceptors currently listening for a connection
  `Collection<TraceRmiConnection>`
  `getAllConnections()`
  Get all of the active connections
  `SocketAddress`
  `getServerAddress()`
  Get the address (and port) of the Trace RMI TCP server
  `boolean`
  `isServerStarted()`
  Check if the service is listening for inbound connections (other than those expected by `acceptOne(SocketAddress)`).
  `void`
  `removeTraceServiceListener(TraceRmiServiceListener listener)`
  Remove a listener for events on the Trace RMI service
  `void`
  `setServerAddress(SocketAddress serverAddress)`
  Set the address (and port) of the Trace RMI TCP server
  `void`
  `startServer()`
  Start the Trace RMI TCP server
  `void`
  `stopServer()`
  Stop the Trace RMI TCP server

- ## Method Details

  - ### getServerAddress

    SocketAddress getServerAddress()
    Get the address (and port) of the Trace RMI TCP server
    Returns:

  - ### setServerAddress

    void setServerAddress(SocketAddress serverAddress)
    Set the address (and port) of the Trace RMI TCP server
    Parameters:
      `serverAddress` - may be null to bind to ephemeral port

  - ### startServer

    void startServer() throws IOException
    Start the Trace RMI TCP server
    Throws:
      `IOException`

  - ### stopServer

    void stopServer()
    Stop the Trace RMI TCP server

  - ### isServerStarted

    boolean isServerStarted()
    Check if the service is listening for inbound connections (other than those expected by `acceptOne(SocketAddress)`).
    Returns:
      true if listening, false otherwise

  - ### connect

    TraceRmiConnection connect(SocketAddress address) throws IOException
    Assuming a back-end debugger is listening, connect to it.
    Parameters:
      `address` - the address (and port) of the back-end system
    Returns:
      the connection
    Throws:
      `IOException` - if the connection failed

  - ### acceptOne

    TraceRmiAcceptor acceptOne(SocketAddress address) throws IOException
    Prepare to accept a single connection by listening on the given address.

    This essentially starts a server (separate from the one creased by `startServer()`) that will accept a single connection. The server is started by this method. The caller can then invoke (on the same thread) whatever back-end system or agent that is expected to connect back to this service. Assuming that system runs in the background, this thread can then invoke `TraceRmiAcceptor.accept()` to actually accept that connection. Once accepted, the service is terminated, and the server socket is closed. The client socket remains open.

    Parameters:
      `address` - the socket address to bind, or null for ephemeral
    Returns:
      the acceptor, which can be used to retrieve the ephemeral address and accept the actual connection
    Throws:
      `IOException` - on error

  - ### getAllConnections

    Collection<TraceRmiConnection> getAllConnections()
    Get all of the active connections
    Returns:
      the connections

  - ### getAllAcceptors

    Collection<TraceRmiAcceptor> getAllAcceptors()
    Get all of the acceptors currently listening for a connection
    Returns:
      the acceptors

  - ### addTraceServiceListener

    void addTraceServiceListener(TraceRmiServiceListener listener)
    Add a listener for events on the Trace RMI service
    Parameters:
      `listener` - the listener to add

  - ### removeTraceServiceListener

    void removeTraceServiceListener(TraceRmiServiceListener listener)
    Remove a listener for events on the Trace RMI service
    Parameters:
      `listener` - the listener to remove