1
/*******************************************************************************
2
* Copyright (c) 2000, 2006 QNX Software Systems and others.
3
* All rights reserved. This program and the accompanying materials
4
* are made available under the terms of the Eclipse Public License v1.0
5
* which accompanies this distribution, and is available at
6
* http://www.eclipse.org/legal/epl-v10.html
9
* QNX Software Systems - Initial API and implementation
10
*******************************************************************************/
12
package org.eclipse.cdt.debug.core.cdi;
14
import java.math.BigInteger;
16
import org.eclipse.cdt.debug.core.cdi.model.ICDITracepoint;
19
* Manages the collection of registered tracepoints and trace snapshoits
20
* in the debug session. Provides methods to control tracing.
24
public interface ICDITraceManager extends ICDISessionObject {
26
* Returns a collection of all tracepoints set for this session.
27
* Returns an empty array if no tracepoints are set.
29
* @return a collection of all tracepoints set for this session
30
* @throws CDIException on failure. Reasons include:
32
ICDITracepoint[] getTracepoints() throws CDIException;
35
* Deletes the given tracepoint.
37
* @param tracepoint - a tracepoint to be deleted
38
* @throws CDIException on failure. Reasons include:
40
void deleteTracepoint( ICDITracepoint tracepoint ) throws CDIException;
43
* Deletes the given array of tracepoints.
45
* @param tracepoints - the array of tracepoints to be deleted
46
* @throws CDIException on failure. Reasons include:
48
void deleteTracepoints( ICDITracepoint[] tracepoints ) throws CDIException;
51
* Deletes all tracepoints.
53
* @throws CDIException on failure. Reasons include:
55
void deleteAllTracepoints() throws CDIException;
58
* Sets a tracepoint at the given location.
59
* The tracepoint is set acording to the choices:
61
* if location.getFile() != null then
62
* if location.getFunction() != null then
63
* tracepoint = file:function
65
* tracepoint = file:line
66
* else if (location.getFuntion() != null) then
67
* tracepoint = function
68
* else if (location.getLineNumber() != 0 then
71
* tracepoint = address
75
* @param location - the location
76
* @return a tracepoint
77
* @throws CDIException on failure. Reasons include:
79
ICDITracepoint setTracepoint( ICDILocation location ) throws CDIException;
82
* Allows the manager to interrupt the excution of program
83
* when setting a tracepoint.
85
void allowProgramInterruption( boolean allow );
88
* Starts the tracing and begins collecting data.
90
* @throws CDIException on failure. Reasons include:
92
void startTracing() throws CDIException;
95
* Stops the tracing and ends collecting data.
97
* @throws CDIException on failure. Reasons include:
99
void stopTracing() throws CDIException;
102
* Returns the status of tracing.
104
* @return the status of tracing
105
* @throws CDIException on failure. Reasons include:
107
boolean isTracing() throws CDIException;
110
* Enables/disables the snapshot debugging mode.
112
* @param enabled <code>true</code> to enable, and <code>false</code>
114
* @throws CDIException on failure. Reasons include:
116
void enableSnapshotMode( boolean enabled ) throws CDIException;
119
* Returns all trace snapshots for this session.
121
* @return all trace snapshots for this session
122
* @throws CDIException on failure. Reasons include:
124
ICDITraceSnapshot[] getSnapshots() throws CDIException;
127
* Returns all trace snapshots associated with the given tracepoints.
129
* @param tracepoints - an array of tracepoints
130
* @return all trace snapshots associated with the given tracepoints
131
* @throws CDIException on failure. Reasons include:
133
ICDITraceSnapshot[] getSnapshots( ICDITracepoint[] tracepoints ) throws CDIException;
136
* Returns all trace snapshots associated with the given locations.
138
* @param locations - an array of locations
139
* @return all trace snapshots associated with the given locations
140
* @throws CDIException on failure. Reasons include:
142
ICDITraceSnapshot[] getSnapshots( ICDILocation[] locations ) throws CDIException;
145
* Creates an ICDILocation object for given file name and line number or function.
147
* @param file - a file name
148
* @param function - a function name
149
* @param line - a line number
150
* @return an ICDILocation object
152
ICDILocation createLocation( String file, String function, int line );
155
* Creates an ICDILocation object for given address.
157
* @param address - an address
158
* @return an ICDILocation object
160
ICDILocation createLocation( BigInteger address );