mirror of
https://github.com/asterisk/asterisk.git
synced 2025-09-03 11:25:35 +00:00
Geolocation: Core Capability Preview
This commit adds res_geolocation which creates the core capabilities to manipulate Geolocation information on SIP INVITEs. An upcoming commit will add res_pjsip_geolocation which will allow the capabilities to be used with the pjsip channel driver. This commit message is intentionally short because this isn't a simple capability. See the documentation at https://wiki.asterisk.org/wiki/display/AST/Geolocation for more information. THE CAPABILITIES IMPLEMENTED HERE MAY CHANGE BASED ON USER FEEDBACK! ASTERISK-30127 Change-Id: Ibfde963121b1ecf57fd98ee7060c4f0808416303
This commit is contained in:
George Joseph
353
include/asterisk/res_geolocation.h
Normal file
353
include/asterisk/res_geolocation.h
Normal file
@@ -0,0 +1,353 @@
|
||||
/*
|
||||
* Asterisk -- An open source telephony toolkit.
|
||||
*
|
||||
* Copyright (C) 2022, Sangoma Technologies Corporation
|
||||
*
|
||||
* George Joseph <gjoseph@sangoma.com>
|
||||
*
|
||||
* See http://www.asterisk.org for more information about
|
||||
* the Asterisk project. Please do not directly contact
|
||||
* any of the maintainers of this project for assistance;
|
||||
* the project provides a web site, mailing lists and IRC
|
||||
* channels for your use.
|
||||
*
|
||||
* This program is free software, distributed under the terms of
|
||||
* the GNU General Public License Version 2. See the LICENSE file
|
||||
* at the top of the source tree.
|
||||
*/
|
||||
|
||||
#ifndef INCLUDE_ASTERISK_RES_GEOLOCATION_H_
|
||||
#define INCLUDE_ASTERISK_RES_GEOLOCATION_H_
|
||||
|
||||
#include "asterisk/channel.h"
|
||||
#include "asterisk/config.h"
|
||||
#include "asterisk/sorcery.h"
|
||||
#include "asterisk/xml.h"
|
||||
#include "asterisk/optional_api.h"
|
||||
|
||||
#define AST_GEOLOC_INVALID_VALUE -1
|
||||
|
||||
enum ast_geoloc_pidf_element {
|
||||
AST_PIDF_ELEMENT_NONE = 0,
|
||||
AST_PIDF_ELEMENT_TUPLE,
|
||||
AST_PIDF_ELEMENT_DEVICE,
|
||||
AST_PIDF_ELEMENT_PERSON,
|
||||
AST_PIDF_ELEMENT_LAST,
|
||||
};
|
||||
|
||||
enum ast_geoloc_format {
|
||||
AST_GEOLOC_FORMAT_NONE = 0,
|
||||
AST_GEOLOC_FORMAT_CIVIC_ADDRESS,
|
||||
AST_GEOLOC_FORMAT_GML,
|
||||
AST_GEOLOC_FORMAT_URI,
|
||||
AST_GEOLOC_FORMAT_LAST,
|
||||
};
|
||||
|
||||
enum ast_geoloc_action {
|
||||
AST_GEOLOC_ACT_PREFER_INCOMING = 0,
|
||||
AST_GEOLOC_ACT_PREFER_CONFIG,
|
||||
AST_GEOLOC_ACT_DISCARD_INCOMING,
|
||||
AST_GEOLOC_ACT_DISCARD_CONFIG,
|
||||
};
|
||||
|
||||
struct ast_geoloc_location {
|
||||
SORCERY_OBJECT(details);
|
||||
AST_DECLARE_STRING_FIELDS(
|
||||
AST_STRING_FIELD(method);
|
||||
AST_STRING_FIELD(location_source);
|
||||
);
|
||||
enum ast_geoloc_format format;
|
||||
struct ast_variable *location_info;
|
||||
};
|
||||
|
||||
struct ast_geoloc_profile {
|
||||
SORCERY_OBJECT(details);
|
||||
AST_DECLARE_STRING_FIELDS(
|
||||
AST_STRING_FIELD(location_reference);
|
||||
AST_STRING_FIELD(notes);
|
||||
);
|
||||
enum ast_geoloc_pidf_element pidf_element;
|
||||
enum ast_geoloc_action action;
|
||||
int geolocation_routing;
|
||||
struct ast_variable *location_refinement;
|
||||
struct ast_variable *location_variables;
|
||||
struct ast_variable *usage_rules;
|
||||
};
|
||||
|
||||
struct ast_geoloc_eprofile {
|
||||
AST_DECLARE_STRING_FIELDS(
|
||||
AST_STRING_FIELD(id);
|
||||
AST_STRING_FIELD(location_reference);
|
||||
AST_STRING_FIELD(location_source);
|
||||
AST_STRING_FIELD(method);
|
||||
AST_STRING_FIELD(notes);
|
||||
);
|
||||
enum ast_geoloc_pidf_element pidf_element;
|
||||
enum ast_geoloc_action action;
|
||||
int geolocation_routing;
|
||||
enum ast_geoloc_format format;
|
||||
struct ast_variable *location_info;
|
||||
struct ast_variable *location_refinement;
|
||||
struct ast_variable *location_variables;
|
||||
struct ast_variable *effective_location;
|
||||
struct ast_variable *usage_rules;
|
||||
};
|
||||
|
||||
/*!
|
||||
* \brief Check if res_geolocation is available
|
||||
*
|
||||
* \return 1 if available, 0 otherwise.
|
||||
*/
|
||||
AST_OPTIONAL_API(int, ast_geoloc_is_loaded, (void), { return 0; });
|
||||
|
||||
/*!
|
||||
* \brief Retrieve a geolocation location object by id.
|
||||
*
|
||||
* \param id Location object id.
|
||||
*
|
||||
* \return Location object or NULL if not found.
|
||||
*/
|
||||
AST_OPTIONAL_API(struct ast_geoloc_location *, ast_geoloc_get_location,
|
||||
(const char *id),
|
||||
{ return NULL; });
|
||||
|
||||
/*!
|
||||
* \brief Retrieve a geolocation profile by id.
|
||||
*
|
||||
* \param id profile id.
|
||||
*
|
||||
* \return Profile or NULL if not found.
|
||||
*/
|
||||
AST_OPTIONAL_API(struct ast_geoloc_profile *, ast_geoloc_get_profile,
|
||||
(const char *id),
|
||||
{ return NULL; });
|
||||
|
||||
/*!
|
||||
* \brief Given a civicAddress code, check whether it's valid.
|
||||
*
|
||||
* \param code Pointer to the code to check
|
||||
*
|
||||
* \return 1 if valid, 0 otherwise.
|
||||
*/
|
||||
int ast_geoloc_civicaddr_is_code_valid(const char *code);
|
||||
|
||||
enum ast_geoloc_validate_result {
|
||||
AST_GEOLOC_VALIDATE_INVALID_VALUE = -1,
|
||||
AST_GEOLOC_VALIDATE_SUCCESS = 0,
|
||||
AST_GEOLOC_VALIDATE_MISSING_SHAPE,
|
||||
AST_GEOLOC_VALIDATE_INVALID_SHAPE,
|
||||
AST_GEOLOC_VALIDATE_INVALID_VARNAME,
|
||||
AST_GEOLOC_VALIDATE_NOT_ENOUGH_VARNAMES,
|
||||
AST_GEOLOC_VALIDATE_TOO_MANY_VARNAMES,
|
||||
};
|
||||
|
||||
const char *ast_geoloc_validate_result_to_str(enum ast_geoloc_validate_result result);
|
||||
|
||||
/*!
|
||||
* \brief Validate that the names of the variables in the list are valid codes or synonyms
|
||||
*
|
||||
* \param varlist Variable list to check.
|
||||
* \param result[OUT] Pointer to char * to receive failing item.
|
||||
*
|
||||
* \return result code.
|
||||
*/
|
||||
enum ast_geoloc_validate_result ast_geoloc_civicaddr_validate_varlist(
|
||||
const struct ast_variable *varlist, const char **result);
|
||||
|
||||
/*!
|
||||
* \brief Validate that the variables in the list represent a valid GML shape
|
||||
*
|
||||
* \param varlist Variable list to check.
|
||||
* \param result[OUT] Pointer to char * to receive failing item.
|
||||
*
|
||||
* \return result code.
|
||||
*/
|
||||
enum ast_geoloc_validate_result ast_geoloc_gml_validate_varlist(const struct ast_variable *varlist,
|
||||
const char **result);
|
||||
|
||||
|
||||
/*!
|
||||
* \brief Geolocation datastore Functions
|
||||
* @{
|
||||
*/
|
||||
|
||||
/*!
|
||||
* \brief Create a geoloc datastore from a profile name
|
||||
*
|
||||
* \param profile_name The name of the profile to use.
|
||||
*
|
||||
* \return The datastore.
|
||||
*/
|
||||
struct ast_datastore *ast_geoloc_datastore_create_from_profile_name(const char *profile_name);
|
||||
|
||||
/*!
|
||||
* \brief Create a geoloc datastore from an effective profile.
|
||||
*
|
||||
* \param eprofile The effective profile to use.
|
||||
*
|
||||
* \return The datastore.
|
||||
*/
|
||||
struct ast_datastore *ast_geoloc_datastore_create_from_eprofile(
|
||||
struct ast_geoloc_eprofile *eprofile);
|
||||
|
||||
/*!
|
||||
* \brief Create an empty geoloc datastore.
|
||||
*
|
||||
* \param id An id to use for the datastore.
|
||||
*
|
||||
* \return The datastore.
|
||||
*/
|
||||
struct ast_datastore *ast_geoloc_datastore_create(const char *id);
|
||||
|
||||
/*!
|
||||
* \brief Retrieve a geoloc datastore's id.
|
||||
*
|
||||
* \param ds The datastore
|
||||
*
|
||||
* \return The datastore's id.
|
||||
*/
|
||||
const char *ast_geoloc_datastore_get_id(struct ast_datastore *ds);
|
||||
|
||||
/*!
|
||||
* \brief Add an eprofile to a datastore
|
||||
*
|
||||
* \param ds The datastore
|
||||
* \param eprofile The eprofile to add.
|
||||
*
|
||||
* \return The new number of eprofiles or -1 to indicate a failure.
|
||||
*/
|
||||
int ast_geoloc_datastore_add_eprofile(struct ast_datastore *ds,
|
||||
struct ast_geoloc_eprofile *eprofile);
|
||||
|
||||
/*!
|
||||
* \brief Insert an eprofile to a datastore at the specified position
|
||||
*
|
||||
* \param ds The datastore
|
||||
* \param eprofile The eprofile to add.
|
||||
* \param index The position to insert at. Existing eprofiles will
|
||||
* be moved up to make room.
|
||||
*
|
||||
* \return The new number of eprofiles or -1 to indicate a failure.
|
||||
*/
|
||||
int ast_geoloc_datastore_insert_eprofile(struct ast_datastore *ds,
|
||||
struct ast_geoloc_eprofile *eprofile, int index);
|
||||
|
||||
/*!
|
||||
* \brief Retrieves the number of eprofiles in the datastore
|
||||
*
|
||||
* \param ds The datastore
|
||||
*
|
||||
* \return The number of eprofiles.
|
||||
*/
|
||||
int ast_geoloc_datastore_size(struct ast_datastore *ds);
|
||||
|
||||
/*!
|
||||
* \brief Sets the inheritance flag on the datastore
|
||||
*
|
||||
* \param ds The datastore
|
||||
* \param inherit 1 to allow the datastore to be inherited by other channels
|
||||
* 0 to prevent the datastore to be inherited by other channels
|
||||
*
|
||||
* \return 0 if successful, -1 otherwise.
|
||||
*/
|
||||
int ast_geoloc_datastore_set_inheritance(struct ast_datastore *ds, int inherit);
|
||||
|
||||
/*!
|
||||
* \brief Retrieve a specific eprofile from a datastore by index
|
||||
*
|
||||
* \param ds The datastore
|
||||
* \param ix The index
|
||||
*
|
||||
* \return The effective profile ao2 object with its reference count bumped.
|
||||
*/
|
||||
struct ast_geoloc_eprofile *ast_geoloc_datastore_get_eprofile(struct ast_datastore *ds, int ix);
|
||||
|
||||
/*!
|
||||
* \brief Delete a specific eprofile from a datastore by index
|
||||
*
|
||||
* \param ds The datastore
|
||||
* \param ix The index
|
||||
*
|
||||
* \return 0 if succesful, -1 otherwise.
|
||||
*/
|
||||
int ast_geoloc_datastore_delete_eprofile(struct ast_datastore *ds, int ix);
|
||||
|
||||
/*!
|
||||
* \brief Retrieves the geoloc datastore from a channel, if any
|
||||
*
|
||||
* \param chan Channel
|
||||
*
|
||||
* \return datastore if found, NULL otherwise.
|
||||
*/
|
||||
struct ast_datastore *ast_geoloc_datastore_find(struct ast_channel *chan);
|
||||
|
||||
/*!
|
||||
* @}
|
||||
*/
|
||||
|
||||
/*!
|
||||
* \brief Geolocation Effective Profile Functions
|
||||
* @{
|
||||
*/
|
||||
|
||||
/*!
|
||||
* \brief Allocate a new, empty effective profile.
|
||||
*
|
||||
* \param name The profile's name
|
||||
*
|
||||
* \return The effective profile ao2 object.
|
||||
*/
|
||||
struct ast_geoloc_eprofile *ast_geoloc_eprofile_alloc(const char *name);
|
||||
|
||||
/*!
|
||||
* \brief Allocate a new effective profile from an existing profile.
|
||||
*
|
||||
* \param profile The profile to use.
|
||||
*
|
||||
* \return The effective profile ao2 object.
|
||||
*/
|
||||
struct ast_geoloc_eprofile *ast_geoloc_eprofile_create_from_profile(struct ast_geoloc_profile *profile);
|
||||
|
||||
/*!
|
||||
* \brief Allocate a new effective profile from an XML PIDF-LO document
|
||||
*
|
||||
* \param pidf_xmldoc The ast_xml_doc to use.
|
||||
* \param geoloc_uri The URI that referenced this document.
|
||||
* \param reference_string An identifying string to use in error messages.
|
||||
*
|
||||
* \return The effective profile ao2 object.
|
||||
*/
|
||||
struct ast_geoloc_eprofile *ast_geoloc_eprofile_create_from_pidf(
|
||||
struct ast_xml_doc *pidf_xmldoc, const char *geoloc_uri, const char *reference_string);
|
||||
|
||||
/*!
|
||||
* \brief Allocate a new effective profile from a URI.
|
||||
*
|
||||
* \param uri The URI to use.
|
||||
* \param reference_string An identifying string to use in error messages.
|
||||
*
|
||||
* \return The effective profile ao2 object.
|
||||
*/
|
||||
struct ast_geoloc_eprofile *ast_geoloc_eprofile_create_from_uri(const char *uri,
|
||||
const char *reference_string);
|
||||
|
||||
const char *ast_geoloc_eprofile_to_uri(struct ast_geoloc_eprofile *eprofile,
|
||||
struct ast_channel *chan, struct ast_str **buf, const char *ref_string);
|
||||
|
||||
const char *ast_geoloc_eprofiles_to_pidf(struct ast_datastore *ds,
|
||||
struct ast_channel *chan, struct ast_str **buf, const char * ref_string);
|
||||
|
||||
/*!
|
||||
* \brief Refresh the effective profile with any changed info.
|
||||
*
|
||||
* \param eprofile The eprofile to refresh.
|
||||
*
|
||||
* \return 0 on success, any other value on error.
|
||||
*/
|
||||
int ast_geoloc_eprofile_refresh_location(struct ast_geoloc_eprofile *eprofile);
|
||||
|
||||
/*!
|
||||
* @}
|
||||
*/
|
||||
|
||||
#endif /* INCLUDE_ASTERISK_RES_GEOLOCATION_H_ */
|
||||
Reference in New Issue
Block a user