mirror of
https://github.com/asterisk/asterisk.git
synced 2025-09-02 11:06:31 +00:00
b221f0f86a
You can now specify the location object's format, location_info, method, location_source and confidence parameters directly on a profile object for simple scenarios where the location information isn't common with any other profiles. This is mutually exclusive with setting location_reference on the profile. Updated appdocsxml.dtd to allow xi:include in a configObject element. This makes it easier to link to complete configOptions in another object. This is used to add the above fields to the profile object without having to maintain the option descriptions in two places. ASTERISK-30185 Change-Id: Ifd5f05be0a76f0a6ad49fa28d17c394027677569
268 lines
10 KiB
XML
268 lines
10 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE docs SYSTEM "appdocsxml.dtd">
|
|
<docs>
|
|
<configInfo name="res_geolocation" language="en_US">
|
|
<synopsis>Core Geolocation Support</synopsis>
|
|
<configFile name="geolocation.conf">
|
|
<configObject name="location">
|
|
<synopsis>Location</synopsis>
|
|
<description>
|
|
<para>cffdffff</para>
|
|
</description>
|
|
<configOption name="type">
|
|
<synopsis>Must be of type 'location'.</synopsis>
|
|
</configOption>
|
|
<configOption name="format" default="">
|
|
<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="">
|
|
<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="">
|
|
<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="">
|
|
<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="">
|
|
<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">
|
|
<synopsis>Profile</synopsis>
|
|
<description>
|
|
<para>cffdffff</para>
|
|
</description>
|
|
<configOption name="type">
|
|
<synopsis>Must be of type 'profile'.</synopsis>
|
|
</configOption>
|
|
<configOption name="pidf_element" default="device">
|
|
<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="location_reference" default="">
|
|
<synopsis>Reference to a location object</synopsis>
|
|
</configOption>
|
|
<configOption name="location_info_refinement" default="">
|
|
<synopsis>Reference to a location object</synopsis>
|
|
</configOption>
|
|
<configOption name="location_variables" default="">
|
|
<synopsis>Reference to a location object</synopsis>
|
|
</configOption>
|
|
<configOption name="usage_rules" default="yes">
|
|
<synopsis>location specification type</synopsis>
|
|
<description>
|
|
<para>xxxx</para>
|
|
</description>
|
|
</configOption>
|
|
<configOption name="notes" default="">
|
|
<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">
|
|
<synopsis>Sets the value of the Geolocation-Routing header.</synopsis>
|
|
</configOption>
|
|
<configOption name="suppress_empty_ca_elements">
|
|
<synopsis>Sets if empty Civic Address elements should be suppressed
|
|
from the PIDF-LO document.</synopsis>
|
|
</configOption>
|
|
|
|
<configOption name="profile_precedence" default="discard_incoming">
|
|
<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">
|
|
<synopsis>
|
|
Get or Set a field in a geolocation profile
|
|
</synopsis>
|
|
<syntax>
|
|
<parameter name="field" required="true">
|
|
<para>The profile field 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="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"/>
|
|
</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>
|
|
</parameter>
|
|
</syntax>
|
|
<description><para>
|
|
When used to set a field 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 field specified
|
|
(value not valid or field name not found)</para></enum>
|
|
</enumlist>
|
|
</description>
|
|
</function>
|
|
</docs>
|
|
|