mirror of
https://github.com/asterisk/asterisk.git
synced 2026-06-24 17:28:41 -07:00
George Joseph
e6d4e62a78
* 3d positions were being rendered without an enclosing `<gml:pos>` element resulting in invalid XML. * There was no way to set the `id` attribute on the enclosing `tuple`, `device` and `person` elements. * There was no way to set the value of the `deviceID` element. * Parsing of degree and radian UOMs was broken resulting in them appearing outside an XML element. * The UOM schemas for degrees and radians were reversed. * The Ellipsoid shape was missing and the Ellipse shape was defined multiple times. * The `crs` location_info parameter, although documented, didn't work. * The `pos3d` location_info parameter appears in some documentation but wasn't being parsed correctly. * The retransmission-allowed and retention-expiry sub-elements of usage-rules were using the `gp` namespace instead of the `gbp` namespace. In addition to fixing the above, several other code refactorings were performed and the unit test enhanced to include a round trip XML -> eprofile -> XML validation. Resolves: #1667 UserNote: Geolocation: Two new optional profile parameters have been added. * `pidf_element_id` which sets the value of the `id` attribute on the top-level PIDF-LO `device`, `person` or `tuple` elements. * `device_id` which sets the content of the `<deviceID>` element. Both parameters can include channel variables. UpgradeNote: Geolocation: In order to correct bugs in both code and documentation, the following changes to the parameters for GML geolocation locations are now in effect: * The documented but unimplemented `crs` (coordinate reference system) element has been added to the location_info parameter that indicates whether the `2d` or `3d` reference system is to be used. If the crs isn't valid for the shape specified, an error will be generated. The default depends on the shape specified. * The Circle, Ellipse and ArcBand shapes MUST use a `2d` crs. If crs isn't specified, it will default to `2d` for these shapes. The Sphere, Ellipsoid and Prism shapes MUST use a `3d` crs. If crs isn't specified, it will default to `3d` for these shapes. The Point and Polygon shapes may use either crs. The default crs is `2d` however so if `3d` positions are used, the crs must be explicitly set to `3d`. * The `geoloc show gml_shape_defs` CLI command has been updated to show which coordinate reference systems are valid for each shape. * The `pos3d` element has been removed in favor of allowing the `pos` element to include altitude if the crs is `3d`. The number of values in the `pos` element MUST be 2 if the crs is `2d` and 3 if the crs is `3d`. An error will be generated for any other combination. * The angle unit-of-measure for shapes that use angles should now be included in the respective parameter. The default is `degrees`. There were some inconsistent references to `orientation_uom` in some documentation but that parameter never worked and is now removed. See examples below. Examples... ``` location_info = shape="Sphere", pos="39.0 -105.0 1620", radius="20" location_info = shape="Point", crs="3d", pos="39.0 -105.0 1620" location_info = shape="Point", pos="39.0 -105.0" location_info = shape=Ellipsoid, pos="39.0 -105.0 1620", semiMajorAxis="20" semiMinorAxis="10", verticalAxis="0", orientation="25 degrees" pidf_element_id = ${CHANNEL(name)}-${EXTEN} device_id = mac:001122334455 Set(GEOLOC_PROFILE(pidf_element_id)=${CHANNEL(name)}/${EXTEN}) ```
426 lines
14 KiB
XML
426 lines
14 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE docs SYSTEM "appdocsxml.dtd">
|
|
<docs xmlns:xi="http://www.w3.org/2001/XInclude">
|
|
<configInfo name="res_geolocation" language="en_US">
|
|
<synopsis>Core Geolocation Support</synopsis>
|
|
<configFile name="geolocation.conf">
|
|
<configObject name="location">
|
|
<since>
|
|
<version>16.29.0</version>
|
|
<version>18.15.0</version>
|
|
<version>19.7.0</version>
|
|
</since>
|
|
<synopsis>Location</synopsis>
|
|
<description>
|
|
<para>Parameters for defining a Location object</para>
|
|
</description>
|
|
|
|
<configOption name="type">
|
|
<since>
|
|
<version>16.28.0</version>
|
|
<version>18.14.0</version>
|
|
<version>19.6.0</version>
|
|
</since>
|
|
<synopsis>Must be of type 'location'.</synopsis>
|
|
</configOption>
|
|
|
|
<configOption name="format" default="none">
|
|
<since>
|
|
<version>16.28.0</version>
|
|
<version>18.14.0</version>
|
|
<version>19.6.0</version>
|
|
</since>
|
|
<synopsis>Location specification type</synopsis>
|
|
<description>
|
|
<enumlist>
|
|
<enum name="civicAddress">
|
|
<para>
|
|
The <literal>location_info</literal>
|
|
parameter must contain a comma separated list of IANA codes
|
|
or synonyms describing the civicAddress of this location.
|
|
The IANA codes and synonyms can be obtained by executing
|
|
the CLI command <literal>geoloc show civicAddr_mapping</literal>.
|
|
</para>
|
|
</enum>
|
|
<enum name="GML">
|
|
<para>
|
|
The
|
|
<literal>location_info</literal> parameter must contain a comma
|
|
separated list valid GML elements describing this location.
|
|
</para>
|
|
</enum>
|
|
<enum name="URI">
|
|
<para>
|
|
The
|
|
<literal>location_info</literal> parameter must contain a single
|
|
URI parameter which contains an external URI describing this location.
|
|
</para>
|
|
</enum>
|
|
</enumlist>
|
|
</description>
|
|
</configOption>
|
|
|
|
<configOption name="location_info" default="none">
|
|
<since>
|
|
<version>16.28.0</version>
|
|
<version>18.14.0</version>
|
|
<version>19.6.0</version>
|
|
</since>
|
|
<synopsis>Location information</synopsis>
|
|
<description>
|
|
<para>The contents of this parameter are specific to the
|
|
location <literal>format</literal>.</para>
|
|
<enumlist>
|
|
<enum name="civicAddress">
|
|
<para>
|
|
location_info = country=US,A1="New York",city_district=Manhattan,
|
|
A3="New York", house_number=1633, street=46th, street_suffix = Street,
|
|
postal_code=10222,floor=20,room=20A2
|
|
</para>
|
|
</enum>
|
|
<enum name="GML">
|
|
<para>
|
|
location_info = Shape=Sphere, pos3d="39.12345 -105.98766 1920", radius=200
|
|
</para>
|
|
</enum>
|
|
<enum name="URI">
|
|
<para>
|
|
location_info = URI=https:/something.com?exten=${EXTEN}
|
|
</para>
|
|
</enum>
|
|
</enumlist>
|
|
</description>
|
|
</configOption>
|
|
|
|
<configOption name="location_source" default="none">
|
|
<since>
|
|
<version>16.28.0</version>
|
|
<version>18.14.0</version>
|
|
<version>19.6.0</version>
|
|
</since>
|
|
<synopsis>Fully qualified host name</synopsis>
|
|
<description>
|
|
<para>This parameter isn't required but if provided, RFC8787 says it MUST be a fully
|
|
qualified host name. IP addresses are specifically NOT allowed. The value will be placed
|
|
in a <literal>loc-src</literal> parameter appended to the URI in the <literal>
|
|
Geolocation</literal> header.</para>
|
|
</description>
|
|
</configOption>
|
|
|
|
<configOption name="method" default="none">
|
|
<since>
|
|
<version>16.28.0</version>
|
|
<version>18.14.0</version>
|
|
<version>19.6.0</version>
|
|
</since>
|
|
<synopsis>Location determination method</synopsis>
|
|
<description>
|
|
<para>This is a rarely used field in the specification that would
|
|
indicate the method used to determine the location. Its usage and values should be
|
|
pre-negotiated with any recipients.</para>
|
|
<enumlist>
|
|
<enum name="GPS"/>
|
|
<enum name="A-GPS"/>
|
|
<enum name="Manual"/>
|
|
<enum name="DHCP"/>
|
|
<enum name="Triangulation"/>
|
|
<enum name="Cell"/>
|
|
<enum name="802.11"/>
|
|
</enumlist>
|
|
</description>
|
|
</configOption>
|
|
|
|
<configOption name="confidence" default="none">
|
|
<since>
|
|
<version>16.28.0</version>
|
|
<version>18.14.0</version>
|
|
<version>19.6.0</version>
|
|
</since>
|
|
<synopsis>Level of confidence</synopsis>
|
|
<description>
|
|
<para>This is a rarely used field in the specification that would
|
|
indicate the confidence in the location specified. See RFC7459
|
|
for exact details.
|
|
</para>
|
|
<para>
|
|
Sub-parameters:
|
|
</para>
|
|
<enumlist>
|
|
<enum name="pdf">
|
|
<para>One of:</para>
|
|
<enumlist>
|
|
<enum name="unknown"/>
|
|
<enum name="normal"/>
|
|
<enum name="rectangular"/>
|
|
</enumlist>
|
|
</enum>
|
|
<enum name="value">
|
|
<para>A percentage indicating the confidence.</para>
|
|
</enum>
|
|
</enumlist>
|
|
</description>
|
|
<see-also>
|
|
<ref type="link">https://www.rfc-editor.org/rfc/rfc7459</ref>
|
|
</see-also>
|
|
</configOption>
|
|
</configObject>
|
|
|
|
<configObject name="profile">
|
|
<since>
|
|
<version>16.29.0</version>
|
|
<version>18.15.0</version>
|
|
<version>19.7.0</version>
|
|
</since>
|
|
<synopsis>Profile</synopsis>
|
|
<description>
|
|
<para>Parameters for defining a Profile object</para>
|
|
</description>
|
|
<configOption name="type">
|
|
<since>
|
|
<version>16.28.0</version>
|
|
<version>18.14.0</version>
|
|
<version>19.6.0</version>
|
|
</since>
|
|
<synopsis>Must be of type 'profile'.</synopsis>
|
|
</configOption>
|
|
|
|
<configOption name="pidf_element" default="device">
|
|
<since>
|
|
<version>16.28.0</version>
|
|
<version>18.14.0</version>
|
|
<version>19.6.0</version>
|
|
</since>
|
|
<synopsis>PIDF-LO element to place this profile in</synopsis>
|
|
<description>
|
|
<enumlist>
|
|
<enum name="tuple" />
|
|
<enum name="device" />
|
|
<enum name="person" />
|
|
</enumlist>
|
|
<para>
|
|
Based on RFC5491 (see below) the recommended and default element
|
|
is <literal>device</literal>.
|
|
</para>
|
|
</description>
|
|
<see-also>
|
|
<ref type="link">https://www.rfc-editor.org/rfc/rfc5491.html#section-3.4</ref>
|
|
</see-also>
|
|
</configOption>
|
|
|
|
<configOption name="pidf_element_id" default="">
|
|
<since>
|
|
<version>20.18.0</version>
|
|
<version>22.8.0</version>
|
|
<version>23.2.0</version>
|
|
</since>
|
|
<synopsis>The id attribute value for the PIDF-LO element</synopsis>
|
|
</configOption>
|
|
|
|
<configOption name="device_id" default="">
|
|
<since>
|
|
<version>20.18.0</version>
|
|
<version>22.8.0</version>
|
|
<version>23.2.0</version>
|
|
</since>
|
|
<synopsis>The content of the deviceID element</synopsis>
|
|
</configOption>
|
|
|
|
<configOption name="location_reference" default="none">
|
|
<since>
|
|
<version>16.28.0</version>
|
|
<version>18.14.0</version>
|
|
<version>19.6.0</version>
|
|
</since>
|
|
<synopsis>Reference to a location object</synopsis>
|
|
</configOption>
|
|
|
|
<configOption name="location_info_refinement" default="none">
|
|
<since>
|
|
<version>16.28.0</version>
|
|
<version>18.14.0</version>
|
|
<version>19.6.0</version>
|
|
</since>
|
|
<synopsis>Reference to a location object</synopsis>
|
|
</configOption>
|
|
<configOption name="location_variables" default="none">
|
|
<since>
|
|
<version>16.28.0</version>
|
|
<version>18.14.0</version>
|
|
<version>19.6.0</version>
|
|
</since>
|
|
<synopsis>Reference to a location object</synopsis>
|
|
</configOption>
|
|
|
|
<configOption name="usage_rules" default="empty <usage_rules> element">
|
|
<since>
|
|
<version>16.28.0</version>
|
|
<version>18.14.0</version>
|
|
<version>19.6.0</version>
|
|
</since>
|
|
<synopsis>location specification type</synopsis>
|
|
<description>
|
|
<para>xxxx</para>
|
|
</description>
|
|
</configOption>
|
|
|
|
<configOption name="notes" default="">
|
|
<since>
|
|
<version>16.28.0</version>
|
|
<version>18.14.0</version>
|
|
<version>19.6.0</version>
|
|
</since>
|
|
<synopsis>Notes to be added to the outgoing PIDF-LO document</synopsis>
|
|
<description>
|
|
<para>The specification of this parameter will cause a
|
|
<literal><note-well></literal> element to be added to the
|
|
outgoing PIDF-LO document. Its usage should be pre-negotiated with
|
|
any recipients.</para>
|
|
</description>
|
|
|
|
</configOption>
|
|
<configOption name="allow_routing_use" default="no">
|
|
<since>
|
|
<version>16.28.0</version>
|
|
<version>18.14.0</version>
|
|
<version>19.6.0</version>
|
|
</since>
|
|
<synopsis>Sets the value of the Geolocation-Routing header.</synopsis>
|
|
</configOption>
|
|
|
|
<configOption name="suppress_empty_ca_elements" default="no">
|
|
<since>
|
|
<version>16.29.0</version>
|
|
<version>18.15.0</version>
|
|
<version>19.7.0</version>
|
|
</since>
|
|
<synopsis>Sets if empty Civic Address elements should be suppressed
|
|
from the PIDF-LO document.</synopsis>
|
|
</configOption>
|
|
|
|
<configOption name="profile_precedence" default="discard_incoming">
|
|
<since>
|
|
<version>16.28.0</version>
|
|
<version>18.14.0</version>
|
|
<version>19.6.0</version>
|
|
</since>
|
|
<synopsis>Determine which profile on a channel should be used</synopsis>
|
|
<description>
|
|
<enumlist>
|
|
<enum name="prefer_incoming">
|
|
<para>Use the incoming profile if it exists and has location information, otherwise use the
|
|
configured profile if it exists and has location information. If neither profile has location
|
|
information, nothing is sent.
|
|
</para></enum>
|
|
<enum name="prefer_config">
|
|
<para>Use the configured profile if it exists and has location information, otherwise use the
|
|
incoming profile if it exists and has location information. If neither profile has location
|
|
information, nothing is sent.
|
|
</para></enum>
|
|
<enum name="discard_incoming"
|
|
><para>Discard any incoming profile and use the configured profile if it exists and
|
|
it has location information. If the configured profile doesn't exist or has no
|
|
location information, nothing is sent.
|
|
</para></enum>
|
|
<enum name="discard_config">
|
|
<para>Discard any configured profile and use the incoming profile if it exists and
|
|
it has location information. If the incoming profile doesn't exist or has no
|
|
location information, nothing is sent.
|
|
</para></enum>
|
|
</enumlist>
|
|
</description>
|
|
</configOption>
|
|
|
|
<xi:include xpointer="xpointer(/docs/configInfo[@name='res_geolocation']/configFile[@name='geolocation.conf']/configObject[@name='location']/configOption[@name='format'])"/>
|
|
<xi:include xpointer="xpointer(/docs/configInfo[@name='res_geolocation']/configFile[@name='geolocation.conf']/configObject[@name='location']/configOption[@name='location_info'])"/>
|
|
<xi:include xpointer="xpointer(/docs/configInfo[@name='res_geolocation']/configFile[@name='geolocation.conf']/configObject[@name='location']/configOption[@name='confidence'])"/>
|
|
<xi:include xpointer="xpointer(/docs/configInfo[@name='res_geolocation']/configFile[@name='geolocation.conf']/configObject[@name='location']/configOption[@name='location_source'])"/>
|
|
<xi:include xpointer="xpointer(/docs/configInfo[@name='res_geolocation']/configFile[@name='geolocation.conf']/configObject[@name='location']/configOption[@name='method'])"/>
|
|
</configObject>
|
|
</configFile>
|
|
</configInfo>
|
|
<function name="GEOLOC_PROFILE" language="en_US">
|
|
<since>
|
|
<version>16.28.0</version>
|
|
<version>18.14.0</version>
|
|
<version>19.6.0</version>
|
|
</since>
|
|
<synopsis>
|
|
Get or Set a field in a geolocation profile
|
|
</synopsis>
|
|
<syntax>
|
|
<parameter name="parameter" required="true">
|
|
<para>The profile parameter to operate on. The following fields from the
|
|
Location and Profile objects are supported.</para>
|
|
<enumlist>
|
|
<enum name="id"/>
|
|
<enum name="location_reference"/>
|
|
<enum name="method"/>
|
|
<enum name="allow_routing_use"/>
|
|
<enum name="profile_precedence"/>
|
|
<enum name="format"/>
|
|
<enum name="pidf_element"/>
|
|
<enum name="pidf_element_id"/>
|
|
<enum name="location_source"/>
|
|
<enum name="notes"/>
|
|
<enum name="location_info"/>
|
|
<enum name="location_info_refinement"/>
|
|
<enum name="location_variables"/>
|
|
<enum name="effective_location"/>
|
|
<enum name="usage_rules"/>
|
|
<enum name="confidence"/>
|
|
<enum name="device_id"/>
|
|
</enumlist>
|
|
<para>Additionally, the <literal>inheritable</literal> field may be
|
|
set to <literal>true</literal> or <literal>false</literal> to control
|
|
whether the profile will be passed to the outgoing channel.
|
|
</para>
|
|
<para>
|
|
</para>
|
|
</parameter>
|
|
|
|
<parameter name="options" required="false">
|
|
<optionlist>
|
|
<option name="a">
|
|
<para>Append provided value to the specified parameter
|
|
instead of replacing the existing value. This only applies
|
|
to variable list parameters like
|
|
<literal>location_info_refinement</literal>.
|
|
</para>
|
|
</option>
|
|
<option name="r">
|
|
<para>Before reading or after writing the specified parameter,
|
|
re-resolve the <literal>effective_location</literal> and
|
|
<literal>usage_rules</literal> parameters using the
|
|
<literal>location_variables</literal> parameter and the variables
|
|
set on the channel in effect at the time this function is called.
|
|
</para>
|
|
<note><para>On a read operation, this does not alter the actual profile
|
|
in any way. On a write operation however, the
|
|
<literal>effective_location</literal> and/or <literal>usage_rules</literal>
|
|
parameters may indeed change and those changes will be passed on
|
|
to any outgoing channel.
|
|
</para></note>
|
|
</option>
|
|
</optionlist>
|
|
</parameter>
|
|
</syntax>
|
|
<description><para>
|
|
When used to set a parameter on a profile, if the profile doesn't already exist, a new
|
|
one will be created automatically.
|
|
</para>
|
|
<para>
|
|
The <literal>${GEOLOCPROFILESTATUS}</literal> channel variable will be set with
|
|
a return code indicating the result of the operation. Possible values are:
|
|
</para>
|
|
<enumlist>
|
|
<enum name="0"><para>Success</para></enum>
|
|
<enum name="-1"><para>No or not enough parameters were supplied</para></enum>
|
|
<enum name="-2"><para>There was an internal error finding or creating a profile</para></enum>
|
|
<enum name="-3"><para>There was an issue specific to the parameter specified
|
|
(value not valid or parameter name not found, etc.)</para></enum>
|
|
</enumlist>
|
|
</description>
|
|
</function>
|
|
</docs>
|
|
|