diff options
| author | Eugene Tarassov | 2019-07-24 20:04:23 +0000 |
|---|---|---|
| committer | Eugene Tarassov | 2019-07-24 20:20:07 +0000 |
| commit | e86b66160bab3e7742350b0b5790fe57f772d655 (patch) | |
| tree | a78a19cded95ba70d1e50071d4cbdd90d5c1ebb0 | |
| parent | e1b87d42fd5d2d309fc39bc282765b794484de9a (diff) | |
| download | org.eclipse.tcf-e86b66160bab3e7742350b0b5790fe57f772d655.tar.gz org.eclipse.tcf-e86b66160bab3e7742350b0b5790fe57f772d655.tar.xz org.eclipse.tcf-e86b66160bab3e7742350b0b5790fe57f772d655.zip | |
TCF Docs: improved specifications of TCF services
35 files changed, 897 insertions, 730 deletions
diff --git a/docs/TCF Agent Porting Guide.html b/docs/TCF Agent Porting Guide.html index 1f8171206..719571df5 100644 --- a/docs/TCF Agent Porting Guide.html +++ b/docs/TCF Agent Porting Guide.html @@ -8,12 +8,9 @@ <h1>TCF Agent Porting Guide</h1> - <p> - Copyright (c) 2009, 2015 Wind River Systems, Inc. and others. Made available under the EPL v1.0 - </p> - <p> - Direct comments, questions to the <a href="https://dev.eclipse.org/mailman/listinfo/tcf-dev">tcf-dev@eclipse.org</a> mailing list - </p> +<p>Copyright (c) 2009-2019 Wind River Systems, Inc. and others. Made available under the EPL v1.0<br/> +Agent portion made available under your choice of EPL v1.0 or EDL v1.0 dual-license.</p> +<p>Direct comments, questions to the <a href="https://dev.eclipse.org/mailman/listinfo/tcf-dev">tcf-dev@eclipse.org</a> mailing list</p> <h2>Table of Contents</h2> <ul> diff --git a/docs/TCF Error Report Format.html b/docs/TCF Error Report Format.html new file mode 100644 index 000000000..8726b1be4 --- /dev/null +++ b/docs/TCF Error Report Format.html @@ -0,0 +1,162 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<html> +<head> + <title>Error Report Format</title> +</head> + +<body lang='EN-US'> + +<h1>Error Report Format</h1> + +<p>Copyright (c) 2007-2019 Wind River Systems, Inc. and others. Made available under the EPL v1.0<br/> +Agent portion made available under your choice of EPL v1.0 or EDL v1.0 dual-license.</p> +<p>Direct comments, questions to the <a href="https://dev.eclipse.org/mailman/listinfo/tcf-dev">tcf-dev@eclipse.org</a> mailing list</p> + +<h2>Table of Contents</h2> +<ul> + <li><a href='#VersionHistory'>Version History</a></li> + <li><a href='#ErrorFormat'>Error Report Format</a></li> +</ul> + +<h2><a name='VersionHistory'>Version History</a></h2> + +<table border=1 cellpadding=8> + <tr> + <th>Version</th> + <th>Date</th> + <th>Change</th> + </tr> + <tr> + <td>0.1</td> + <td>2008-01-10</td> + <td>Initial contribution</td> + </tr> + <tr> + <td>1.0</td> + <td>2008-05-06</td> + <td>Approved</td> + </tr> + <tr> + <td>1.1</td> + <td>2008-06-25</td> + <td>Enhanced error reporting format, see <a href='http://bugs.eclipse.org/bugs/show_bug.cgi?id=232410'>Bug 232410</a></td> + </tr> +</table> + + +<h2><a name='ErrorFormat'>Error Report Format</a></h2> + +<p>TCF standard services use same format for error reporting:</p> + +<pre><b><font face="Courier New" size="2" color="#333399"> +<i><error report></i> + ⇒ + ⇒ null + ⇒ <i><object: error description></i> +</font></b></pre> + +<p>Error reports use JSON for message encoding, see +<a href='TCF JSON.html'>JSON - Preferred Marshaling</a>.</p> + +<p>Empty or null error report means success. Error description provides error details, including +error code and a short, localizable, human readable explanation of the error.</p> + +<p>Error description properties are:</p> +<dl> + <dt><b><font face="Courier New" size="2" color="#333399">"Code" : <i><integer></i></font></b></dt> + <dd>Error code. Can belong to one of predefined ranges: + <ul> + <li> 0x0-0xffff Standard TCF codes, includes a limited subset of POSIX errors, and OTHER error code, which + can be used together with "AltCode"</li> + <li> 0x10000-0x1ffff Service specific codes</li> + <li> 0x20000-0x2ffff Reserved codes - will never be used by the TCF standard</li> + </ul> + </dd> + + <dt><b><font face="Courier New" size="2" color="#333399">"Time" : <i><integer></i></font></b></dt> + <dd> Error timestamp, in milliseconds since midnight, January 1, 1970 UTC</dd> + + <dt><b><font face="Courier New" size="2" color="#333399">"Service" : <i><string></i></font></b></dt> + <dd> Name of the service that reported the error. Required when "Code" is service specific code.</dd> + + <dt><b><font face="Courier New" size="2" color="#333399">"Format" : <i><string></i></font></b></dt> + <dd> Error description format supports separation between constant and variable parts + of error message ("Format" and "Params"). This is done to support localization. + Format string is expected to allow translation into foreign languages by means of string table lookup. + The format string syntax is defined in the Java language library + <b><font face="Courier New" size="2">java.text.MessageFormat</font></b>. + In order to simplify clients written in other languages, only a subset of the syntax is supported: + <ul> + <li> Supported format types: (none), number</li> + <li> Supported format styles: + <ul> + <li> number: (none), "integer", "percent"</li> + </ul> + </li> + </ul> + </dd> + + <dt><b><font face="Courier New" size="2" color="#333399">"Params" : <i><array></i></font></b></dt> + <dd> An array of values to be used together with "Format" to create the error message.</dd> + + <dt><b><font face="Courier New" size="2" color="#333399">"Severity" : <i><integer></i></font></b></dt> + <dd> Predefined severity values: + <ul> + <li>0 - error (default)</li> + <li>1 - warning</li> + <li>2 - fatal</li> + </ul> + </dd> + <dt><b><font face="Courier New" size="2" color="#333399">"AltCode" : <i><integer></i></font></b></dt> + <dd> Alternative error code. This can be used to represent, + for example, OS, POSIX, or other vendor specific error codes</dd> + + <dt><b><font face="Courier New" size="2" color="#333399">"AltOrg" : <i><string></i></font></b></dt> + <dd> ID of organization defining "AltCode", for example "Linux", "VxWorks", "Wind River", etc</dd> + + <dt><b><font face="Courier New" size="2" color="#333399">"CausedBy" : <i><object: error description></i></font></b></dt> + <dd> A nested error description. Can be used to describe a root cause of this error.</dd> +</dl> + +<p>All fields except "Code" are optional.</p> + +<p>Standard error codes:</p> +<pre><code> + OTHER = 1 + JSON_SYNTAX = 2 + PROTOCOL = 3 + BUFFER_OVERFLOW = 4 + CHANNEL_CLOSED = 5 + COMMAND_CANCELLED = 6 + UNKNOWN_PEER = 7 + BASE64 = 8 + EOF = 9 + ALREADY_STOPPED = 10 + ALREADY_EXITED = 11 + ALREADY_RUNNING = 12 + ALREADY_ATTACHED = 13 + IS_RUNNING = 14 + INV_DATA_SIZE = 15 + INV_CONTEXT = 16 + INV_ADDRESS = 17 + INV_EXPRESSION = 18 + INV_FORMAT = 19 + INV_NUMBER = 20 + INV_DWARF = 21 + SYM_NOT_FOUND = 22 + UNSUPPORTED = 23 + INV_DATA_TYPE = 24 + INV_COMMAND = 25 +</code></pre> + +<p>Service specific error code definitions, if any, are part of service specfications. +Standard and service specific error codes can be extended over time. A +client that does not recognize a specific error code should treat it in the +same way as "OTHER".</p> + +<p>For encoding of <b><i><font face="Courier New" size="2" color="#333399"><object></font></i></b>, +<b><i><font face="Courier New" size="2" color="#333399"><string></font></i></b>, etc., see +<a href='TCF JSON.html'>JSON - Preferred Marshaling</a>.</p> + +</body> +</html> diff --git a/docs/TCF Getting Started.html b/docs/TCF Getting Started.html index 2583e4ada..72a8776ed 100644 --- a/docs/TCF Getting Started.html +++ b/docs/TCF Getting Started.html @@ -8,8 +8,9 @@ <h1>Target Communication Framework: Getting Started</h1> -<p>Copyright (c) 2007, 2017 Wind River Systems, Inc. and others. Made available under the EPL v1.0 -<p>Direct comments, questions to the <a href="https://dev.eclipse.org/mailman/listinfo/tcf-dev">tcf-dev@eclipse.org</a> mailing list +<p>Copyright (c) 2007-2019 Wind River Systems, Inc. and others. Made available under the EPL v1.0<br/> +Agent portion made available under your choice of EPL v1.0 or EDL v1.0 dual-license.</p> +<p>Direct comments, questions to the <a href="https://dev.eclipse.org/mailman/listinfo/tcf-dev">tcf-dev@eclipse.org</a> mailing list</p> <h2>Table of Contents</h2> <ul> diff --git a/docs/TCF JSON.html b/docs/TCF JSON.html new file mode 100644 index 000000000..23f5c1684 --- /dev/null +++ b/docs/TCF JSON.html @@ -0,0 +1,157 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<html> +<head> + <title>JSON - Preferred Marshaling</title> +</head> +<body lang='EN-US'> + +<h1>JSON - Preferred Marshaling</h1> + +<p>The TCF message data format is service specific. Since service specifications are +separate from the protocol specification, a service designer can choose any data format that +suits the service requirements best. However, to promote better compatibility and to +simplify service design and implementation, we recommend using <b>JSON</b> for data formatting.</p> + +<p><b>JSON</b> (pronounced like the +English given name <i>Jason</i>), which stands for "<b>J</b>ava<b>S</b>cript <b>O</b>bject +<b>N</b>otation", is a lightweight, text-based, language-independent computer data +interchange format. <b>JSON</b> is a subset of the object literal notation of JavaScript +but its use does not require JavaScript.</p> + +<p><b>JSON</b> represents data with the same basic types that programming languages +use. <b>JSON</b>'s basic types are:</p> + +<ul type='disc'> + <li>Number (integer, real, or floating-point) + + <li>String (double-quoted with backslash escapement) + + <li>Boolean (<code>true</code> and <code>false</code>) + + <li>Array (an ordered sequence of values) + + <li>Object (collection of key/value pairs) + + <li><code>null</code> + </ul> + +<p>The structures used in most programming languages easily map directly onto JSON's +structures, and back again.</p> + +<p>JSON maps data onto Unicode string. Then the string is mapped onto array of bytes +using UTF-8 encoding.</p> + +<p>JSON specification:</p> + +<pre><b><font face="Courier New" size=2 color=#333399> +<i><object></i> + ⇒ {} + ⇒ { <i><members></i> } + +<i><members></i> + ⇒ <i><string></i> : <i><value></i> + ⇒ <i><members></i> , <i><string></i> : <i><value></i> + +<i><array></i> + ⇒ [] + ⇒ [ <i><elements></i> ] + +<i><elements></i> + ⇒ <i><value></i> + ⇒ <i><elements</i>> , <i><value></i> + +<i><value></i> + ⇒ <i><string></i> + ⇒ <i><number></i> + ⇒ <i><object></i> + ⇒ <i><array></i> + ⇒ <i><boolean></i> + ⇒ null + +<i><boolean></i> + ⇒ true + ⇒ false + +<i><string></i> + ⇒ "" + ⇒ " <i><chars></i> " + +<i><chars></i> + ⇒ <i><char></i> + ⇒ <i><chars> <char></i> + +<i><char</i>> + ⇒ <i><any Unicode except " or \ or control></i> + ⇒ \"<i></i> + ⇒ \\<i></i> + ⇒ \/<i></i> + ⇒ \b<i></i> + ⇒ \f<i></i> + ⇒ \n<i></i> + ⇒ \r<i></i> + ⇒ \t<i></i> + ⇒ \u <i><four-hex-digits></i> + +<i><number</i>> + ⇒ <i><int></i> + ⇒ <<i>int> <fraction></i> + ⇒ <<i>int> <exponent></i> + ⇒ <<i>int> <fraction> <exponent></i> + +<i><int></i> + ⇒ <i><digit></i> + ⇒ <<i>digit 1-9> <digits></i> + ⇒ - <<i>digit></i> + ⇒ - <<i>digit 1-9> <digits</i>> + +<i><fraction></i> + ⇒ . <i><digits></i> + +<i><exponent></i> + ⇒ <i><e></i> <i><digits></i> + +<i><digits></i> + ⇒ <i><digit></i> + ⇒ <<i>digits></i> <<i>digit></i> + +<i><e></i> + ⇒ e + ⇒ e+ + ⇒ e- + ⇒ E + ⇒ E+ + ⇒ E- + +</font></b></pre> + +<p>See <a href='http://www.json.org/'>www.json.org</a> for more details.</p> + +<h2><a name='JSONExamples'>Examples</a></h2> + +<p>This is a JSON array containing two objects:</p> + +<pre> + [ + { + "Precision": "zip", + "Latitude": 37.7668, + "Longitude": -122.3959, + "City": "SAN FRANCISCO", + "State": "CA", + "Zip": "94107", + "Country": "US" + }, + { + "Precision": "zip", + "Latitude": 37.371991, + "Longitude": -122.026020, + "City": "SUNNYVALE", + "State": "CA", + "Zip": "94085", + "Country": "US" + } + ] +</pre> + +</body> +</html> diff --git a/docs/TCF Linux Agent Prototype.html b/docs/TCF Linux Agent Prototype.html index 90156d408..f8895c214 100644 --- a/docs/TCF Linux Agent Prototype.html +++ b/docs/TCF Linux Agent Prototype.html @@ -9,12 +9,9 @@ <h1>TCF Agent Prototype Implementation</h1> -<p> - Copyright (c) 2009 Wind River Systems, Inc. Made available under the EPL v1.0 -</p> -<p> - Direct comments, questions to the <a href="https://dev.eclipse.org/mailman/listinfo/tcf-dev">tcf-dev@eclipse.org</a> mailing list -</p> +<p>Copyright (c) 2007-2019 Wind River Systems, Inc. and others. Made available under the EPL v1.0<br/> +Agent portion made available under your choice of EPL v1.0 or EDL v1.0 dual-license.</p> +<p>Direct comments, questions to the <a href="https://dev.eclipse.org/mailman/listinfo/tcf-dev">tcf-dev@eclipse.org</a> mailing list</p> <h2>Table of Contents</h2> <ul> @@ -203,7 +200,7 @@ Any thread can queue new events.</p> <h3>JSON Library</h3> <p>The module contains utility functions for parsing and generating of JSON text. -TCF standard services use JSON as messages format. See <a href='TCF Specification.html#JSON'>JSON - Preferred Marshaling</a> +TCF standard services use JSON as messages format. See <a href='TCF JSON.html'>JSON - Preferred Marshaling</a> for JSON description.</p> <p>Files:</p> <ul> diff --git a/docs/TCF Lua Integration.html b/docs/TCF Lua Integration.html index a99b0ae5c..5818f6b1d 100644 --- a/docs/TCF Lua Integration.html +++ b/docs/TCF Lua Integration.html @@ -8,8 +8,9 @@ <h1>Target Communication Framework: Lua Integration</h1> -<p>Copyright (c) 2007, 2012 Wind River Systems, Inc. Made available under the EPL v1.0 -<p>Direct comments, questions to the <a href="https://dev.eclipse.org/mailman/listinfo/tcf-dev">tcf-dev@eclipse.org</a> mailing list +<p>Copyright (c) 2007-2019 Wind River Systems, Inc. and others. Made available under the EPL v1.0<br/> +Agent portion made available under your choice of EPL v1.0 or EDL v1.0 dual-license.</p> +<p>Direct comments, questions to the <a href="https://dev.eclipse.org/mailman/listinfo/tcf-dev">tcf-dev@eclipse.org</a> mailing list</p> <h2><a name='TcfLua'>TCF Integration with Lua</a></h2> diff --git a/docs/TCF Service - Breakpoints.html b/docs/TCF Service - Breakpoints.html index 2c0afe0b5..7fba67a37 100644 --- a/docs/TCF Service - Breakpoints.html +++ b/docs/TCF Service - Breakpoints.html @@ -118,7 +118,7 @@ channels, target agent should treat it as single breakpoint with multiple refere is removed when all referring channels are closed. <p>The service uses standard format for error reports, -see <a href='TCF Services.html#ErrorFormat'>Error Report Format</a>.</p> +see <a href='TCF Error Report Format.html'>Error Report Format</a>.</p> <h2><a name='Cmds'>Commands</a></h2> diff --git a/docs/TCF Service - Context Query.html b/docs/TCF Service - Context Query.html index c7bd91202..fb83240ed 100755 --- a/docs/TCF Service - Context Query.html +++ b/docs/TCF Service - Context Query.html @@ -57,7 +57,7 @@ starts with a "/" the first part of the query must match a child of the root of the context tree.</p> <p>The service uses standard format for error reports, -see <a href='TCF Services.html#ErrorFormat'>Error Report Format</a>.</p> +see <a href='TCF Error Report Format.html'>Error Report Format</a>.</p> <h2><a name='SyntaxandSemantics'>Syntax and Semantics</a></h2> diff --git a/docs/TCF Service - Context Reset.html b/docs/TCF Service - Context Reset.html index 6849c3e90..857a79466 100644 --- a/docs/TCF Service - Context Reset.html +++ b/docs/TCF Service - Context Reset.html @@ -39,7 +39,7 @@ </p> <p> The service uses standard format for error reports, - see <a href='TCF Services.html#ErrorFormat'>Error Report Format</a>. + see <a href='TCF Error Report Format.html'>Error Report Format</a>. </p> <h2><a name='Cmds'>Commands</a></h2> <h3><a name='CmdGetCapabilities'>Get Capabilities</a></h3> diff --git a/docs/TCF Service - Debug Print.html b/docs/TCF Service - Debug Print.html index 538a3c663..15e933c00 100644 --- a/docs/TCF Service - Debug Print.html +++ b/docs/TCF Service - Debug Print.html @@ -46,7 +46,7 @@ </p> <p>The service uses standard format for error reports, -see <a href='TCF Services.html#ErrorFormat'>Error Report Format</a>.</p> +see <a href='TCF Error Report Format.html'>Error Report Format</a>.</p> <h2><a name='Cmds'>Commands</a></h2> diff --git a/docs/TCF Service - Diagnostics.html b/docs/TCF Service - Diagnostics.html index 09bf6e08e..85508f8de 100644 --- a/docs/TCF Service - Diagnostics.html +++ b/docs/TCF Service - Diagnostics.html @@ -48,7 +48,7 @@ communication channel functionality and reliability.</p> <p>The service uses standard format for error reports, -see <a href='TCF Services.html#ErrorFormat'>Error Report Format</a>.</p> +see <a href='TCF Error Report Format.html'>Error Report Format</a>.</p> <h2><a name='Cmds'>Commands</a></h2> diff --git a/docs/TCF Service - Disassembly.html b/docs/TCF Service - Disassembly.html index 84b16d61c..4f7e2b1f2 100644 --- a/docs/TCF Service - Disassembly.html +++ b/docs/TCF Service - Disassembly.html @@ -41,7 +41,7 @@ <p>While disassembly is dependent upon a specific processor architecture, the memory from which it is derived is not. So for a given memory context, or buffer, the specified ISA used to disassemble the memory bytes is subjective to the Tool or user.</p> <p>The service uses standard format for error reports, -see <a href='TCF Services.html#ErrorFormat'>Error Report Format</a>.</p> +see <a href='TCF Error Report Format.html'>Error Report Format</a>.</p> <h2><a name='Cmds'>Commands</a></h2> diff --git a/docs/TCF Service - Expressions.html b/docs/TCF Service - Expressions.html index 118f9d960..a86cd1078 100644 --- a/docs/TCF Service - Expressions.html +++ b/docs/TCF Service - Expressions.html @@ -61,7 +61,7 @@ it can be evaluated multiple times, for example, each time the target is suspend </ol> <p>The service uses standard format for error reports, -see <a href='TCF Services.html#ErrorFormat'>Error Report Format</a>.</p> +see <a href='TCF Error Report Format.html'>Error Report Format</a>.</p> <h2><a name='Cmds'>Commands</a></h2> diff --git a/docs/TCF Service - File System.html b/docs/TCF Service - File System.html index 01ddbcad4..894dc21cc 100644 --- a/docs/TCF Service - File System.html +++ b/docs/TCF Service - File System.html @@ -175,7 +175,7 @@ Tools and targets can define additional attributes. Predefined attributes are:</ <h2><a name='ErrorCodes'>Error codes</a></h2> <p>The service uses standard format for error reports, -see <a href='TCF Services.html#ErrorFormat'>Error Report Format</a>.</p> +see <a href='TCF Error Report Format.html'>Error Report Format</a>.</p> <p>Currently, the following values are defined for service specific error codes (other values may be defined by future versions of this protocol):</p> diff --git a/docs/TCF Service - Line Numbers.html b/docs/TCF Service - Line Numbers.html index d7203bd83..fed09b48e 100644 --- a/docs/TCF Service - Line Numbers.html +++ b/docs/TCF Service - Line Numbers.html @@ -120,7 +120,7 @@ continues range of code addresses. Code Area data object is collection of area p </font></b></pre> <p>The service uses standard format for error reports, -see <a href='TCF Services.html#ErrorFormat'>Error Report Format</a>.</p> +see <a href='TCF Error Report Format.html'>Error Report Format</a>.</p> <h2><a name='Cmds'>Commands</a></h2> diff --git a/docs/TCF Service - Locator.html b/docs/TCF Service - Locator.html new file mode 100644 index 000000000..fcce86b11 --- /dev/null +++ b/docs/TCF Service - Locator.html @@ -0,0 +1,435 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<html> +<head> + <title>Target Communication Framework Services - Locator</title> +</head> +<body lang='EN-US'> + +<h1>Target Communication Framework Services - Locator</h1> + +<ul> + <li><a href='#VersionHistory'>Version History</a> + <li><a href='#Overview'>Overview</a> + <li><a href='#Cmds'>Commands</a> + <li><a href='#Interfaces'>Interfaces</a> + <li><a href='#API'>API</a> +</ul> + +<h1>Locator Service</h1> + +<h2><a name='VersionHistory'>Version History</a></h2> + +<table border=1 cellpadding=8> + <tr> + <th>Version + <th>Date + <th>Change + <tr> + <td>1.0 + <td>2008-05-06 + <td>Initial +</table> + +<h2><a name='Overview'>Overview</a></h2> + +<p>The Locator service uses the transport layer to search for peers and to collect data about +the peer's attributes and capabilities (services). The discovery mechanism depends on the transport +protocol and is part of that protocol handler. Targets, known by other hosts, are +added to local list of peers. <font color=red>Security? </font>Automatically discovered +targets require no further configuration. Additional targets can be configured manually.</p> + +<p>All TCF peers must implement Locator service. The implementation is part of the framework itself. +It is the only required service, all other services are optional and, formally, not part of the framework.</p> + +<h2><a name='LocatorPeer'>Peer Attributes</a></h2> + +<p><i><object: peer data></i> is collection of peer attributes. It should, at least, contain member +<b><font face="Courier New" size=2 color=#333399>"ID" : <i><string></i></font></b>. +It can also contain a number of components describing peer properties and capabilities. +Predefined attributes are:</p> + +<ul> + <li><code><b><font face="Courier New" size=2 color=#333399>"ID" : <i><string></i></font></b></code> + - unique ID of the peer. + + <li><code><b><font face="Courier New" size=2 color=#333399>"ServiceManagerID" : <i><string></i></font></b></code> + - unique ID of service manager that is represented by this peer. + + <li><code><b><font face="Courier New" size=2 color=#333399>"AgentID" : <i><string></i></font></b></code> + - agent unique ID. + + <li><code><b><font face="Courier New" size=2 color=#333399>"Name" : <i><string></i></font></b></code> + - human readable peer name. + + <li><code><b><font face="Courier New" size=2 color=#333399>"OSName" : <i><string></i></font></b></code> + - peer OS name, if applicable. + + <li><code><b><font face="Courier New" size=2 color=#333399>"TransportName" : <i><string></i></font></b></code> + - name of a trasport protocol to use to connect to this peer, for example: TCP. + + <li><code><b><font face="Courier New" size=2 color=#333399>"Host" : <i><string></i></font></b></code> + - peer host name, if transport is TCP or UDP. + + <li><code><b><font face="Courier New" size=2 color=#333399>"Aliases" : <i><string></i></font></b></code> + - peer host name aliases, if transport is TCP or UDP. + + <li><code><b><font face="Courier New" size=2 color=#333399>"Addresses" : <i><string></i></font></b></code> + - peer IP addresses, if transport is TCP or UDP. + + <li><code><b><font face="Courier New" size=2 color=#333399>"Port" : <i><string></i></font></b></code> + - peer port number, if transport is TCP or UDP. +</ul> + +<p>Most clients do not need to know any peer attributes other than ID and Name. Clients are expected to call the IPeer.openChannel() +method and let the framework check peer attributes and create appropriate communication channel that is best suited for +communication with the peer. After a channel is established, a client can learn the peer capabilities by looking +at what services it implements (use IChannel.getRemoteServices() method to get a map of services).</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='CmdRedirect'>redirect</a></h3> + +<pre><b><font face="Courier New" size=2 color=#333399> +C • <i><token></i> • Locator • redirect • <i><peer></i> • + +<i><peer></i> + ⇒ <i><string: peer ID></i> + ⇒ <i><object: peer data></i> +</font></b></pre> + +<p>The command redirects the channel to become connected to the given peer. +The Locator service starts acting as a proxy.</p> + +<p>Reply:</p> + +<pre><b><font face="Courier New" size=2 color=#333399> +R • <i><token></i> • <i><error report></i> • +</font></b></pre> + +<h3><a name='CmdSync'>sync</a></h3> + +<pre><b><font face="Courier New" size=2 color=#333399> +C • <i><token></i> • Locator • sync • +</font></b></pre> + +<p>The sync command does nothing and simply returns back an empty result. The command is used for +cross channel synchronization. Since commands are executed in order they were issued, by waiting +for sync result a client makes sure that all commands, that were issued before sync, are fully processed.</p> + +<p>Reply:</p> + +<pre><b><font face="Courier New" size=2 color=#333399> +R • <i><token></i> • +</font></b></pre> + +<h3><a name='CmdGetAgentID'>Get Agent ID</a></h3> + +<pre><b><font face="Courier New" size=2 color=#333399> +C • <i><token></i> • Locator • getAgentID • +</font></b></pre> + +<p>Get agent ID of the agent providing the locator service. +The agent ID can be used to identify the agent among all the peers.</p> + +<p>Reply:</p> + +<pre><b><font face="Courier New" size=2 color=#333399> +R • <i><token></i> • <i><error report></i> • <i><string: agent ID></i> • +</font></b></pre> + +<h2><a name='LocatorEvents'>Locator Service Events</a></h2> + +<pre><b><font face="Courier New" size=2 color=#333399> +E • Locator • Hello • <i><array: service names></i> • +E • Locator • peerAdded • <i><object: peer data></i> • +E • Locator • peerChanged • <i><object: peer data></i> • +E • Locator • peerRemoved • <i><string: peer ID></i> • +E • Locator • peerHeartBeat • <i><string: peer ID></i> • +</font></b></pre> + +<dl> + <dt><b>Hello</b> + <dd>is the first message sent by the framework after establishing a communication channel. + The message lets other side of the channel know capabilities of this peer. + Message data consists of an array of service names that are provided by the peer. + The service name list is a complete and unambiguous declaration of peer's capabilities. + To avoid ambiguity, different services (even slightly different, like versions of same service) + must have different names. Framework delays all other communications between peers until exchange + of Hello messages is complete. + <dt><b>peerAdded</b> + <dd>is sent when the service discovers a new peer. + <dt><b>peerChanged</b> + <dd>is sent when peer attributes change. + <dt><b>peerRemoved</b> + <dd>is sent when the service deletes information about a peer. + <dt><b>peerHeartBeat</b> + <dd>is sent periodically when the service receives a communication from the peer + that confirms that the peer is still alive. +</dl> + +<h2><a name='Interfaces'>Interfaces</a></h2> + +<pre> +<font color=#3F5FBF>/** + * Base interface for all service interfaces. A client can get list of available services + * by calling IChannel.getLocalServices() and IChannel.getRemoteServices(). + * + * Remote services are represented by a proxy objects that implement service interfaces by + * translating method calls to TCF messages and sending them to a remote peer. + * When communication channel is open, TCF automatically creates proxies for standard services. + * TCF clients can provides addition proxies for non-standard services by calling IChannel.setServiceProxy(). + */</font> +<font color=#7F0055>public</font> interface IService { + + <font color=#3F5FBF>/** + * Get unique name of this service. + */</font> + String getName(); +} + +<font color=#3F5FBF>/** + * Both hosts and targets are represented by objects + * implementing IPeer interface. A peer can act as host or + * target depending on services it implements. + * List of currently known peers can be retrieved by + * calling ILocator.getPeers() + * + * A TCF agent houses one or more service managers. A service manager has a one or more + * services to expose to the world. The service manager creates one or more peers + * to represent itself, one for every access path the agent is + * reachable by. For example, in agents accessible via TCP/IP, the + * service manger would create a peer for every subnet it wants to participate in. + * All peers of particular service manager represent identical sets of services. + * + * @noimplement This interface is not intended to be implemented by clients. + * Client can extends the abstract IPeer implementation: AbstractPeer. + */</font> +<font color=#7F0055>public interface</font> IPeer { + + <font color=#3F5FBF>/** + * Peer property names. Implementation can define additional properties. + */</font> + <font color=#7F0055>static final</font> String + <font color=#3F5FBF>/** Peer unique ID */</font> + <i><font color=#0000C0>ATTR_ID</font></i> = <font color=#2A00FF>"ID"</font>, + + <font color=#3F5FBF>/** Unique ID of service manager that is represented by this peer */</font> + <i><font color=#0000C0>ATTR_SERVICE_MANGER_ID</font></i> = <font color=#2A00FF>"ServiceManagerID"</font>, + + <font color=#3F5FBF>/** Agent unique ID */</font> + <i><font color=#0000C0>ATTR_AGENT_ID</font></i> = <font color=#2A00FF>"AgentID"</font>, + + <font color=#3F5FBF>/** Peer name */</font> + <i><font color=#0000C0>ATTR_NAME</font></i> = <font color=#2A00FF>"Name"</font>, + + <font color=#3F5FBF>/** Name of the peer operating system */</font> + <i><font color=#0000C0>ATTR_OS_NAME</font></i> = <font color=#2A00FF>"OSName"</font>, + + <font color=#3F5FBF>/** Transport name, for example TCP, SSL */</font> + <i><font color=#0000C0>ATTR_TRANSPORT_NAME</font></i> = <font color=#2A00FF>"TransportName"</font>, + + <font color=#3F5FBF>/** If present, indicates that the peer can forward traffic to other peers */</font> + <i><font color=#0000C0>ATTR_PROXY</font></i> = <font color=#2A00FF>"Proxy"</font>, + + <font color=#3F5FBF>/** Host DNS name or IP address */</font> + <i><font color=#0000C0>ATTR_IP_HOST</font></i> = <font color=#2A00FF>"Host"</font>, + + <font color=#3F5FBF>/** Optional list of host aliases */</font> + <i><font color=#0000C0>ATTR_IP_ALIASES</font></i> = <font color=#2A00FF>"Aliases"</font>, + + <font color=#3F5FBF>/** Optional list of host addresses */</font> + <i><font color=#0000C0>ATTR_IP_ADDRESSES</font></i> = <font color=#2A00FF>"Addresses"</font>, + + <font color=#3F5FBF>/** IP port number, must be decimal number */</font> + <i><font color=#0000C0>ATTR_IP_PORT</font></i> = <font color=#2A00FF>"Port"</font>; + + + <font color=#3F5FBF>/** + * <font color=#7F9FBF>@return</font> map of peer attributes + */</font> + Map<String, String> getAttributes(); + + <font color=#3F5FBF>/** + * <font color=#7F9FBF>@return</font> peer unique ID, same as getAttributes().get(ATTR_ID) + */</font> + String getID(); + + <font color=#3F5FBF>/** + * <font color=#7F9FBF>@return</font> service manager unique ID, same as getAttributes().get(ATTR_SERVICE_MANAGER_ID) + */</font> + String getServiceManagerID(); + + <font color=#3F5FBF>/** + * <font color=#7F9FBF>@return</font> agent unique ID, same as getAttributes().get(ATTR_AGENT_ID) + */</font> + String getAgentID(); + + <font color=#3F5FBF>/** + * <font color=#7F9FBF>@return</font> peer name, same as getAttributes().get(ATTR_NAME) + */</font> + String getName(); + + <font color=#3F5FBF>/** + * <font color=#7F9FBF>@return</font> agent OS name, same as getAttributes().get(ATTR_OS_NAME) + */</font> + String getOSName(); + + <font color=#3F5FBF>/** + * <font color=#7F9FBF>@return</font> transport name, same as getAttributes().get(ATTR_TRANSPORT_NAME) + */</font> + String getTransportName(); + + <font color=#3F5FBF>/** + * Open channel to communicate with this peer. + * Note: the channel is not fully open yet when this method returns. + * It's state is IChannel.STATE_OPENNING. + * Protocol.Listener will be called when the channel will be opened or closed. + */</font> + IChannel openChannel() <font color=#7F0055>throws</font> IOException; +} +</pre> + +<h2><a name='API'>API</a></h2> + +<pre> +<font color=#3F5FBF>/** + * ILocator service uses transport layer to search for peers and to collect data about + * peer's attributes and capabilities (services). Discovery mechanism depends on transport protocol + * and is part of that protocol handler. Targets, known to other hosts, can be found through + * remote instances of ILocator service. Automatically discovered targets require no further + * configuration. Additional targets can be configured manually. + * + * Clients should use Protocol.getLocator() to obtain local instance of ILocator, + * then ILocator.getPeers() can be used to get list of available peers (hosts and targets). + * + * <font color=#7F9FBF>@noimplement</font> This interface is not intended to be implemented by clients. + */</font> +<font color=#7F0055>public interface</font> ILocator <font color=#7F0055>extends</font> IService { + + <font color=#7F0055>static final</font> String NAME = "Locator"; + + <font color=#3F5FBF>/** + * Peer data retention period in milliseconds. + */</font> + <font color=#7F0055>static final</font> <font color=#7F0055>long</font> DATA_RETENTION_PERIOD = 60 * 1000; + + <font color=#3F5FBF>/** + * Auto-configuration protocol version. + */</font> + static char CONF_VERSION = '2'; + + <font color=#3F5FBF>/** + * Auto-configuration command and response codes. + */</font> + <font color=#7F0055>static final int</font> + CONF_REQ_INFO = 1, + CONF_PEER_INFO = 2, + CONF_REQ_SLAVES = 3, + CONF_SLAVES_INFO = 4, + CONF_PEERS_REMOVED = 5; + + <font color=#3F5FBF>/** + * <font color=#7F9FBF>@return</font> Locator service name: "Locator" + */</font> + String getName(); + + <font color=#3F5FBF>/** + * Get map (ID -> IPeer) of available peers (hosts and targets). + * The method return cached (currently known to the framework) list of peers. + * The list is updated according to event received from transport layer + */</font> + Map<String,IPeer> getPeers(); + + <font color=#3F5FBF>/** + * Redirect this service channel to given peer using this service as a proxy. + * <font color=#7F9FBF>@param</font> peer_id - Peer ID. + */</font> + IToken redirect(String peer_id, DoneRedirect done); + + <font color=#3F5FBF>/** + * Redirect this service channel to given peer using this service as a proxy. + * <font color=#7F9FBF>@param</font> peer - Peer attributes. + */</font> + IToken redirect(Map<String,String> peer, DoneRedirect done); + + <font color=#7F0055>interface</font> DoneRedirect { + <font color=#7F0055>void</font> doneRedirect(IToken token, Exception error); + } + + <font color=#3F5FBF>/** + * Call back after TCF messages sent to this target up to this moment are delivered. + * This method is intended for synchronization of messages + * across multiple channels. + * + * Note: Cross channel synchronization can reduce performance and throughput. + * Most clients don't need channel synchronization and should not call this method. + * + * <font color=#7F9FBF>@param</font> done will be executed by dispatch thread after communication + * messages are delivered to corresponding targets. + * + * This is internal API, TCF clients should use {@code org.eclipse.tcf.protocol.Protocol}. + */</font> + IToken sync(DoneSync done); + + <font color=#7F0055>interface</font> DoneSync { + <font color=#7F0055>void</font> doneSync(IToken token); + } + + <font color=#3F5FBF>/** + * Get agent ID of the agent providing the locator service. + * + * The agent ID can be used to identify the agent among all the peers + * returned by {@link #getPeers()}. + */</font> + IToken getAgentID(DoneGetAgentID done); + + <font color=#7F0055>interface</font> DoneGetAgentID { + <font color=#7F0055>void</font> doneGetAgentID(IToken token, Exception error, String agentID); + } + + <font color=#3F5FBF>/** + * Add a listener for ILocator service events. + */</font> + <font color=#7F0055>void</font> addListener(LocatorListener listener); + + <font color=#3F5FBF>/** + * Remove a listener for ILocator service events. + */</font> + <font color=#7F0055>void</font> removeListener(LocatorListener listener); + + <font color=#3F5FBF>/** + * ILocator service event listener interface + */</font> + <font color=#7F0055>interface</font> LocatorListener { + <font color=#3F5FBF>/** + * A new peer is added into locator peer table. + * <font color=#7F9FBF>@param</font> peer + */</font> + <font color=#7F0055>void</font> peerAdded(IPeer peer); + + <font color=#3F5FBF>/** + * Peer attributes have changed. + * <font color=#7F9FBF>@param</font> peer + */</font> + <font color=#7F0055>void</font> peerChanged(IPeer peer); + + <font color=#3F5FBF>/** + * A peer is removed from locator peer table. + * <font color=#7F9FBF>@param</font> id - peer ID + */</font> + <font color=#7F0055>void</font> peerRemoved(String id); + + <font color=#3F5FBF>/** + * Peer heart beat detected. + * <font color=#7F9FBF>@param</font> id - peer ID + */</font> + <font color=#7F0055>void</font> peerHeartBeat(String id); + } +} +</pre> + +</body> +</html> diff --git a/docs/TCF Service - Memory Map.html b/docs/TCF Service - Memory Map.html index f2b5d179d..c59d7d13b 100644 --- a/docs/TCF Service - Memory Map.html +++ b/docs/TCF Service - Memory Map.html @@ -39,10 +39,10 @@ <p>The service provides basic operations to get and set memory mapping on a target. Command and event parameters are encoded as zero terminated <a -href='TCF Specification.html#JSON'>JSON</a> strings.</p> +href='TCF JSON.html'>JSON</a> strings.</p> <p>The service uses standard format for error reports, -see <a href='TCF Services.html#ErrorFormat'>Error Report Format</a>.</p> +see <a href='TCF Error Report Format.html'>Error Report Format</a>.</p> <h2><a name='Cmds'>Commands</a></h2> diff --git a/docs/TCF Service - Memory.html b/docs/TCF Service - Memory.html index 7efa58933..d530c7a4f 100644 --- a/docs/TCF Service - Memory.html +++ b/docs/TCF Service - Memory.html @@ -49,10 +49,10 @@ <h2><a name='Overview'>Overview</a></h2> <p>The service provides basic operations to read/write memory on a target. Command -and event parameters are encoded as zero terminated <a href='TCF Specification.html#JSON'>JSON</a> strings.</p> +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 Services.html#ErrorFormat'>Error Report Format</a>.</p> +see <a href='TCF Error Report Format.html'>Error Report Format</a>.</p> <p>A single memory access can succeed for some addresses and fail for others. In such situation result message can contain partially valid data. Array of error addresses, diff --git a/docs/TCF Service - Path Map.html b/docs/TCF Service - Path Map.html index ae604fa15..6a65148df 100644 --- a/docs/TCF Service - Path Map.html +++ b/docs/TCF Service - Path Map.html @@ -39,10 +39,10 @@ <p>The service manages file path translation across systems. Command and event parameters are encoded as zero terminated <a -href='TCF Specification.html#JSON'>JSON</a> strings.</p> +href='TCF JSON.html'>JSON</a> strings.</p> <p>The service uses standard format for error reports, -see <a href='TCF Services.html#ErrorFormat'>Error Report Format</a>.</p> +see <a href='TCF Error Report Format.html'>Error Report Format</a>.</p> <h2><a name='Cmds'>Commands</a></h2> diff --git a/docs/TCF Service - PortForward.html b/docs/TCF Service - PortForward.html index 13495276f..6f5d05917 100755 --- a/docs/TCF Service - PortForward.html +++ b/docs/TCF Service - PortForward.html @@ -67,9 +67,9 @@ if you want to re-instantiate the connection.<br> </p> <p>Command are encoded as zero terminated <a - href="TCF%20Specification.html#JSON">JSON</a> strings.</p> + href='TCF JSON.html'>JSON</a> strings.</p> <p>The service uses standard format for error reports, see <a - href="TCF%20Services.html#ErrorFormat">Error Report Format</a>.</p> + href='TCF Error Report Format.html'>Error Report Format</a>.</p> <h2><a name="Cmds">Commands</a></h2> <h3><a name="CmdGetConfig">getConfig</a></h3> <pre><b><font color="#333399" face="Courier New" size="2"> diff --git a/docs/TCF Service - PortServer.html b/docs/TCF Service - PortServer.html index de7d308b7..32986888d 100755 --- a/docs/TCF Service - PortServer.html +++ b/docs/TCF Service - PortServer.html @@ -65,9 +65,9 @@ one connected to through the value-add).<br> </p> <p>Command are encoded as zero terminated <a - href="TCF%20Specification.html#JSON">JSON</a> strings.</p> + href='TCF JSON.html'>JSON</a> strings.</p> <p>The service uses standard format for error reports, see <a - href="TCF%20Services.html#ErrorFormat">Error Report Format</a>.</p> + href='TCF Error Report Format.html'>Error Report Format</a>.</p> <h2><a name="Cmds">Commands</a></h2> <h3><a name="CmdGetConfig">getConfig</a></h3> <b><font color="#333399" face="Courier New" size="2"> diff --git a/docs/TCF Service - Processes.html b/docs/TCF Service - Processes.html index d24120e7f..6d97be7a2 100644 --- a/docs/TCF Service - Processes.html +++ b/docs/TCF Service - Processes.html @@ -61,10 +61,10 @@ available for client to read/write using <a href='TCF Service - Streams.html'>St streams is set to "Processes".</p> <p>Command and event parameters are encoded -as zero terminated <a href='TCF Specification.html#JSON'>JSON</a> strings.</p> +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 Services.html#ErrorFormat'>Error Report Format</a>.</p> +see <a href='TCF Error Report Format.html'>Error Report Format</a>.</p> <h2><a name='Cmds'>Commands</a></h2> diff --git a/docs/TCF Service - Profiler.html b/docs/TCF Service - Profiler.html index 0bc1d0915..a8f9b7462 100644 --- a/docs/TCF Service - Profiler.html +++ b/docs/TCF Service - Profiler.html @@ -35,7 +35,7 @@ <p><font color=#FF7000>TBD</font></p> <p>The service uses standard format for error reports, -see <a href='TCF Services.html#ErrorFormat'>Error Report Format</a>.</p> +see <a href='TCF Error Report Format.html'>Error Report Format</a>.</p> <h2><a name='Cmds'>Commands</a></h2> diff --git a/docs/TCF Service - Registers.html b/docs/TCF Service - Registers.html index fd298042c..9f5786674 100644 --- a/docs/TCF Service - Registers.html +++ b/docs/TCF Service - Registers.html @@ -55,10 +55,10 @@ <h2><a name='Overview'>Overview</a></h2> <p>The service provides basic operations to read/write CPU and hardware registers. Command -and event parameters are encoded as zero terminated <a href='TCF Specification.html#JSON'>JSON</a> strings.</p> +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 Services.html#ErrorFormat'>Error Report Format</a>.</p> +see <a href='TCF Error Report Format.html'>Error Report Format</a>.</p> In addition to commands that can set/get individual register context values, the service defines commands to set/get values at multiple locations. This allows: diff --git a/docs/TCF Service - Run Control.html b/docs/TCF Service - Run Control.html index 84da3dd3c..0b434bc06 100644 --- a/docs/TCF Service - Run Control.html +++ b/docs/TCF Service - Run Control.html @@ -55,10 +55,10 @@ <h2><a name='Overview'>Overview</a></h2> <p>The service provides basic run control operations for execution contexts on a target. -Command and event parameters are encoded as zero terminated <a href='TCF Specification.html#JSON'>JSON</a> strings.</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 Services.html#ErrorFormat'>Error Report Format</a>.</p> +see <a href='TCF Error Report Format.html'>Error Report Format</a>.</p> <h2><a name='Cmds'>Commands</a></h2> diff --git a/docs/TCF Service - Stack Trace.html b/docs/TCF Service - Stack Trace.html index 9899d6a79..0ac734324 100755 --- a/docs/TCF Service - Stack Trace.html +++ b/docs/TCF Service - Stack Trace.html @@ -48,10 +48,10 @@ <h2><a name='Overview'>Overview</a></h2> <p>The service implements thread stack back tracing. Command -and event parameters are encoded as zero terminated <a href='TCF Specification.html#JSON'>JSON</a> strings.</p> +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 Services.html#ErrorFormat'>Error Report Format</a>.</p> +see <a href='TCF Error Report Format.html'>Error Report Format</a>.</p> <h2><a name='Cmds'>Commands</a></h2> diff --git a/docs/TCF Service - Streams.html b/docs/TCF Service - Streams.html index ba68da3bf..2ba6445b0 100644 --- a/docs/TCF Service - Streams.html +++ b/docs/TCF Service - Streams.html @@ -61,10 +61,10 @@ <li> Flow control: peers can throttle data flow of individual streams by delaying 'read' and 'write' commands. </ul> -<p> Command and event parameters are encoded as zero terminated <a href='TCF Specification.html#JSON'>JSON</a> strings.</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 Services.html#ErrorFormat'>Error Report Format</a>.</p> +see <a href='TCF Error Report Format.html'>Error Report Format</a>.</p> <h2><a name='Cmds'>Commands</a></h2> diff --git a/docs/TCF Service - Symbols.html b/docs/TCF Service - Symbols.html index cb39f132a..17a81f8b1 100644 --- a/docs/TCF Service - Symbols.html +++ b/docs/TCF Service - Symbols.html @@ -35,7 +35,7 @@ <p><font color=#FF7000>TBD</font></p> <p>The service uses standard format for error reports, -see <a href='TCF Services.html#ErrorFormat'>Error Report Format</a>.</p> +see <a href='TCF Error Report Format.html'>Error Report Format</a>.</p> <h2><a name='Cmds'>Commands</a></h2> diff --git a/docs/TCF Service - System Monitor.html b/docs/TCF Service - System Monitor.html index 6eeba35bb..8c2eee685 100644 --- a/docs/TCF Service - System Monitor.html +++ b/docs/TCF Service - System Monitor.html @@ -49,10 +49,10 @@ and some resource utilization data. The service can be used by a client to provi similar to Unix 'top' utility or Windows 'Task Manager'.</p> <p>Command and event parameters are encoded -as zero terminated <a href='TCF Specification.html#JSON'>JSON</a> strings.</p> +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 Services.html#ErrorFormat'>Error Report Format</a>.</p> +see <a href='TCF Error Report Format.html'>Error Report Format</a>.</p> <h2><a name='Cmds'>Commands</a></h2> diff --git a/docs/TCF Service - Terminals.html b/docs/TCF Service - Terminals.html index e2c947a29..6cc860d8c 100644 --- a/docs/TCF Service - Terminals.html +++ b/docs/TCF Service - Terminals.html @@ -50,10 +50,10 @@ available for client to read/write using <a href="TCF Service - Streams.html">St streams is set to "Terminals".</p> <p>Command and event parameters are encoded -as zero terminated <a href="TCF Specification.html#JSON">JSON</a> strings.</p> +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 Services.html#ErrorFormat">Error Report Format</a>.</p> +see <a href="TCF Error Report Format.html">Error Report Format</a>.</p> <h2><a name="Cmds">Commands</a></h2> diff --git a/docs/TCF Services.html b/docs/TCF Services.html index b51c87fe6..843ef09e2 100644 --- a/docs/TCF Services.html +++ b/docs/TCF Services.html @@ -8,15 +8,14 @@ <h1>Target Communication Framework Services</h1> -<p>Copyright (c) 2007 Wind River Systems, Inc. Made available under the EPL v1.0</p> +<p>Copyright (c) 2007-2019 Wind River Systems, Inc. and others. Made available under the EPL v1.0<br/> +Agent portion made available under your choice of EPL v1.0 or EDL v1.0 dual-license.</p> <p>Direct comments, questions to the <a href="https://dev.eclipse.org/mailman/listinfo/tcf-dev">tcf-dev@eclipse.org</a> mailing list</p> <h2>Table of Contents</h2> <ul> <li><a href='#VersionHistory'>Version History</a></li> <li><a href='#Overview'>Overview</a></li> - <li><a href='#Syntax'>Syntax Rules Notation</a></li> - <li><a href='#ErrorFormat'>Error Report Format</a></li> <li><a href='#Services'>Services</a></li> </ul> @@ -38,11 +37,6 @@ <td>2008-05-06</td> <td>Approved</td> </tr> - <tr> - <td>1.1</td> - <td>2008-06-25</td> - <td>Enhanced error reporting format, see <a href='http://bugs.eclipse.org/bugs/show_bug.cgi?id=232410'>Bug 232410</a></td> - </tr> </table> <h2><a name='Overview'>Overview</a></h2> @@ -54,149 +48,14 @@ Service definitions are not part of the <a href='TCF Specification.html'>framewo are expected to be defined by developers of tools and target agents. Defenitions of standard services are provided to achieve certain level of compatibility between tools and targets.</p> -<h2><a name='Syntax'>Syntax Rules Notation</a></h2> - -<p>Format of the protocol messages is defined by syntax rules. Syntax is described -using a simple variant of Backus-Naur Form. In particular:</p> - -<ul type='disc'> - <li>Italic lower case words in a courier font, enclosed into angular brackets, are - used to denote syntactic categories, for example: <b><i><font face="Courier New" size="2" color="#333399"><token>. - </font></i></b>Category name can be followed by colon and a text, which explains semantics - of the category, for example: <b><i><font face="Courier New" size="2" color="#333399"><int: - error code></font></i></b> has same meaning as <b><i><font face="Courier New" size="2" color="#333399"><int></font></i></b>, - but denotes that the integer number used to indicate an "error code".</li> - - <li>A syntax rule consists of a category designation followed by one or more syntax - definitions for the category. The category name and each definition are placed on - separate lines, bullets are used to denote definitions, for example:</li> -</ul> - -<pre><b><font face="Courier New" size="2" color="#333399"> -<i><chars></i> - ⇒ <i><char></i> - ⇒ <i><chars> <char></i> -</font></b></pre> - -<ul type='disc'> - <li>Spaces are added for readability only and they are not part of the syntax.</li> - - <li>All text in the category definition, other than categories and spaces, is UTF-8 - based representation of a message bytes.</li> - - <li>The symbol ‘•’ designates a zero byte.</li> -</ul> - -<h2><a name='ErrorFormat'>Error Report Format</a></h2> - -<p>Most of TCF standard services use same format for error reporting:</p> - -<pre><b><font face="Courier New" size="2" color="#333399"> -<i><error report></i> - ⇒ - ⇒ null - ⇒ <i><object: error description></i> -</font></b></pre> - -<p>Empty or null error report means success. Error description provides error details, including -error code and a short, localizable, human readable explanation of the error.</p> - -<p>Error description properties are:</p> -<dl> - <dt><b><font face="Courier New" size="2" color="#333399">"Code" : <i><integer></i></font></b></dt> - <dd>Error code. Can belong to one of predefined ranges: - <ul> - <li> 0x0-0xffff Standard TCF codes, includes a limited subset of POSIX errors, and OTHER error code, which - can be used together with "AltCode"</li> - <li> 0x10000-0x1ffff Service specific codes</li> - <li> 0x20000-0x2ffff Reserved codes - will never be used by the TCF standard</li> - </ul> - </dd> - - <dt><b><font face="Courier New" size="2" color="#333399">"Time" : <i><integer></i></font></b></dt> - <dd> Error timestamp, in milliseconds since midnight, January 1, 1970 UTC</dd> - - <dt><b><font face="Courier New" size="2" color="#333399">"Service" : <i><string></i></font></b></dt> - <dd> Name of the service that reported the error. Required when "Code" is service specific code.</dd> - - <dt><b><font face="Courier New" size="2" color="#333399">"Format" : <i><string></i></font></b></dt> - <dd> Error description format supports separation between constant and variable parts - of error message ("Format" and "Params"). This is done to support localization. - Format string is expected to allow translation into foreign languages by means of string table lookup. - The format string syntax is defined in the Java language library - <b><font face="Courier New" size="2">java.text.MessageFormat</font></b>. - In order to simplify clients written in other languages, only a subset of the syntax is supported: - <ul> - <li> Supported format types: (none), number</li> - <li> Supported format styles: - <ul> - <li> number: (none), "integer", "percent"</li> - </ul> - </li> - </ul> - </dd> - - <dt><b><font face="Courier New" size="2" color="#333399">"Params" : <i><array></i></font></b></dt> - <dd> An array of values to be used together with "Format" to create the error message.</dd> - - <dt><b><font face="Courier New" size="2" color="#333399">"Severity" : <i><integer></i></font></b></dt> - <dd> Predefined severity values: - <ul> - <li>0 - error (default)</li> - <li>1 - warning</li> - <li>2 - fatal</li> - </ul> - </dd> - <dt><b><font face="Courier New" size="2" color="#333399">"AltCode" : <i><integer></i></font></b></dt> - <dd> Alternative error code. This can be used to represent, - for example, OS, POSIX, or other vendor specific error codes</dd> - - <dt><b><font face="Courier New" size="2" color="#333399">"AltOrg" : <i><string></i></font></b></dt> - <dd> ID of organization defining "AltCode", for example "Linux", "VxWorks", "Wind River", etc</dd> - - <dt><b><font face="Courier New" size="2" color="#333399">"CausedBy" : <i><object: error description></i></font></b></dt> - <dd> A nested error description. Can be used to describe a root cause of this error.</dd> -</dl> - -<p>All fields except "Code" are optional.</p> - -<p>Standard error codes:</p> -<pre><code> - OTHER = 1 - JSON_SYNTAX = 2 - PROTOCOL = 3 - BUFFER_OVERFLOW = 4 - CHANNEL_CLOSED = 5 - COMMAND_CANCELLED = 6 - UNKNOWN_PEER = 7 - BASE64 = 8 - EOF = 9 - ALREADY_STOPPED = 10 - ALREADY_EXITED = 11 - ALREADY_RUNNING = 12 - ALREADY_ATTACHED = 13 - IS_RUNNING = 14 - INV_DATA_SIZE = 15 - INV_CONTEXT = 16 - INV_ADDRESS = 17 - INV_EXPRESSION = 18 - INV_FORMAT = 19 - INV_NUMBER = 20 - INV_DWARF = 21 - SYM_NOT_FOUND = 22 - UNSUPPORTED = 23 - INV_DATA_TYPE = 24 - INV_COMMAND = 25 -</code></pre> +<p>Format of the protocol messages is defined by syntax rules, see +<a href='TCF Syntax Rules Notation.html'>Syntax Rules Notation</a>.</p> -<p>Service specific error code definitions, if any, are part of service specfications. -Standard and service specific error codes can be extended over time. A -client that does not recognize a specific error code should treat it in the -same way as "OTHER".</p> +<p>TCF standard services use JSON for message encoding, see +<a href='TCF JSON.html'>JSON - Preferred Marshaling</a>.</p> -<p>For encoding of <b><i><font face="Courier New" size="2" color="#333399"><object></font></i></b>, -<b><i><font face="Courier New" size="2" color="#333399"><string></font></i></b>, etc., see -<a href='TCF Specification.html#JSON'>JSON - Preferred Marshaling</a>.</p> +<p>TCF standard services use same format for error reporting, see +<a href='TCF Error Report Format.html'>Error Report Format</a>.</p> <h2><a name='Services'>Services</h2> <ul> @@ -209,7 +68,7 @@ same way as "OTHER".</p> <li><a href='TCF Service - Expressions.html'>Expressions Service</a></li> <li><a href='TCF Service - File System.html'>File System Service</a></li> <li><a href='TCF Service - Line Numbers.html'>Line Numbers Service</a></li> - <li><a href='TCF Specification.html#Locator'>Locator Service</a></li> + <li><a href='TCF Service - Locator.html'>Locator Service</a></li> <li><a href='TCF Service - Memory.html'>Memory Service</a></li> <li><a href='TCF Service - Memory Map.html'>Memory Map Service</a></li> <li><a href='TCF Service - Path Map.html'>Path Map Service</a></li> diff --git a/docs/TCF Specification.html b/docs/TCF Specification.html index b1fac7593..6306f54db 100644 --- a/docs/TCF Specification.html +++ b/docs/TCF Specification.html @@ -7,8 +7,9 @@ <h1>Target Communication Framework Specification</h1> -<p>Copyright (c) 2007, 2008 Wind River Systems, Inc. Made available under the EPL v1.0 -<p>Direct comments, questions to the <a href="https://dev.eclipse.org/mailman/listinfo/tcf-dev">tcf-dev@eclipse.org</a> mailing list +<p>Copyright (c) 2007-2019 Wind River Systems, Inc. and others. Made available under the EPL v1.0<br/> +Agent portion made available under your choice of EPL v1.0 or EDL v1.0 dual-license.</p> +<p>Direct comments, questions to the <a href="https://dev.eclipse.org/mailman/listinfo/tcf-dev">tcf-dev@eclipse.org</a> mailing list</p> <h1>Table of Contents</h1> @@ -19,7 +20,6 @@ <li><a href='#Goals'>Goals</a> <li><a href='#Definitions'>Definitions</a> <li><a href='#Requirements'>Requirements</a> - <li><a href='#Syntax'>Syntax Rules Notation</a> </ul> <li><a href='#Design'>Framework Software Design Considerations</a> <ul> @@ -38,16 +38,7 @@ </ul> <li><a href='#API'>API</a> <li><a href='#JSON'>JSON - Preferred Marshaling</a> - <ul> - <li><a href='#JSONExamples'>JSON - Examples</a> - </ul> <li><a href='#Locator'>Locator Service</a> - <ul> - <li><a href='#LocatorPeer'>Peer Attributes</a> - <li><a href='#LocatorCommands'>Locator Service Commands</a> - <li><a href='#LocatorEvents'>Locator Service Events</a> - <li><a href='#LocatorAPI'>Locator Service API</a> - </ul> </ul> <h2><a name='VersionHistory'>Version History</a></h2> @@ -212,36 +203,9 @@ them about state changes. <li>Events can be broadcasted at any time, i.e. no polling should be required. <li>The protocol should support a standard mechanism of sending data larger than MTU. -</ul> - -<h2><a name='Syntax'>Syntax Rules Notation</a></h2> -<p>The protocol message format is defined by syntax rules. The syntax is described -using a simple variant of Backus-Naur Form. In particular:</p> - -<ul type='disc'> - <li>Italic lower case words in a courier font, enclosed into angular brackets, are - used to denote syntactic categories, for example: <b><i><font face="Courier New" size=2 color=#333399><token>. - </font></i></b>Category name can be followed by colon and a text, which explains the semantics - of the category, for example: <b><i><font face="Courier New" size=2 color=#333399><int: - error code></font></i></b> has same meaning as <b><i><font face="Courier New" size=2 color=#333399><int></font></i></b>, - but denotes that the integer number is used to indicate an “error code”. - - <li>A syntax rule consists of a category designation followed by one or more syntax - definitions for the category. The category name and each definition are placed on - separate lines, bullets are used to denote definitions, for example: - <pre><b><font face="Courier New" size=2 color=#333399> - <i><chars></i> - ⇒ <i><char></i> - ⇒ <i><chars> <char></i> - </font></b></pre> - - <li>Spaces are added for readability only and they are not part of the syntax. - - <li>All text in the category definition, other then categories and spaces, is UTF-8 - based representation of message bytes. - - <li>The symbol ‘•’ designates a zero byte. + <li>Format of the protocol messages is defined by syntax rules, see + <a href='TCF Syntax Rules Notation.html'>Syntax Rules Notation</a>. </ul> <h1><a name='Design'>Framework Software Design Considerations</a></h1> @@ -1109,493 +1073,12 @@ Receive: R 3 “Already suspended” <p>The TCF message data format is service specific. Since service specifications are separate from the protocol specification, a service designer can choose any data format that suits the service requirements best. However, to promote better compatibility and to -simplify service design and implementation, we recommend using <b>JSON</b> for data formatting.</p> - -<p><b>JSON</b> (pronounced like the -English given name <i>Jason</i>), which stands for "<b>J</b>ava<b>S</b>cript <b>O</b>bject -<b>N</b>otation", is a lightweight, text-based, language-independent computer data -interchange format. <b>JSON</b> is a subset of the object literal notation of JavaScript -but its use does not require JavaScript.</p> - -<p><b>JSON</b> represents data with the same basic types that programming languages -use. <b>JSON</b>'s basic types are:</p> - -<ul type='disc'> - <li>Number (integer, real, or floating-point) - - <li>String (double-quoted with backslash escapement) - - <li>Boolean (<code>true</code> and <code>false</code>) - - <li>Array (an ordered sequence of values) - - <li>Object (collection of key/value pairs) - - <li><code>null</code> - </ul> - -<p>The structures used in most programming languages easily map directly onto JSON's -structures, and back again.</p> - -<p>JSON maps data onto Unicode string. Then the string is mapped onto array of bytes -using UTF-8 encoding.</p> - -<p>JSON specification:</p> - -<pre><b><font face="Courier New" size=2 color=#333399> -<i><object></i> - ⇒ {} - ⇒ { <i><members></i> } - -<i><members></i> - ⇒ <i><string></i> : <i><value></i> - ⇒ <i><members></i> , <i><string></i> : <i><value></i> - -<i><array></i> - ⇒ [] - ⇒ [ <i><elements></i> ] - -<i><elements></i> - ⇒ <i><value></i> - ⇒ <i><elements</i>> , <i><value></i> - -<i><value></i> - ⇒ <i><string></i> - ⇒ <i><number></i> - ⇒ <i><object></i> - ⇒ <i><array></i> - ⇒ <i><boolean></i> - ⇒ null - -<i><boolean></i> - ⇒ true - ⇒ false - -<i><string></i> - ⇒ "" - ⇒ " <i><chars></i> " - -<i><chars></i> - ⇒ <i><char></i> - ⇒ <i><chars> <char></i> - -<i><char</i>> - ⇒ <i><any Unicode except " or \ or control></i> - ⇒ \"<i></i> - ⇒ \\<i></i> - ⇒ \/<i></i> - ⇒ \b<i></i> - ⇒ \f<i></i> - ⇒ \n<i></i> - ⇒ \r<i></i> - ⇒ \t<i></i> - ⇒ \u <i><four-hex-digits></i> - -<i><number</i>> - ⇒ <i><int></i> - ⇒ <<i>int> <fraction></i> - ⇒ <<i>int> <exponent></i> - ⇒ <<i>int> <fraction> <exponent></i> - -<i><int></i> - ⇒ <i><digit></i> - ⇒ <<i>digit 1-9> <digits></i> - ⇒ - <<i>digit></i> - ⇒ - <<i>digit 1-9> <digits</i>> - -<i><fraction></i> - ⇒ . <i><digits></i> - -<i><exponent></i> - ⇒ <i><e></i> <i><digits></i> - -<i><digits></i> - ⇒ <i><digit></i> - ⇒ <<i>digits></i> <<i>digit></i> - -<i><e></i> - ⇒ e - ⇒ e+ - ⇒ e- - ⇒ E - ⇒ E+ - ⇒ E- - -</font></b></pre> - -<p>See <a href='http://www.json.org/'>www.json.org</a> for more details.</p> - -<h2><a name='JSONExamples'>Examples</a></h2> - -<p>This is a JSON array containing two objects:</p> - -<pre> - [ - { - "Precision": "zip", - "Latitude": 37.7668, - "Longitude": -122.3959, - "City": "SAN FRANCISCO", - "State": "CA", - "Zip": "94107", - "Country": "US" - }, - { - "Precision": "zip", - "Latitude": 37.371991, - "Longitude": -122.026020, - "City": "SUNNYVALE", - "State": "CA", - "Zip": "94085", - "Country": "US" - } - ] -</pre> +simplify service design and implementation, we recommend using <a href='TCF JSON.html'>JSON</a> for data formatting.</p> <h1><a name='Locator'>Locator Service</a></h1> <p>The Locator service uses the transport layer to search for peers and to collect data about -the peer's attributes and capabilities (services). The discovery mechanism depends on the transport -protocol and is part of that protocol handler. Targets, known by other hosts, are -added to local list of peers. <font color=red>Security? </font>Automatically discovered -targets require no further configuration. Additional targets can be configured manually.</p> - -<p>All TCF peers must implement Locator service. The implementation is part of the framework itself. -It is the only required service, all other services are optional and, formally, not part of the framework.</p> - -<h2><a name='LocatorPeer'>Peer Attributes</a></h2> - -<p><i><object: peer data></i> is collection of peer attributes. It should, at least, contain member -<b><font face="Courier New" size=2 color=#333399>"ID" : <i><string></i></font></b>. -It can also contain a number of components describing peer properties and capabilities. -Predefined attributes are:</p> - -<ul> - <li><code><b><font face="Courier New" size=2 color=#333399>"ID" : <i><string></i></font></b></code> - - unique ID of the peer. - - <li><code><b><font face="Courier New" size=2 color=#333399>"ServiceManagerID" : <i><string></i></font></b></code> - - unique ID of service manager that is represented by this peer. - - <li><code><b><font face="Courier New" size=2 color=#333399>"AgentID" : <i><string></i></font></b></code> - - agent unique ID. - - <li><code><b><font face="Courier New" size=2 color=#333399>"Name" : <i><string></i></font></b></code> - - human readable peer name. - - <li><code><b><font face="Courier New" size=2 color=#333399>"OSName" : <i><string></i></font></b></code> - - peer OS name, if applicable. - - <li><code><b><font face="Courier New" size=2 color=#333399>"TransportName" : <i><string></i></font></b></code> - - name of a trasport protocol to use to connect to this peer, for example: TCP. - - <li><code><b><font face="Courier New" size=2 color=#333399>"Host" : <i><string></i></font></b></code> - - peer host name, if transport is TCP or UDP. - - <li><code><b><font face="Courier New" size=2 color=#333399>"Aliases" : <i><string></i></font></b></code> - - peer host name aliases, if transport is TCP or UDP. - - <li><code><b><font face="Courier New" size=2 color=#333399>"Addresses" : <i><string></i></font></b></code> - - peer IP addresses, if transport is TCP or UDP. - - <li><code><b><font face="Courier New" size=2 color=#333399>"Port" : <i><string></i></font></b></code> - - peer port number, if transport is TCP or UDP. -</ul> - -<p>Most clients do not need to know any peer attributes other than ID and Name. Clients are expected to call the IPeer.openChannel() -method and let the framework check peer attributes and create appropriate communication channel that is best suited for -communication with the peer. After a channel is established, a client can learn the peer capabilities by looking -at what services it implements (use IChannel.getRemoteServices() method to get a map of services).</p> - -<h2><a name='LocatorCommands'>Locator Service Commands</a></h2> - -<h3><a name='LocatorCommandRedirect'>redirect</a></h3> - -<pre><b><font face="Courier New" size=2 color=#333399> -C • <i><token></i> • Locator • redirect • <i><peer></i> • - -<i><peer></i> - ⇒ <i><string: peer ID></i> - ⇒ <i><object: peer data></i> -</font></b></pre> - -<p>The command redirects the channel to become connected to the given peer. -The Locator service starts acting as a proxy.</p> - -<p>Reply:</p> - -<pre><b><font face="Courier New" size=2 color=#333399> -R • <i><token></i> • <i><error report></i> • -</font></b></pre> - -<h3><a name='LocatorCommandSync'>sync</a></h3> - -<pre><b><font face="Courier New" size=2 color=#333399> -C • <i><token></i> • Locator • sync • -</font></b></pre> - -<p>The sync command does nothing and simply returns back an empty result. The command is used for -cross channel synchronization. Since commands are executed in order they were issued, by waiting -for sync result a client makes sure that all commands, that were issued before sync, are fully processed.</p> - -<p>Reply:</p> - -<pre><b><font face="Courier New" size=2 color=#333399> -R • <i><token></i> • -</font></b></pre> - -<h2><a name='LocatorEvents'>Locator Service Events</a></h2> - -<pre><b><font face="Courier New" size=2 color=#333399> -E • Locator • Hello • <i><array: service names></i> • -E • Locator • peerAdded • <i><object: peer data></i> • -E • Locator • peerChanged • <i><object: peer data></i> • -E • Locator • peerRemoved • <i><string: peer ID></i> • -E • Locator • peerHeartBeat • <i><string: peer ID></i> • -</font></b></pre> - -<dl> - <dt><b>Hello</b> - <dd>is the first message sent by the framework after establishing a communication channel. - The message lets other side of the channel know capabilities of this peer. - Message data consists of an array of service names that are provided by the peer. - The service name list is a complete and unambiguous declaration of peer's capabilities. - To avoid ambiguity, different services (even slightly different, like versions of same service) - must have different names. Framework delays all other communications between peers until exchange - of Hello messages is complete. - <dt><b>peerAdded</b> - <dd>is sent when the service discovers a new peer. - <dt><b>peerChanged</b> - <dd>is sent when peer attributes change. - <dt><b>peerRemoved</b> - <dd>is sent when the service deletes information about a peer. - <dt><b>peerHeartBeat</b> - <dd>is sent periodically when the service receives a communication from the peer - that confirms that the peer is still alive. -</dl> - -<h2><a name='LocatorAPI'>Locator Service API</a></h2> - -<pre> -<font color=#3F5FBF>/** - * Base interface for all service interfaces. A client can get list of available services - * by calling IChannel.getLocalServices() and IChannel.getRemoteServices(). - * - * Remote services are represented by a proxy objects that implement service interfaces by - * translating method calls to TCF messages and sending them to a remote peer. - * When communication channel is open, TCF automatically creates proxies for standard services. - * TCF clients can provides addition proxies for non-standard services by calling IChannel.setServiceProxy(). - */</font> -<font color=#7F0055>public</font> interface IService { - - <font color=#3F5FBF>/** - * Get unique name of this service. - */</font> - String getName(); -} - -<font color=#3F5FBF>/** - * Both hosts and targets are represented by objects - * implementing IPeer interface. A peer can act as host or - * target depending on services it implements. - * List of currently known peers can be retrieved by - * calling ILocator.getPeers() - * - * A TCF agent houses one or more service managers. A service manager has a one or more - * services to expose to the world. The service manager creates one or more peers - * to represent itself, one for every access path the agent is - * reachable by. For example, in agents accessible via TCP/IP, the - * service manger would create a peer for every subnet it wants to participate in. - * All peers of particular service manager represent identical sets of services. - * - * @noimplement This interface is not intended to be implemented by clients. - * Client can extends the abstract IPeer implementation: AbstractPeer. - */</font> -<font color=#7F0055>public interface</font> IPeer { - - <font color=#3F5FBF>/** - * Peer property names. Implementation can define additional properties. - */</font> - <font color=#7F0055>static final</font> String - <font color=#3F5FBF>/** Peer unique ID */</font> - <i><font color=#0000C0>ATTR_ID</font></i> = <font color=#2A00FF>"ID"</font>, - - <font color=#3F5FBF>/** Unique ID of service manager that is represented by this peer */</font> - <i><font color=#0000C0>ATTR_SERVICE_MANGER_ID</font></i> = <font color=#2A00FF>"ServiceManagerID"</font>, - - <font color=#3F5FBF>/** Agent unique ID */</font> - <i><font color=#0000C0>ATTR_AGENT_ID</font></i> = <font color=#2A00FF>"AgentID"</font>, - - <font color=#3F5FBF>/** Peer name */</font> - <i><font color=#0000C0>ATTR_NAME</font></i> = <font color=#2A00FF>"Name"</font>, - - <font color=#3F5FBF>/** Name of the peer operating system */</font> - <i><font color=#0000C0>ATTR_OS_NAME</font></i> = <font color=#2A00FF>"OSName"</font>, - - <font color=#3F5FBF>/** Transport name, for example TCP, SSL */</font> - <i><font color=#0000C0>ATTR_TRANSPORT_NAME</font></i> = <font color=#2A00FF>"TransportName"</font>, - - <font color=#3F5FBF>/** If present, indicates that the peer can forward traffic to other peers */</font> - <i><font color=#0000C0>ATTR_PROXY</font></i> = <font color=#2A00FF>"Proxy"</font>, - - <font color=#3F5FBF>/** Host DNS name or IP address */</font> - <i><font color=#0000C0>ATTR_IP_HOST</font></i> = <font color=#2A00FF>"Host"</font>, - - <font color=#3F5FBF>/** Optional list of host aliases */</font> - <i><font color=#0000C0>ATTR_IP_ALIASES</font></i> = <font color=#2A00FF>"Aliases"</font>, - - <font color=#3F5FBF>/** Optional list of host addresses */</font> - <i><font color=#0000C0>ATTR_IP_ADDRESSES</font></i> = <font color=#2A00FF>"Addresses"</font>, - - <font color=#3F5FBF>/** IP port number, must be decimal number */</font> - <i><font color=#0000C0>ATTR_IP_PORT</font></i> = <font color=#2A00FF>"Port"</font>; - - - <font color=#3F5FBF>/** - * <font color=#7F9FBF>@return</font> map of peer attributes - */</font> - Map<String, String> getAttributes(); - - <font color=#3F5FBF>/** - * <font color=#7F9FBF>@return</font> peer unique ID, same as getAttributes().get(ATTR_ID) - */</font> - String getID(); - - <font color=#3F5FBF>/** - * <font color=#7F9FBF>@return</font> service manager unique ID, same as getAttributes().get(ATTR_SERVICE_MANAGER_ID) - */</font> - String getServiceManagerID(); - - <font color=#3F5FBF>/** - * <font color=#7F9FBF>@return</font> agent unique ID, same as getAttributes().get(ATTR_AGENT_ID) - */</font> - String getAgentID(); - - <font color=#3F5FBF>/** - * <font color=#7F9FBF>@return</font> peer name, same as getAttributes().get(ATTR_NAME) - */</font> - String getName(); - - <font color=#3F5FBF>/** - * <font color=#7F9FBF>@return</font> agent OS name, same as getAttributes().get(ATTR_OS_NAME) - */</font> - String getOSName(); - - <font color=#3F5FBF>/** - * <font color=#7F9FBF>@return</font> transport name, same as getAttributes().get(ATTR_TRANSPORT_NAME) - */</font> - String getTransportName(); - - <font color=#3F5FBF>/** - * Open channel to communicate with this peer. - * Note: the channel is not fully open yet when this method returns. - * It's state is IChannel.STATE_OPENNING. - * Protocol.Listener will be called when the channel will be opened or closed. - */</font> - IChannel openChannel() <font color=#7F0055>throws</font> IOException; -} - -<font color=#3F5FBF>/** - * ILocator service uses transport layer to search for peers and to collect data about - * peers attributes and capabilities (services). Discovery mechanism depends on transport protocol - * and is part of that protocol handler. Targets, known to other hosts, can be found through - * remote instances of ILocator service. Automatically discovered targets require no further - * configuration. Additional targets can be configured manually. - * - * Clients should use Protocol.getLocator() to obtain local instance of ILocator, - * then ILocator.getPeers() can be used to get list of available peers (hosts and targets). - */</font> -<font color=#7F0055>public interface</font> ILocator <font color=#7F0055>extends</font> IService { - - <font color=#7F0055>static final</font> String <i><font color=#0000C0>NAME</font></i> = <font color=#2A00FF>"Locator"</font>; - - <font color=#3F5FBF>/** - * Auto-configuration command and response codes. - */</font> - <font color=#7F0055>static final int</font> - <i><font color=#0000C0>CONF_REQ_INFO</font></i> = 1, - <i><font color=#0000C0>CONF_PEER_INFO</font></i> = 2, - <i><font color=#0000C0>CONF_REQ_SLAVES</font></i> = 3, - <i><font color=#0000C0>CONF_SLAVES_INFO</font></i> = 4; - - <font color=#3F5FBF>/** - * <font color=#7F9FBF>@return</font> Locator service name: "Locator" - */</font> - String getName(); - - <font color=#3F5FBF>/** - * Get map (ID -> IPeer) of available peers (hosts and targets). - * The method return cached (currently known to the framework) list of peers. - * The list is updated according to event received from transport layer - */</font> - Map<String,IPeer> getPeers(); - - <font color=#3F5FBF>/** - * Redirect this service channel to given peer using this service as a proxy. - * @param peer_id - Peer ID. - */</font> - IToken redirect(String peer_id, DoneRedirect done); - - <font color=#7F0055>interface</font> DoneRedirect { - <font color=#7F0055>void</font> doneRedirect(IToken token, Exception error); - } - - <font color=#3F5FBF>/** - * Call back after TCF messages sent to this target up to this moment are delivered. - * This method is intended for synchronization of messages - * across multiple channels. - * - * Note: Cross channel synchronization can reduce performance and throughput. - * Most clients don't need channel synchronization and should not call this method. - * - * @param done will be executed by dispatch thread after communication - * messages are delivered to corresponding targets. - * - * This is internal API, TCF clients should use {@code org.eclipse.tm.tcf.protocol.Protocol}. - */</font> - IToken sync(DoneSync done); - - <font color=#7F0055>interface</font> DoneSync { - <font color=#7F0055>void</font> doneSync(IToken token); - } - - <font color=#3F5FBF>/** - * Add a listener for locator service events. - */</font> - <font color=#7F0055>void</font> addListener(Listener listener); - - <font color=#3F5FBF>/** - * Remove a listener for locator service events. - */</font> - <font color=#7F0055>void</font> removeListener(Listener listener); - - <font color=#7F0055>interface</font> Listener { - <font color=#3F5FBF>/** - * A new peer is added into locator peer table. - * @param peer - */</font> - <font color=#7F0055>void</font> peerAdded(IPeer peer); - - <font color=#3F5FBF>/** - * Peer attributes have changed. - * @param peer - */</font> - <font color=#7F0055>void</font> peerChanged(IPeer peer); - - <font color=#3F5FBF>/** - * A peer is removed from locator peer table. - * @param id - peer ID - */</font> - <font color=#7F0055>void</font> peerRemoved(String id); - - <font color=#3F5FBF>/** - * Peer heart beat detected. - * @param id - peer ID - */</font> - <font color=#7F0055>void</font> peerHeartBeat(String id); - } -} -</pre> +the peer's attributes and capabilities (services), see <a href='TCF Service - Locator.html'>Locator Service</a>.</p> </body> </html> diff --git a/docs/TCF Syntax Rules Notation.html b/docs/TCF Syntax Rules Notation.html new file mode 100644 index 000000000..b2b72f7c9 --- /dev/null +++ b/docs/TCF Syntax Rules Notation.html @@ -0,0 +1,75 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<html> +<head> + <title>Syntax Rules Notation</title> +</head> + +<body lang='EN-US'> + +<h1>Syntax Rules Notation</h1> + +<p>Copyright (c) 2007-2019 Wind River Systems, Inc. and others. Made available under the EPL v1.0<br/> +Agent portion made available under your choice of EPL v1.0 or EDL v1.0 dual-license.</p> +<p>Direct comments, questions to the <a href="https://dev.eclipse.org/mailman/listinfo/tcf-dev">tcf-dev@eclipse.org</a> mailing list</p> + +<h2>Table of Contents</h2> +<ul> + <li><a href='#VersionHistory'>Version History</a></li> + <li><a href='#Syntax'>Syntax Rules Notation</a></li> +</ul> + +<h2><a name='VersionHistory'>Version History</a></h2> + +<table border=1 cellpadding=8> + <tr> + <th>Version</th> + <th>Date</th> + <th>Change</th> + </tr> + <tr> + <td>0.1</td> + <td>2008-01-10</td> + <td>Initial contribution</td> + </tr> + <tr> + <td>1.0</td> + <td>2008-05-06</td> + <td>Approved</td> + </tr> +</table> + +<h2><a name='Syntax'>Syntax Rules Notation</a></h2> + +<p>Format of the protocol messages is defined by syntax rules. Syntax is described +using a simple variant of Backus-Naur Form. In particular:</p> + +<ul type='disc'> + <li>Italic lower case words in a courier font, enclosed into angular brackets, are + used to denote syntactic categories, for example: <b><i><font face="Courier New" size="2" color="#333399"><token>. + </font></i></b>Category name can be followed by colon and a text, which explains semantics + of the category, for example: <b><i><font face="Courier New" size="2" color="#333399"><int: + error code></font></i></b> has same meaning as <b><i><font face="Courier New" size="2" color="#333399"><int></font></i></b>, + but denotes that the integer number used to indicate an "error code".</li> + + <li>A syntax rule consists of a category designation followed by one or more syntax + definitions for the category. The category name and each definition are placed on + separate lines, bullets are used to denote definitions, for example:</li> +</ul> + +<pre><b><font face="Courier New" size="2" color="#333399"> +<i><chars></i> + ⇒ <i><char></i> + ⇒ <i><chars> <char></i> +</font></b></pre> + +<ul type='disc'> + <li>Spaces are added for readability only and they are not part of the syntax.</li> + + <li>All text in the category definition, other than categories and spaces, is UTF-8 + based representation of a message bytes.</li> + + <li>The symbol ‘•’ designates a zero byte.</li> +</ul> + +</body> +</html> diff --git a/docs/index.html b/docs/index.html index 4c924d1d9..a74430768 100644 --- a/docs/index.html +++ b/docs/index.html @@ -6,8 +6,8 @@ <body> <h1>Target Communication Framework</h1> -<p>Copyright (c) 2007, 2008 Wind River Systems, Inc. and others. Made available under the EPL v1.0 -(Agent portion made available under your choice of EPL v1.0 or EDL v1.0 dual-license).</p> +<p>Copyright (c) 2007-2019 Wind River Systems, Inc. and others. Made available under the EPL v1.0<br/> +Agent portion made available under your choice of EPL v1.0 or EDL v1.0 dual-license.</p> <p>Direct comments, questions to the <a href="https://dev.eclipse.org/mailman/listinfo/tcf-dev">tcf-dev@eclipse.org</a> mailing list</p> <h2>Available Documentation</h2> diff --git a/plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/services/ILocator.java b/plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/services/ILocator.java index fd68c2152..b979b1821 100644 --- a/plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/services/ILocator.java +++ b/plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/services/ILocator.java @@ -1,5 +1,5 @@ /******************************************************************************* - * Copyright (c) 2007, 2013 Wind River Systems, Inc. and others. + * Copyright (c) 2007-2019 Wind River Systems, Inc. and others. * All rights reserved. This program and the accompanying materials * are made available under the terms of the Eclipse Public License v1.0 * which accompanies this distribution, and is available at @@ -102,7 +102,7 @@ public interface ILocator extends IService { /** * Get agent ID of the agent providing the locator service. - * <p> + * * The agent ID can be used to identify the agent among all the peers * returned by {@link #getPeers()}. */ |