docs/TCF Service - Terminals.html - gerrit/tcf/org.eclipse.tcf - Git at Google

 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
 <html>

 <head>
 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
 <title>Target Communication Framework Services - Processes</title>
 </head>

 <body lang="EN-US">

 <h1>Target Communication Framework Services - Terminals</h1>

 <ul>
     <li><a href="#VersionHistory">Version History</a>
     </li><li><a href="#Overview">Overview</a>
     </li><li><a href="#Cmds">Commands</a>
     <ul>
         <li><a href="#CmdGetContext">Get Context</a>
         </li><li><a href="#CmdExit">Exit</a>
         </li><li><a href="#CmdSetWinSize">SetWinSize</a>
         </li><li><a href="#CmdLaunch">Launch</a>
         </li></ul>
     </li><li><a href="#Events">Events</a>
     </li><li><a href="#API">API</a>
 </li></ul>

 <h1>Processes Service</h1>

 <h2><a name="VersionHistory">Version History</a></h2>

 <table border="1" cellpadding="8">
     <tbody><tr>
         <th>Version
         </th><th>Date
         </th><th>Change
     </th></tr><tr>
         <td>0.1
         </td><td>2010-09-29
         </td><td>Initial contribution
     </td></tr></tbody></table>

 <h2><a name="Overview">Overview</a></h2>

 <p>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. <br>
 </p>

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

 <p>Command and event parameters are encoded
 as zero terminated <a href='TCF JSON.html'>JSON</a> strings.</p>

 <p>The service uses standard format for error reports,
 see <a href="TCF Error Report Format.html">Error Report Format</a>.</p>

 <h2><a name="Cmds">Commands</a></h2>

 <h3><a name="CmdGetContext">Get Context</a></h3>

 <pre><b><font color="#333399" face="Courier New" size="2">
 C &#8226; &lt;token&gt; &#8226; Terminals &#8226; getContext &#8226; &lt;string: context ID&gt; &#8226;<br></font></b></pre>

 <p>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.
 </p>

 <p>Reply:</p>

 <pre><b><font color="#333399" face="Courier New" size="2">
 R &#8226; &lt;token&gt; &#8226; &lt;error report&gt; &#8226; &lt;context data&gt; &#8226;<br><br><i>&lt;context data&gt;</i>
     &#8658; null
     &#8658; <i>&lt;object&gt;</i>
 </font></b></pre>

 <p>Context data object should, at least, contain member
 <b><font color="#333399" face="Courier New" size="2">"ID" : <i>&lt;string&gt;.</i></font></b>
 </p>

 <p>Predefined process context properties are:</p>
 <ul>
     <li><code><b><font color="#333399" face="Courier New" size="2">"ID" : <i>&lt;string&gt;</i></font></b></code>
     - ID of the context, same as getContext command argument.

     <li><code><b><font color="#333399" face="Courier New" size="2">"ProcessID" : <i>&lt;string&gt;</i></font></b></code>
     - the process ID of the login process of the terminal.

     </li><li><code><b><font color="#333399" face="Courier New" size="2">"PtyType" : <i>&lt;string&gt;</i></font></b></code>
     - terminal type.

     </li><li><code><b><font color="#333399" face="Courier New" size="2">"Encoding" : <i>&lt;string&gt;</i></font></b></code>
     - encoding.

     </li><li><code><b><font color="#333399" face="Courier New" size="2">"Width" : <i>&lt;integer&gt;</i></font></b></code>
     - width of the terminal.

     </li><li><code><b><font color="#333399" face="Courier New" size="2">"Height" : <i>&lt;integer&gt;</i></font></b></code>
     - height of the terminal.

     </li><li><code><b><font color="#333399" face="Courier New" size="2">"StdInID" : <i>&lt;string&gt;</i></font></b></code>
     - terminal standard input stream ID.

     </li><li><code><b><font color="#333399" face="Courier New" size="2">"StdOutID" : <i>&lt;string&gt;</i></font></b></code>
     - terminal standard output stream ID.

     </li><li><code><b><font color="#333399" face="Courier New" size="2">"StdErrID" : <i>&lt;string&gt;</i></font></b></code>
     - terminal standard error stream ID.
 </li></ul>

 <h3><a name="CmdExit">Exit</a></h3>

 <pre><b><font color="#333399" face="Courier New" size="2">
 C &#8226; &lt;token&gt; &#8226; Terminals &#8226; exit&#8226; &lt;string: context ID&gt; &#8226;<br></font></b></pre>The command exits the shell and closes the terminal connection.

 <p>Reply:</p>

 <pre><b><font color="#333399" face="Courier New" size="2">
 <span style="font-style: italic;">R &#8226; &lt;token&gt; &#8226; &lt;error report&gt; &#8226;</span><i></i>
 </font></b></pre>

 <h3><a name="CmdSetWinSize">SetWinSize</a></h3>

 <pre><b><font color="#333399" face="Courier New" size="2">
 C &#8226; &lt;token&gt; &#8226; Terminals &#8226; setWinSize &#8226; &lt;string: context ID&gt; &#8226; &lt;integer: newWidth&gt; &#8226; &lt;integer: newHeight&gt; &#8226;<br></font></b></pre>

 <p>The command sets the remote terminal windows size.</p>

 <p>Reply:</p>

 <pre><b><font color="#333399" face="Courier New" size="2">
 R &#8226; <i>&lt;token&gt;</i> &#8226; <i>&lt;error report&gt;</i> &#8226;<br></font></b></pre>

 <h3><a name="CmdLaunch">Launch</a></h3>

 <pre><b><font color="#333399" face="Courier New" size="2"><br>C &#8226; &lt;token&gt; &#8226; Terminals &#8226; launch&#8226; &lt;string: pty type&gt; &#8226; &lt;string: encoding&gt; &#8226; &lt;string array: environment variables&gt; &#8226;<br></font></b><b><i><span style="font-size: 10pt; font-family: &quot;Courier New&quot;; color: rgb(51, 51, 153);" lang="EN-US"><br>&lt;string array&gt;</span></i><span style="font-size: 10pt; font-family: &quot;Courier New&quot;; color: rgb(51, 51, 153);" lang="EN-US"><br><span style="">&nbsp;&nbsp;&nbsp; </span></span><span style="font-size: 10pt; font-family: &quot;MS Gothic&quot;; color: rgb(51, 51, 153);">&#8658;</span><span style="font-size: 10pt; font-family: &quot;Courier New&quot;; color: rgb(51, 51, 153);" lang="EN-US"> null<br><span style="">&nbsp;&nbsp;&nbsp; </span></span><span style="font-size: 10pt; font-family: &quot;MS Gothic&quot;; color: rgb(51, 51, 153);">&#8658;</span><span style="font-size: 10pt; font-family: &quot;Courier New&quot;; color: rgb(51, 51, 153);" lang="EN-US"> [ ]<br><span style="">&nbsp;&nbsp;&nbsp; </span></span><span style="font-size: 10pt; font-family: &quot;MS Gothic&quot;; color: rgb(51, 51, 153);">&#8658;</span><span style="font-size: 10pt; font-family: &quot;Courier New&quot;; color: rgb(51, 51, 153);" lang="EN-US"> [ <i>&lt;string list&gt;</i> ]</span></b><br></pre>
 <p class="MsoNormal" style="text-align: left;" align="left"><b><i><span style="font-size: 10pt; font-family: &quot;Courier New&quot;; color: rgb(51, 51, 153);" lang="EN-US">&lt;string list&gt;</span></i></b><b><span style="font-size: 10pt; font-family: &quot;Courier New&quot;; color: rgb(51, 51, 153);" lang="EN-US"><br>
 <span style="">&nbsp;&nbsp;&nbsp; </span></span></b><b><span style="font-size: 10pt; font-family: &quot;MS Gothic&quot;; color: rgb(51, 51, 153);">&#8658;</span></b><b><span style="font-size: 10pt; font-family: &quot;Courier New&quot;; color: rgb(51, 51, 153);"> <i><span lang="EN-US">&lt;string&gt;</span></i><span lang="EN-US"><br>
 <span style="">&nbsp;&nbsp;&nbsp; </span></span></span></b><b><span style="font-size: 10pt; font-family: &quot;MS Gothic&quot;; color: rgb(51, 51, 153);">&#8658;</span></b><b><span style="font-size: 10pt; font-family: &quot;Courier New&quot;; color: rgb(51, 51, 153);"> <i><span lang="EN-US">&lt;string list&gt;</span></i><span lang="EN-US"> , <i>&lt;string&gt;</i></span></span></b><b><span style="font-size: 10pt; font-family: &#23435;&#20307;; color: rgb(51, 51, 153);" lang="EN-US"><o:p></o:p></span></b></p>


 <p>The command launches a new terminal connection to the remote machine.
 </p><ul>
         <li><i>&lt;string: pty type&gt;</i> - requested terminal type for the new terminal.
         </li><li><i>&lt;string: encoding&gt;</i> - requested terminal type for the new terminal.
         </li><li><i>&lt;string array: environment variables&gt;</i> - list of environment variables for the terminal.
         </li></ul>

 <p>Reply:</p>

 <pre><b><font color="#333399" face="Courier New" size="2">
 R &#8226; <i>&lt;token&gt;</i> &#8226; <i>&lt;error report&gt;</i> &#8226; <i>&lt;context data&gt;</i> &#8226;<br></font></b></pre>

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

 <h2><a name="Events">Events</a></h2>

 <p>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.</p>

 <pre></pre>
 <p><b><font color="#333399" face="Courier New" size="2">
 E &#8226; Terminals &#8226; exited &#8226; &lt;string: terminal ID&gt; &#8226; &lt;int: exit code&gt; &#8226;</font></b></p>
 Sent when a terminal is exited. "terminal ID" is the ID of the terminal. "exit code" is the terminal exit code.<br>
 <br>
 <p><b><font color="#333399" face="Courier New" size="2">E &#8226; Terminals &#8226; winSizeChanged &#8226; &lt;string: terminal ID&gt; &#8226; &lt;int: newWidth&gt; &#8226; &lt;int: newHeight&gt; &#8226;</font></b></p>
 Sent when a terminal's window size is changed. "terminal ID" is the ID
 of the terminal. "newWidth" is the new width of the terminal,
 "newHight" is the new height of the terminal.<br>

 <h2><a name='API'>API</a></h2>

 <pre>
 <font color=#3F5FBF>/**
  * ITerminalsService allows to launch a new terminal on the remote target system.
  *
  * <font color=#7F9FBF>@noimplement</font> This interface is not intended to be implemented by clients.
  */</font>
 <font color=#7F0055>public interface</font> ITerminals <font color=#7F0055>extends</font> IService {

     <font color=#3F5FBF>/**
      * This service name, as it appears on the wire - a TCF name of the service.
      */</font>
     <font color=#7F0055>static final</font> String NAME = "Terminals";

     <font color=#3F5FBF>/**
      * 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
      *
      * <font color=#7F9FBF>@param</font> id - context ID.
      * <font color=#7F9FBF>@param</font> done - call back interface called when operation is completed.
      */</font>
     IToken getContext(String id, DoneGetContext done);

     <font color=#3F5FBF>/**
      * Client call back interface for getContext().
      */</font>
     <font color=#7F0055>interface</font> DoneGetContext {
         <font color=#3F5FBF>/**
          * Called when contexts data retrieval is done.
          * <font color=#7F9FBF>@param</font> error - error description if operation failed, null if succeeded.
          * <font color=#7F9FBF>@param</font> context - context data.
          */</font>
         <font color=#7F0055>void</font> doneGetContext(IToken token, Exception error, TerminalContext context);
     }

     <font color=#3F5FBF>/**
      * Context property names.
      */</font>
     <font color=#7F0055>static final</font> String
         <font color=#3F5FBF>/** The TCF context ID of the terminal */</font>
         PROP_ID = "ID",

         <font color=#3F5FBF>/** The process ID of the login process of the terminal */</font>
         PROP_PROCESS_ID = "ProcessID",

         <font color=#3F5FBF>/** The PTY type */</font>
         PROP_PTY_TYPE = "PtyType",

         <font color=#3F5FBF>/** The terminal streams encoding */</font>
         PROP_ENCODING = "Encoding",

         <font color=#3F5FBF>/** Window width size */</font>
         PROP_WIDTH = "Width",

         <font color=#3F5FBF>/** Window height size */</font>
         PROP_HEIGHT = "Height",

         <font color=#3F5FBF>/** Terminal standard input stream ID */</font>
         PROP_STDIN_ID = "StdInID",

         <font color=#3F5FBF>/** Terminal standard output stream ID */</font>
         PROP_STDOUT_ID = "StdOutID",

         <font color=#3F5FBF>/** Terminal standard error stream ID */</font>
         PROP_STDERR_ID = "StdErrID";

     <font color=#7F0055>interface</font> TerminalContext {

         <font color=#3F5FBF>/**
          * Get context ID.
          * Same as getProperties().get("ID")
          */</font>
         String getID();

         <font color=#3F5FBF>/**
          * Get process ID of the login process of the terminal.
          * Same as getProperties().get("ProcessID")
          */</font>
         String getProcessID();

         <font color=#3F5FBF>/**
          * Get terminal type.
          * Same as getProperties().get("PtyType")
          */</font>
         String getPtyType();

         <font color=#3F5FBF>/**
          * Get encoding.
          * Same as getProperties().get("Encoding")
          */</font>
         String getEncoding();

         <font color=#3F5FBF>/**
          * Get width.
          * Same as getProperties().get("Width")
          */</font>
         <font color=#7F0055>int</font> getWidth();

         <font color=#3F5FBF>/**
          * Get height.
          * Same as getProperties().get("Height")
          */</font>
         <font color=#7F0055>int</font> getHeight();

         <font color=#3F5FBF>/**
          * Get standard input stream ID of the terminal.
          * Same as getProperties().get("StdInID")
          */</font>
         String getStdInID();

         <font color=#3F5FBF>/**
          * Get standard output stream ID of the terminal.
          * Same as getProperties().get("StdOutID")
          */</font>
         String getStdOutID();

         <font color=#3F5FBF>/**
          * Get standard error stream ID of the terminal.
          * Same as getProperties().get("StdErrID")
          */</font>
         String getStdErrID();

         <font color=#3F5FBF>/**
          * Get all available terminal properties.
          * <font color=#7F9FBF>@return</font> Map 'property name' -&gt; 'property value'
          */</font>
         Map&lt;String, Object&gt; getProperties();

         <font color=#3F5FBF>/**
          * Exit the terminal.
          * <font color=#7F9FBF>@param</font> done - call back interface called when operation is completed.
          * <font color=#7F9FBF>@return</font> pending command handle, can be used to cancel the command.
          */</font>
         IToken exit(DoneCommand done);
     }

     <font color=#3F5FBF>/**
      * Call-back interface to be called when "setWinSize" or "exit" command is complete.
      */</font>
     <font color=#7F0055>interface</font> DoneCommand {
         <font color=#7F0055>void</font> doneCommand(IToken token, Exception error);
     }

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

     <font color=#3F5FBF>/**
      * Call-back interface to be called when "launch" command is complete.
      */</font>
     <font color=#7F0055>interface</font> DoneLaunch {
         <font color=#7F0055>void</font> doneLaunch(IToken token, Exception error, TerminalContext terminal);
     }

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

     <font color=#3F5FBF>/**
      * Exit a terminal.
      * <font color=#7F9FBF>@param</font> id - context ID.
      * <font color=#7F9FBF>@param</font> done - call back interface called when operation is completed.
      * <font color=#7F9FBF>@return</font> pending command handle, can be used to cancel the command.
      */</font>
     IToken exit(String id, DoneCommand done);

     <font color=#3F5FBF>/**
      * Add terminals service event listener.
      * <font color=#7F9FBF>@param</font> listener - event listener implementation.
      */</font>
     <font color=#7F0055>void</font> addListener(TerminalsListener listener);

     <font color=#3F5FBF>/**
      * Remove terminals service event listener.
      * <font color=#7F9FBF>@param</font> listener - event listener implementation.
      */</font>
     <font color=#7F0055>void</font> removeListener(TerminalsListener listener);

     <font color=#3F5FBF>/**
      * Process event listener is notified when a terminal changes or exits.
      * Event are reported only for terminals that were started by 'launch' command.
      */</font>
     <font color=#7F0055>interface</font> TerminalsListener {

         <font color=#3F5FBF>/**
          * Called when a terminal exits.
          * <font color=#7F9FBF>@param</font> terminal_id - terminal context ID
          * <font color=#7F9FBF>@param</font> exit_code - terminal exit code
          */</font>
         <font color=#7F0055>void</font> exited(String terminal_id, <font color=#7F0055>int</font> exit_code);

         <font color=#3F5FBF>/**
          * Called when a terminal windows size changes.
          * <font color=#7F9FBF>@param</font> terminal_id - terminal context ID
          * <font color=#7F9FBF>@param</font> new_width - new terminal width
          * <font color=#7F9FBF>@param</font> new_height - new terminal height
          */</font>
         <font color=#7F0055>void</font> winSizeChanged(String terminal_id, <font color=#7F0055>int</font> new_width, <font color=#7F0055>int</font> new_height);
     }
 }
 </pre>

 </body>
 </html>
	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
	<html>

	<head>
	<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
	<title>Target Communication Framework Services - Processes</title>
	</head>

	<body lang="EN-US">

	<h1>Target Communication Framework Services - Terminals</h1>

	<ul>
	<li><a href="#VersionHistory">Version History</a>
	</li><li><a href="#Overview">Overview</a>
	</li><li><a href="#Cmds">Commands</a>
	<ul>
	<li><a href="#CmdGetContext">Get Context</a>
	</li><li><a href="#CmdExit">Exit</a>
	</li><li><a href="#CmdSetWinSize">SetWinSize</a>
	</li><li><a href="#CmdLaunch">Launch</a>
	</li></ul>
	</li><li><a href="#Events">Events</a>
	</li><li><a href="#API">API</a>
	</li></ul>

	<h1>Processes Service</h1>

	<h2><a name="VersionHistory">Version History</a></h2>

	<table border="1" cellpadding="8">
	<tbody><tr>
	<th>Version
	</th><th>Date
	</th><th>Change
	</th></tr><tr>
	<td>0.1
	</td><td>2010-09-29
	</td><td>Initial contribution
	</td></tr></tbody></table>

	<h2><a name="Overview">Overview</a></h2>

	<p>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. <br>
	</p>

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

	<p>Command and event parameters are encoded
	as zero terminated <a href='TCF JSON.html'>JSON</a> strings.</p>

	<p>The service uses standard format for error reports,
	see <a href="TCF Error Report Format.html">Error Report Format</a>.</p>

	<h2><a name="Cmds">Commands</a></h2>

	<h3><a name="CmdGetContext">Get Context</a></h3>

	<pre><b><font color="#333399" face="Courier New" size="2">
	C • <token> • Terminals • getContext • <string: context ID> •<br></font></b></pre>

	<p>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.
	</p>

	<p>Reply:</p>

	<pre><b><font color="#333399" face="Courier New" size="2">
	R • <token> • <error report> • <context data> •<br><br><i><context data></i>
	⇒ null
	⇒ <i><object></i>
	</font></b></pre>

	<p>Context data object should, at least, contain member
	<b><font color="#333399" face="Courier New" size="2">"ID" : <i><string>.</i></font></b>
	</p>

	<p>Predefined process context properties are:</p>
	<ul>
	<li><code><b><font color="#333399" face="Courier New" size="2">"ID" : <i><string></i></font></b></code>
	- ID of the context, same as getContext command argument.

	<li><code><b><font color="#333399" face="Courier New" size="2">"ProcessID" : <i><string></i></font></b></code>
	- the process ID of the login process of the terminal.

	</li><li><code><b><font color="#333399" face="Courier New" size="2">"PtyType" : <i><string></i></font></b></code>
	- terminal type.

	</li><li><code><b><font color="#333399" face="Courier New" size="2">"Encoding" : <i><string></i></font></b></code>
	- encoding.

	</li><li><code><b><font color="#333399" face="Courier New" size="2">"Width" : <i><integer></i></font></b></code>
	- width of the terminal.

	</li><li><code><b><font color="#333399" face="Courier New" size="2">"Height" : <i><integer></i></font></b></code>
	- height of the terminal.

	</li><li><code><b><font color="#333399" face="Courier New" size="2">"StdInID" : <i><string></i></font></b></code>
	- terminal standard input stream ID.

	</li><li><code><b><font color="#333399" face="Courier New" size="2">"StdOutID" : <i><string></i></font></b></code>
	- terminal standard output stream ID.

	</li><li><code><b><font color="#333399" face="Courier New" size="2">"StdErrID" : <i><string></i></font></b></code>
	- terminal standard error stream ID.
	</li></ul>

	<h3><a name="CmdExit">Exit</a></h3>

	<pre><b><font color="#333399" face="Courier New" size="2">
	C • <token> • Terminals • exit• <string: context ID> •<br></font></b></pre>The command exits the shell and closes the terminal connection.

	<p>Reply:</p>

	<pre><b><font color="#333399" face="Courier New" size="2">
	<span style="font-style: italic;">R • <token> • <error report> •</span><i></i>
	</font></b></pre>

	<h3><a name="CmdSetWinSize">SetWinSize</a></h3>

	<pre><b><font color="#333399" face="Courier New" size="2">
	C • <token> • Terminals • setWinSize • <string: context ID> • <integer: newWidth> • <integer: newHeight> •<br></font></b></pre>

	<p>The command sets the remote terminal windows size.</p>

	<p>Reply:</p>

	<pre><b><font color="#333399" face="Courier New" size="2">
	R • <i><token></i> • <i><error report></i> •<br></font></b></pre>

	<h3><a name="CmdLaunch">Launch</a></h3>

	<pre><b><font color="#333399" face="Courier New" size="2"><br>C • <token> • Terminals • launch• <string: pty type> • <string: encoding> • <string array: environment variables> •<br></font></b><b><i><span style="font-size: 10pt; font-family: "Courier New"; color: rgb(51, 51, 153);" lang="EN-US"><br><string array></span></i><span style="font-size: 10pt; font-family: "Courier New"; color: rgb(51, 51, 153);" lang="EN-US"><br><span style="">    </span></span><span style="font-size: 10pt; font-family: "MS Gothic"; color: rgb(51, 51, 153);">⇒</span><span style="font-size: 10pt; font-family: "Courier New"; color: rgb(51, 51, 153);" lang="EN-US"> null<br><span style="">    </span></span><span style="font-size: 10pt; font-family: "MS Gothic"; color: rgb(51, 51, 153);">⇒</span><span style="font-size: 10pt; font-family: "Courier New"; color: rgb(51, 51, 153);" lang="EN-US"> [ ]<br><span style="">    </span></span><span style="font-size: 10pt; font-family: "MS Gothic"; color: rgb(51, 51, 153);">⇒</span><span style="font-size: 10pt; font-family: "Courier New"; color: rgb(51, 51, 153);" lang="EN-US"> [ <i><string list></i> ]</span></b><br></pre>
	<p class="MsoNormal" style="text-align: left;" align="left"><b><i><span style="font-size: 10pt; font-family: "Courier New"; color: rgb(51, 51, 153);" lang="EN-US"><string list></span></i></b><b><span style="font-size: 10pt; font-family: "Courier New"; color: rgb(51, 51, 153);" lang="EN-US"><br>
	<span style="">    </span></span></b><b><span style="font-size: 10pt; font-family: "MS Gothic"; color: rgb(51, 51, 153);">⇒</span></b><b><span style="font-size: 10pt; font-family: "Courier New"; color: rgb(51, 51, 153);"> <i><span lang="EN-US"><string></span></i><span lang="EN-US"><br>
	<span style="">    </span></span></span></b><b><span style="font-size: 10pt; font-family: "MS Gothic"; color: rgb(51, 51, 153);">⇒</span></b><b><span style="font-size: 10pt; font-family: "Courier New"; color: rgb(51, 51, 153);"> <i><span lang="EN-US"><string list></span></i><span lang="EN-US"> , <i><string></i></span></span></b><b><span style="font-size: 10pt; font-family: 宋体; color: rgb(51, 51, 153);" lang="EN-US"><o:p></o:p></span></b></p>




	<p>The command launches a new terminal connection to the remote machine.
	</p><ul>
	<li><i><string: pty type></i> - requested terminal type for the new terminal.
	</li><li><i><string: encoding></i> - requested terminal type for the new terminal.
	</li><li><i><string array: environment variables></i> - list of environment variables for the terminal.
	</li></ul>

	<p>Reply:</p>

	<pre><b><font color="#333399" face="Courier New" size="2">
	R • <i><token></i> • <i><error report></i> • <i><context data></i> •<br></font></b></pre>

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

	<h2><a name="Events">Events</a></h2>

	<p>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.</p>

	<pre></pre>
	<p><b><font color="#333399" face="Courier New" size="2">
	E • Terminals • exited • <string: terminal ID> • <int: exit code> •</font></b></p>
	Sent when a terminal is exited. "terminal ID" is the ID of the terminal. "exit code" is the terminal exit code.<br>
	<br>
	<p><b><font color="#333399" face="Courier New" size="2">E • Terminals • winSizeChanged • <string: terminal ID> • <int: newWidth> • <int: newHeight> •</font></b></p>
	Sent when a terminal's window size is changed. "terminal ID" is the ID
	of the terminal. "newWidth" is the new width of the terminal,
	"newHight" is the new height of the terminal.<br>

	<h2><a name='API'>API</a></h2>

	<pre>
	<font color=#3F5FBF>/**
	* ITerminalsService allows to launch a new terminal on the remote target system.
	*
	* <font color=#7F9FBF>@noimplement</font> This interface is not intended to be implemented by clients.
	*/</font>
	<font color=#7F0055>public interface</font> ITerminals <font color=#7F0055>extends</font> IService {

	<font color=#3F5FBF>/**
	* This service name, as it appears on the wire - a TCF name of the service.
	*/</font>
	<font color=#7F0055>static final</font> String NAME = "Terminals";

	<font color=#3F5FBF>/**
	* 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
	*
	* <font color=#7F9FBF>@param</font> id - context ID.
	* <font color=#7F9FBF>@param</font> done - call back interface called when operation is completed.
	*/</font>
	IToken getContext(String id, DoneGetContext done);

	<font color=#3F5FBF>/**
	* Client call back interface for getContext().
	*/</font>
	<font color=#7F0055>interface</font> DoneGetContext {
	<font color=#3F5FBF>/**
	* Called when contexts data retrieval is done.
	* <font color=#7F9FBF>@param</font> error - error description if operation failed, null if succeeded.
	* <font color=#7F9FBF>@param</font> context - context data.
	*/</font>
	<font color=#7F0055>void</font> doneGetContext(IToken token, Exception error, TerminalContext context);
	}

	<font color=#3F5FBF>/**
	* Context property names.
	*/</font>
	<font color=#7F0055>static final</font> String
	<font color=#3F5FBF>/** The TCF context ID of the terminal */</font>
	PROP_ID = "ID",

	<font color=#3F5FBF>/** The process ID of the login process of the terminal */</font>
	PROP_PROCESS_ID = "ProcessID",

	<font color=#3F5FBF>/** The PTY type */</font>
	PROP_PTY_TYPE = "PtyType",

	<font color=#3F5FBF>/** The terminal streams encoding */</font>
	PROP_ENCODING = "Encoding",

	<font color=#3F5FBF>/** Window width size */</font>
	PROP_WIDTH = "Width",

	<font color=#3F5FBF>/** Window height size */</font>
	PROP_HEIGHT = "Height",

	<font color=#3F5FBF>/** Terminal standard input stream ID */</font>
	PROP_STDIN_ID = "StdInID",

	<font color=#3F5FBF>/** Terminal standard output stream ID */</font>
	PROP_STDOUT_ID = "StdOutID",

	<font color=#3F5FBF>/** Terminal standard error stream ID */</font>
	PROP_STDERR_ID = "StdErrID";

	<font color=#7F0055>interface</font> TerminalContext {

	<font color=#3F5FBF>/**
	* Get context ID.
	* Same as getProperties().get("ID")
	*/</font>
	String getID();

	<font color=#3F5FBF>/**
	* Get process ID of the login process of the terminal.
	* Same as getProperties().get("ProcessID")
	*/</font>
	String getProcessID();

	<font color=#3F5FBF>/**
	* Get terminal type.
	* Same as getProperties().get("PtyType")
	*/</font>
	String getPtyType();

	<font color=#3F5FBF>/**
	* Get encoding.
	* Same as getProperties().get("Encoding")
	*/</font>
	String getEncoding();

	<font color=#3F5FBF>/**
	* Get width.
	* Same as getProperties().get("Width")
	*/</font>
	<font color=#7F0055>int</font> getWidth();

	<font color=#3F5FBF>/**
	* Get height.
	* Same as getProperties().get("Height")
	*/</font>
	<font color=#7F0055>int</font> getHeight();

	<font color=#3F5FBF>/**
	* Get standard input stream ID of the terminal.
	* Same as getProperties().get("StdInID")
	*/</font>
	String getStdInID();

	<font color=#3F5FBF>/**
	* Get standard output stream ID of the terminal.
	* Same as getProperties().get("StdOutID")
	*/</font>
	String getStdOutID();

	<font color=#3F5FBF>/**
	* Get standard error stream ID of the terminal.
	* Same as getProperties().get("StdErrID")
	*/</font>
	String getStdErrID();

	<font color=#3F5FBF>/**
	* Get all available terminal properties.
	* <font color=#7F9FBF>@return</font> Map 'property name' -> 'property value'
	*/</font>
	Map<String, Object> getProperties();

	<font color=#3F5FBF>/**
	* Exit the terminal.
	* <font color=#7F9FBF>@param</font> done - call back interface called when operation is completed.
	* <font color=#7F9FBF>@return</font> pending command handle, can be used to cancel the command.
	*/</font>
	IToken exit(DoneCommand done);
	}

	<font color=#3F5FBF>/**
	* Call-back interface to be called when "setWinSize" or "exit" command is complete.
	*/</font>
	<font color=#7F0055>interface</font> DoneCommand {
	<font color=#7F0055>void</font> doneCommand(IToken token, Exception error);
	}

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

	<font color=#3F5FBF>/**
	* Call-back interface to be called when "launch" command is complete.
	*/</font>
	<font color=#7F0055>interface</font> DoneLaunch {
	<font color=#7F0055>void</font> doneLaunch(IToken token, Exception error, TerminalContext terminal);
	}

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

	<font color=#3F5FBF>/**
	* Exit a terminal.
	* <font color=#7F9FBF>@param</font> id - context ID.
	* <font color=#7F9FBF>@param</font> done - call back interface called when operation is completed.
	* <font color=#7F9FBF>@return</font> pending command handle, can be used to cancel the command.
	*/</font>
	IToken exit(String id, DoneCommand done);

	<font color=#3F5FBF>/**
	* Add terminals service event listener.
	* <font color=#7F9FBF>@param</font> listener - event listener implementation.
	*/</font>
	<font color=#7F0055>void</font> addListener(TerminalsListener listener);

	<font color=#3F5FBF>/**
	* Remove terminals service event listener.
	* <font color=#7F9FBF>@param</font> listener - event listener implementation.
	*/</font>
	<font color=#7F0055>void</font> removeListener(TerminalsListener listener);

	<font color=#3F5FBF>/**
	* Process event listener is notified when a terminal changes or exits.
	* Event are reported only for terminals that were started by 'launch' command.
	*/</font>
	<font color=#7F0055>interface</font> TerminalsListener {

	<font color=#3F5FBF>/**
	* Called when a terminal exits.
	* <font color=#7F9FBF>@param</font> terminal_id - terminal context ID
	* <font color=#7F9FBF>@param</font> exit_code - terminal exit code
	*/</font>
	<font color=#7F0055>void</font> exited(String terminal_id, <font color=#7F0055>int</font> exit_code);

	<font color=#3F5FBF>/**
	* Called when a terminal windows size changes.
	* <font color=#7F9FBF>@param</font> terminal_id - terminal context ID
	* <font color=#7F9FBF>@param</font> new_width - new terminal width
	* <font color=#7F9FBF>@param</font> new_height - new terminal height
	*/</font>
	<font color=#7F0055>void</font> winSizeChanged(String terminal_id, <font color=#7F0055>int</font> new_width, <font color=#7F0055>int</font> new_height);
	}
	}
	</pre>

	</body>
	</html>