Target Communication Framework Services - Terminals

• Version History
• Overview
• Commands
  • Get Context
  • Exit
  • SetWinSize
  • Launch
• Events
• API

Processes Service

Version History

Overview

Terminals service provides access to the target OS's termianl login, allows to start and exit a terminal login, and allows to set the terminal's window size.

If a terminal is laucnhed by this service, its standard input/output streams are available for client to read/write using Streams Service. Stream type of such streams is set to "Terminals".

Command and event parameters are encoded as zero terminated JSON strings.

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

Commands

Get Context

C • <token> • Terminals • getContext • <string: context ID> •

The command retrieves context info for given context ID. A context corresponds to an connected active terminal. Context IDs are valid across TCF services, so it is allowed to issue 'Terminals.getContext' command with a context that was obtained, for example, from Memory service. However, 'Terminals.getContext' is supposed to return only process specific data. If the ID is not a process ID, 'Terminals.getContext' may not return any useful information.

Reply:

R • <token> • <error report> • <context data> •

<context data>
    ⇒ null
    ⇒ <object>

Context data object should, at least, contain member "ID" : <string>.

Predefined process context properties are:

• "ID" : <string> - ID of the context, same as getContext command argument.
• "ProcessID" : <string> - the process ID of the login process of the terminal.
• "PtyType" : <string> - terminal type.
• "Encoding" : <string> - encoding.
• "Width" : <integer> - width of the terminal.
• "Height" : <integer> - height of the terminal.
• "StdInID" : <string> - terminal standard input stream ID.
• "StdOutID" : <string> - terminal standard output stream ID.
• "StdErrID" : <string> - terminal standard error stream ID.

Exit

C • <token> • Terminals • exit• <string: context ID> •

Reply:

R • <token> • <error report> •

SetWinSize

C • <token> • Terminals • setWinSize • <string: context ID> • <integer: newWidth> • <integer: newHeight> •

The command sets the remote terminal windows size.

Reply:

R • <token> • <error report> •

Launch

C • <token> • Terminals • launch• <string: pty type> • <string: encoding> • <string array: environment variables> •

<string array>
    ⇒ null
    ⇒ [ ]
    ⇒ [ <string list> ]

<string list>
    ⇒ <string>
    ⇒ <string list> , <string>

The command launches a new terminal connection to the remote machine.

• <string: pty type> - requested terminal type for the new terminal.
• <string: encoding> - requested terminal type for the new terminal.
• <string array: environment variables> - list of environment variables for the terminal.

Reply:

R • <token> • <error report> • <context data> •

On success the command returns context data for created terminal. Context data has same format as Get Context result.

Events

Terminals service broadcasts notification event when a terminal exits, or the terminal window size is changed. Only terminals that were launched by the service will get the events.

E • Terminals • exited • <string: terminal ID> • <int: exit code> •

E • Terminals • winSizeChanged • <string: terminal ID> • <int: newWidth> • <int: newHeight> •

API

/**
 * ITerminalsService allows to launch a new terminal on the remote target system.
 *
 * @noimplement This interface is not intended to be implemented by clients.
 */
public interface ITerminals extends IService {

    /**
     * This service name, as it appears on the wire - a TCF name of the service.
     */
    static final String NAME = "Terminals";

    /**
     * Retrieve context info for given context ID.
     * A context corresponds to an terminal.
     * Context IDs are valid across TCF services, so it is allowed to issue
     * 'ITerminals.getContext' command with a context that was obtained,
     * for example, from Memory service.
     * However, 'ITerminals.getContext' is supposed to return only terminal specific data,
     * If the ID is not a terminal ID, 'ITerminals.getContext' may not return any
     * useful information
     *
     * @param id - context ID.
     * @param done - call back interface called when operation is completed.
     */
    IToken getContext(String id, DoneGetContext done);

    /**
     * Client call back interface for getContext().
     */
    interface DoneGetContext {
        /**
         * Called when contexts data retrieval is done.
         * @param error - error description if operation failed, null if succeeded.
         * @param context - context data.
         */
        void doneGetContext(IToken token, Exception error, TerminalContext context);
    }

    /**
     * Context property names.
     */
    static final String
        /** The TCF context ID of the terminal */
        PROP_ID = "ID",

