Processes service provides access to the target OS's process information, allows to start and terminate a process, and allows 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.
Command and event parameters are encoded as zero terminated JSON strings.
The service uses standard format for error reports, see Error Report Format.
C <token> Processes getContext <string: context ID>
The command retrieves context info for given context ID. A context corresponds to an execution thread, process, address space, etc. Context IDs are valid across TCF services, so it is allowed to issue 'Processes.getContext' command with a context that was obtained, for example, from Memory service. However, 'Processes.getContext' is supposed to return only process specific data. If the ID is not a process ID, 'Processes.getContext' may not return any useful information.
Reply:
R <token> <error report> <context data>
<context data>
Ψ null
Ψ <object>
Context data object should, at least, contain member "ID" : <string>.
Predefined process context properties are:
"ID" : <string>
- ID of the context, same as getContext command argument.
"ParentID" : <string>
- parent context ID.
"Name" : <string>
- process name. Client UI can show this name to a user.
"Attached" : <boolean>
- true if the context is attached to debugger.
"CanTerminate" : <boolean>
- true if the service can terminate the process.
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 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.
Reply:
R <token> <error report> <array of context IDs>
<array of context IDs>
Ψ null
Ψ [ ]
Ψ [ <context ID list> ]
<context ID list>
Ψ <string: context ID>
Ψ <context ID list> , <string: context ID>
C <token> Processes attach <string: context ID>
The command attaches debugger to a process. Services like Run Control, Memory, Breakpoints work only with attached processes.
Reply:
R <token> <error report>
C <token> Processes detach <string: context ID>
The command detaches debugger from a process.
Reply:
R <token> <error report>
C <token> Processes terminate <string: context ID>
The command terminates a process.
Reply:
R <token> <error report>
C <token> Processes signal <string: context ID> <int: signal>
The command sends a signal to a process.
Reply:
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>
<string array>
Ψ null
Ψ [ ]
Ψ [ <string list> ]
<string list>
Ψ <string>
Ψ <string list> , <string>
The command starts a new process on remote machine. <string: working directory> - initial value of working directory for the process. <string: program image file> - image file to start process with. <string array: command line> - command line arguments for the process. <string array: environment variables> - list of environment variables for the process, they will be added to default process environment. <boolean: attach> - if true debugger should be attached to the process.
Reply:
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.
No events are currently defined for Processes service.
public interface IProcesses extends IService {
static final String NAME = "Processes";
/**
* Retrieve context info for given context ID.
* A context corresponds to an execution thread, process, address space, etc.
* Context IDs are valid across TCF services, so it is allowed to issue
* 'IProcesses.getContext' command with a context that was obtained,
* for example, from Memory service.
* However, 'Processes.getContext' is supposed to return only process specific data,
* If the ID is not a process ID, 'IProcesses.getContext' may not return any
* useful information
*
* @param id context ID.
* @param done - call back interface called when operation is completed.
*/
IToken getContext(String id, DoneGetContext done);
/**
* Client call back interface for getContext().
*/
interface DoneGetContext {
/**
* Called when contexts data retrieval is done.
* @param error error description if operation failed, null if succeeded.
* @param context context data.
*/
void doneGetContext(IToken token, Exception error, ProcessContext context);
}
/**
* Retrieve children of given context.
*
* @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.
*/
IToken getChildren(String parent_context_id, boolean attached_only, DoneGetChildren done);
/**
* Client call back interface for getChildren().
*/
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.
*/
void doneGetChildren(IToken token, Exception error, String[] context_ids);
}
/**
* Context property names.
*/
static final String
/** The TCF context ID */
PROP_ID = "ID",
/** The TCF parent context ID */
PROP_PARENTID = "ParentID",
/** Is the context attached */
PROP_ATTACHED = "Attached",
/** Can terminate the context */
PROP_CAN_TERMINATE = "CanTerminate",
/** Process name. Client UI can show this name to a user */
PROP_NAME = "Name";
interface ProcessContext {
/**
* Get context ID.
* Same as getProperties().get(ID)
*/
String getID();
/**
* Get parent context ID.
* Same as getProperties().get(ParentID)
*/
String getParentID();
/**
* Get process name.
* Client UI can show this name to a user.
* Same as getProperties().get(Name)
*/
String getName();
/**
* Utility method to read context property PROP_ATTACHED.
* Services like IRunControl, IMemory, IBreakpoints work only with attached processes.
* @return value of PROP_ATTACHED.
*/
boolean isAttached();
/**
* Utility method to read context property PROP_CAN_TERMINATE.
* @return value of PROP_CAN_TERMINATE.
*/
boolean canTerminate();
/**
* Get all available context properties.
* @return Map 'property name' -> 'property value'
*/
Map<String, Object> getProperties();
/**
* Attach debugger to a process.
* Services like IRunControl, IMemory, IBreakpoints work only with attached processes.
* @param done - call back interface called when operation is completed.
* @return pending command handle, can be used to cancel the command.
*/
IToken attach(DoneCommand done);
/**
* Detach debugger from a process.
* Process execution will continue without debugger supervision.
* @param done - call back interface called when operation is completed.
* @return pending command handle, can be used to cancel the command.
*/
IToken detach(DoneCommand done);
/**
* Terminate a process.
* @param done - call back interface called when operation is completed.
* @return pending command handle, can be used to cancel the command.
*/
IToken terminate(DoneCommand done);
/**
* Send a signal to a process.
* @param signal - signal ID.
* @param done - call back interface called when operation is completed.
* @return pending command handle, can be used to cancel the command.
*/
IToken signal(int signal, DoneCommand done);
}
interface DoneCommand {
void doneCommand(IToken token, Exception error);
}
/**
* Start a new process on remote machine.
* @param directory - initial value of working directory for the process.
* @param file - process image file.
* @param command_line - command line arguments for the process.
* @param environment - list of environment variables for the process.
* @param attach - if true debugger should be attached to the process.
* @param done - call back interface called when operation is completed.
* @return pending command handle, can be used to cancel the command.
*/
IToken start(String directory, String file,
String[] command_line, String[] environment, boolean attach, DoneStart done);
interface DoneStart {
void doneStart(IToken token, Exception error, ProcessContext process);
}
}