Gocator API

GoTools.h
Go to the documentation of this file.
1 /**
2 * @file GoTools.h
3 * @brief Declares the GoTool classes.
4 *
5 * @internal
6 * Copyright (C) 2016-2020 by LMI Technologies Inc.
7 * Licensed under the MIT License.
8 * Redistributed files must retain the above copyright notice.
9 */
10 #ifndef GO_TOOLS_H
11 #define GO_TOOLS_H
12
13 #include <GoSdk/GoSdkDef.h>
14 #include <GoSdk/Tools/GoTool.h>
15 #include <GoSdk/Tools/GoExtTool.h>
16 #include <GoSdk/Tools/GoProfileTools.h>
17 #include <GoSdk/Tools/GoRangeTools.h>
18 #include <GoSdk/Tools/GoSurfaceTools.h>
19
20 kBeginHeader()
21
22 typedef kObject GoToolOption;
23
24 /**
25 * @class GoTools
26 * @extends kObject
27 * @ingroup GoSdk-Tools
28 * @brief Represents a collection of tools.
29 */
30 typedef kObject GoTools;
31
32 /**
33 * Returns the current number of tools.
34 *
35 * @public @memberof GoTools
36 * @version Introduced in firmware 4.0.10.27
37 * @param tools GoTools object.
38 * @return The current tool count.
39 */
40 GoFx(kSize) GoTools_ToolCount(GoTools tools);
41
42 /**
43 * Returns a tool handle at the given index.
44 *
45 * @public @memberof GoTools
46 * @version Introduced in firmware 4.0.10.27
47 * @param tools GoTools object.
48 * @param index The index with which to retrieve a tool.
49 * @return A handle to a tool at the given index or kNULL if the index is invalid.
50 */
51 GoFx(GoTool) GoTools_ToolAt(GoTools tools, kSize index);
52
53 /**
54 * Moves a tool to another position in the array
55 *
56 * @public @memberof GoTools
57 * @version Introduced in firmware 4.7.9.77
58 * @param tools GoTools object.
59 * @param index The index with which tool to move around.
60 * @param newIndex The new index at which the tool will be moved too
61 * @return Operation status
62 */
63 GoFx(kStatus) GoTools_MoveTool(GoTools tools, kSize index, kSize newIndex);
64
65 /**
66 * Adds a tool and returns a handle to it. NOTE: This function will always succeed,
67 * but the tool handle will be null if passed in and an error occurs.
68 *
69 * DEPRECATED: this API is deprecated as of 4.7.11.72. Use the
70 * GoTools_AddToolByName() API instead.
71 *
72 * @deprecated
73 * @public @memberof GoTools
74 * @version Introduced in firmware 4.0.10.27
75 * @param tools GoTools object.
76 * @param type The tool type enumerator value representing the type of tool to add.
77 * @param tool A pointer to the newly added tool.
78 * @return Operation status.
79 */
80 GoFx(kStatus) GoTools_AddTool(GoTools tools, GoToolType type, GoTool* tool);
81
82 /**
83 * Removes a tool at the given index.
84 *
85 * @public @memberof GoTools
86 * @version Introduced in firmware 4.0.10.27
87 * @param tools GoTools object.
88 * @param index The index with which to remove a tool.
89 * @return Operation status.
90 */
91 GoFx(kStatus) GoTools_RemoveTool(GoTools tools, kSize index);
92
93 /**
94 * Removes all tools in the given GoTools instance.
95 *
96 * @public @memberof GoTools
97 * @version Introduced in firmware 4.0.10.27
98 * @param tools GoTools object.
99 * @return Operation status.
100 */
101 GoFx(kStatus) GoTools_ClearTools(GoTools tools);
102
103 /**
104 * Returns an enabled measurement handle if the specified ID is valid.
105 *
106 * @public @memberof GoTools
107 * @version Introduced in firmware 4.0.10.27
108 * @param tools GoTools object.
109 * @param id The measurement ID to search for.
110 * @return A GoMeasurement object if an enabled measurement with the ID is found, otherwise kNULL.
111 */
112 GoFx(GoMeasurement) GoTools_FindMeasurementById(GoTools tools, k32u id);
113
114 /**
115 * Automatically update a given measurement to use a valid ID within the set of tools contained in the GoTools object.
116 *
117 * @public @memberof GoTools
118 * @version Introduced in firmware 4.0.10.27
119 * @param tools GoTools object.
120 * @param measurement GoMeasurement object to update.
121 * @return Operation status.
122 */
123 GoFx(kStatus) GoTools_AssignMeasurementId(GoTools tools, GoMeasurement measurement);
124
125 /**
126 * Returns the number of tool options available for the current configuration.
127 *
128 * @public @memberof GoTools
129 * @version Introduced in firmware 4.3.3.124
130 * @param tools GoTools object.
131 * @return The number of tool options available for the current configuration.
132 */
133 GoFx(kSize) GoTools_ToolOptionCount(GoTools tools);
134
135 /**
136 * Retrieves the tool option at the given index.
137 *
138 * @public @memberof GoTools
139 * @version Introduced in firmware 4.3.3.124
140 * @param tools GoTools object.
141 * @param index The index of the option list to access.
142 * @return The tool option associated with the given index.
143 */
144 GoFx(GoToolOption) GoTools_ToolOptionAt(GoTools tools, kSize index);
145
146 /**
147 * Returns the name associated with the given tool option.
148 *
149 * @public @memberof GoTools
150 * @version Introduced in firmware 4.3.3.124
151 * @param option GoToolOption object.
152 * @return The name associated with the tool option.
153 */
154 GoFx(const kChar*) GoToolOption_Name(GoToolOption option);
155
156 /**
157 * Returns the number of measurement options available for the given tool option.
158 *
159 * @public @memberof GoTools
160 * @version Introduced in firmware 4.3.3.124
161 * @param option GoToolOption object.
162 * @return The number of measurement options available for the given tool option.
163 */
164 GoFx(kSize) GoToolOption_MeasurementOptionCount(GoToolOption option);
165
166 /**
167 * Retrieves the measurement option at the given index of the tool option.
168 *
169 * @public @memberof GoTools
170 * @version Introduced in firmware 4.3.3.124
171 * @param option GoToolOption object.
172 * @param index The index of the option list to access.
173 * @return The measurement option associated with the given index.
174 */
175 GoFx(const GoMeasurementOption*) GoToolOption_MeasurementOptionAt(GoToolOption option, kSize index);
176
177 /**
178 * Returns the number of feature options available for the given tool option.
179 *
180 * @public @memberof GoTools
181 * @version Introduced in firmware 4.6.3.27
182 * @param option GoToolOption object.
183 * @return The number of feature options available for the given tool option.
184 */
185 GoFx(kSize) GoToolOption_FeatureOptionCount(GoToolOption option);
186
187 /**
188 * Retrieves the feature option at the given index of the tool option.
189 *
190 * @public @memberof GoTools
191 * @version Introduced in firmware 4.6.3.27
192 * @param option GoToolOption object.
193 * @param index The index of the option list to access.
194 * @return The feature option associated with the given index.
195 */
196 GoFx(const GoFeatureOption*) GoToolOption_FeatureOptionAt(GoToolOption option, kSize index);
197
198 /**
199 * Returns the number of tool data output options available for the given tool option.
200 *
201 * @public @memberof GoTools
202 * @version Introduced in firmware 4.7.3.97
203 * @param option GoToolOption object.
204 * @return The number of tool data output options available for the given tool option.
205 */
206 GoFx(kSize) GoToolOption_ToolDataOutputOptionCount(GoToolOption option);
207
208 /**
209 * Retrieves the tool data output option at the given index of the tool option.
210 *
211 * @public @memberof GoTools
212 * @version Introduced in firmware 4.7.3.97
213 * @param option GoToolOption object.
214 * @param index The index of the option list to access.
215 * @return The tool data output option associated with the given index.
216 */
217 GoFx(const GoToolDataOutputOption*) GoToolOption_ToolDataOutputOptionAt(GoToolOption option, kSize index);
218
219 /**
220 * Adds a tool by name.
221 *
222 * @public @memberof GoTools
223 * @version Introduced in firmware 4.3.3.124
224 * @param tools GoTools object.
225 * @param optionName The name of the tool to add.
226 * @param tool A handle to the newly constructed tool. kNULL can be used.
227 * @return Operation status.
228 * @see GoTools_ToolOptionCount, GoTools_ToolOptionAt, GoToolOption_Name
229 */
230 GoFx(kStatus) GoTools_AddToolByName(GoTools tools, const kChar* optionName, GoTool* tool);
231
232 /**
233 * Adds a measurement to a tool via a string representing the type.
234 *
235 * @public @memberof GoTools
236 * @version Introduced in firmware 4.3.3.124
237 * @param tools GoTools object.
238 * @param tool The tool of which the measurement is being added.
239 * @param type The measurement type represented as a string to be added.
240 * @param name The name to assign the new measurement.
241 * @param measurement A handle to the newly added measurement. kNULL can be used.
242 * @return Operation status.
243 * @see GoTools_ToolOptionCount, GoTools_ToolOptionAt,
244 * GoToolOption_MeasurementOptionCount, GoToolOption_MeasurementOptionAt
245 */
246 GoFx(kStatus) GoTools_AddMeasurementByName(GoTools tools, GoTool tool, const kChar* type, const kChar* name, GoMeasurement* measurement);
247
248
249
250 /**
251 * @class GoScript
252 * @extends GoTool
253 * @ingroup GoSdk-Tools
254 * @brief Represents a script tool.
255 */
256 typedef GoTool GoScript;
257
258 /**
259 * Gets the code for the script.
260 *
261 * @public @memberof GoScript
262 * @version Introduced in firmware 4.0.10.27
263 * @param tool GoScript object.
264 * @param code Receives a null-terminated string containing the script code.
265 * @return Operation status.
266 */
267 GoFx(kStatus) GoScript_Code(GoScript tool, kChar** code);
268
269 /**
270 * Sets the code for the script.
271 *
272 * @public @memberof GoScript
273 * @version Introduced in firmware 4.0.10.27
274 * @param tool GoScript object.
275 * @param code The code to set.
276 * @return Operation status.
277 */
278 GoFx(kStatus) GoScript_SetCode(GoScript tool, kChar* code);
279
280 /**
281 * Adds a script output.
282 *
283 * @public @memberof GoScript
284 * @version Introduced in firmware 4.0.10.27
285 * @param tool GoScript object.
286 * @param id An ID (must not already be used by other measurements) of the script output to add.
287 * @return Operation status.
288 */
289 GoFx(kStatus) GoScript_AddOutput(GoScript tool, k32u id);
290
291 /**
292 * Removes a script output with the specific ID.
293 *
294 * @public @memberof GoScript
295 * @version Introduced in firmware 4.0.10.27
296 * @param tool GoScript object.
297 * @param id An ID of the script output to remove.
298 * @return Operation status.
299 */
300 GoFx(kStatus) GoScript_RemoveOutput(GoScript tool, k32u id);
301
302 /**
303 * Returns the count of script tool outputs.
304 *
305 * @public @memberof GoScript
306 * @version Introduced in firmware 4.0.10.27
307 * @param tool GoScript object.
308 * @return Script output count.
309 */
310 GoFx(kSize) GoScript_OutputCount(GoScript tool);
311
312 /**
313 * Returns a handle to a script output at the given index.
314 *
315 * @public @memberof GoScript
316 * @version Introduced in firmware 4.0.10.27
317 * @param tool GoScript object.
318 * @param index The index with which to return a corresponding script output.
319 * @return A GoScriptOutput object or kNULL if the index is invalid.
320 */
321 GoFx(GoScriptOutput) GoScript_OutputAt(GoScript tool, kSize index);
322
323 kEndHeader()
324 #include <GoSdk/Tools/GoTools.x.h>
325
326 #endif
GoToolType
Lists all tool types.
k32u
GoTool.h
Declares the base GoTool class.
GoTools::GoTools_MoveTool
kStatus GoTools_MoveTool(GoTools tools, kSize index, kSize newIndex)
Moves a tool to another position in the array.
GoMeasurement
Represents the base class for a tool measurement or script output.
GoTools::GoToolOption_Name
const kChar * GoToolOption_Name(GoToolOption option)
Returns the name associated with the given tool option.
GoScript::GoScript_AddOutput
kStatus GoScript_AddOutput(GoScript tool, k32u id)
Adds a script output.
GoTools::GoTools_AddTool
kStatus GoTools_AddTool(GoTools tools, GoToolType type, GoTool *tool)
Adds a tool and returns a handle to it.
GoTools::GoToolOption_FeatureOptionAt
const GoFeatureOption * GoToolOption_FeatureOptionAt(GoToolOption option, kSize index)
Retrieves the feature option at the given index of the tool option.
GoTools::GoTools_ClearTools
kStatus GoTools_ClearTools(GoTools tools)
Removes all tools in the given GoTools instance.
GoExtTool.h
Declares the base GoExtTool class.
GoTools::GoTools_AddToolByName
kStatus GoTools_AddToolByName(GoTools tools, const kChar *optionName, GoTool *tool)
Adds a tool by name.
kSize
GoTools::GoTools_ToolCount
kSize GoTools_ToolCount(GoTools tools)
Returns the current number of tools.
GoScript::GoScript_RemoveOutput
kStatus GoScript_RemoveOutput(GoScript tool, k32u id)
Removes a script output with the specific ID.
kChar
GoScriptOutput
Represents a script output for a Script Tool.
GoTools::GoTools_RemoveTool
kStatus GoTools_RemoveTool(GoTools tools, kSize index)
Removes a tool at the given index.
GoSurfaceTools.h
Declares all surface tools and their related classes.
GoScript::GoScript_OutputAt
GoScriptOutput GoScript_OutputAt(GoScript tool, kSize index)
Returns a handle to a script output at the given index.
GoSdkDef.h
Essential SDK declarations.
GoTools::GoToolOption_MeasurementOptionCount
kSize GoToolOption_MeasurementOptionCount(GoToolOption option)
Returns the number of measurement options available for the given tool option.
GoScript::GoScript_Code
kStatus GoScript_Code(GoScript tool, kChar **code)
Gets the code for the script.
GoTool
Represents the base tool class.
GoTools::GoToolOption_MeasurementOptionAt
const GoMeasurementOption * GoToolOption_MeasurementOptionAt(GoToolOption option, kSize index)
Retrieves the measurement option at the given index of the tool option.
GoTools
Represents a collection of tools.
GoScript::GoScript_SetCode
kStatus GoScript_SetCode(GoScript tool, kChar *code)
Sets the code for the script.
GoTools::GoToolOption_FeatureOptionCount
kSize GoToolOption_FeatureOptionCount(GoToolOption option)
Returns the number of feature options available for the given tool option.
GoProfileTools.h
Declares all profile tools and their related classes.
GoTools::GoTools_AssignMeasurementId
kStatus GoTools_AssignMeasurementId(GoTools tools, GoMeasurement measurement)
Automatically update a given measurement to use a valid ID within the set of tools contained in the G...
GoScript::GoScript_OutputCount
kSize GoScript_OutputCount(GoScript tool)
Returns the count of script tool outputs.
GoScript
Represents a script tool.
GoTools::GoTools_AddMeasurementByName
kStatus GoTools_AddMeasurementByName(GoTools tools, GoTool tool, const kChar *type, const kChar *name, GoMeasurement *measurement)
Adds a measurement to a tool via a string representing the type.
GoTools::GoTools_ToolOptionCount
kSize GoTools_ToolOptionCount(GoTools tools)
Returns the number of tool options available for the current configuration.
kObject
kStatus
GoTools::GoTools_FindMeasurementById
GoMeasurement GoTools_FindMeasurementById(GoTools tools, k32u id)
Returns an enabled measurement handle if the specified ID is valid.
GoTools::GoTools_ToolOptionAt
GoToolOption GoTools_ToolOptionAt(GoTools tools, kSize index)
Retrieves the tool option at the given index.
GoTools::GoToolOption_ToolDataOutputOptionAt
const GoToolDataOutputOption * GoToolOption_ToolDataOutputOptionAt(GoToolOption option, kSize index)
Retrieves the tool data output option at the given index of the tool option.
GoTools::GoTools_ToolAt
GoTool GoTools_ToolAt(GoTools tools, kSize index)
Returns a tool handle at the given index.
GoTools::GoToolOption_ToolDataOutputOptionCount
kSize GoToolOption_ToolDataOutputOptionCount(GoToolOption option)
Returns the number of tool data output options available for the given tool option.