Asterisk - The Open Source Telephony Project GIT-master-55f4e6d
res_geolocation.h
Go to the documentation of this file.
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"
27
28#define AST_GEOLOC_INVALID_VALUE -1
29
36};
37
44};
45
51};
52
53#define CONFIG_STR_TO_ENUM_DECL(_stem) int ast_geoloc_ ## _stem ## _str_to_enum(const char *str);
54CONFIG_STR_TO_ENUM_DECL(pidf_element)
57#define GEOLOC_ENUM_TO_NAME_DECL(_stem) const char * ast_geoloc_ ## _stem ## _to_name(int ix);
58GEOLOC_ENUM_TO_NAME_DECL(pidf_element)
61
66 AST_STRING_FIELD(location_source);
67 );
71};
72
80 );
91};
92
100 );
112};
113
114/*!
115 * \brief Check if res_geolocation is available
116 *
117 * \return 1 if available, 0 otherwise.
118 */
119AST_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 */
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 */
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 */
150int ast_geoloc_civicaddr_is_code_valid(const char *code);
151
160};
161
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 */
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 */
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 */
199struct 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 */
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 */
218struct 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 */
227const 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 */
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 */
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 */
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 */
271int 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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
371const 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 */
384const 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 */
397const 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 */
408
409/*!
410 * @}
411 */
412
413#endif /* INCLUDE_ASTERISK_RES_GEOLOCATION_H_ */
static PGresult * result
Definition: cel_pgsql.c:84
General Asterisk PBX channel definitions.
char buf[BUFSIZE]
Definition: eagi_proxy.c:66
static const char name[]
Definition: format_mp3.c:68
Configuration File Parser.
Optional API function macros.
#define AST_OPTIONAL_API(result, name, proto, stub)
Declare an optional API function.
Definition: optional_api.h:230
ast_geoloc_precedence
@ AST_GEOLOC_PRECED_DISCARD_CONFIG
@ AST_GEOLOC_PRECED_PREFER_CONFIG
@ AST_GEOLOC_PRECED_DISCARD_INCOMING
@ AST_GEOLOC_PRECED_PREFER_INCOMING
struct ast_datastore * ast_geoloc_datastore_create_from_profile_name(const char *profile_name)
Geolocation datastore Functions.
int ast_geoloc_eprofile_refresh_location(struct ast_geoloc_eprofile *eprofile)
Refresh the effective profile with any changed info.
struct ast_geoloc_eprofile * ast_geoloc_eprofile_dup(struct ast_geoloc_eprofile *src)
Duplicate an effective profile.
const char * ast_geoloc_validate_result_to_str(enum ast_geoloc_validate_result result)
Definition: geoloc_common.c:32
struct ast_geoloc_eprofile * ast_geoloc_datastore_get_eprofile(struct ast_datastore *ds, int ix)
Retrieve a specific eprofile from a datastore by index.
struct ast_datastore * ast_geoloc_datastore_create_from_eprofile(struct ast_geoloc_eprofile *eprofile)
Create a geoloc datastore from an effective profile.
#define CONFIG_STR_TO_ENUM_DECL(_stem)
ast_geoloc_validate_result
@ AST_GEOLOC_VALIDATE_TOO_MANY_VARNAMES
@ AST_GEOLOC_VALIDATE_MISSING_SHAPE
@ AST_GEOLOC_VALIDATE_INVALID_VALUE
@ AST_GEOLOC_VALIDATE_SUCCESS
@ AST_GEOLOC_VALIDATE_NOT_ENOUGH_VARNAMES
@ AST_GEOLOC_VALIDATE_INVALID_SHAPE
@ AST_GEOLOC_VALIDATE_INVALID_VARNAME
const char * ast_geoloc_eprofiles_to_pidf(struct ast_datastore *ds, struct ast_channel *chan, struct ast_str **buf, const char *ref_string)
Convert a datastore containing eprofiles to a PIDF-LO document.
int ast_geoloc_datastore_insert_eprofile(struct ast_datastore *ds, struct ast_geoloc_eprofile *eprofile, int index)
Insert an eprofile to a datastore at the specified position.
enum ast_geoloc_validate_result ast_geoloc_civicaddr_validate_varlist(const struct ast_variable *varlist, const char **result)
Validate that the names of the variables in the list are valid codes or synonyms.
const char * ast_geoloc_eprofile_to_uri(struct ast_geoloc_eprofile *eprofile, struct ast_channel *chan, struct ast_str **buf, const char *ref_string)
Convert a URI eprofile to a URI string.
struct ast_geoloc_eprofile * ast_geoloc_eprofile_create_from_pidf(struct ast_xml_doc *pidf_xmldoc, const char *geoloc_uri, const char *reference_string)
Allocate a new effective profile from an XML PIDF-LO document.
struct ast_geoloc_eprofile * ast_geoloc_eprofile_create_from_uri(const char *uri, const char *reference_string)
Allocate a new effective profile from a URI.
struct ast_geoloc_profile * ast_geoloc_get_profile(const char *id)
Retrieve a geolocation profile by id.
const char * ast_geoloc_datastore_get_id(struct ast_datastore *ds)
Retrieve a geoloc datastore's id.
struct ast_datastore * ast_geoloc_datastore_create(const char *id)
Create an empty geoloc datastore.
ast_geoloc_pidf_element
@ AST_PIDF_ELEMENT_PERSON
@ AST_PIDF_ELEMENT_TUPLE
@ AST_PIDF_ELEMENT_DEVICE
@ AST_PIDF_ELEMENT_NONE
@ AST_PIDF_ELEMENT_LAST
int ast_geoloc_is_loaded(void)
Check if res_geolocation is available.
ast_geoloc_format
@ AST_GEOLOC_FORMAT_GML
@ AST_GEOLOC_FORMAT_CIVIC_ADDRESS
@ AST_GEOLOC_FORMAT_LAST
@ AST_GEOLOC_FORMAT_URI
@ AST_GEOLOC_FORMAT_NONE
struct ast_geoloc_eprofile * ast_geoloc_eprofile_alloc(const char *name)
Geolocation Effective Profile Functions.
struct ast_geoloc_location * ast_geoloc_get_location(const char *id)
Retrieve a geolocation location object by id.
int ast_geoloc_datastore_set_inheritance(struct ast_datastore *ds, int inherit)
Sets the inheritance flag on the datastore.
int ast_geoloc_datastore_add_eprofile(struct ast_datastore *ds, struct ast_geoloc_eprofile *eprofile)
Add an eprofile to a datastore.
const char * ast_geoloc_eprofile_to_pidf(struct ast_geoloc_eprofile *eprofile, struct ast_channel *chan, struct ast_str **buf, const char *ref_string)
Convert a single eprofile to a PIDF-LO document.
int ast_geoloc_datastore_size(struct ast_datastore *ds)
Retrieves the number of eprofiles in the datastore.
struct ast_datastore * ast_geoloc_datastore_find(struct ast_channel *chan)
Retrieves the geoloc datastore from a channel, if any.
struct ast_geoloc_eprofile * ast_geoloc_eprofile_create_from_profile(struct ast_geoloc_profile *profile)
Allocate a new effective profile from an existing profile.
enum ast_geoloc_validate_result ast_geoloc_gml_validate_varlist(const struct ast_variable *varlist, const char **result)
Validate that the variables in the list represent a valid GML shape.
Definition: geoloc_gml.c:124
int ast_geoloc_civicaddr_is_code_valid(const char *code)
Given a civicAddress code, check whether it's valid.
int ast_geoloc_datastore_delete_eprofile(struct ast_datastore *ds, int ix)
Delete a specific eprofile from a datastore by index.
#define GEOLOC_ENUM_TO_NAME_DECL(_stem)
const char * method
Definition: res_pjsip.c:1279
#define NULL
Definition: resample.c:96
Sorcery Data Access Layer API.
#define AST_DECLARE_STRING_FIELDS(field_list)
Declare the fields needed in a structure.
Definition: stringfields.h:341
#define AST_STRING_FIELD(name)
Declare a string field.
Definition: stringfields.h:303
Main Channel structure associated with a channel.
Structure for a data store object.
Definition: datastore.h:64
struct ast_variable * effective_location
const ast_string_field location_reference
enum ast_geoloc_format format
enum ast_geoloc_pidf_element pidf_element
const ast_string_field method
struct ast_variable * location_refinement
enum ast_geoloc_precedence precedence
const ast_string_field notes
struct ast_variable * location_variables
struct ast_variable * confidence
struct ast_variable * usage_rules
const ast_string_field location_source
struct ast_variable * location_info
enum ast_geoloc_format format
struct ast_variable * confidence
struct ast_variable * location_info
SORCERY_OBJECT(details)
const ast_string_field location_reference
enum ast_geoloc_format format
enum ast_geoloc_pidf_element pidf_element
const ast_string_field method
struct ast_variable * location_refinement
enum ast_geoloc_precedence precedence
const ast_string_field notes
struct ast_variable * location_variables
struct ast_variable * confidence
struct ast_variable * usage_rules
const ast_string_field location_source
struct ast_variable * location_info
Support for dynamic strings.
Definition: strings.h:623
Structure for variables, used for configurations and for channel variables.
Asterisk XML abstraction layer.