# Target Communication Framework Services - Breakpoints

- Commands
  - Set
  - Add
  - Change
  - Enable
  - Disable
  - Remove
  - Get IDs
  - Get Properties
  - Get Status
- Events
- API

# Breakpoints Service

Breakpoint is represented by unique identifier and set of properties. Breakpoint identifier (String id) needs to be unique across all hosts and targets

Breakpoint properties is extendable collection of named attributes, which define breakpoint location and behavior. The service defines some common attribute names, host tools and target agents may support additional attributes.

For each breakpoint a target agent maintains another extendable collection of named attributes: breakpoint status. While breakpoint properties are persistent and represent user input, breakpoint status reflects dynamic target agent reports about breakpoint current state, like actual addresses where breakpoint is planted or planting errors.

Breakpoints are associated with communication channel and traget agent must remove them when the channel is closed. Target agent should maintain separate breakpoint table for each communication channel. It is allowed to set same breakpoint (same ID) through multiple channels, target agent should treat it as single breakpoint with maltiple references. Such breakpoint is removed when all refering channels are closed.

The service uses standard format for error reports, see Error Report Format.

## Commands

### Set

    C • <token> • Breakpoints • set • <array of breakpoints> •

    <array of breakpoints>
        Ø null
        Ø [ ]
        Ø [ <breakpoints list> ]

    <breakpoints list>
        Ø <breakpoint data>
        Ø <breakpoint data> , <breakpoint data>

    <breakpoint data>
        Ø <object>

The command downloads breakpoints data to a target agent. The command is intended to be used only to initialize target breakpoints table when communication channel is open. After that, host should notify target about (incremental) changes in breakpoint data by sending Add, Change and Remove commands.

Breakpoint data consists of a list of breakpoint properties. All properties are optional, except ID. Tools and targets can define additional properties. Predefined properties are:

- `"ID" : <string>` - breakpoint ID
- `"Enabled" : <boolean>` - if true breakpoint is enabled
- `"Address" : <string>` - if preset, defines address of the breakpoint. Address is an expression that evaluates to breakpoint memory address. Alternatively, breakpoint location can be given as File/Line/Column.
- `"Condition" : <string>` - a conditional expression that is evaluted every time execution hits the breakpoint. If condition is evaluated to false, the breakpoint is skipped and execution is resumed without sending notifications to a host.
- `"File" : <string>` - source code file name of breakpoint location.
- `"Line" : <int>` - source code line number of breakpoint location.
- `"Column" : <int>` - source code column number of breakpoint location.

Reply:

    R • <token> • <error report> •

### Add

    C • <token> • Breakpoints • add • <breakpoint data> •

The command adds breakpoint to target agent breakpoint table. Host should send this command when user creates new breakpoint

Reply:

    R • <token> • <error report> •

### Change

    C • <token> • Breakpoints • change • <breakpoint data> •

The command updates breakpoint data in target agent breakpoint table. Host should send this command when user modifies a breakpoint

Reply:

    R • <token> • <error report> •

### Enable

    C • <token> • Breakpoints • enable • <array of breakpoint IDs> •

    <array of breakpoint IDs>
        Ø null
        Ø [ ]
        Ø [ <breakpoint IDs list> ]

    <breakpoint IDs list>
        Ø <breakpoint ID>
        Ø <breakpoint ID> , <breakpoint ID>

    <breakpoint ID>
        Ø <string>

The command enables a list of breakpoints - sets brekpoint property "Enabled" to true.

Reply:

    R • <token> • <error report> •

### Disable

    C • <token> • Breakpoints • disable • <array of breakpoint IDs> •

The command disables a list of breakpoints - sets brekpoint property "Enabled" to false.

Reply:

    R • <token> • <error report> •

### Remove

    C • <token> • Breakpoints • remove • <array of breakpoint IDs> •

The command removes a list of breakpoints. Host should send this command when user deletes breakpoints.

Reply:

    R • <token> • <error report> •

### Get IDs

    C • <token> • Breakpoints • getIDs •

The command uploads IDs of breakpoints known to target agent. Only breakpoints what are set through this communication channel are reported. Target agent should maintain separate breakpoint table for each communication channel.

Reply:

    R • <token> • <error report> • <array of breakpoint IDs> •

### Get Properties

    C • <token> • Breakpoints • getProperties • <string: breakpoint ID> •

The command uploads properties of given breakpoint from target agent breakpoint table.

Reply:

    R • <token> • <error report> • <;breakpoint data> •

### Get Status

    C • <token> • Breakpoints • getStatus • <string: breakpoint ID> •

The command uploads status of given breakpoint from target agent.

Reply:

    R • <token> • <error report> • <;breakpoint status> •

    <breakpoint status>
        Ø <object>

Breakpoint stat consists of a list of status properties. All properties are optional. Tools and targets can define additional properties. Predefined properties are:

