forked from u-blox/ubxlib
-
Notifications
You must be signed in to change notification settings - Fork 0
/
u_wifi_geofence.h
257 lines (239 loc) · 12.8 KB
/
u_wifi_geofence.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
/*
* Copyright 2019-2024 u-blox
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
#ifndef _U_WIFI_GEOFENCE_H_
#define _U_WIFI_GEOFENCE_H_
/* Only header files representing a direct and unavoidable
* dependency between the API of this module and the API
* of another module should be included here; otherwise
* please keep #includes to your .c files. */
#include "u_device.h"
/** \addtogroup _wifi
* @{
*/
/** @file
* @brief This header file defines the functions that apply a
* geofence, created using the common uGeofence API, to wifi.
*
* This API is ONLY available if U_CFG_GEOFENCE is defined; this
* is because it uses floating point and maths functions that would
* otherwise cause unnecessary bloat from the C library.
*
* Here you will find only the functions to apply, remove and test
* a geofence. All of the functions which manipulate the geofence
* can be found in /common/geofence/api.
*
* -----------------------------------------------------------------
*
* IMPORTANT: if the shapes in your geofence are less than 1 km in size
* then a flat surface can be assumed. For shapes larger than that,
* if you do nothing, this code will assume a spherical earth.
* However this can be out by, worst case, 0.5%, hence to get
* accurate results please see u_geofence_geodesic.h in the common
* Geofence API for the functions which must be provided to take account
* of the non-spherial nature of the earth.
*
* -----------------------------------------------------------------
*
* To use a geofence, create one or more geofences with pUGeofenceCreate()
* and then call uGeofenceAddCircle() and uGeofenceAddVertex() as
* required to form the 2D perimeters of your geofence; at least one
* circle or at least three vertices are required to form a valid
* geofence. You may also call uGeofenceSetAltitudeMax() and/or
* uGeofenceSetAltitudeMin() if that is important to you.
*
* With the geofence set up, call uWifiGeofenceSetCallback() to be informed
* as to the state of a Wi-Fi device with respect to any geofences that
* are applied to it, then call uWifiGeofenceApply() to apply the geofence
* to Wifi: from that point onwards, if a position arrives as a result of
* any of the uWifiLocXxx APIs for that instance it will be evaluated
* against the geofence and your callback(s) may be called.
*
* You may also call uWifiGeofencePosition() to supply a position for
* evaluation against the geofence "manually".
*
* When done, call uWifiGeofenceRemove() to remove the geofence from Wifi
* and then call uGeofenceFree() to free the memory that held the geofence;
* there is no automatic clean-up, it is up to the application to do this.
*/
#ifdef __cplusplus
extern "C" {
#endif
/* ----------------------------------------------------------------
* COMPILE-TIME MACROS
* -------------------------------------------------------------- */
/* ----------------------------------------------------------------
* TYPES
* -------------------------------------------------------------- */
/* ----------------------------------------------------------------
* FUNCTIONS
* -------------------------------------------------------------- */
/** Set the maximum horzontal speed that the Wi-Fi instance can be
* assumed to travel at in MILLIMETRES per second; if not called then
* #U_GEOFENCE_HORIZONTAL_SPEED_MILLIMETRES_PER_SECOND_MAX will
* be assumed. Setting this appropriately can help to reduce
* calculation overhead.
*
* @param wifiHandle the handle of the Wi-Fi
* instance.
* @param maxSpeedMillimetresPerSecond the maximum horizontal speed
* in millimetres per second.
* @return zero on success else negative
* error code.
*/
int32_t uWifiGeofenceSetMaxSpeed(uDeviceHandle_t wifiHandle,
int64_t maxSpeedMillimetresPerSecond);
/** Apply the given geofence to the given Wi-Fi instance; this
* must be called to make use of a geofence after it has been set
* up to your liking with calls to uGeofenceAddVertex() and/or
* uGeofenceAddCircle() etc. As many geofences as you like may
* be applied and the same geofence may be applied to many instances.
* You will probably also want to call uWifiGeofenceSetCallback().
*
* @param wifiHandle the handle of the Wi-Fi instance.
* @param[in] pFence a pointer to the geofence to be applied;
* cannot be NULL.
* @return zero on success else negative error code.
*/
int32_t uWifiGeofenceApply(uDeviceHandle_t wifiHandle,
uGeofence_t *pFence);
/** Remove the given geofence(s) from the given Wi-Fi instance(s).
*
* @param wifiHandle the handle of the Wi-Fi instance; use NULL
* to remove the geofence from all Wi-Fi
* instances.
* @param[in] pFence a pointer to the geofence to be removed; use
* NULL to remove all geofences from the given
* Wi-Fi instance(s).
* @return zero on success else negative error code.
*/
int32_t uWifiGeofenceRemove(uDeviceHandle_t wifiHandle,
uGeofence_t *pFence);
/** Set a callback to be called if a position reading arrives from
* the Wi-Fi device that affects any geofences that have been applied.
* There is only one callback per Wi-Fi instance, setting a new one
* will replace the previous. ANY position reading received because
* of any of the uWifiLocXxx APIs, or through uWifiGeofencePosition(),
* may trigger this callback; the callback will be called once for
* each geofence attached to the Wi-Fi instance.
*
* IMPORTANT: don't do much in your callback! There may be many,
* many, calls and they should not be blocked. Also, DEFINITELY don't
* call into the Wi-Fi or short-range APIs from your callback as the
* APIs may be locked, you will get stuck.
*
* @param wifiHandle the handle of the Wi-Fi instance.
* @param testType the type of callback; use
* #U_GEOFENCE_TEST_TYPE_NONE
* to remove an existing callback.
* @param pessimisticNotOptimistic if true then the radius of position and
* uncertainty of altitude, where present,
* are taken into account pessimistically.
* For #U_GEOFENCE_TEST_TYPE_INSIDE
* this means that if the radius is
* such that the position might _not_
* be inside the geofence(s) then the
* result will be callback with
* #U_GEOFENCE_POSITION_STATE_OUTSIDE;
* for #U_GEOFENCE_TEST_TYPE_OUTSIDE
* this means that if the radius is
* such that the position might _not_
* be outside the geofence(s) then the
* callback will be called with
* #U_GEOFENCE_POSITION_STATE_INSIDE;
* for #U_GEOFENCE_TEST_TYPE_TRANSIT, if
* the radius is such that the position
* _might_ cause a transit then the
* callback will be called with the
* opposite position state to what
* went before. Putting it another way,
* the pessimist expects the worst.
* @param[in] pCallback the function to be called; ignored
* if testType is #U_GEOFENCE_TEST_TYPE_NONE,
* otherwise cannot be NULL.
* @param[in,out] pCallbackParam parameter that will be passed to pCallback
* as its last parameter; may be NULL.
* @return zero on success else negative error code.
*/
int32_t uWifiGeofenceSetCallback(uDeviceHandle_t wifiHandle,
uGeofenceTestType_t testType,
bool pessimisticNotOptimistic,
uGeofenceCallback_t *pCallback,
void *pCallbackParam);
/** Manually provide a position to be evaluated against the geofences
* applied to a Wi-Fi instance; if set, the callback may be called once
* per fence. If you want to test a geofence with a position before
* applying it to a Wi-Fi instance, use uGeofenceTest().
*
* IMPORTANT: the latitude/longitude parameters are multiplied by
* ten to the power NINE (1e9), i.e. for a latitude of 52.1234567 you
* would pass in the value 52,123,456,700, rather than the usual
* ten to the power seven (1e7).
*
* @param wifiHandle the handle of the Wi-Fi instance;
* NULL to send the position to
* all instances.
* @param testType the type of test to perform;
* set this to
* #U_GEOFENCE_TEST_TYPE_NONE
* to just let any callbacks do their
* thing according to what you set
* for them, or set to a specific value
* to override the setting associated
* with the callbacks.
* @param pessimisticNotOptimistic if true then the test is pessimistic
* with respect to radiusMillimetres
* and altitudeUncertaintyMillimetres,
* else it is optimistic; see the
* description of this parameter to
* uWifiGeofenceSetCallback() for more
* information; ignored if testType is
* #U_GEOFENCE_TEST_TYPE_NONE.
* @param latitudeX1e9 the latitude of the position to be
* checked in degrees times ten to the
* power nine.
* @param longitudeX1e9 the longitude of the position to be
* checked in degrees times ten to the
* power nine.
* @param altitudeMillimetres the altitude of the position to be
* checked in millimetres; use INT_MIN
* to express a 2D position.
* @param radiusMillimetres the horizontal radius of the position
* to be checked in millimetres; -1 if
* the horizontal radius of position is
* unknown.
* @param altitudeUncertaintyMillimetres like radiusMillimetres but vertically;
* -1 if the altitude uncertainty is
* unknown, ignored if altitudeMillimetres
* is INT_MIN.
* @return the outcome of the evaluation; where
* there are multiple geofences inside ANY
* geofence will result in an "inside"
* outcome.
*/
uGeofencePositionState_t uWifiGeofencePosition(uDeviceHandle_t wifiHandle,
uGeofenceTestType_t testType,
bool pessimisticNotOptimistic,
int64_t latitudeX1e9,
int64_t longitudeX1e9,
int32_t altitudeMillimetres,
int32_t radiusMillimetres,
int32_t altitudeUncertaintyMillimetres);
#ifdef __cplusplus
}
#endif
/** @}*/
#endif // _U_WIFI_GEOFENCE_H_
// End of file