        /** The process ID of the login process of the terminal */
        PROP_PROCESS_ID = "ProcessID",

        /** The PTY type */
        PROP_PTY_TYPE = "PtyType",

        /** The terminal streams encoding */
        PROP_ENCODING = "Encoding",

        /** Window width size */
        PROP_WIDTH = "Width",

        /** Window height size */
        PROP_HEIGHT = "Height",

        /** Terminal standard input stream ID */
        PROP_STDIN_ID = "StdInID",

        /** Terminal standard output stream ID */
        PROP_STDOUT_ID = "StdOutID",

        /** Terminal standard error stream ID */
        PROP_STDERR_ID = "StdErrID";

    interface TerminalContext {

        /**
         * Get context ID.
         * Same as getProperties().get("ID")
         */
        String getID();

        /**
         * Get process ID of the login process of the terminal.
         * Same as getProperties().get("ProcessID")
         */
        String getProcessID();

        /**
         * Get terminal type.
         * Same as getProperties().get("PtyType")
         */
        String getPtyType();

        /**
         * Get encoding.
         * Same as getProperties().get("Encoding")
         */
        String getEncoding();

        /**
         * Get width.
         * Same as getProperties().get("Width")
         */
        int getWidth();

        /**
         * Get height.
         * Same as getProperties().get("Height")
         */
        int getHeight();

        /**
         * Get standard input stream ID of the terminal.
         * Same as getProperties().get("StdInID")
         */
        String getStdInID();

        /**
         * Get standard output stream ID of the terminal.
         * Same as getProperties().get("StdOutID")
         */
        String getStdOutID();

        /**
         * Get standard error stream ID of the terminal.
         * Same as getProperties().get("StdErrID")
         */
        String getStdErrID();

        /**
         * Get all available terminal properties.
         * @return Map 'property name' -> 'property value'
         */
        Map<String, Object> getProperties();

        /**
         * Exit the terminal.
         * @param done - call back interface called when operation is completed.
         * @return pending command handle, can be used to cancel the command.
         */
        IToken exit(DoneCommand done);
    }

    /**
     * Call-back interface to be called when "setWinSize" or "exit" command is complete.
     */
    interface DoneCommand {
        void doneCommand(IToken token, Exception error);
    }

    /**
     * Launch a new terminal to remote machine.
     * @param type - requested terminal type for the new terminal.
     * @param encoding - requested encoding for the new terminal.
     * @param environment - Array of environment variable strings.
     * if null then default set of environment variables will be used.
     * @param done - call back interface called when operation is completed.
     * @return pending command handle, can be used to cancel the command.
     */
    IToken launch(String type, String encoding, String[] environment, DoneLaunch done);

    /**
     * Call-back interface to be called when "launch" command is complete.
     */
    interface DoneLaunch {
        void doneLaunch(IToken token, Exception error, TerminalContext terminal);
    }

    /**
     * Set the terminal widow size
     * @param id - context ID.
     * @param col - number of columns.
     * @param row - number of rows.
     * @param done - call back interface called when operation is completed.
     * @return pending command handle, can be used to cancel the command.
     */
    IToken setWinSize(String id, int col, int row, DoneCommand done);

    /**
     * Exit a terminal.
     * @param id - context ID.
     * @param done - call back interface called when operation is completed.
     * @return pending command handle, can be used to cancel the command.
     */
    IToken exit(String id, DoneCommand done);

    /**
     * Add terminals service event listener.
     * @param listener - event listener implementation.
     */
    void addListener(TerminalsListener listener);

    /**
     * Remove terminals service event listener.
     * @param listener - event listener implementation.
     */
    void removeListener(TerminalsListener listener);

    /**
     * Process event listener is notified when a terminal changes or exits.
     * Event are reported only for terminals that were started by 'launch' command.
     */
    interface TerminalsListener {

        /**
         * Called when a terminal exits.
         * @param terminal_id - terminal context ID
         * @param exit_code - terminal exit code
         */
        void exited(String terminal_id, int exit_code);

        /**
         * Called when a terminal windows size changes.
         * @param terminal_id - terminal context ID
         * @param new_width - new terminal width
         * @param new_height - new terminal height
         */
        void winSizeChanged(String terminal_id, int new_width, int new_height);
    }
}