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