Gocator API
 All Classes Files Functions Variables Typedefs Macros Modules Pages
GoDiscovery.h
Go to the documentation of this file.
1 /**
2  * @file GoDiscovery.h
3  * @brief Declares discovery-related types.
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_SDK_DISCOVERY_H
11 #define GO_SDK_DISCOVERY_H
12 
13 #include <GoSdk/GoSdkDef.h>
14 #include <kApi/Data/kArrayList.h>
16 
17 /**
18  * @struct GoDiscoveryInfo
19  * @extends kValue
20  * @ingroup GoSdk-Internal
21  * @brief Represents discovery information for a single device.
22  */
23 typedef struct GoDiscoveryInfo
24 {
25  k32u id; ///< device identifier (serial number)
26  GoAddressInfo address; ///< network configuration
27  GoPortInfo ports;
28 
29  // Gocator firmware version the sensor is running.
30  kVersion version;
31  // opMode: indicates if the main controller (host) is:
32  // a. a virtual sensor, or
33  // b. a standalone sensor, or
34  // c. an accelerator host that is accelerating a sensor.
35  GoDiscoveryOpMode opMode;
36  // If opMode indicates main controller is an accelerator host,
37  // then the IP address of the accelerated sensor
38  // is stored in the following field.
39  // Otherwise, this field is not meaningful.
40  kIpAddress accelSensorIpAddress;
41 
42  // IP address of the discovery server that sent the discovery information
43  // about the sensor. This can be the physical sensor or a host controller
44  // (eg. virtual sensor, accelerated sensor).
45  kIpAddress discoveryServerAddress;
46 
47  // Basic identifying sensor traits received via discovery information
48  // about the sensor.
49  kText32 partNumber;
50  kText32 modelNumber;
51  kText32 modelDisplayName;
52  kText32 family;
54 
55 /**
56  * @class GoDiscovery
57  * @extends kObject
58  * @ingroup GoSdk-Internal
59  * @brief Represents a discovery client.
60  */
61 typedef kObject GoDiscovery;
62 
63 /** Defines the signature for a discovery enumeration handler. */
64 typedef kStatus (kCall* GoDiscoveryEnumFx)(kPointer context, GoDiscovery discovery, kArrayList info);
65 
66 /**
67  * Constructs a GoDiscovery object.
68  *
69  * @public @memberof GoDiscovery
70  * @version Introduced in firmware 4.0.10.27
71  * @param discovery Receives constructed discovery object.
72  * @param enableAutoDiscovery whether or not to enable all interfaces to support running the Discovery Protocol.
73  * @param allocator Memory allocator (or kNULL for default)
74  * @return Operation status.
75  */
76 GoFx(kStatus) GoDiscovery_Construct(GoDiscovery* discovery, kBool enableAutoDiscovery, kAlloc allocator);
77 
78 /**
79  * Enumerates sensors present in the network.
80  *
81  * @public @memberof GoDiscovery
82  * @version Introduced in firmware 4.0.10.27
83  * @param discovery Discovery object.
84  * @param infoList List to be populated with sensor descriptors (kArrayList<GoDiscoveryInfo>).
85  * @return Operation status.
86  */
87 GoFx(kStatus) GoDiscovery_Enumerate(GoDiscovery discovery, kArrayList infoList);
88 
89 /**
90  * Configures a sensor's network address settings.
91  *
92  * This function uses UDP broadcasts; the sensor and can be on a different subnet than the client.
93  *
94  * The sensor will automatically reboot if the address is successfully changed.
95  *
96  * @public @memberof GoDiscovery
97  * @version Introduced in firmware 4.0.10.27
98  * @param discovery Discovery object.
99  * @param deviceId Sensor device identifier (serial number).
100  * @param address New address information.
101  * @return Operation status.
102  */
103 GoFx(kStatus) GoDiscovery_SetAddress(GoDiscovery discovery, k32u deviceId, const GoAddressInfo* address);
104 
105 /**
106  * Retrieves a sensor's network address settings.
107  *
108  * This function uses UDP broadcasts; the sensor and can be on a different subnet than the client.
109  *
110  * @public @memberof GoDiscovery
111  * @version Introduced in firmware 4.0.10.27
112  * @param discovery Discovery object.
113  * @param deviceId Sensor device identifier (serial number).
114  * @param address Receives address information.
115  * @return Operation status.
116  */
117 GoFx(kStatus) GoDiscovery_GetAddress(GoDiscovery discovery, k32u deviceId, GoAddressInfo* address);
118 
119 /**
120  * Retrieves a sensor's information.
121  *
122  * This function uses UDP broadcasts; the sensor and can be on a different subnet than the client.
123  *
124  * @public @memberof GoDiscovery
125  * @version Introduced in firmware 4.3.3.124
126  * @param discovery Discovery object.
127  * @param deviceId Sensor device identifier (serial number).
128  * @param info Receives sensor information.
129  * @param allocator Memory allocator. In order to prevent memory leaks,
130  * the received information object should be destroyed when no longer used.
131  * @return Operation status.
132  */
133 GoFx(kStatus) GoDiscovery_GetExtendedInfo(GoDiscovery discovery, k32u deviceId, GoDiscoveryExtInfo* info, kAlloc allocator);
134 
135 /**
136  * Sets the enumeration period that will be used when background updates are enabled via StartEnum.
137  *
138  * @public @memberof GoDiscovery
139  * @version Introduced in firmware 4.0.10.27
140  * @param discovery Discovery object.
141  * @param period Enumeration period, in microseconds.
142  * @return Operation status.
143  */
144 GoFx(kStatus) GoDiscovery_SetEnumPeriod(GoDiscovery discovery, k64u period);
145 
146 /**
147  * Sets the enumeration callback to be used when background updates are enabled via StartEnum.
148  *
149  * @public @memberof GoDiscovery
150  * @version Introduced in firmware 4.0.10.27
151  * @param discovery Discovery object.
152  * @param function Enumeration callback function (or kNULL to unregister).
153  * @param receiver Receiver argument for callback.
154  * @return Operation status.
155  */
156 GoFx(kStatus) GoDiscovery_SetEnumHandler(GoDiscovery discovery, GoDiscoveryEnumFx function, kPointer receiver);
157 
158 /**
159  * Starts periodic background discovery enumeration.
160  *
161  * @public @memberof GoDiscovery
162  * @version Introduced in firmware 4.0.10.27
163  * @param discovery Discovery object.
164  * @param waitFirst kTRUE to block until first enumeration cycle is completed; kFALSE otherwise.
165  * @return Operation status.
166  */
167 GoFx(kStatus) GoDiscovery_StartEnum(GoDiscovery discovery, kBool waitFirst);
168 
169 /**
170  * Stops periodic background discovery enumeration.
171  *
172  * @public @memberof GoDiscovery
173  * @version Introduced in firmware 4.0.10.27
174  * @param discovery Discovery object.
175  * @return Operation status.
176  */
177 GoFx(kStatus) GoDiscovery_StopEnum(GoDiscovery discovery);
178 
179 /**
180 * Enable or disable running the Gocator Discovery Protocol over the specified
181 * host interface which the given address.
182 *
183 * @public @memberof GoDiscovery
184 * @version Introduced in firmware 4.6.7.157
185 * @param discovery Discovery object.
186 * @param address IP address of interface over which the discovery protocol should run.
187 * @param enable Select whether to enable or disable the interface.
188 * @return Operation status.
189 */
190 GoFx(kStatus) GoDiscovery_SetOneInterface(GoDiscovery discovery, kIpAddress* address, kBool enable);
191 
192 /**
193 * Enable running the Gocator Discovery Protocol over all the host interfaces.
194 *
195 * @public @memberof GoDiscovery
196 * @version Introduced in firmware 4.6.7.157
197 * @param discovery Discovery object.
198 * @param enable Select whether to enable or disable the interface.
199 * @return Operation status.
200 */
201 GoFx(kStatus) GoDiscovery_SetAllInterface(GoDiscovery discovery, kBool enable);
202 
203 /**
204 * Enables or disables compatibility mode.
205 *
206 * Compatibility mode allows discovery of older firmware but increase
207 * broadcast traffic.
208 *
209 * @public @memberof GoDiscovery
210 * @version Introduced in firmware 5.2.18.3
211 * @param discovery Discovery object.
212 * @param enable Enable or disable compatibility mode.
213 * @return Operation status.
214 */
215 GoFx(kStatus) GoDiscovery_EnableCompatMode(GoDiscovery discovery, kBool enable);
216 
217 /**
218 * Gets the current state of compatibility mode.
219 *
220 * @public @memberof GoDiscovery
221 * @version Introduced in firmware 5.2.18.3
222 * @param discovery Discovery object.
223 * @return Compatibility enable flag.
224 */
226 
227 #include <GoSdk/Internal/GoDiscovery.x.h>
228 
229 #endif
Ports used from a source device.
Definition: GoSdkDef.h:802
kStatus GoDiscovery_SetAddress(GoDiscovery discovery, k32u deviceId, const GoAddressInfo *address)
Configures a sensor's network address settings.
kStatus GoDiscovery_StopEnum(GoDiscovery discovery)
Stops periodic background discovery enumeration.
kStatus GoDiscovery_SetEnumPeriod(GoDiscovery discovery, k64u period)
Sets the enumeration period that will be used when background updates are enabled via StartEnum...
Represents discovery information for a single device.
Definition: GoDiscovery.h:23
kStatus GoDiscovery_GetAddress(GoDiscovery discovery, k32u deviceId, GoAddressInfo *address)
Retrieves a sensor's network address settings.
GoAddressInfo address
network configuration
Definition: GoDiscovery.h:26
kStatus GoDiscovery_SetEnumHandler(GoDiscovery discovery, GoDiscoveryEnumFx function, kPointer receiver)
Sets the enumeration callback to be used when background updates are enabled via StartEnum.
Declares the GoDiscoveryExtInfo class and related types.
Represents operational mode of the main controller responding to the discovery protocol.
kStatus GoDiscovery_SetOneInterface(GoDiscovery discovery, kIpAddress *address, kBool enable)
Enable or disable running the Gocator Discovery Protocol over the specified host interface which the ...
kStatus GoDiscovery_EnableCompatMode(GoDiscovery discovery, kBool enable)
Enables or disables compatibility mode.
Essential SDK declarations.
kStatus GoDiscovery_GetExtendedInfo(GoDiscovery discovery, k32u deviceId, GoDiscoveryExtInfo *info, kAlloc allocator)
Retrieves a sensor's information.
kStatus GoDiscovery_SetAllInterface(GoDiscovery discovery, kBool enable)
Enable running the Gocator Discovery Protocol over all the host interfaces.
kStatus GoDiscovery_Construct(GoDiscovery *discovery, kBool enableAutoDiscovery, kAlloc allocator)
Constructs a GoDiscovery object.
kStatus GoDiscovery_Enumerate(GoDiscovery discovery, kArrayList infoList)
Enumerates sensors present in the network.
kBool GoDiscovery_CompatModeEnabled(GoDiscovery discovery)
Gets the current state of compatibility mode.
Represents a discovery client.
Represents an extended Discovery Information object.
kStatus(kCall * GoDiscoveryEnumFx)(kPointer context, GoDiscovery discovery, kArrayList info)
Defines the signature for a discovery enumeration handler.
Definition: GoDiscovery.h:64
k32u id
device identifier (serial number)
Definition: GoDiscovery.h:25
kStatus GoDiscovery_StartEnum(GoDiscovery discovery, kBool waitFirst)
Starts periodic background discovery enumeration.
Sensor network address settings.
Definition: GoSdkDef.h:788