diff options
| author | eutarass | 2009-02-26 22:59:31 +0000 |
|---|---|---|
| committer | eutarass | 2009-02-26 22:59:31 +0000 |
| commit | 621c165a02ce2ce41da80c4400d98d7ab3ff3f21 (patch) | |
| tree | 6e224e716db349f993e0a3df5ad5c0724f692697 /docs | |
| parent | 5f9d0bd3ba6b991e33f5b5f4a7d07b7e1bd91f49 (diff) | |
| download | org.eclipse.tcf-621c165a02ce2ce41da80c4400d98d7ab3ff3f21.tar.gz org.eclipse.tcf-621c165a02ce2ce41da80c4400d98d7ab3ff3f21.tar.xz org.eclipse.tcf-621c165a02ce2ce41da80c4400d98d7ab3ff3f21.zip | |
Updated Processes service description to be in sync with current implementation
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/TCF Service - Processes.html | 273 |
1 files changed, 251 insertions, 22 deletions
diff --git a/docs/TCF Service - Processes.html b/docs/TCF Service - Processes.html index 3b64c2843..4d6e334a1 100644 --- a/docs/TCF Service - Processes.html +++ b/docs/TCF Service - Processes.html @@ -16,7 +16,11 @@ <li><a href='#CmdAttach'>Attach</a> <li><a href='#CmdDetach'>Detach</a> <li><a href='#CmdTerminate'>Terminate</a> + <li><a href='#CmdGetSignalList'>Get Signal List</a> + <li><a href='#CmdGetSignalMask'>Get Signal Mask</a> + <li><a href='#CmdSetSignalMask'>Set Signal Mask</a> <li><a href='#CmdSignal'>Signal</a> + <li><a href='#CmdGetEnvironment'>Get Environment</a> <li><a href='#CmdStart'>Start</a> </ul> <li><a href='#Events'>Events</a> @@ -31,6 +35,10 @@ to attach and detach a process for debugging. Debug services, like Memory and Run Control, require a process to be attached before they can access it.</p> +<p>If a process is started by this service, its standard input/output streams are +available for client to read/write using Streams service. Stream type of such +streams is set to "Processes".</p> + <p>Command and event parameters are encoded as zero terminated <a href='TCF Specification.html#JSON'>JSON</a> strings.</p> @@ -157,13 +165,93 @@ C • <i><token></i> • Processes • terminate • <i><st R • <i><token></i> • <i><error report></i> • </font></b></pre> +<h3><a name='CmdGetSignalList'>Get Signal List</a></h3> + +<pre><b><font face="Courier New" size=2 color=#333399> +C • <i><token></i> • Processes • getSignalList • <i><string: context ID></i> • +</font></b></pre> + +<p>The command returns a complete list of available signals. The list containg all signals that can be sent to a given context.</p> + +<p>Reply:</p> + +<pre><b><font face="Courier New" size=2 color=#333399> +R • <i><token></i> • <i><error report></i> • <i><array of signal descriptions></i> • + +<i><array of signal descriptions></i> + ⇒ null + ⇒ [ ] + ⇒ [ <i><signal description list></i> ] + +<i><signal description list></i> + ⇒ <i><object: signal description></i> + ⇒ <i><signal description list></i> , <i><object: signal description></i> +</font></b></pre> + +<p>Signal description is a list of properties. Predefined signal properties are:</p> +<ul> + <li><code><b><font face="Courier New" size=2 color=#333399>"Index" : <i><int></i></font></b></code> + - bit position of the signal in bitsets that are used by Get Signal Mask and Set Signal Mask commands. + + <li><code><b><font face="Courier New" size=2 color=#333399>"Name" : <i><string></i></font></b></code> + - signal name. Client UI can show this name to a user. + + <li><code><b><font face="Courier New" size=2 color=#333399>"Code" : <i><string></i></font></b></code> + - human readable description of the signal. +</ul> + + +<h3><a name='CmdGetSignalMask'>Get Signal Mask</a></h3> + +<pre><b><font face="Courier New" size=2 color=#333399> +C • <i><token></i> • Processes • getSignalMask • <i><string: context ID></i> • +</font></b></pre> + +<p>The command returns signal mask of a process or a thread. +Bits in the mask control how signals should be handled by debug agent. +When new context is created it inherits the mask from its parent. +If context is not attached the command will return an error.</p> + +<p>Reply:</p> + +<pre><b><font face="Courier New" size=2 color=#333399> +R • <i><token></i> • <i><error report></i> • <i><int: don't stop bitset></i> • <i><int: don't pass bitset></i> • <i><int: pending bitset></i> • +</font></b></pre> +<ul> + <li>don't stop bitset - signals that should suspend execution of the context. + <li>don't pass bitset - signals that should not be delivered to the context. + <li>pending bitset - signals that are generated but not delivered yet. +</ul> +Note: "pending bitset" is meaningful only if the context is suspended. + +<h3><a name='CmdSetSignalMask'>Set Signal Mask</a></h3> + +<pre><b><font face="Courier New" size=2 color=#333399> +C • <i><token></i> • Processes • setSignalMask • <i><string: context ID></i> • <i><int: don't stop bitset></i> • <i><int: don't pass bitset></i> • +</font></b></pre> + +<p>The command sets signal mask of a process or a thread. +Bits in the mask control how signals should be handled by debug agent. +If context is not attached the command will return an error.</p> +<ul> + <li>don't stop bitset - signals that should not suspend execution of the context. + By default, debugger suspends a process before it receives a signal. + <li>don't pass bitset - signals that should not be delivered to the context. +</ul> + +<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='CmdSignal'>Signal</a></h3> <pre><b><font face="Courier New" size=2 color=#333399> C • <i><token></i> • Processes • signal • <i><string: context ID></i> • <i><int: signal></i> • </font></b></pre> -<p>The command sends a signal to a process.</p> +<p>The command sends a signal to a context.</p> <p>Reply:</p> @@ -171,11 +259,25 @@ C • <i><token></i> • Processes • signal • <i><strin R • <i><token></i> • <i><error report></i> • </font></b></pre> +<h3><a name='CmdGetEnvironment'>Get Environment</a></h3> + +<pre><b><font face="Courier New" size=2 color=#333399> +C • <i><token></i> • Processes • getEnvironment • +</font></b></pre> + +<p>The command returns default set of environment variables used to start a new process.</p> + +<p>Reply:</p> + +<pre><b><font face="Courier New" size=2 color=#333399> +R • <i><token></i> • <i><error report></i> • <i><object: environment variables></i> • +</font></b></pre> + <h3><a name='CmdStart'>Start</a></h3> <pre><b><font face="Courier New" size=2 color=#333399> C • <i><token></i> • Processes • start • <i><string: working directory></i> • <i><string: program image file></i> • - <i><string array: command line></i> • <i><string array: environment variables></i> • <i><boolean: attach></i> • + <i><string array: command line></i> • <i><object: environment variables></i> • <i><boolean: attach></i> • <i><string array></i> ⇒ null @@ -188,12 +290,14 @@ C • <i><token></i> • Processes • start • <i><string </font></b></pre> <p>The command starts a new process on remote machine. -<i><string: working directory></i> - initial value of working directory for the process. -<i><string: program image file></i> - image file to start process with. -<i><string array: command line></i> - command line arguments for the process. -<i><string array: environment variables></i> - list of environment variables for the process, -they will be added to default process environment. -<i><boolean: attach></i> - if true debugger should be attached to the process.</p> +<ul> + <li><i><string: working directory></i> - initial value of working directory for the process. + <li><i><string: program image file></i> - image file to start process with. + <li><i><string array: command line></i> - command line arguments for the process. + <li><i><object: environment variables></i> - list of environment variables for the process, + they will be added to default process environment. + <li><i><boolean: attach></i> - if true debugger should be attached to the process.</p> +</ul> <p>Reply:</p> @@ -205,7 +309,12 @@ R • <i><token></i> • <i><error report></i> • <i><c <h2><a name='Events'>Events</a></h2> -<p>No events are currently defined for Processes service.</p> +<p>Processes service broadcasts notification event when a proceess exits. +Only processes that were started by the service will generate exit event.</p> + +<pre><b><font face="Courier New" size=2 color=#333399> +E • Processes • exited • <i><string: process ID></i> • <i><int: exit code></i> • +</font></b></pre> <h2><a name='API'>API</a></h2> @@ -224,8 +333,8 @@ R • <i><token></i> • <i><error report></i> • <i><c * If the ID is not a process ID, 'IProcesses.getContext' may not return any * useful information * - * <font color=#7F9FBF><font color=#7F9FBF>@param</font></font> id – context ID. - * <font color=#7F9FBF><font color=#7F9FBF>@param</font></font> done - call back interface called when operation is completed. + * <font color=#7F9FBF>@param</font> id – context ID. + * <font color=#7F9FBF>@param</font> done - call back interface called when operation is completed. */</font> IToken getContext(String id, DoneGetContext done); @@ -280,8 +389,17 @@ R • <i><token></i> • <i><error report></i> • <i><c PROP_CAN_TERMINATE = "CanTerminate", <font color=#3F5FBF>/** Process name. Client UI can show this name to a user */</font> - PROP_NAME = "Name"; - + PROP_NAME = "Name", + + <font color=#3F5FBF>/** Process standard input stream ID */</font> + PROP_STDIN_ID = "StdInID", + + <font color=#3F5FBF>/** Process standard output stream ID */</font> + PROP_STDOUT_ID = "StdOutID", + + <font color=#3F5FBF>/** Process standard error stream ID */</font> + PROP_STDERR_ID = "StdErrID"; + <font color=#7F0055>interface</font> ProcessContext { <font color=#3F5FBF>/** @@ -306,13 +424,13 @@ R • <i><token></i> • <i><error report></i> • <i><c <font color=#3F5FBF>/** * Utility method to read context property PROP_ATTACHED. * Services like IRunControl, IMemory, IBreakpoints work only with attached processes. - * <font color=#7F9FBF><font color=#7F9FBF>@return</font></font> value of PROP_ATTACHED. + * <font color=#7F9FBF>@return</font> value of PROP_ATTACHED. */</font> <font color=#7F0055>boolean</font> isAttached(); <font color=#3F5FBF>/** * Utility method to read context property PROP_CAN_TERMINATE. - * <font color=#7F9FBF><font color=#7F9FBF>@return</font></font> value of PROP_CAN_TERMINATE. + * <font color=#7F9FBF>@return</font> value of PROP_CAN_TERMINATE. */</font> <font color=#7F0055>boolean</font> canTerminate(); @@ -344,18 +462,99 @@ R • <i><token></i> • <i><error report></i> • <i><c * <font color=#7F9FBF>@return</font> pending command handle, can be used to cancel the command. */</font> IToken terminate(DoneCommand done); + } + <font color=#7F0055>interface</font> DoneCommand { + <font color=#7F0055>void</font> doneCommand(IToken token, Exception error); + } + + <font color=#3F5FBF>/** + * Signal property names used by "getSignalList" command. + */</font> + <font color=#7F0055>static final</font> String + <font color=#3F5FBF>/** Number, bit position in the signal mask */</font> + SIG_INDEX = "Index", + + <font color=#3F5FBF>/** String, signal name, for example "SIGHUP" */</font> + SIG_NAME = "Name", + + <font color=#3F5FBF>/** Number, signal code, as defined by OS */</font> + SIG_CODE = "Code", + + <font color=#3F5FBF>/** String, human readable description of the signal */</font> + SIG_DESCRIPTION = "Description"; + + <font color=#3F5FBF>/** + * Get list of signals that can be send to the context. + * <font color=#7F9FBF>@param</font> done - call back interface called when operation is completed. + * <font color=#7F9FBF>@return</font> pending command handle, can be used to cancel the command. + */</font> + IToken getSignalList(String context_id, DoneGetSignalList done); + + <font color=#3F5FBF>/** + * Call-back interface to be called when "getSignalList" command is complete. + */</font> + <font color=#7F0055>interface</font> DoneGetSignalList { + <font color=#7F0055>void</font> doneGetSignalList(IToken token, Exception error, Collection<Map<String,Object>> list); + } + + <font color=#3F5FBF>/** + * Get process or thread signal mask. + * Bits in the mask control how signals should be handled by debug agent. + * When new context is created it inherits the mask from its parent. + * If context is not attached the command will return an error. + * <font color=#7F9FBF>@param</font> done - call back interface called when operation is completed. + * <font color=#7F9FBF>@return</font> pending command handle, can be used to cancel the command. + */</font> + IToken getSignalMask(String context_id, DoneGetSignalMask done); + + <font color=#3F5FBF>/** + * Call-back interface to be called when "getSignalMask" command is complete. + */</font> + <font color=#7F0055>interface</font> DoneGetSignalMask { <font color=#3F5FBF>/** - * Send a signal to a process. - * <font color=#7F9FBF>@param</font> signal - signal ID. - * <font color=#7F9FBF>@param</font> done - call back interface called when operation is completed. - * <font color=#7F9FBF>@return</font> pending command handle, can be used to cancel the command. + * <font color=#7F9FBF>@param</font> token - command handle. + * <font color=#7F9FBF>@param</font> dont_stop - bit-set of signals that should suspend execution of the context. + * <font color=#7F9FBF>@param</font> dont_pass - bit-set of signals that should not be delivered to the context. + * <font color=#7F9FBF>@param</font> pending - bit-set of signals that are generated but not delivered yet. + * Note: "pending" is meaningful only if the context is suspended. */</font> - IToken signal(<font color=#7F0055>int</font> signal, DoneCommand done); + <font color=#7F0055>void</font> doneGetSignalMask(IToken token, Exception error, <font color=#7F0055>int</font> dont_stop, <font color=#7F0055>int</font> dont_pass, <font color=#7F0055>int</font> pending); } - <font color=#7F0055>interface</font> DoneCommand { - <font color=#7F0055>void</font> doneCommand(IToken token, Exception error); + <font color=#3F5FBF>/** + * Set process or thread signal mask. + * Bits in the mask control how signals should be handled by debug agent. + * If context is not attached the command will return an error. + * <font color=#7F9FBF>@param</font> dont_stop - bit-set of signals that should not suspend execution of the context. + * By default, debugger suspends a context before it receives a signal. + * <font color=#7F9FBF>@param</font> dont_pass - bit-set of signals that should not be delivered to the context. + * <font color=#7F9FBF>@param</font> done - call back interface called when operation is completed. + * <font color=#7F9FBF>@return</font> pending command handle, can be used to cancel the command. + */</font> + IToken setSignalMask(String context_id, <font color=#7F0055>int</font> dont_stop, <font color=#7F0055>int</font> dont_pass, DoneCommand done); + + <font color=#3F5FBF>/** + * Send a signal to a process or thread. + * <font color=#7F9FBF>@param</font> context_id - context ID. + * <font color=#7F9FBF>@param</font> signal - signal code. + * <font color=#7F9FBF>@param</font> done - call back interface called when operation is completed. + * <font color=#7F9FBF>@return</font> pending command handle, can be used to cancel the command. + */</font> + IToken signal(String context_id, <font color=#7F0055>long</font> signal, DoneCommand done); + + <font color=#3F5FBF>/** + * Get default set of environment variables used to start a new process. + * <font color=#7F9FBF>@param</font> done - call back interface called when operation is completed. + * <font color=#7F9FBF>@return</font> pending command handle, can be used to cancel the command. + */</font> + IToken getEnvironment(DoneGetEnvironment done); + + <font color=#3F5FBF>/** + * Call-back interface to be called when "getEnvironment" command is complete. + */</font> + <font color=#7F0055>interface</font> DoneGetEnvironment { + <font color=#7F0055>void</font> doneGetEnvironment(IToken token, Exception error, Map<String,String> environment); } <font color=#3F5FBF>/** @@ -364,6 +563,7 @@ R • <i><token></i> • <i><error report></i> • <i><c * <font color=#7F9FBF>@param</font> file - process image file. * <font color=#7F9FBF>@param</font> command_line - command line arguments for the process. * <font color=#7F9FBF>@param</font> environment - list of environment variables for the process. + * if null then default set of environment variables will be used. * <font color=#7F9FBF>@param</font> attach - if true debugger should be attached to the process. * <font color=#7F9FBF>@param</font> done - call back interface called when operation is completed. * <font color=#7F9FBF>@return</font> pending command handle, can be used to cancel the command. @@ -371,9 +571,38 @@ R • <i><token></i> • <i><error report></i> • <i><c IToken start(String directory, String file, String[] command_line, String[] environment, <font color=#7F0055>boolean</font> attach, DoneStart done); + <font color=#3F5FBF>/** + * Call-back interface to be called when "start" command is complete. + */</font> <font color=#7F0055>interface</font> DoneStart { <font color=#7F0055>void</font> doneStart(IToken token, Exception error, ProcessContext process); } + + <font color=#3F5FBF>/** + * Add processes service event listener. + * <font color=#7F9FBF>@param</font> listener - event listener implementation. + */</font> + <font color=#7F0055>void</font> addListener(ProcessesListener listener); + + <font color=#3F5FBF>/** + * Remove processes service event listener. + * <font color=#7F9FBF>@param</font> listener - event listener implementation. + */</font> + <font color=#7F0055>void</font> removeListener(ProcessesListener listener); + + <font color=#3F5FBF>/** + * Process event listener is notified when a process exits. + * Event are reported only for processes that were started by 'start' command. + */</font> + <font color=#7F0055>interface</font> ProcessesListener { + + <font color=#3F5FBF>/** + * Called when a process exits. + * <font color=#7F9FBF>@param</font> process_id - process context ID + * <font color=#7F9FBF>@param</font> exit_code - process exit code + */</font> + <font color=#7F0055>void</font> exited(String process_id, <font color=#7F0055>int</font> exit_code); + } } </pre> |