-C <token> Breakpoints set <array of breakpoints> +C • <token> • Breakpoints • set • <array of breakpoints> • <array of breakpoints> - Ψ null - Ψ [ ] - Ψ [ <breakpoints list> ] + ⇒ null + ⇒ [ ] + ⇒ [ <breakpoints list> ] <breakpoints list> - Ψ <breakpoint data> - Ψ <breakpoints list>, <breakpoint data> + ⇒ <breakpoint data> + ⇒ <breakpoints list>, <breakpoint data> <breakpoint data> - Ψ <object> + ⇒ <object>
The command downloads breakpoint data to a target agent. @@ -223,7 +223,7 @@ A breakpoint service implementation may not change the properties set by the cli
Reply:
-R <token> <error report> +R • <token> • <error report> •
Examples:
@@ -274,7 +274,7 @@ The following properties set a temporal breakpoint that stopscore0
-C <token> Breakpoints add <breakpoint data> +C • <token> • Breakpoints • add • <breakpoint data> •
The command adds a breakpoint to the target agent breakpoint table. The host should send this command when the user creates a new breakpoint
@@ -282,13 +282,13 @@ CReply:
-R <token> <error report> +R • <token> • <error report> •
-C <token> Breakpoints change <breakpoint data> +C • <token> • Breakpoints • change • <breakpoint data> •
The command updates the breakpoint data in the target agent breakpoint table. The host should send this command when the user modifies a breakpoint
@@ -296,25 +296,25 @@ CReply:
-R <token> <error report> +R • <token> • <error report> •
-C <token> Breakpoints enable <array of breakpoint IDs> +C • <token> • Breakpoints • enable • <array of breakpoint IDs> • <array of breakpoint IDs> - Ψ null - Ψ [ ] - Ψ [ <breakpoint IDs list> ] + ⇒ null + ⇒ [ ] + ⇒ [ <breakpoint IDs list> ] <breakpoint IDs list> - Ψ <breakpoint ID> - Ψ <breakpoint IDs list>, <breakpoint ID> + ⇒ <breakpoint ID> + ⇒ <breakpoint IDs list>, <breakpoint ID> <breakpoint ID> - Ψ <string> + ⇒ <string>
The command enables a list of breakpoints - sets breakpoint property "Enabled" to true.
@@ -322,13 +322,13 @@ CReply:
-R <token> <error report> +R • <token> • <error report> •
-C <token> Breakpoints disable <array of breakpoint IDs> +C • <token> • Breakpoints • disable • <array of breakpoint IDs> •
The command disables a list of breakpoints - sets breakpoint property "Enabled" to false.
@@ -336,13 +336,13 @@ CReply:
-R <token> <error report> +R • <token> • <error report> •
-C <token> Breakpoints remove <array of breakpoint IDs> +C • <token> • Breakpoints • remove • <array of breakpoint IDs> •
The command removes a list of breakpoints. Host should send this command when user deletes breakpoints.
@@ -350,13 +350,13 @@ CReply:
-R <token> <error report> +R • <token> • <error report> •
-C <token> Breakpoints getIDs +C • <token> • Breakpoints • getIDs •
The command uploads IDs of breakpoints known to target agent, @@ -368,13 +368,13 @@ channels.
Reply:
-R <token> <error report> <array of breakpoint IDs> +R • <token> • <error report> • <array of breakpoint IDs> •
-C <token> Breakpoints getProperties <string: breakpoint ID> +C • <token> • Breakpoints • getProperties • <string: breakpoint ID> •
The command uploads the properties of the given breakpoint from the target agent breakpoint table.
@@ -382,13 +382,13 @@ CReply:
-R <token> <error report> <breakpoint data> +R • <token> • <error report> • <breakpoint data> •
-C <token> Breakpoints getStatus <string: breakpoint ID> +C • <token> • Breakpoints • getStatus • <string: breakpoint ID> •
The command uploads the status of given the breakpoint from the target agent.
@@ -396,10 +396,10 @@ CReply:
-R <token> <error report> <breakpoint status> +R • <token> • <error report> • <breakpoint status> • <breakpoint status> - Ψ <object> + ⇒ <object>
Breakpoint status consists of a list of status properties. All properties are optional. @@ -424,16 +424,16 @@ in a list of instance status data objects
<array of instance status data> - Ψ null - Ψ [ ] - Ψ [ <Instance status data list> ] + ⇒ null + ⇒ [ ] + ⇒ [ <Instance status data list> ] <Instance status data list> - Ψ <Instance status data> - Ψ <Instance staus data list>, <Instance status data> + ⇒ <Instance status data> + ⇒ <Instance staus data list>, <Instance status data> <Instance status data> - Ψ <object> + ⇒ <object>
Instance status data consists of a list of properties pertaining to each installed instance of the breakpoint. @@ -449,7 +449,7 @@ in a list of instance status data objects
-C <token> Breakpoints getCapabilities <string: context ID> +C • <token> • Breakpoints • getCapabilities • <string: context ID> •
The command reports breakpoint service capabilities to clients so they @@ -462,10 +462,10 @@ capabilities.
Reply:
-R <token> <error report> <service capabilities> +R • <token> • <error report> • <service capabilities> • <service capabilities> - Ψ <object> + ⇒ <object>
Service capabilities consist of a list of properties. All properties are optional. @@ -492,10 +492,10 @@ of breakpoint properties that was sent by a client to a target. The purpose of t let all clients know about breakpoints that were created by other clients.
-E Breakpoints status <string: breakpoint ID> <breakpoint status> -E Breakpoints contextAdded <array of breakpoints> -E Breakpoints contextChanged <array of breakpoints> -E Breakpoints contextRemoved <array of breakpoint IDs> +E • Breakpoints • status • <string: breakpoint ID> • <breakpoint status> • +E • Breakpoints • contextAdded • <array of breakpoints> • +E • Breakpoints • contextChanged • <array of breakpoints> • +E • Breakpoints • contextRemoved • <array of breakpoint IDs> •
<file attributes> - Ψ <object> + ⇒ <object>
All attributes are optional. @@ -212,7 +212,7 @@ defined by future versions of this protocol):
-C <token> FileSystem open <string: file name> <int: mode> <file attributes> +C • <token> • FileSystem • open • <string: file name> • <int: mode> • <file attributes> •
The command opens or creates a file on a remote system. If mode contains O_CREAT then new file is created, otherwise exsting @@ -222,11 +222,11 @@ the command parameters, a default value is used.
Reply:
-R <token> <error report> <file handle> +R • <token> • <error report> • <file handle> • <file handle> - Ψ null - Ψ <string> + ⇒ null + ⇒ <string>
On success, the replay contains open file handle. The handle is encoded as a string of characters. Client should never try @@ -236,7 +236,7 @@ not needed any more. Server should close all files that were left open after cli
-C <token> FileSystem close <string: file handle> +C • <token> • FileSystem • close • <string: file handle> •
The command closes a handle, which was open by 'open' or 'opendir' commands.
@@ -244,13 +244,13 @@ CReply:
-R <token> <error report> +R • <token> • <error report> •
-C <token> FileSystem read <string: file handle> <int: offset> <int: size> +C • <token> • FileSystem • read • <string: file handle> • <int: offset> • <int: size> •
The command reads bytes from an open file. @@ -266,7 +266,7 @@ or error. For e.g. device files this may return fewer bytes than requested.
Reply:
-R <token> <string: data> <error report> <boolean: eof> +R • <token> • <string: data> • <error report> • <boolean: eof> •
<string: data> is Base64 encoded byte array of file data. Number of bytes is determined by the string length. @@ -275,7 +275,7 @@ R
-C <token> FileSystem write <string: file handle> <int: offset> <string: data> +C • <token> • FileSystem • write • <string: file handle> • <int: offset> • <string: data> •
The command writes bytes into an open file. @@ -287,13 +287,13 @@ and then the data. <string: data> is Base64 encoded array of data b
Reply:
-R <token> <error report> +R • <token> • <error report> •
-C <token> FileSystem stat <string: file name> +C • <token> • FileSystem • stat • <string: file name> •
The command retrieves file attributes.
@@ -301,13 +301,13 @@ CReply:
-R <token> <error report> <file attributes> +R • <token> • <error report> • <file attributes> •
-C <token> FileSystem lstat <string: file name> +C • <token> • FileSystem • lstat • <string: file name> •
The command retrieves file attributes. @@ -316,13 +316,13 @@ Unlike 'stat', 'lstat' does not follow symbolic links.
Reply:
-R <token> <error report> <file attributes> +R • <token> • <error report> • <file attributes> •
-C <token> FileSystem fstat <string: file handle> +C • <token> • FileSystem • fstat • <string: file handle> •
The command retrieves file attributes for an open file (identified by the file handle).
@@ -330,13 +330,13 @@ CReply:
-R <token> <error report> <file attributes> +R • <token> • <error report> • <file attributes> •
-C <token> FileSystem setstat <string: file name> <file attributes> +C • <token> • FileSystem • setstat • <string: file name> • <file attributes> •
The command sets file attributes. @@ -349,13 +349,13 @@ specified attributes.
Reply:
-R <token> <error report> +R • <token> • <error report> •
-C <token> FileSystem fsetstat <string: file handle> <file attributes> +C • <token> • FileSystem • fsetstat • <string: file handle> • <file attributes> •
The command sets file attributes for an open file (identified by the file handle). @@ -365,13 +365,13 @@ permissions or access times, as well as for truncating a file.
Reply:
-R <token> <error report> +R • <token> • <error report> •
-C <token> FileSystem opendir <string: path> +C • <token> • FileSystem • opendir • <string: path> •
The command opens a directory for reading. @@ -384,13 +384,13 @@ should be closed regardless of whether a read errors have occurred or not.
Reply:
-R <token> <error report> <file handle> +R • <token> • <error report> • <file handle> •
-C <token> FileSystem readdir <string: file handle> +C • <token> • FileSystem • readdir • <string: file handle> •
The command returns one @@ -405,19 +405,19 @@ response.
Reply:
-R <token> <array of directory entries> <error report> <boolean: eof> +R • <token> • <array of directory entries> • <error report> • <boolean: eof> • <array of directory entries> - Ψ null - Ψ [ ] - Ψ [ <directory entry list> ] + ⇒ null + ⇒ [ ] + ⇒ [ <directory entry list> ] <directory entry list> - Ψ <directory entry> - Ψ <directory entry list> , <directory entry> + ⇒ <directory entry> + ⇒ <directory entry list> , <directory entry> <directory entry> - Ψ <object> + ⇒ <object>
Directory entry attributes are:
@@ -435,7 +435,7 @@ R-C <token> FileSystem mkdir <string: directory path> <file attributes> +C • <token> • FileSystem • mkdir • <string: directory path> • <file attributes> •
The command creates a directory on the server. @@ -445,13 +445,13 @@ C
Reply:
-R <token> <error report> +R • <token> • <error report> •
-C <token> FileSystem rmdir <string: directory path> +C • <token> • FileSystem • rmdir • <string: directory path> •
The command removes a directory. @@ -463,13 +463,13 @@ directory. <string: directory path> - specifies the directory to be
Reply:
-R <token> <error report> +R • <token> • <error report> •
-C <token> FileSystem roots +C • <token> • FileSystem • roots •
The command retrieves file system roots - top level file system objects. @@ -483,13 +483,13 @@ protocol file names to OS native names and back.
Reply:
-R <token> <error report> <array of directory entries> +R • <token> • <error report> • <array of directory entries> •
-C <token> FileSystem remove <string: path> +C • <token> • FileSystem • remove • <string: path> •
The command removes a file or symbolic link. @@ -498,13 +498,13 @@ This request cannot be used to remove directories.
Reply:
-R <token> <error report> +R • <token> • <error report> •
-C <token> FileSystem realpath <string: path> +C • <token> • FileSystem • realpath • <string: path> •
The command canonicalizes any given path name to an absolute path. @@ -514,13 +514,13 @@ relative pathnames without a leading slash into absolute paths.
Reply:
-R <token> <error report> <string: path> +R • <token> • <error report> • <string: path> •
-C <token> FileSystem rename <string: old path> <string: new path> +C • <token> • FileSystem • rename • <string: old path> • <string: new path> •
The command renames a file. @@ -532,13 +532,13 @@ point to different file systems on the server.
Reply:
-R <token> <error report> +R • <token> • <error report> •
-C <token> FileSystem readlink <string: link path> +C • <token> • FileSystem • readlink • <string: link path> •
The command reads the target of a symbolic link. @@ -547,13 +547,13 @@ C
Reply:
-R <token> <error report> <string: path> +R • <token> • <error report> • <string: path> •
-C <token> FileSystem symlink <string: link path> <string: target path> +C • <token> • FileSystem • symlink • <string: link path> • <string: target path> •
The command creates a symbolic link on the server. @@ -563,14 +563,14 @@ C
Reply:
-R <token> <error report> +R • <token> • <error report> •
-C <token> FileSystem copy <string: source path> <string: destination path> - <boolean: copy permissions> <boolean: copy ownership> +C • <token> • FileSystem • copy • <string: source path> • <string: destination path> • + <boolean: copy permissions> • <boolean: copy ownership> •
The command copies a file on remote system. @@ -582,13 +582,13 @@ If <boolean: copy ownership> is true then copy source file UID and
Reply:
-R <token> <error report> +R • <token> • <error report> •
-C <token> FileSystem user +C • <token> • FileSystem • user •
The command retrieves information about user account, which is used by server @@ -597,8 +597,8 @@ to access file system on behalf of the client.
Reply:
-R <token> <int: real UID> <int: effective UID> - <int: real GID> <int: effective GID> <string: home directory> +R • <token> • <int: real UID> • <int: effective UID> • + <int: real GID> • <int: effective GID> • <string: home directory> •
<array of error addresses>
- Ψ null
- Ψ [ <error address list> ]
+ ⇒ null
+ ⇒ [ <error address list> ]
<error address list>
- Ψ <error address>
- Ψ <error address list> , <error address>
+ ⇒ <error address>
+ ⇒ <error address list> , <error address>
<error address>
- Ψ { "addr" : <int: range starting address> , "size" : <int: range length in bytes> , "stat" : <int: status code> , "msg" : <error description> }
+ ⇒ { "addr" : <int: range starting address> , "size" : <int: range length in bytes> , "stat" : <int: status code> , "msg" : <error description> }
If there is no entry in error addresses array for a data byte, then status of such @@ -51,10 +51,10 @@ byte is defined by main error report.
Status code is bitwise or of status flags:
BYTE_VALID = 0x00 BYTE_UNKNOWN = 0x01 BYTE_INVALID = 0x02 BYTE_CANNOT_READ = 0x04 BYTE_VALID = 0x00 BYTE_UNKNOWN = 0x01 BYTE_INVALID = 0x02 BYTE_CANNOT_READ = 0x04 BYTE_CANNOT_WRITE = 0x08 -C <token> Memory getContext <string: context ID> +C • <token> • Memory • getContext • <string: context ID> •
The command retrieves context info for given context ID. A context corresponds to an @@ -90,11 +90,11 @@ that is:
Reply:
-R <token> <error report> <context data> +R • <token> • <error report> • <context data> • <context data> - Ψ null - Ψ <object> + ⇒ null + ⇒ <object>
Context data object should, at least, contain member @@ -120,12 +120,12 @@ Service sends contextChanged event to notify changes in context data.
-C <token> Memory getChildren <string: parent context ID> +C • <token> • Memory • getChildren • <string: parent context ID> •
The command requests a list of contexts available for memory access commands.
-Parent context ID can be null to retrieve top level of the hierarchy, can be one +
Parent context ID can be null – to retrieve top level of the hierarchy, can be one of context IDs retrieved by previous getChildren commands, or it can be obtained from another service. Contexts hierarchy can be simple plain list or it can form a tree. It is up to target agent developers to choose layout that is most descriptive for a given target.
@@ -133,25 +133,25 @@ choose layout that is most descriptive for a given target.Reply:
-R <token> <error report> <array of context IDs> +R • <token> • <error report> • <array of context IDs> • <array of context IDs> - Ψ null - Ψ [ ] - Ψ [ <context ID list> ] + ⇒ null + ⇒ [ ] + ⇒ [ <context ID list> ] <context ID list> - Ψ <string: context ID> - Ψ <context ID list> , <string: context ID> + ⇒ <string: context ID> + ⇒ <context ID list> , <string: context ID>
-C <token> Memory set - <string: context ID> <int: address> <int: word size> - <int: byte count> <int: mode> <string: BASE64 encoded byte array> +C • <token> • Memory • set • + <string: context ID> • <int: address> • <int: word size> • + <int: byte count> • <int: mode> • <string: BASE64 encoded byte array> •
Writes data bytes at given address in memory, "word size" bytes at a time. Address @@ -159,15 +159,15 @@ should be aligned by "word size". Context ID must be one returned by getContexts Mode is logical OR of any combination of:
Result message:
-R <token> <error report> <array of error addresses> +R • <token> • <error report> • <array of error addresses> •
Error report provides integer error code and a short, human readable explanation @@ -177,9 +177,9 @@ to be written into memory.
-C <token> Memory get - <string: context ID> <int: address> <int: word size> - <int: byte count> <int: mode> +C • <token> • Memory • get • + <string: context ID> • <int: address> • <int: word size> • + <int: byte count> • <int: mode> •
Reads data bytes at given address in memory, "word size" bytes at a time. Address @@ -187,15 +187,15 @@ should be aligned by "word size". Context ID must be one returned by getContexts Mode is logical OR of any combination of:
Result message:
-R <token> <string: BASE64 encoded byte array> <error report> <array of error addresses> +R • <token> • <string: BASE64 encoded byte array> • <error report> • <array of error addresses> •
Error report provides integer error code and a short, human readable explanation @@ -205,9 +205,9 @@ to be retrieved from memory.
-C <token> Memory fill - <string: context ID> <int: address> <int: word size> - <int: byte count> <int: mode> <array: array of pattern bytes> +C • <token> • Memory • fill • + <string: context ID> • <int: address> • <int: word size> • + <int: byte count> • <int: mode> • <array: array of pattern bytes> •
Writes pattern bytes at given address in memory, "word size" bytes at a time. Address @@ -216,15 +216,15 @@ pattern is repeated necessary number of times. Context ID must be one returned b getContexts. Mode is logical OR of any combination of:
Result message:
-R <token> <error report> <array of error addresses> +R • <token> • <error report> • <array of error addresses> •
Error report provides integer error code and a short, human readable explanation @@ -237,30 +237,30 @@ to be written into memory.
or changed, and when memory content is altered by "set" or "fill" commands.
-E Memory contextAdded <array of context data>
-E Memory contextChanged <array of context data>
-E Memory contextRemoved <array of context IDs>
-E Memory memoryChanged <string: context ID> <array of address ranges>
+E • Memory • contextAdded • <array of context data> •
+E • Memory • contextChanged • <array of context data> •
+E • Memory • contextRemoved • <array of context IDs> •
+E • Memory • memoryChanged • <string: context ID> • <array of address ranges> •
<array of context data> - see Get Contexts command.
<array of context IDs>
- Ψ [ <context ID list> ]
+ ⇒ [ <context ID list> ]
<context ID list>
- Ψ <string: context ID>
- Ψ <context ID list> , <string: context ID>
+ ⇒ <string: context ID>
+ ⇒ <context ID list> , <string: context ID>
<array of address ranges>
- Ψ null
- Ψ [ <address ranges list> ]
+ ⇒ null
+ ⇒ [ <address ranges list> ]
<address ranges list>
- Ψ <address range>
- Ψ <address ranges list> , <address range>
+ ⇒ <address range>
+ ⇒ <address ranges list> , <address range>
<address range>
- Ψ { "addr" : <int: range starting address> , "size" : <int: range length in bytes> }
+ ⇒ { "addr" : <int: range starting address> , "size" : <int: range length in bytes> }
-C <token> Processes getContext <string: context ID> +C • <token> • Processes • getContext • <string: context ID> •
The command retrieves context info for given context ID. @@ -57,11 +57,11 @@ useful information.
Reply:
-R <token> <error report> <context data> +R • <token> • <error report> • <context data> • <context data> - Ψ null - Ψ <object> + ⇒ null + ⇒ <object>
Context data object should, at least, contain member @@ -89,12 +89,12 @@ R
-C <token> Processes getChildren <string: parent context ID> +C • <token> • Processes • getChildren • <string: parent context ID> •
The command requests a list of contexts available for process control commands.
-Parent context ID can be null to retrieve top level of the hierarchy, can be one +
Parent context ID can be null – to retrieve top level of the hierarchy, can be one of context IDs retrieved by previous getChildren commands, or it can be obtained from another service. Contexts hierarchy can be simple plain list or it can form a tree. It is up to target agent developers to choose layout that is most descriptive for a given target.
@@ -102,22 +102,22 @@ choose layout that is most descriptive for a given target.Reply:
-R <token> <error report> <array of context IDs> +R • <token> • <error report> • <array of context IDs> • <array of context IDs> - Ψ null - Ψ [ ] - Ψ [ <context ID list> ] + ⇒ null + ⇒ [ ] + ⇒ [ <context ID list> ] <context ID list> - Ψ <string: context ID> - Ψ <context ID list> , <string: context ID> + ⇒ <string: context ID> + ⇒ <context ID list> , <string: context ID>
-C <token> Processes attach <string: context ID> +C • <token> • Processes • attach • <string: context ID> •
The command attaches debugger to a process. @@ -126,13 +126,13 @@ Services like Run Control, Memory, Breakpoints work only with attached processes
Reply:
-R <token> <error report> +R • <token> • <error report> •
-C <token> Processes detach <string: context ID> +C • <token> • Processes • detach • <string: context ID> •
The command detaches debugger from a process.
@@ -140,13 +140,13 @@ CReply:
-R <token> <error report> +R • <token> • <error report> •
-C <token> Processes terminate <string: context ID> +C • <token> • Processes • terminate • <string: context ID> •
The command terminates a process.
@@ -154,13 +154,13 @@ CReply:
-R <token> <error report> +R • <token> • <error report> •
-C <token> Processes signal <string: context ID> <int: signal> +C • <token> • Processes • signal • <string: context ID> • <int: signal> •
The command sends a signal to a process.
@@ -168,23 +168,23 @@ CReply:
-R <token> <error report> +R • <token> • <error report> •
-C <token> Processes start <string: working directory> <string: program image file> - <string array: command line> <string array: environment variables> <boolean: attach> +C • <token> • Processes • start • <string: working directory> • <string: program image file> • + <string array: command line> • <string array: environment variables> • <boolean: attach> • <string array> - Ψ null - Ψ [ ] - Ψ [ <string list> ] + ⇒ null + ⇒ [ ] + ⇒ [ <string list> ] <string list> - Ψ <string> - Ψ <string list> , <string> + ⇒ <string> + ⇒ <string list> , <string>
The command starts a new process on remote machine. @@ -198,7 +198,7 @@ they will be added to default process environment.
Reply:
-R <token> <error report> <context data> +R • <token> • <error report> • <context data> •
On success the command returns context data for created process. Context data has same format as Get Context result.
@@ -224,7 +224,7 @@ R * If the ID is not a process ID, 'IProcesses.getContext' may not return any * useful information * - * @param id context ID. + * @param id – context ID. * @param done - call back interface called when operation is completed. */ IToken getContext(String id, DoneGetContext done); @@ -235,8 +235,8 @@ R interface DoneGetContext { /** * Called when contexts data retrieval is done. - * @param error error description if operation failed, null if succeeded. - * @param context context data. + * @param error – error description if operation failed, null if succeeded. + * @param context – context data. */ void doneGetContext(IToken token, Exception error, ProcessContext context); } @@ -244,7 +244,7 @@ R /** * Retrieve children of given context. * - * @param parent_context_id parent context ID. Can be null + * @param parent_context_id – parent context ID. Can be null – * to retrieve top level of the hierarchy, or one of context IDs retrieved * by previous getContext or getChildren commands. * @param done - call back interface called when operation is completed. @@ -257,8 +257,8 @@ R interface DoneGetChildren { /** * Called when contexts data retrieval is done. - * @param error error description if operation failed, null if succeeded. - * @param context_ids array of available context IDs. + * @param error – error description if operation failed, null if succeeded. + * @param context_ids – array of available context IDs. */ void doneGetChildren(IToken token, Exception error, String[] context_ids); } @@ -286,20 +286,20 @@ R /** * Get context ID. - * Same as getProperties().get(ID) + * Same as getProperties().get(“ID”) */ String getID(); /** * Get parent context ID. - * Same as getProperties().get(ParentID) + * Same as getProperties().get(“ParentID”) */ String getParentID(); /** * Get process name. * Client UI can show this name to a user. - * Same as getProperties().get(Name) + * Same as getProperties().get(“Name”) */ String getName(); diff --git a/docs/TCF Service - Registers.html b/docs/TCF Service - Registers.html index 44b713bdf..b47f490c7 100644 --- a/docs/TCF Service - Registers.html +++ b/docs/TCF Service - Registers.html @@ -43,7 +43,7 @@ multiple locations. This allows:-C <token> Registers getContext <string: context ID> +C • <token> • Registers • getContext • <string: context ID> •
The command retrieves context info for given context ID. A context corresponds to an @@ -59,11 +59,11 @@ Target agent should define contexts hierarchy that is:
Reply:
-R <token> <error report> <context data> +R • <token> • <error report> • <context data> • <context data> - Ψ null - Ψ <object> + ⇒ null + ⇒ <object>
Context data object should, at least, contain member @@ -135,7 +135,7 @@ Service sends contextChanged event to notify changes in context data.
-C <token> Registers getChildren <string: parent context ID> +C • <token> • Registers • getChildren • <string: parent context ID> •
The command requests a list of contexts available for registers access commands.
@@ -148,23 +148,23 @@ It is up to target agent developers to choose layout that is most descriptive foReply:
-R <token> <error report> <array of context IDs> +R • <token> • <error report> • <array of context IDs> • <array of context IDs> - Ψ null - Ψ [ ] - Ψ [ <context ID list> ] + ⇒ null + ⇒ [ ] + ⇒ [ <context ID list> ] <context ID list> - Ψ <string: context ID> - Ψ <context ID list> , <string: context ID> + ⇒ <string: context ID> + ⇒ <context ID list> , <string: context ID>
-C <token> Registers set <string: context ID> <string: value> +C • <token> • Registers • set • <string: context ID> • <string: value> •
Writes value into given register context. Context ID must be one returned by getContexts. @@ -173,7 +173,7 @@ Value is BASE64 encoded byte array of binary data. Array size should match the s
Result message:
-R <token> <error report> +R • <token> • <error report> •
Error report provides integer error code and a short, human readable explanation @@ -182,7 +182,7 @@ of error.
-C <token> Registers get <string: context ID> +C • <token> • Registers • get • <string: context ID> •
Reads register value from given register context. Context ID must be one returned by getContexts. @@ -191,7 +191,7 @@ C
Result message:
-R <token> <error report> <string: value> +R • <token> • <error report> • <string: value> •
Error report provides integer error code and a short, human readable explanation @@ -200,17 +200,17 @@ of error. Value is BASE64 encoded byte array of binary data. Array size should m
-C <token> Registers setm <array of locations> <string: value> +C • <token> • Registers • setm • <array of locations> • <string: value> • <array of locations> - Ψ [ <location list> ] + ⇒ [ <location list> ] <location list> - Ψ <location> - Ψ <location list> , <location> + ⇒ <location> + ⇒ <location list> , <location> <location> - Ψ [ <string: register context ID> , <int: offset in bytes> , <int: size in bytes> ] + ⇒ [ <string: register context ID> , <int: offset in bytes> , <int: size in bytes> ]
Writes value into given list of locations in registers. Each location is represented by 3-element array that consists of @@ -220,7 +220,7 @@ Value is BASE64 encoded byte array of binary data. Byte array size should match
Result message:
-R <token> <error report> +R • <token> • <error report> •
Error report provides integer error code and a short, human readable explanation @@ -229,17 +229,17 @@ of error.
-C <token> Registers getm <array of locations> +C • <token> • Registers • getm • <array of locations> • <array of locations> - Ψ [ <location list> ] + ⇒ [ <location list> ] <location list> - Ψ <location> - Ψ <location list> , <location> + ⇒ <location> + ⇒ <location list> , <location> <location> - Ψ [ <string: register context ID> , <int: offset in bytes> , <int: size in bytes> ] + ⇒ [ <string: register context ID> , <int: offset in bytes> , <int: size in bytes> ]
Reads register values from given list of locations in registers. Each location is represented by 3-element array that consists of @@ -249,7 +249,7 @@ context ID, offset in the context in bytes and value size in bytes.
Result message:
-R <token> <error report> <string: value> +R • <token> • <error report> • <string: value> •
Error report provides integer error code and a short, human readable explanation @@ -261,8 +261,8 @@ of error. Value is BASE64 encoded byte array of binary data. Byte array size sho a register content is altered by "set" commands.
-E Registers contextChanged -E Registers registerChanged <string: context ID> +E • Registers • contextChanged • +E • Registers • registerChanged • <string: context ID> •
-C <token> RunControl getContext <string: context ID> +C • <token> • RunControl • getContext • <string: context ID> •
The command retrieves context properties for given context ID. @@ -63,11 +63,11 @@ attributes and functionality, which is relevant to that service.
Reply:
-R <token> <error report> <context data> +R • <token> • <error report> • <context data> • <context data> - Ψ null - Ψ <object: context properties> + ⇒ null + ⇒ <object: context properties>
Context data object is collection of context properties. It should, at least, contain member @@ -115,12 +115,12 @@ contextChanged event to notify changes in context data.
-C <token> RunControl getChildren <string: parent context ID> +C • <token> • RunControl • getChildren • <string: parent context ID> •
The command requests list of execution contexts available for run control commands.
-Parent context ID can be null to retrieve top level of the hierarchy, can be one +
Parent context ID can be null – to retrieve top level of the hierarchy, can be one of context IDs retrieved by previous getChildren commands, or it can be obtained from another service. Contexts hierarchy can be simple plain list or it can form a tree. It is up to target agent developers to choose layout that is most descriptive for a given target.
@@ -128,21 +128,21 @@ choose layout that is most descriptive for a given target.Reply:
-R <token> <error report> <array of context IDs> +R • <token> • <error report> • <array of context IDs> • <array of context IDs> - Ψ null - Ψ [ <context ID list> ] + ⇒ null + ⇒ [ <context ID list> ] <context ID list> - Ψ <string: context ID> - Ψ <context ID list> , <string: context ID> + ⇒ <string: context ID> + ⇒ <context ID list> , <string: context ID>
-C <token> RunControl suspend <string: context ID> +C • <token> • RunControl • suspend • <string: context ID> •
The command suspends execution of given context. The command should fail if CanSuspend property of the context is false. @@ -152,13 +152,13 @@ can be suspended.
Result message:
-R <token> <error report> +R • <token> • <error report> •
-C <token> RunControl resume <string: context ID> <int: mode> <int: count> +C • <token> • RunControl • resume • <string: context ID> • <int: mode> • <int: count> •
The command resumes execution of given context. The command should fail if CanResume @@ -211,13 +211,13 @@ to context's children. Only contexts with HasState = true can be resumed.
Result message:
-R <token> <error report> +R • <token> • <error report> •
-C <token> RunControl getState <string: context ID> +C • <token> • RunControl • getState • <string: context ID> •
The command retrieves current state of the context. The command should fail if HasState property of @@ -226,12 +226,12 @@ the context is false.
Result message:
-R <token> <error report> <boolean: suspended> - <int: PC> <string: last state change reason> <state data> +R • <token> • <error report> • <boolean: suspended> • + <int: PC> • <string: last state change reason> • <state data> • <state data> - Ψ null - Ψ <object: context state properties> + ⇒ null + ⇒ <object: context state properties>
State change reason can be any text, but if it is one of predefined strings, @@ -254,7 +254,7 @@ Definition of state properties depends on a target.
-C <token> RunControl terminate <string: context ID> +C • <token> • RunControl • terminate • <string: context ID> •
The command terminates execution of given context. The command should fail if CanTerminate @@ -263,37 +263,37 @@ property of the context is false.
Result message:
-R <token> <error report> +R • <token> • <error report> •
-E RunControl contextAdded <array of context data> +E • RunControl • contextAdded • <array of context data> • -E RunControl contextChanged <array of context data> +E • RunControl • contextChanged • <array of context data> • -E RunControl contextRemoved <array of context IDs> +E • RunControl • contextRemoved • <array of context IDs> • -E RunControl contextSuspended <string: context ID> <int: PC> - <string: reason> <state data> +E • RunControl • contextSuspended • <string: context ID> • <int: PC> • + <string: reason> • <state data> • -E RunControl contextResumed <string: context ID> +E • RunControl • contextResumed • <string: context ID> • -E RunControl contextException <string: context ID> <string: description> +E • RunControl • contextException • <string: context ID> • <string: description> • -E RunControl containerSuspended <string: context ID> <int: PC> - <string: reason> <state data> <array of context IDs> +E • RunControl • containerSuspended • <string: context ID> • <int: PC> • + <string: reason> • <state data> • <array of context IDs> • -E RunControl containerResumed <array of context IDs> +E • RunControl • containerResumed • <array of context IDs> • <array of context data> - Ψ null - Ψ [ <context data list> ] + ⇒ null + ⇒ [ <context data list> ] <context data list> - Ψ <object: context data> - Ψ <context data list> , <object: context data> + ⇒ <object: context data> + ⇒ <context data list> , <object: context data>
-C <token> StackTrace getContext <array of context IDs> +C • <token> • StackTrace • getContext • <array of context IDs> • <array of context IDs> - Ψ null - Ψ [ ] - Ψ [ <context ID list> ] + ⇒ null + ⇒ [ ] + ⇒ [ <context ID list> ] <context ID list> - Ψ <string: context ID> - Ψ <context ID list> , <string: context ID> + ⇒ <string: context ID> + ⇒ <context ID list> , <string: context ID>
The command retrieves context info for given context IDs. @@ -52,20 +52,20 @@ each stack is also represented by a separate context.
Reply:
-R <token> <array of context data> <error report> +R • <token> • <array of context data> • <error report> • <array of context data> - Ψ null - Ψ [ ] - Ψ [ <context data list> ] + ⇒ null + ⇒ [ ] + ⇒ [ <context data list> ] <context data list> - Ψ <context data> - Ψ <context data list> , <context data> + ⇒ <context data> + ⇒ <context data list> , <context data> <context data> - Ψ null - Ψ <object> + ⇒ null + ⇒ <object>
Context data object should, at least, contain member @@ -106,7 +106,7 @@ Cached context data should by flushed when parent thread is resumed.
-C <token> StackTrace getChildren <string: parent context ID> +C • <token> • StackTrace • getChildren • <string: parent context ID> •
The command retrieves stack trace context list. @@ -121,16 +121,16 @@ Client can use Run Control service to suspend a thread.
Reply:
-R <token> <error report> <array of context IDs> +R • <token> • <error report> • <array of context IDs> • <array of context IDs> - Ψ null - Ψ [ ] - Ψ [ <context ID list> ] + ⇒ null + ⇒ [ ] + ⇒ [ <context ID list> ] <context ID list> - Ψ <string: context ID> - Ψ <context ID list> , <string: context ID> + ⇒ <string: context ID> + ⇒ <context ID list> , <string: context ID>@@ -166,7 +166,7 @@ R * The command will fail if parent thread is not suspended. * Client can use Run Control service to suspend a thread. * - * @param id array of context IDs. + * @param id – array of context IDs. * @param done - call back interface called when operation is completed. */
-C <token> SysMonitor getContext <string: context ID> +C • <token> • SysMonitor • getContext • <string: context ID> •
The command retrieves context info for given context ID. @@ -49,11 +49,11 @@ command with a context that was obtained from another service.
Reply:
-R <token> <error report> <context data> +R • <token> • <error report> • <context data> • <context data> - Ψ null - Ψ <object> + ⇒ null + ⇒ <object>
Context data object should, at least, contain member @@ -225,12 +225,12 @@ R
-C <token> SysMonitor getChildren <string: parent context ID> +C • <token> • SysMonitor • getChildren • <string: parent context ID> •
The command requests a list of contexts available for System Monitor commands.
-Parent context ID can be null to retrieve top level of the hierarchy, can be one +
Parent context ID can be null – to retrieve top level of the hierarchy, can be one of context IDs retrieved by previous getChildren commands, or it can be obtained from another service. Contexts hierarchy can be simple plain list or it can form a tree. It is up to target agent developers to choose layout that is most descriptive for a given target.
@@ -238,22 +238,22 @@ choose layout that is most descriptive for a given target.Reply:
-R <token> <error report> <array of context IDs> +R • <token> • <error report> • <array of context IDs> • <array of context IDs> - Ψ null - Ψ [ ] - Ψ [ <context ID list> ] + ⇒ null + ⇒ [ ] + ⇒ [ <context ID list> ] <context ID list> - Ψ <string: context ID> - Ψ <context ID list> , <string: context ID> + ⇒ <string: context ID> + ⇒ <context ID list> , <string: context ID>
-C <token> SysMonitor getCommandLine <string: context ID> +C • <token> • SysMonitor • getCommandLine • <string: context ID> •
The command requests a list of progess command line arguments.
@@ -261,22 +261,22 @@ CReply:
-R <token> <error report> <array of string> +R • <token> • <error report> • <array of string> • <array of string> - Ψ null - Ψ [ ] - Ψ [ <string list> ] + ⇒ null + ⇒ [ ] + ⇒ [ <string list> ] <string list> - Ψ <string> - Ψ <string list> , <string> + ⇒ <string> + ⇒ <string list> , <string>
-C <token> SysMonitor getEnvironment <string: context ID> +C • <token> • SysMonitor • getEnvironment • <string: context ID> •
The command requests a list of progess environment variables.
@@ -284,7 +284,7 @@ CReply:
-R <token> <error report> <array of string> +R • <token> • <error report> • <array of string> •
<chars> - Ψ <char> - Ψ <chars> <char> + ⇒ <char> + ⇒ <chars> <char>
<error report> - Ψ <int: error code> <error description> + ⇒ <int: error code> • <error description>
Error code zero means success. Error description provides a short, localizable, @@ -75,13 +75,13 @@ human readable explanation of error.
<error description>
- Ψ null
- Ψ <string>
- Ψ { "format" : <string> , "params" : [ <params> ] }
+ ⇒ null
+ ⇒ <string>
+ ⇒ { "format" : <string> , "params" : [ <params> ] }
<params>
- Ψ <value>
- Ψ <params> , <value>
+ ⇒ <value>
+ ⇒ <params> , <value>
For <string> diff --git a/docs/TCF Specification.html b/docs/TCF Specification.html index 39becc8d1..6233ba279 100644 --- a/docs/TCF Specification.html +++ b/docs/TCF Specification.html @@ -85,8 +85,8 @@ A service can be discovered, added or removed as a group at communication endpoi
<chars>
- Ψ <char>
- Ψ <chars> <char>
+ ⇒ <char>
+ ⇒ <chars> <char>
The framework will be packaged, distributed and installed on a host as separate product. It should be installed as system service and require no configuration for -most common case target connected over TCP or UDP on a local network. For more complicated +most common case – target connected over TCP or UDP on a local network. For more complicated setup, framework should have easily accessible and user friendly GUI with all relevant configuration options.
@@ -304,7 +304,7 @@ be asynchronous. Asynchronous functions do not have any return value, and return immediately, most of the time before the intended job is done. They take additional arguments to specify a callback function and callback data. In object-oriented languages such as Java, this is typically done by a single callback object argument containing -both the data and the function. The result listener is called asynchronously when +both the data and the function. The result listener is called asynchronously when the job is done. This approach is commonly known as asynchronous, event-driven or callback-based programming. @@ -318,7 +318,7 @@ of Control (also known as the Hollywood Principle - "Don't call us, we'll call yCommunication between development tools and embedded devices must allow a host to collect target side data and build a reflection of target state. Reflection is -usually incomplete a subset of all remote data. Reflection is always delayed it +usually incomplete – a subset of all remote data. Reflection is always delayed – it represents a remote peer state in the past. Reflection can be updated by polling for data changes or by listening to events (event is communication message that is sent asynchronously by a peer to notify others about state change). Reflection is correct @@ -388,7 +388,7 @@ value 3.
the client will know that command was executed after X was assigned 3, the last message contains last known value of X and 2 is the correct value to show. If the target is allowed to transmit events and results in arbitrary order, the client -will have no clue what to show 2 or 3. In fact, the client will have to make a tough +will have no clue what to show – 2 or 3. In fact, the client will have to make a tough decision about each message it receives: either trust message data as correct last known target state, or assume the message came in out-of-order and ignore it, or re-request the information from the target. @@ -411,7 +411,7 @@ coming in frequently, client can end up in infinite loop re-requesting the data and again, and it will never have trustworthy data about current target state.Developers should be careful when using multithreading or multiple queues in software -design it can easily cause message reordering.
+design – it can easily cause message reordering.The framework itself is required to preserve message order. However, if for whatever reason a target agent cannot preserve message order, the result will be that clients @@ -455,25 +455,25 @@ example:
Service discovery protocols, as well as transport protocols will be supported by framework plug-ins, they are not part of framework code itself, and they can be developed -by 3rd parties. Note that existing discovery protocols define term service differently +by 3rd parties. Note that existing discovery protocols define term “service” differently - as an independent communication endpoint (usually a TCP/IP port). In this document -it is called peer (host, target, communication endpoint), and a peer can provide +it is called “peer” (host, target, communication endpoint), and a peer can provide multiple services over single communication channel.
Using of standard discovery protocols should be optional, because it can potentially cause conflict or interference between development tools and application being developed -over a use of same standard protocol devices software often includes implementation +over a use of same standard protocol – devices software often includes implementation of service discovery protocols as part of application code to support their main functions.
@@ -487,9 +487,9 @@ packet is treated as array of bytes at this level. The communication protocol im also provides:Protocol defines three packet types: commands (requests), results (responses), @@ -501,24 +501,24 @@ using framework preferred marshaling for data formatting.
Syntax:
<message> - Ψ <command> - Ψ <result> - Ψ <event> - Ψ <flow control message> + ⇒ <command> + ⇒ <result> + ⇒ <event> + ⇒ <flow control message>
<command> - Ψ C <token> <service name> <command name> <byte array: arguments> + ⇒ C • <token> • <service name> • <command name> • <byte array: arguments>-
Command packets start with string C.
+Command packets start with string “C”.
<token> - Ψ <chars> + ⇒ <chars>
Token is unique string generated by framework for each command. It is used to match @@ -526,7 +526,7 @@ results to commands.
<service name> - Ψ <chars> + ⇒ <chars>
Service name is used to identify a service that handles the command, it is same @@ -534,13 +534,13 @@ string as returned by Service.getName().
<command name> - Ψ <chars> + ⇒ <chars>
Command name interpretation depends on a service.
A command should always be answered with result packed. Result does not have to -be positive it can include an error code, but there always must be one. Since client +be positive – it can include an error code, but there always must be one. Since client cannot detect that a response is missing, if for some reasons peer is not able to answer a command, it should consider such situation a fatal communication error and it must shutdown the communication channel. It is not necessary to wait for result @@ -554,19 +554,19 @@ store the requests and time to process them.
<result> - Ψ R <token> <byte array: result data> - Ψ P <token> <byte array: result data> + ⇒ R • <token> • <byte array: result data> + ⇒ P • <token> • <byte array: result data>-
Result packets start with string P for intermediate result and R for final -result. Receiving of R result concludes execution of corresponding command. -There should be exactly one R result for each command. In addition, command execution can produce any number of -intermediate P results. P results can be sent before R, and it can serve, for +
Result packets start with string “P” for intermediate result and “R” for final +result. Receiving of “R” result concludes execution of corresponding command. +There should be exactly one “R” result for each command. In addition, command execution can produce any number of +intermediate “P” results. “P” results can be sent before “R”, and it can serve, for example, as command execution progress report when execution takes long time.
<token> - Ψ <chars> + ⇒ <chars>
Token should match token field of one of the pending commands that produced the result.
@@ -575,14 +575,14 @@ example, as command execution progress report when execution takes long time. <event> - Ψ E <service name> <event name> <byte array: event data> + ⇒ E • <service name> • <event name> • <byte array: event data> -Event packets start with string E.
+Event packets start with string “E”.
<service name> - Ψ <chars> + ⇒ <chars>
Service name identifies a service that fired event, same string as returned by @@ -590,7 +590,7 @@ Service.getName().
<event name> - Ψ <chars> + ⇒ <chars>
Event name meaning depends on a service.
@@ -598,11 +598,11 @@ Service.getName().Events are used to notify clients about changes in peer state. Services should provide sufficient variety of events for clients to track remote peer state without too much of polling. Clients, interested in a particular aspect of the target state, -should have a reflection (or model) of that state and update the reflection by +should have a “reflection” (or “model”) of that state and update the reflection by listening for relevant events. If a service implements a command that changes a particular aspect of peers state, then, normally, it should also generate notifications event when that same part of the state changes and it should provide a command to retrieve -current value of the state to be used by clients to initialize the reflection. Service +current value of the state – to be used by clients to initialize the reflection. Service events are defined statically, together with commands. The framework does not do any event processing besides delivering them to clients, however a service can define additional event related functionality if necessary, for example, commands for event @@ -627,10 +627,10 @@ to less detailed messages, etc.
<flow control message> - Ψ F <int: traffic congestion level> + ⇒ F • <int: traffic congestion level> •-
Traffic congestion level value is in range 100..100, where 100 means no pending +
Traffic congestion level value is in range –100..100, where –100 means no pending messages (no traffic), 0 means optimal load, and positive numbers indicate level of congestion. When a peer receives flow control message with congestion level > 0 it should try to reduce its transmition speed.
@@ -645,29 +645,29 @@ for actual data formats.
-Send : C 1 RunControl suspend Thread1 -Receive: E RunControl suspended Thread1 -Receive: R 1 Success +Send : C 1 RunControl suspend “Thread1” +Receive: E RunControl suspended “Thread1” +Receive: R 1 “Success”
Same command, but target was already suspended:
-Receive: E RunControl suspended Thread1 - -Send : C 2 RunControl suspend Thread1 -Receive: R 2 Already suspended +Receive: E RunControl suspended “Thread1” +… +Send : C 2 RunControl suspend “Thread1” +Receive: R 2 “Already suspended”
Same command, but target was suspended (by another client) after sending the command, but before command was executed:
-Receive: E RunControl running Thread1 - -Send : C 3 RunControl suspend Thread1 -Receive: E RunControl suspended Thread1 -Receive: R 3 Already suspended +Receive: E RunControl running “Thread1” +… +Send : C 3 RunControl suspend “Thread1” +Receive: E RunControl suspended “Thread1” +Receive: R 3 “Already suspended”
run methods of that objects in a sequence by a single thread.
@@ -697,92 +697,92 @@ Receive:
* invoked from the dispatch thread.
*
* @param event_queue - IEventQueue implementation.
- */
- public static void setEventQueue(IEventQueue event_queue);
-
- /**
- * @return instance of IEventQueue that should be used for TCF events.
- */
- public static IEventQueue getEventQueue();
-
- /**
- * Returns true if the calling thread is TCF dispatch thread.
- * Use this call to ensure that a given task is being executed (or not being)
- * on dispatch thread.
- * This method is thread-safe.
- *
- * @return true if running on the dispatch thread.
- */
- public static boolean isDispatchThread();
-
- /**
- * Causes runnable to have its run
- * method called in the dispatch thread of the framework.
- * Runnables are dispatched in same order as queued.
+ */
+ public static void setEventQueue(IEventQueue event_queue);
+
+ /**
+ * @return instance of IEventQueue that should be used for TCF events.
+ */
+ public static IEventQueue getEventQueue();
+
+ /**
+ * Returns true if the calling thread is TCF dispatch thread.
+ * Use this call to ensure that a given task is being executed (or not being)
+ * on dispatch thread.
+ * This method is thread-safe.
+ *
+ * @return true if running on the dispatch thread.
+ */
+ public static boolean isDispatchThread();
+
+ /**
+ * Causes runnable to have its run
+ * method called in the dispatch thread of the framework.
+ * Runnables are dispatched in same order as queued.
* If invokeLater is called from the dispatching thread
* the runnable.run() will still be deferred until
* all pending events have been processed.
*
* This method can be invoked from any thread.
- *
- * @param runnable the Runnable whose run
- * method should be executed asynchronously.
- */
- public static void invokeLater(Runnable runnable);
-
- /**
- * Causes runnable to have its run
- * method called in the dispatch thread of the framework.
- * Calling thread is suspended util the method is executed.
- * This method is thread-safe.
- *
- * @param runnable the Runnable whose run
- * method should be executed on dispatch thread.
- */
- public static void invokeAndWait(Runnable runnable)
- throws InterruptedException;
-
- /**
+ *
+ * @param runnable the Runnable whose run
+ * method should be executed asynchronously.
+ */
+ public static void invokeLater(Runnable runnable);
+
+ /**
+ * Causes runnable to have its run
+ * method called in the dispatch thread of the framework.
+ * Calling thread is suspended util the method is executed.
+ * This method is thread-safe.
+ *
+ * @param runnable the Runnable whose run
+ * method should be executed on dispatch thread.
+ */
+ public static void invokeAndWait(Runnable runnable)
+ throws InterruptedException;
+
+ /**
* Get instance of the framework locator service.
* The service can be used to discover available remote peers.
*
* @return instance of ILocator.
- */
+ */
public static ILocator getLocator();
- /**
+ /**
* Return an array of all open channels.
* @return an array of IChannel
- */
+ */
public static IChannel[] getOpenChannels();
- /**
+ /**
* Interface to be implemented by clients willing to be notified when
* new TCF communication channel is opened.
- */
+ */
public interface ChannelOpenListener {
public void onChannelOpen(IChannel channel);
}
- /**
+ /**
* Add a listener that will be notified when new channel is opened.
* @param listener
- */
+ */
public static void addChannelOpenListener(ChannelOpenListener listener);
- /**
+ /**
* Remove channel opening listener.
* @param listener
- */
+ */
public static void removeChannelOpenListener(ChannelOpenListener listener);
- /**
+ /**
* Transmit TCF event message.
- * The message is sent to all open communication channels broadcasted.
- */
+ * The message is sent to all open communication channels – broadcasted.
+ */
public static void sendEvent(String service, String name, byte[] data);
- /**
+ /**
* Call back after TCF messages sent by this host up to this moment are delivered
* to their intended target. This method is intended for synchronization of messages
* across multiple channels.
@@ -792,204 +792,204 @@ Receive:
*
* @param done will be executed by dispatch thread after communication
* messages are delivered to corresponding targets.
- */
+ */
public static void sync(Runnable done);
}
/**
- * IChannel represents communication link connecting two endpoints (peers).
- * The channel asynchroniously transmits messages: commands, results and events.
- * A single channel may be used to communicate with multiple services.
- * Multiple channels may be used to connect the same peers, however no command or event
- * ordering is guaranteed across channels.
- */
+ * IChannel represents communication link connecting two endpoints (peers).
+ * The channel asynchroniously transmits messages: commands, results and events.
+ * A single channel may be used to communicate with multiple services.
+ * Multiple channels may be used to connect the same peers, however no command or event
+ * ordering is guaranteed across channels.
+ */
public interface IChannel {
-
- /**
- * Channel state IDs
- */
- static final int
- STATE_OPENNING = 0,
- STATE_OPEN = 1,
- STATE_CLOSED = 2;
-
- /**
- * @return channel current state, see STATE_*
- */
- int getState();
-
- /**
- * Send command message to remote peer for execution. Commands can be queued
- * locally before transmission. Sending commands too fast can fill up
- * communication channel buffers. Calling thread will be blocked until
- * enough buffer space is freed up by transmitting pending messages.
- */
- IToken sendCommand(IService service, String name, byte[] args,
- ICommandListener done);
-
- /**
- * Command listener interface. Clients implement this interface
- * to receive command results.
- */
- interface ICommandListener {
-
- /**
- * Called when progress message (intermediate result) is received
- * from remote peer.
- */
- void progress(byte[] data);
-
- /**
- * Called when command result received from remote peer.
- */
- void result(byte[] data);
- }
-
- /**
- * Send result message to remote peer. Messages can be queued locally before
- * transmission. Sending messages too fast can fill up communication channel
- * buffers. Calling thread will be blocked until enough buffer space is
- * freed up by transmitting pending messages.
- */
- void sendResult(IToken token, byte[] results);
-
- /**
- * Get current level of outbound traffic congestion.
- *
- * @return integer value in range 100..100, where 100 means no pending
- * messages (no traffic), 0 means optimal load, and positive numbers
- * indicate level of congestion.
- *
- * Note: inbound traffic congestion is detected by framework and reported to
- * remote peer without client needed to be involved.
- */
- int getCongestion();
-
- /**
- * Channel listener interface.
- */
- interface IChannelListener {
-
- /**
- * Notifies listeners about congestion level changes. When level > 0
- * client should delay sending more messages.
- */
- void congestionLevel(int level);
- }
-
- /**
- * Subscribe a channel listener. The listener will be notified about changes of
- * outbound traffic congestion level.
- */
- void addChannelListener(IChannelListener listener);
-
- /**
- * Remove a channel listener.
- */
- void removeChannelListener(IChannelListener listener);
-
- /**
- * Command server interface.
- * This interface is to be implemented by service providers.
- */
- interface ICommandServer {
-
- /**
- * Called every time a command is received from remote peer.
- */
- void command(IToken token, String name, byte[] data);
- }
-
- /**
- * Subscribe a command server. The server will be notified about command
- * messages received through this channel for given service.
- */
- void addCommandServer(IService service, ICommandServer listener);
-
- /**
- * Remove a command server.
- */
- void removeCommandServer(IService service, ICommandServer listener);
+
+ /**
+ * Channel state IDs
+ */
+ static final int
+ STATE_OPENNING = 0,
+ STATE_OPEN = 1,
+ STATE_CLOSED = 2;
+
+ /**
+ * @return channel current state, see STATE_*
+ */
+ int getState();
+
+ /**
+ * Send command message to remote peer for execution. Commands can be queued
+ * locally before transmission. Sending commands too fast can fill up
+ * communication channel buffers. Calling thread will be blocked until
+ * enough buffer space is freed up by transmitting pending messages.
+ */
+ IToken sendCommand(IService service, String name, byte[] args,
+ ICommandListener done);
+
+ /**
+ * Command listener interface. Clients implement this interface
+ * to receive command results.
+ */
+ interface ICommandListener {
+
+ /**
+ * Called when progress message (intermediate result) is received
+ * from remote peer.
+ */
+ void progress(byte[] data);
+
+ /**
+ * Called when command result received from remote peer.
+ */
+ void result(byte[] data);
+ }
+
+ /**
+ * Send result message to remote peer. Messages can be queued locally before
+ * transmission. Sending messages too fast can fill up communication channel
+ * buffers. Calling thread will be blocked until enough buffer space is
+ * freed up by transmitting pending messages.
+ */
+ void sendResult(IToken token, byte[] results);
+
+ /**
+ * Get current level of outbound traffic congestion.
+ *
+ * @return integer value in range –100..100, where –100 means no pending
+ * messages (no traffic), 0 means optimal load, and positive numbers
+ * indicate level of congestion.
+ *
+ * Note: inbound traffic congestion is detected by framework and reported to
+ * remote peer without client needed to be involved.
+ */
+ int getCongestion();
+
+ /**
+ * Channel listener interface.
+ */
+ interface IChannelListener {
+
+ /**
+ * Notifies listeners about congestion level changes. When level > 0
+ * client should delay sending more messages.
+ */
+ void congestionLevel(int level);
+ }
+
+ /**
+ * Subscribe a channel listener. The listener will be notified about changes of
+ * outbound traffic congestion level.
+ */
+ void addChannelListener(IChannelListener listener);
+
+ /**
+ * Remove a channel listener.
+ */
+ void removeChannelListener(IChannelListener listener);
+
+ /**
+ * Command server interface.
+ * This interface is to be implemented by service providers.
+ */
+ interface ICommandServer {
+
+ /**
+ * Called every time a command is received from remote peer.
+ */
+ void command(IToken token, String name, byte[] data);
+ }
+
+ /**
+ * Subscribe a command server. The server will be notified about command
+ * messages received through this channel for given service.
+ */
+ void addCommandServer(IService service, ICommandServer listener);
+
+ /**
+ * Remove a command server.
+ */
+ void removeCommandServer(IService service, ICommandServer listener);
/**
- * A generic interface for service event listener.
- * Services usually define a service specific event listener interface,
- * which is implemented using this generic listener.
- * Service clients should use service specific listener interface,
- * unless no such interface is defined.
- */
- interface IEventListener {
- void event(String name, byte[] data);
- }
-
- /**
- * Subscribe an event message listener for given service.
- */
- void addEventListener(IService service, IEventListener listener);
-
- /**
- * Unsubscribe an event message listener for given service.
- */
- void removeEventListener(IService service, IEventListener listener);
+ * A generic interface for service event listener.
+ * Services usually define a service specific event listener interface,
+ * which is implemented using this generic listener.
+ * Service clients should use service specific listener interface,
+ * unless no such interface is defined.
+ */
+ interface IEventListener {
+ void event(String name, byte[] data);
+ }
+
+ /**
+ * Subscribe an event message listener for given service.
+ */
+ void addEventListener(IService service, IEventListener listener);
+
+ /**
+ * Unsubscribe an event message listener for given service.
+ */
+ void removeEventListener(IService service, IEventListener listener);
+
+ /**
+ * @return IPeer object representing local endpoint of communication channel.
+ */
+ IPeer getLocalPeer();
+
+ /**
+ * @return IPeer object representing remote endpoint of communication channel.
+ */
+ IPeer getRemotePeer();
+
+ /**
+ * @return map of services available on local peer. It maps service names to
+ * IService implemetations.
+ */
+ Map<String, IService> getLocalServices();
+
+ /**
+ * @return map of services available on removte peer. It maps service names to
+ * IService implemetations.
+ */
+ Map<String, IService> getRemoteServices();
/**
- * @return IPeer object representing local endpoint of communication channel.
- */
- IPeer getLocalPeer();
-
- /**
- * @return IPeer object representing remote endpoint of communication channel.
- */
- IPeer getRemotePeer();
-
- /**
- * @return map of services available on local peer. It maps service names to
- * IService implemetations.
- */
- Map<String, IService> getLocalServices();
-
- /**
- * @return map of services available on removte peer. It maps service names to
- * IService implemetations.
- */
- Map<String, IService> getRemoteServices();
-
- /**
- * Close communication channel.
- */
- void close();
-
- /**
- * Close channel in case of communication error.
- * @param error
- */
- void terminate(Throwable error);
-
- /**
- * Redirect this channel to given peer using this channel remote peer
- * locator service as a proxy.
- * @param peer_id
- */
- void redirect(String peer_id);
+ * Close communication channel.
+ */
+ void close();
+
+ /**
+ * Close channel in case of communication error.
+ * @param error
+ */
+ void terminate(Throwable error);
+
+ /**
+ * Redirect this channel to given peer using this channel remote peer
+ * locator service as a proxy.
+ * @param peer_id
+ */
+ void redirect(String peer_id);
}
/**
* Object implemeting IToken interface is created by framework for every
- * command sent over communication channel. It is used to match command to its
- * results, and also can be used to cancel commands.
- */
+ * command sent over communication channel. It is used to match command to its
+ * results, and also can be used to cancel commands.
+ */
public interface IToken {
-
- /**
- * Try to cancel a command associated with given token. A command can be
- * canceled by this method only if it was not transmitted yet to remote peer
- * for execution. Successfully canceled command does not produce any result
- * messages.
- *
- * @return true if successful.
- */
- boolean cancel();
+
+ /**
+ * Try to cancel a command associated with given token. A command can be
+ * canceled by this method only if it was not transmitted yet to remote peer
+ * for execution. Successfully canceled command does not produce any result
+ * messages.
+ *
+ * @return true if successful.
+ */
+ boolean cancel();
}
@@ -1034,82 +1034,82 @@ using UTF-8 encoding.
<object>
- Ψ {}
- Ψ { <members> }
-
+ ⇒ {}
+ ⇒ { <members> }
+
<members>
- Ψ <string> : <value>
- Ψ <members> , <string> : <value>
+ ⇒ <string> : <value>
+ ⇒ <members> , <string> : <value>
<array>
- Ψ []
- Ψ [ <elements> ]
+ ⇒ []
+ ⇒ [ <elements> ]
<elements>
- Ψ <value>
- Ψ <elements> , <value>
+ ⇒ <value>
+ ⇒ <elements> , <value>
<value>
- Ψ <string>
- Ψ <number>
- Ψ <object>
- Ψ <array>
- Ψ <boolean>
- Ψ null
+ ⇒ <string>
+ ⇒ <number>
+ ⇒ <object>
+ ⇒ <array>
+ ⇒ <boolean>
+ ⇒ null
<boolean>
- Ψ true
- Ψ false
+ ⇒ true
+ ⇒ false
<string>
- Ψ ""
- Ψ " <chars> "
+ ⇒ ""
+ ⇒ " <chars> "
<chars>
- Ψ <char>
- Ψ <chars> <char>
+ ⇒ <char>
+ ⇒ <chars> <char>
<char>
- Ψ <any Unicode except " or \ or control>
- Ψ \"
- Ψ \\
- Ψ \/
- Ψ \b
- Ψ \f
- Ψ \n
- Ψ \r
- Ψ \t
- Ψ \u <four-hex-digits>
+ ⇒ <any Unicode except " or \ or control>
+ ⇒ \"
+ ⇒ \\
+ ⇒ \/
+ ⇒ \b
+ ⇒ \f
+ ⇒ \n
+ ⇒ \r
+ ⇒ \t
+ ⇒ \u <four-hex-digits>
<number>
- Ψ <int>
- Ψ <int> <fraction>
- Ψ <int> <exponent>
- Ψ <int> <fraction> <exponent>
-
+ ⇒ <int>
+ ⇒ <int> <fraction>
+ ⇒ <int> <exponent>
+ ⇒ <int> <fraction> <exponent>
+
<int>
- Ψ <digit>
- Ψ <digit 1-9> <digits>
- Ψ - <digit>
- Ψ - <digit 1-9> <digits>
+ ⇒ <digit>
+ ⇒ <digit 1-9> <digits>
+ ⇒ - <digit>
+ ⇒ - <digit 1-9> <digits>
<fraction>
- Ψ . <digits>
+ ⇒ . <digits>
<exponent>
- Ψ <e> <digits>
+ ⇒ <e> <digits>
<digits>
- Ψ <digit>
- Ψ <digits> <digit>
+ ⇒ <digit>
+ ⇒ <digits> <digit>
<e>
- Ψ e
- Ψ e+
- Ψ e-
- Ψ E
- Ψ E+
- Ψ E-
+ ⇒ e
+ ⇒ e+
+ ⇒ e-
+ ⇒ E
+ ⇒ E+
+ ⇒ E-
@@ -1120,32 +1120,32 @@ using UTF-8 encoding.
This is a JSON array containing two objects:
- [
- {
- "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"
- }
- ]
+ [
+ {
+ "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"
+ }
+ ]
Locator Service uses transport layer to search for peers and to collect data about -peers attributes and capabilities (services). Discovery mechanism depends on transport +peer's attributes and capabilities (services). Discovery mechanism depends on transport protocol and is part of that protocol handler. Targets, known by other hosts, are added to local list of peers. Security? Automatically discovered targets require no further configuration. Additional targets can be configured manually.
@@ -1196,7 +1196,7 @@ at services it implements (use IChannel.getRemoteServices() method to get a map-C <token> Locator redirect <string: peer ID> +C • <token> • Locator • redirect • <string: peer ID> •
The command redirects the channel to become connected to given peer. @@ -1205,13 +1205,13 @@ Locator service starts acting as a proxy.
Reply:
-R <token> <error report> +R • <token> • <error report> •
-C <token> Locator sync +C • <token> • Locator • sync •
Sync command does nothing and simply returns back an empty result. The command is used for @@ -1221,16 +1221,16 @@ for sync result a client makes sure that all commands, that were issued before s
Reply:
-R <token> +R • <token> •
-E Locator Hello <array: service names> -E Locator peerAdded <object: peer data> -E Locator peerChanged <object: peer data> -E Locator peerRemoved <string: peer ID> +E • Locator • Hello • <array: service names> • +E • Locator • peerAdded • <object: peer data> • +E • Locator • peerChanged • <object: peer data> • +E • Locator • peerRemoved • <string: peer ID> •
/**
- * Base interface for all service interfaces.
- * A client can get list of available services by
- * calling IPeer.getLocalServices or IPeer.getRemoteServives
- */
+ * Base interface for all service interfaces.
+ * A client can get list of available services by
+ * calling IPeer.getLocalServices or IPeer.getRemoteServives
+ */
public interface IService {
- /**
- * Get unique name of this service.
- */
- String getName();
+ /**
+ * Get unique name of this service.
+ */
+ String getName();
}
/**
- * 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
- */
+ * 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
+ */
public interface IPeer {
-
- static final String
- ATTR_ID = "ID",
- ATTR_NAME = "Name",
- ATTR_OS_NAME = "OSName",
- ATTR_TRANSPORT_NAME = "TransportName",
- ATTR_IP_HOST = "Host",
- ATTR_IP_ALIASES = "Aliases",
- ATTR_IP_ADDRESSES = "Addresses",
- ATTR_IP_PORT = "Port";
-
-
- /**
- * @return map of peer attributes
- */
- Map<String, String> getAttributes();
-
- /**
- * @return peer unique ID, same as getAttributes().get(ATTR_ID)
- */
- String getID();
-
- /**
- * @return peer name, same as getAttributes().get(ATTR_NAME)
- */
- String getName();
-
- /**
- * Same as getAttributes().get(ATTR_OS_NAME)
- */
- String getOSName();
-
- /**
- * Same as getAttributes().get(ATTR_TRANSPORT_NAME)
- */
- String getTransportName();
-
- /**
- * Open channel to communicate with this peer.
- * Note: the channel is not fully open yet when this method returns.
- * Its state is IChannel.STATE_OPENNING.
- * Protocol.Listener will be called when the channel will be opened or closed.
- */
- IChannel openChannel() throws IOException;
+
+ static final String
+ ATTR_ID = "ID",
+ ATTR_NAME = "Name",
+ ATTR_OS_NAME = "OSName",
+ ATTR_TRANSPORT_NAME = "TransportName",
+ ATTR_IP_HOST = "Host",
+ ATTR_IP_ALIASES = "Aliases",
+ ATTR_IP_ADDRESSES = "Addresses",
+ ATTR_IP_PORT = "Port";
+
+
+ /**
+ * @return map of peer attributes
+ */
+ Map<String, String> getAttributes();
+
+ /**
+ * @return peer unique ID, same as getAttributes().get(ATTR_ID)
+ */
+ String getID();
+
+ /**
+ * @return peer name, same as getAttributes().get(ATTR_NAME)
+ */
+ String getName();
+
+ /**
+ * Same as getAttributes().get(ATTR_OS_NAME)
+ */
+ String getOSName();
+
+ /**
+ * Same as getAttributes().get(ATTR_TRANSPORT_NAME)
+ */
+ String getTransportName();
+
+ /**
+ * 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.
+ */
+ IChannel openChannel() throws IOException;
}
/**
- * 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 by other
- * hosts, are added to local list of peers.
- * 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 of available peers (hosts and targets).
- */
+ * 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 by other
+ * hosts, are added to local list of peers.
+ * 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 of available peers (hosts and targets).
+ */
public interface ILocator extends IService {
-
- static final String NAME = "Locator";
+
+ static final String NAME = "Locator";
/**
* Auto-configuration command and response codes.
@@ -1342,28 +1342,28 @@ E
CONF_REQ_INFO = 1,
CONF_PEER_INFO = 2;
- /**
- * @return Locator service name: "Locator"
- */
- String getName();
+ /**
+ * @return Locator service name: "Locator"
+ */
+ String getName();
- /**
+ /**
* 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
- */
- Map<String,IPeer> getPeers();
-
- /**
- * Redirect this service channel to given peer using this service as a proxy.
- */
- IToken redirect(String peer_id, DoneRedirect done);
-
- interface DoneRedirect {
- void doneRedirect(IToken token, Exception error);
- }
-
- /**
+ */
+ Map<String,IPeer> getPeers();
+
+ /**
+ * Redirect this service channel to given peer using this service as a proxy.
+ */
+ IToken redirect(String peer_id, DoneRedirect done);
+
+ interface DoneRedirect {
+ void doneRedirect(IToken token, Exception error);
+ }
+
+ /**
* 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.
@@ -1382,23 +1382,23 @@ E
void doneSync(IToken token);
}
- /**
- * Add a listener for locator service events.
- */
- void addListener(Listener listener);
+ /**
+ * Add a listener for locator service events.
+ */
+ void addListener(Listener listener);
- /**
- * Remove a listener for locator service events.
- */
- void removeListener(Listener listener);
+ /**
+ * Remove a listener for locator service events.
+ */
+ void removeListener(Listener listener);
- interface Listener {
- void peerAdded(IPeer peer);
+ interface Listener {
+ void peerAdded(IPeer peer);
- void peerRemoved(IPeer peer);
+ void peerRemoved(IPeer peer);
- void peerChanged(IPeer peer);
- }
+ void peerChanged(IPeer peer);
+ }
}
--
cgit v1.2.3