Asterisk - The Open Source Telephony Project  21.4.1
res_geolocation.h
1  /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2022, Sangoma Technologies Corporation
5  *
6  * George Joseph <gjoseph@sangoma.com>
7  *
8  * See http://www.asterisk.org for more information about
9  * the Asterisk project. Please do not directly contact
10  * any of the maintainers of this project for assistance;
11  * the project provides a web site, mailing lists and IRC
12  * channels for your use.
13  *
14  * This program is free software, distributed under the terms of
15  * the GNU General Public License Version 2. See the LICENSE file
16  * at the top of the source tree.
17  */
18 
19 #ifndef INCLUDE_ASTERISK_RES_GEOLOCATION_H_
20 #define INCLUDE_ASTERISK_RES_GEOLOCATION_H_
21 
22 #include "asterisk/channel.h"
23 #include "asterisk/config.h"
24 #include "asterisk/sorcery.h"
25 #include "asterisk/xml.h"
26 #include "asterisk/optional_api.h"
27 
28 #define AST_GEOLOC_INVALID_VALUE -1
29 
30 enum ast_geoloc_pidf_element {
31  AST_PIDF_ELEMENT_NONE = 0,
32  AST_PIDF_ELEMENT_DEVICE,
33  AST_PIDF_ELEMENT_TUPLE,
34  AST_PIDF_ELEMENT_PERSON,
35  AST_PIDF_ELEMENT_LAST,
36 };
37 
38 enum ast_geoloc_format {
39  AST_GEOLOC_FORMAT_NONE = 0,
40  AST_GEOLOC_FORMAT_CIVIC_ADDRESS,
41  AST_GEOLOC_FORMAT_GML,
42  AST_GEOLOC_FORMAT_URI,
43  AST_GEOLOC_FORMAT_LAST,
44 };
45 
46 enum ast_geoloc_precedence {
47  AST_GEOLOC_PRECED_PREFER_INCOMING = 0,
48  AST_GEOLOC_PRECED_PREFER_CONFIG,
49  AST_GEOLOC_PRECED_DISCARD_INCOMING,
50  AST_GEOLOC_PRECED_DISCARD_CONFIG,
51 };
52 
53 #define CONFIG_STR_TO_ENUM_DECL(_stem) int ast_geoloc_ ## _stem ## _str_to_enum(const char *str);
54 CONFIG_STR_TO_ENUM_DECL(pidf_element)
55 CONFIG_STR_TO_ENUM_DECL(format);
56 CONFIG_STR_TO_ENUM_DECL(precedence);
57 #define GEOLOC_ENUM_TO_NAME_DECL(_stem) const char * ast_geoloc_ ## _stem ## _to_name(int ix);
58 GEOLOC_ENUM_TO_NAME_DECL(pidf_element)
59 GEOLOC_ENUM_TO_NAME_DECL(format);
60 GEOLOC_ENUM_TO_NAME_DECL(precedence);
61 
63  SORCERY_OBJECT(details);
65  AST_STRING_FIELD(method);
66  AST_STRING_FIELD(location_source);
67  );
68  enum ast_geoloc_format format;
69  struct ast_variable *location_info;
70  struct ast_variable *confidence;
71 };
72 
74  SORCERY_OBJECT(details);
76  AST_STRING_FIELD(location_reference);
77  AST_STRING_FIELD(notes);
78  AST_STRING_FIELD(method);
79  AST_STRING_FIELD(location_source);
80  );
81  enum ast_geoloc_pidf_element pidf_element;
82  enum ast_geoloc_precedence precedence;
83  int allow_routing_use;
84  struct ast_variable *location_refinement;
85  struct ast_variable *location_variables;
86  struct ast_variable *usage_rules;
87  int suppress_empty_ca_elements;
88  enum ast_geoloc_format format;
89  struct ast_variable *location_info;
90  struct ast_variable *confidence;
91 };
92 
95  AST_STRING_FIELD(id);
96  AST_STRING_FIELD(location_reference);
97  AST_STRING_FIELD(location_source);
98  AST_STRING_FIELD(method);
99  AST_STRING_FIELD(notes);
100  );
101  enum ast_geoloc_pidf_element pidf_element;
102  enum ast_geoloc_precedence precedence;
103  int allow_routing_use;
104  enum ast_geoloc_format format;
105  struct ast_variable *location_info;
106  struct ast_variable *location_refinement;
107  struct ast_variable *location_variables;
108  struct ast_variable *effective_location;
109  struct ast_variable *usage_rules;
110  struct ast_variable *confidence;
111  int suppress_empty_ca_elements;
112 };
113 
114 /*!
115  * \brief Check if res_geolocation is available
116  *
117  * \return 1 if available, 0 otherwise.
118  */
119 AST_OPTIONAL_API(int, ast_geoloc_is_loaded, (void), { return 0; });
120 
121 /*!
122  * \brief Retrieve a geolocation location object by id.
123  *
124  * \param id Location object id.
125  *
126  * \return Location object or NULL if not found.
127  */
128 AST_OPTIONAL_API(struct ast_geoloc_location *, ast_geoloc_get_location,
129  (const char *id),
130  { return NULL; });
131 
132 /*!
133  * \brief Retrieve a geolocation profile by id.
134  *
135  * \param id profile id.
136  *
137  * \return Profile or NULL if not found.
138  */
139 AST_OPTIONAL_API(struct ast_geoloc_profile *, ast_geoloc_get_profile,
140  (const char *id),
141  { return NULL; });
142 
143 /*!
144  * \brief Given a civicAddress code, check whether it's valid.
145  *
146  * \param code Pointer to the code to check
147  *
148  * \return 1 if valid, 0 otherwise.
149  */
150 int ast_geoloc_civicaddr_is_code_valid(const char *code);
151 
152 enum ast_geoloc_validate_result {
153  AST_GEOLOC_VALIDATE_INVALID_VALUE = -1,
154  AST_GEOLOC_VALIDATE_SUCCESS = 0,
155  AST_GEOLOC_VALIDATE_MISSING_SHAPE,
156  AST_GEOLOC_VALIDATE_INVALID_SHAPE,
157  AST_GEOLOC_VALIDATE_INVALID_VARNAME,
158  AST_GEOLOC_VALIDATE_NOT_ENOUGH_VARNAMES,
159  AST_GEOLOC_VALIDATE_TOO_MANY_VARNAMES,
160 };
161 
162 const char *ast_geoloc_validate_result_to_str(enum ast_geoloc_validate_result result);
163 
164 /*!
165  * \brief Validate that the names of the variables in the list are valid codes or synonyms
166  *
167  * \param varlist Variable list to check.
168  * \param[out] result Pointer to char * to receive failing item.
169  *
170  * \return result code.
171  */
172 enum ast_geoloc_validate_result ast_geoloc_civicaddr_validate_varlist(
173  const struct ast_variable *varlist, const char **result);
174 
175 /*!
176  * \brief Validate that the variables in the list represent a valid GML shape
177  *
178  * \param varlist Variable list to check.
179  * \param[out] result Pointer to char * to receive failing item.
180  *
181  * \return result code.
182  */
183 enum ast_geoloc_validate_result ast_geoloc_gml_validate_varlist(const struct ast_variable *varlist,
184  const char **result);
185 
186 
187 /*!
188  * \brief Geolocation datastore Functions
189  * @{
190  */
191 
192 /*!
193  * \brief Create a geoloc datastore from a profile name
194  *
195  * \param profile_name The name of the profile to use.
196  *
197  * \return The datastore.
198  */
199 struct ast_datastore *ast_geoloc_datastore_create_from_profile_name(const char *profile_name);
200 
201 /*!
202  * \brief Create a geoloc datastore from an effective profile.
203  *
204  * \param eprofile The effective profile to use.
205  *
206  * \return The datastore.
207  */
208 struct ast_datastore *ast_geoloc_datastore_create_from_eprofile(
209  struct ast_geoloc_eprofile *eprofile);
210 
211 /*!
212  * \brief Create an empty geoloc datastore.
213  *
214  * \param id An id to use for the datastore.
215  *
216  * \return The datastore.
217  */
218 struct ast_datastore *ast_geoloc_datastore_create(const char *id);
219 
220 /*!
221  * \brief Retrieve a geoloc datastore's id.
222  *
223  * \param ds The datastore
224  *
225  * \return The datastore's id.
226  */
227 const char *ast_geoloc_datastore_get_id(struct ast_datastore *ds);
228 
229 /*!
230  * \brief Add an eprofile to a datastore
231  *
232  * \param ds The datastore
233  * \param eprofile The eprofile to add.
234  *
235  * \return The new number of eprofiles or -1 to indicate a failure.
236  */
237 int ast_geoloc_datastore_add_eprofile(struct ast_datastore *ds,
238  struct ast_geoloc_eprofile *eprofile);
239 
240 /*!
241  * \brief Insert an eprofile to a datastore at the specified position
242  *
243  * \param ds The datastore
244  * \param eprofile The eprofile to add.
245  * \param index The position to insert at. Existing eprofiles will
246  * be moved up to make room.
247  *
248  * \return The new number of eprofiles or -1 to indicate a failure.
249  */
250 int ast_geoloc_datastore_insert_eprofile(struct ast_datastore *ds,
251  struct ast_geoloc_eprofile *eprofile, int index);
252 
253 /*!
254  * \brief Retrieves the number of eprofiles in the datastore
255  *
256  * \param ds The datastore
257  *
258  * \return The number of eprofiles.
259  */
260 int ast_geoloc_datastore_size(struct ast_datastore *ds);
261 
262 /*!
263  * \brief Sets the inheritance flag on the datastore
264  *
265  * \param ds The datastore
266  * \param inherit 1 to allow the datastore to be inherited by other channels
267  * 0 to prevent the datastore to be inherited by other channels
268  *
269  * \return 0 if successful, -1 otherwise.
270  */
271 int ast_geoloc_datastore_set_inheritance(struct ast_datastore *ds, int inherit);
272 
273 /*!
274  * \brief Retrieve a specific eprofile from a datastore by index
275  *
276  * \param ds The datastore
277  * \param ix The index
278  *
279  * \return The effective profile ao2 object with its reference count bumped.
280  */
281 struct ast_geoloc_eprofile *ast_geoloc_datastore_get_eprofile(struct ast_datastore *ds, int ix);
282 
283 /*!
284  * \brief Delete a specific eprofile from a datastore by index
285  *
286  * \param ds The datastore
287  * \param ix The index
288  *
289  * \return 0 if succesful, -1 otherwise.
290  */
291 int ast_geoloc_datastore_delete_eprofile(struct ast_datastore *ds, int ix);
292 
293 /*!
294  * \brief Retrieves the geoloc datastore from a channel, if any
295  *
296  * \param chan Channel
297  *
298  * \return datastore if found, NULL otherwise.
299  */
300 struct ast_datastore *ast_geoloc_datastore_find(struct ast_channel *chan);
301 
302 /*!
303  * @}
304  */
305 
306 /*!
307  * \brief Geolocation Effective Profile Functions
308  * @{
309  */
310 
311 /*!
312  * \brief Allocate a new, empty effective profile.
313  *
314  * \param name The profile's name
315  *
316  * \return The effective profile ao2 object.
317  */
318 struct ast_geoloc_eprofile *ast_geoloc_eprofile_alloc(const char *name);
319 
320 /*!
321  * \brief Duplicate an effective profile.
322  *
323  * \param src The eprofile to duplicate.
324  *
325  * \return The duplicated effective profile ao2 object.
326  */
327 struct ast_geoloc_eprofile *ast_geoloc_eprofile_dup(struct ast_geoloc_eprofile *src);
328 
329 /*!
330  * \brief Allocate a new effective profile from an existing profile.
331  *
332  * \param profile The profile to use.
333  *
334  * \return The effective profile ao2 object.
335  */
336 struct ast_geoloc_eprofile *ast_geoloc_eprofile_create_from_profile(struct ast_geoloc_profile *profile);
337 
338 /*!
339  * \brief Allocate a new effective profile from an XML PIDF-LO document
340  *
341  * \param pidf_xmldoc The ast_xml_doc to use.
342  * \param geoloc_uri The URI that referenced this document.
343  * \param reference_string An identifying string to use in error messages.
344  *
345  * \return The effective profile ao2 object.
346  */
347 struct ast_geoloc_eprofile *ast_geoloc_eprofile_create_from_pidf(
348  struct ast_xml_doc *pidf_xmldoc, const char *geoloc_uri, const char *reference_string);
349 
350 /*!
351  * \brief Allocate a new effective profile from a URI.
352  *
353  * \param uri The URI to use.
354  * \param reference_string An identifying string to use in error messages.
355  *
356  * \return The effective profile ao2 object.
357  */
358 struct ast_geoloc_eprofile *ast_geoloc_eprofile_create_from_uri(const char *uri,
359  const char *reference_string);
360 
361 /*!
362  * \brief Convert a URI eprofile to a URI string
363  *
364  * \param eprofile Effective profile to convert
365  * \param chan Channel to use to resolve variables
366  * \param buf Pointer to ast_str pointer to use for work
367  * \param ref_string An identifying string to use in error messages.
368  *
369  * \return String representation of URI allocated from buf or NULL on failure
370  */
371 const char *ast_geoloc_eprofile_to_uri(struct ast_geoloc_eprofile *eprofile,
372  struct ast_channel *chan, struct ast_str **buf, const char *ref_string);
373 
374 /*!
375  * \brief Convert a datastore containing eprofiles to a PIDF-LO document
376  *
377  * \param ds Datastore containing effective profiles to convert
378  * \param chan Channel to use to resolve variables
379  * \param buf Pointer to ast_str pointer to use for work
380  * \param ref_string An identifying string to use in error messages.
381  *
382  * \return String representation PIDF-LO allocated from buf or NULL on failure.
383  */
384 const char *ast_geoloc_eprofiles_to_pidf(struct ast_datastore *ds,
385  struct ast_channel *chan, struct ast_str **buf, const char * ref_string);
386 
387 /*!
388  * \brief Convert a single eprofile to a PIDF-LO document
389  *
390  * \param eprofile Effective profile to convert
391  * \param chan Channel to use to resolve variables
392  * \param buf Pointer to ast_str pointer to use for work
393  * \param ref_string An identifying string to use in error messages.
394  *
395  * \return String representation PIDF-LO allocated from buf or NULL on failure.
396  */
397 const char *ast_geoloc_eprofile_to_pidf(struct ast_geoloc_eprofile *eprofile,
398  struct ast_channel *chan, struct ast_str **buf, const char * ref_string);
399 
400 /*!
401  * \brief Refresh the effective profile with any changed info.
402  *
403  * \param eprofile The eprofile to refresh.
404  *
405  * \return 0 on success, any other value on error.
406  */
407 int ast_geoloc_eprofile_refresh_location(struct ast_geoloc_eprofile *eprofile);
408 
409 /*!
410  * @}
411  */
412 
413 #endif /* INCLUDE_ASTERISK_RES_GEOLOCATION_H_ */
Main Channel structure associated with a channel.
Optional API function macros.
Structure for variables, used for configurations and for channel variables.
#define SORCERY_OBJECT(details)
Macro which must be used at the beginning of each sorcery capable object.
Definition: sorcery.h:356
#define AST_OPTIONAL_API(result, name, proto, stub)
Declare an optional API function.
Definition: optional_api.h:230
#define AST_DECLARE_STRING_FIELDS(field_list)
Declare the fields needed in a structure.
Definition: stringfields.h:341
Structure for a data store object.
Definition: datastore.h:64
Configuration File Parser.
General Asterisk PBX channel definitions.
#define AST_STRING_FIELD(name)
Declare a string field.
Definition: stringfields.h:303
Asterisk XML abstraction layer.
Support for dynamic strings.
Definition: strings.h:623
Sorcery Data Access Layer API.