asterisk/res/res_geolocation/geoloc_doc.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>&lt;note-well&gt;</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="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>
			</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>