- `"Planted" : <array of addresses>`
- `"Error" : <string>`
- `"File" : <string>`
- `"Line" : <int>`
- `"Column" : <int>`

## Events

    E • Breakpoints • status • <string: breakpoint ID> • <breakpoint status> •

status
  is sent when breakpoint status changes.

## API

    /**
     * Breakpoint is represented by unique identifier and set of properties.
     * Breakpoint identifier (String id) needs to be unique across all hosts and targets.
     *
     * Breakpoint properties (Map) is extendable collection of named attributes,
     * which define breakpoint location and behavior. This module defines some common
     * attribute names (see PROP_*), host tools and target agents may support additional attributes.
     *
     * For each breakpoint a target agent maintains another extendable collection of named attributes:
     * breakpoint status (Map, see STATUS_*). While breakpoint properties are
     * persistent and represent user input, breakpoint status reflects dynamic target agent reports
     * about breakpoint current state, like actual addresses where breakpoint is planted or planting errors.
     */
    public interface IBreakpoints extends IService {

        /**
         * Service name.
         */
        static final String NAME = "Breakpoints";

        /**
         * Breakpoint property names.
         */
        static final String
            PROP_ID = "ID",                 // String
            PROP_ENABLED = "Enabled",       // Boolean
            PROP_ADDRESS = "Address",       // String
            PROP_CONDITION = "Condition",   // String
            PROP_FILE = "File",             // String
            PROP_LINE = "Line",             // Number
            PROP_COLUMN = "Column";         // Number

        /**
         * Breakpoint status field names.
         */
        static final String
            STATUS_PLANTED = "Planted",     // Array of addresses
            STATUS_ERROR = "Error",         // String
            STATUS_FILE = "File",           // String
            STATUS_LINE = "Line",           // Number
            STATUS_COLUMN = "Column";       // Number

        /**
         * Call back interface for breakpoint service commands.
         */
        interface DoneCommand {
            void doneCommand(IToken token, Exception error);
        }

        /**
         * Download breakpoints data to target agent.
         * The command is intended to be used only to initialize target breakpoints table
         * when communication channel is open. After that, host should
         * notify target about (incremental) changes in breakpoint data by sending
         * add, change and remove commands.
         *
         * @param properties - array of breakpoints.
         * @param done - command result call back object.
         */
        IToken set(Map<String,Object>[] properties, DoneCommand done);

        /**
         * Called when breakpoint is added into breakpoints table.
         * @param properties - breakpoint properties.
         * @param done - command result call back object.
         */
        IToken add(Map<String,Object> properties, DoneCommand done);

        /**
         * Called when breakpoint properties are changed.
         * @param properties - breakpoint properties.
         * @param done - command result call back object.
         */
        IToken change(Map<String,Object> properties, DoneCommand done);

        /**
         * Tell target to change (only) PROP_ENABLED breakpoint property 'true'.
         * @param ids - array of enabled breakpoint identifiers.
         * @param done - command result call back object.
         */
        IToken enable(String[] ids, DoneCommand done);

        /**
         * Tell target to change (only) PROP_ENABLED breakpoint property to 'false'.
         * @param ids - array of disabled breakpoint identifiers.
         * @param done - command result call back object.
         */
        IToken disable(String[] ids, DoneCommand done);

        /**
         * Tell target to remove breakpoint.
         * @param id - unique breakpoint identifier.
         * @param done - command result call back object.
         */
        IToken remove(String[] ids, DoneCommand done);

        /**
         * Upload IDs of breakpoints known to target agent.
         * @param done - command result call back object.
         */
        IToken getIDs(DoneGetIDs done);

        interface DoneGetIDs {
            void doneGetIDs(IToken token, Exception error, String[] ids);
        }

        /**
         * Upload properties of given breakpoint from target agent breakpoint table.
         * @param id - unique breakpoint identifier.
         * @param done - command result call back object.
         */
        IToken getProperties(String id, DoneGetProperties done);

        interface DoneGetProperties {
            void doneGetProperties(IToken token, Exception error, Map<String,Object> properties);
        }

        /**
         * Upload status of given breakpoint from target agent.
         * @param id - unique breakpoint identifier.
         * @param done - command result call back object.
         */
        IToken getStatus(String id, DoneGetStatus done);

        interface DoneGetStatus {
            void doneGetStatus(IToken token, Exception error, Map<String,Object> status);
        }

        /**
         * Breakpoints service events listener.
         */
        interface BreakpointsListener {

            /**
             * Called when breakpoint status changes.
             * @param id - unique breakpoint identifier.
             * @param status - breakpoint status.
             */
            void breakpointStatusChanged(String id, Map<String,Object> status);
        }

        void addListener(BreakpointsListener listener);

        void removeListener(BreakpointsListener listener);
    }