Gocator API
 All Classes Files Functions Variables Typedefs Macros Groups 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) 2011-2012 by LMI Technologies Inc.
7  * Licensed under the MIT License.
8  * Redistributed files must retain the above copyright notice.
9  */
10 #ifndef GO_API_DISCOVERY_H
11 #define GO_API_DISCOVERY_H
12 
13 #include <GoSdk/GoSdkDef.h>
14 #include <kApi/Data/kArrayList.h>
15 kBeginHeader()
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
28 
29 /**
30  * @class GoDiscovery
31  * @extends kObject
32  * @ingroup GoSdk-Internal
33  * @brief Represents a discovery client.
34  */
35 typedef kObject GoDiscovery;
36 
37 /** Defines the signature for a discovery enumeration handler. */
38 typedef kStatus (kCall* GoDiscoveryEnumFx)(kPointer context, GoDiscovery discovery, kArrayList info);
39 
40 /**
41  * Constructs a GoDiscovery object.
42  *
43  * @public @memberof GoDiscovery
44  * @param discovery Receives constructed discovery object.
45  * @param allocator Memory allocator (or kNULL for default)
46  * @return Operation status.
47  */
48 GoFx(kStatus) GoDiscovery_Construct(GoDiscovery* discovery, kAlloc allocator);
49 
50 /**
51  * Enumerates sensors present in the network.
52  *
53  * @public @memberof GoDiscovery
54  * @param discovery Discovery object.
55  * @param infoList List to be populated with sensor descriptors (kArrayList<GoDiscoveryInfo>).
56  * @return Operation status.
57  */
58 GoFx(kStatus) GoDiscovery_Enumerate(GoDiscovery discovery, kArrayList infoList);
59 
60 /**
61  * Configures a sensor's network address settings.
62  *
63  * This function uses UDP broadcasts; the sensor and can be on a different subnet than the client.
64  *
65  * The sensor will automatically reboot if the address is successfully changed.
66  *
67  * @public @memberof GoDiscovery
68  * @param discovery Discovery object.
69  * @param deviceId Sensor device identifier (serial number).
70  * @param address New address information.
71  * @return Operation status.
72  */
73 GoFx(kStatus) GoDiscovery_SetAddress(GoDiscovery discovery, k32u deviceId, const GoAddressInfo* address);
74 
75 /**
76  * Retrieves a sensor's network address settings.
77  *
78  * This function uses UDP broadcasts; the sensor and can be on a different subnet than the client.
79  *
80  * @public @memberof GoDiscovery
81  * @param discovery Discovery object.
82  * @param deviceId Sensor device identifier (serial number).
83  * @param address Receives address information.
84  * @return Operation status.
85  */
86 GoFx(kStatus) GoDiscovery_GetAddress(GoDiscovery discovery, k32u deviceId, GoAddressInfo* address);
87 
88 /**
89  * Sets the enumeration period that will be used when background updates are enabled via StartEnum.
90  *
91  * @public @memberof GoDiscovery
92  * @param discovery Discovery object.
93  * @param period Enumeration period, in microseconds.
94  * @return Operation status.
95  */
96 GoFx(kStatus) GoDiscovery_SetEnumPeriod(GoDiscovery discovery, k64u period);
97 
98 /**
99  * Sets the enumeration callback to be used when background updates are enabled via StartEnum.
100  *
101  * @public @memberof GoDiscovery
102  * @param discovery Discovery object.
103  * @param function Enumeration callback function (or kNULL to unregister).
104  * @param receiver Receiver argument for callback.
105  * @return Operation status.
106  */
107 GoFx(kStatus) GoDiscovery_SetEnumHandler(GoDiscovery discovery, GoDiscoveryEnumFx function, kPointer receiver);
108 
109 /**
110  * Starts periodic background discovery enumeration.
111  *
112  * @public @memberof GoDiscovery
113  * @param discovery Discovery object.
114  * @param waitFirst kTRUE to block until first enumeration cycle is completed; kFALSE otherwise.
115  * @return Operation status.
116  */
117 GoFx(kStatus) GoDiscovery_StartEnum(GoDiscovery discovery, kBool waitFirst);
118 
119 /**
120  * Stops periodic background discovery enumeration.
121  *
122  * @public @memberof GoDiscovery
123  * @param discovery Discovery object.
124  * @return Operation status.
125  */
126 GoFx(kStatus) GoDiscovery_StopEnum(GoDiscovery discovery);
127 
128 kEndHeader()
129 #include <GoSdk/GoDiscovery.x.h>
130 
131 #endif
kStatus GoDiscovery_GetAddress(GoDiscovery discovery, k32u deviceId, GoAddressInfo *address)
Retrieves a sensor's network address settings.
Represents discovery information for a single device.
Definition: GoDiscovery.h:15
kStatus GoDiscovery_StartEnum(GoDiscovery discovery, kBool waitFirst)
Starts periodic background discovery enumeration.
kStatus(kCall * GoDiscoveryEnumFx)(kPointer context, GoDiscovery discovery, kArrayList info)
Defines the signature for a discovery enumeration handler.
Definition: GoDiscovery.h:38
kStatus GoDiscovery_SetAddress(GoDiscovery discovery, k32u deviceId, const GoAddressInfo *address)
Configures a sensor's network address settings.
GoDiscoveryInfo
Definition: GoDiscovery.h:27
Essential API declarations.
kStatus GoDiscovery_Enumerate(GoDiscovery discovery, kArrayList infoList)
Enumerates sensors present in the network.
kStatus GoDiscovery_SetEnumPeriod(GoDiscovery discovery, k64u period)
Sets the enumeration period that will be used when background updates are enabled via StartEnum...
Represents a discovery client.
kStatus GoDiscovery_Construct(GoDiscovery *discovery, kAlloc allocator)
Constructs a GoDiscovery object.
kStatus GoDiscovery_SetEnumHandler(GoDiscovery discovery, GoDiscoveryEnumFx function, kPointer receiver)
Sets the enumeration callback to be used when background updates are enabled via StartEnum.
Sensor network address settings.
Definition: GoSdkDef.h:382
kStatus GoDiscovery_StopEnum(GoDiscovery discovery)
Stops periodic background discovery enumeration.