mirror of
https://github.com/asterisk/asterisk.git
synced 2025-10-25 14:06:27 +00:00
a9c6f4bd54
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
317 lines
11 KiB
Plaintext
317 lines
11 KiB
Plaintext
;--
|
|
Geolocation Profile Sample Configuration
|
|
|
|
--;
|
|
|
|
;--
|
|
=======================================================================
|
|
Overview
|
|
=======================================================================
|
|
|
|
Geolocation information is actually comprised of two objects, a
|
|
Location object, and a Profile object.
|
|
|
|
Location objects must contain one of the following:
|
|
|
|
- Location information specified in Geographic Markup Language
|
|
(GML) or civicAddress formats.
|
|
|
|
- A URI that points to externally hosted location information.
|
|
|
|
Profile objects contain instructions for the disposition of location
|
|
information, an optional reference to a Location object, and updates or
|
|
overrides to that Location object if specified.
|
|
|
|
Channel drivers and the dialplan functions are responsible for
|
|
associating Profiles to endpoints/devices and calls. Normally, two
|
|
profiles would be assigned to an endpoint to control behavior in each
|
|
direction and to optionally specify location information. One for
|
|
incoming calls (Asterisk is the UAS) and and one for outgoing calls
|
|
(Asterisk is the UAC).
|
|
|
|
NOTE:
|
|
|
|
See https://wiki.asterisk.org/wiki/display/AST/Geolocation for the most
|
|
complete and up-to-date information on valid values for the object
|
|
parameters and a full list of references.
|
|
|
|
GENERAL CAUTION: You must coordinate with your partners with regards
|
|
to what location information is expected by each party and how it should
|
|
be formatted. An outgoing configuration mismatch for instance, could
|
|
result in misinformation or no information being sent to an emergency
|
|
response center or even call failure for which you are solely responsible.
|
|
--;
|
|
|
|
|
|
;--
|
|
=======================================================================
|
|
Location Object Description
|
|
=======================================================================
|
|
[<location_id>]
|
|
|
|
-- type (required) ----------------------------------------------------
|
|
Defines the object type.
|
|
type = location
|
|
|
|
Must be "location" to identify this configuration section as a
|
|
Geolocation Location object.
|
|
|
|
-- format (required) --------------------------------------------------
|
|
Sets the format used to express the location.
|
|
format = < civicAddress | GML | URI >
|
|
|
|
Values:
|
|
civicAddress: [RFC4119] [RFC5139] [RFC5491]
|
|
The location information will be placed in an XML document
|
|
conforming to the PIDF-LO standard.
|
|
For chan_pjsip, this will be placed in the body of
|
|
outgoing INVITE messages in addition to any SDP.
|
|
|
|
GML: [RFC4119] [RFC5491] [GeoShape]
|
|
The location information will be placed in an XML document
|
|
conforming to the PIDF-LO standard.
|
|
For chan_pjsip, this will be placed in the body of
|
|
outgoing INVITE messages in addition to any SDP.
|
|
|
|
URI: [RFC6442]
|
|
The external URI at which the the location information
|
|
can be found. For chan_pjsip, this URI will be placed
|
|
in a "Geolocation" header in outgoing INVITE messages.
|
|
|
|
There is no default.
|
|
|
|
Example:
|
|
format = civicAddress
|
|
|
|
-- location_info (required) -------------------------------------------
|
|
The location-format-specific information describing the location.
|
|
location_info = <location_format_specific_description>
|
|
|
|
For readability, multiple "location" parameters can be specified and
|
|
they will be concatenated into one specification. The description may
|
|
contain replacement variables which may be the names of common channel
|
|
variables like ${EXTEN}, channel variables you may have added in the
|
|
dialplan, or variables you may have specified in the profile that
|
|
references this location object.
|
|
|
|
NOTE: See https://wiki.asterisk.org/wiki/display/AST/Geolocation for the
|
|
most complete and up-to-date information on valid values for the object
|
|
parameters and a full list of references.
|
|
|
|
WARNING: Asterisk can only validate that a particular sub-parameter
|
|
name is valid for a particular format. It can't validate the actual
|
|
value of the sub-parameter.
|
|
|
|
Example for civicAddress:
|
|
|
|
location_info = country=US
|
|
location_info = A1="New York", A3="New York", A4=Manhattan,
|
|
location_info = HNO=1633, PRD=W, RD=46th, STS=Street
|
|
location_info = PC=10222
|
|
|
|
Example for GML with replacement variables:
|
|
|
|
location_info = type=Point, crs=2d, pos="${mylat} ${mylon}"
|
|
|
|
Example for URI with replacement variables:
|
|
location_info = URI=https://some.company.com?number=${phone_number}
|
|
|
|
-- method (optional) --------------------------------------------------
|
|
The method used to determine the location_info
|
|
method = <"GPS" | "A-GPS" | "Manual" | "DHCP"
|
|
| "Triangulation" | "Cell" | "802.11">
|
|
|
|
Example:
|
|
method = Manual
|
|
|
|
-- location_source (optional) -----------------------------------------
|
|
Original source of the location-info.
|
|
location_source = < FQDN >
|
|
|
|
The value MUST be a FQDN. IP addresses are specifically not
|
|
allowed. See RFC8787.
|
|
|
|
Example:
|
|
location_source = sip1.myserver.net
|
|
|
|
-- confidence (optional) -----------------------------------------
|
|
The confidence in the location specified.
|
|
confidence = pdf=[ unknown | normal | rectangular ], value=<percent_confident>
|
|
|
|
Please see RFC7459 for the exact description of this parameter.
|
|
|
|
Example:
|
|
confidence = pdf=normal, value=75
|
|
|
|
|
|
-- Location Example ---------------------------------------------------
|
|
|
|
[mylocation]
|
|
type = location
|
|
format = civicAddress
|
|
location_info = country=US
|
|
location_info = A1="New York", A3="New York", A4=Manhattan
|
|
location_info = HNO=1633, PRD=W, RD=46th, STS=Street
|
|
location_info = PC=10222
|
|
method = Manual
|
|
location_source = sip1.myserver.net
|
|
|
|
=======================================================================
|
|
--;
|
|
|
|
|
|
;--
|
|
=======================================================================
|
|
Profile Object Descriptions
|
|
=======================================================================
|
|
[<profile_id>]
|
|
|
|
-- type (required) ----------------------------------------------------
|
|
Defines the object type.
|
|
type = profile
|
|
|
|
-- profile_precedence (optional) --------------------------------------
|
|
Sets how to reconcile incoming and configured profiles.
|
|
|
|
profile_precedence = < prefer_incoming | prefer_config | discard_incoming
|
|
| discard_config >
|
|
|
|
On an incoming call leg, "incoming" is the location description
|
|
received in the SIP INVITE (if any) and "config" is this profile.
|
|
|
|
On an outgoing call leg, "incoming" is the location description
|
|
passed through the dialplan to this channel (if any) and "config"
|
|
is this profile.
|
|
|
|
Values:
|
|
|
|
prefer_incoming: If there's an incoming location description, use it
|
|
even if there's also a configured one.
|
|
prefer_config: If there's a configured location description, use it
|
|
even if there's also an incoming one.
|
|
discard_incoming: Discard any incoming location description. If there's
|
|
a configured one, use it. If not, no location
|
|
information is propagated.
|
|
discard_config: Discard any configured location description. If
|
|
there's an incoming one, use it. If not, no location
|
|
information is propagated.
|
|
|
|
discard_incoming is the default.
|
|
|
|
Example:
|
|
profile_precedence = prefer_config
|
|
|
|
-- pidf_element (optional) --------------------------------------------
|
|
PIDF-LO element in which to place the location description.
|
|
|
|
pidf_element = < tuple | device | person >
|
|
Default: device
|
|
|
|
If the format is civicAddress or GML, this sets the PIDF element into
|
|
which the location information will be placed.
|
|
|
|
Values:
|
|
tuple: Places the information in a "tuple" element.
|
|
device: Places the information in a "device" element.
|
|
person: Places the information in a "person" element.
|
|
|
|
Per [RFC5491], "device" is preferred and therefore the default.
|
|
|
|
Example:
|
|
pidf_element = tuple
|
|
|
|
-- allow_routing_use (optional) ---------------------------------------
|
|
Sets whether the "Geolocation-Routing" header is added to outgoing
|
|
requests.
|
|
|
|
allow_routing_use = < yes | no >
|
|
Default: no
|
|
|
|
Set to "yes" to indicate that servers later in the path
|
|
can use the location information for routing purposes. Set to "no"
|
|
if they should not. If this value isn't specified, no
|
|
"Geolocation-Routing" header will be added.
|
|
|
|
Example:
|
|
allow_routing_use = yes
|
|
|
|
-- location_reference (optional) --------------------------------------
|
|
The name of an existing Location object.
|
|
location_reference = <location_id>
|
|
|
|
The location_info_refinement and location_variables parameters below can
|
|
be used to refine the location object for this specific profile.
|
|
|
|
Example:
|
|
location_reference = "my_building"
|
|
|
|
-- location_info_refinement (optional) --------------------------------
|
|
Location info to add to that already retrieved from the location object.
|
|
|
|
location_info_refinement = <location_format_specific_description>
|
|
|
|
The information in the referenced Location object can be refined on a
|
|
per-profile basis. For example, if the referenced Location object has a
|
|
civicAddress for a building, you could set location_refinement to add a
|
|
floor and room just for this profile
|
|
|
|
Example:
|
|
location_info_refinement = floor=20, room=20a2
|
|
|
|
-- location_variables (optional) --------------------------------------
|
|
|
|
If the referenced Location object uses any replacement variables, they
|
|
can be assigned here. There is no need to define variables that come
|
|
from the channel using this profile. They get assigned automatically.
|
|
|
|
location_variables = myfloor=20, myroom=222
|
|
|
|
-- suppress_empty_ca_elements (optional) ------------------------------
|
|
Sets whether empty values for Civic Address elements should be
|
|
suppressed from the outgoing PIDF-LO document.
|
|
|
|
suppress_empty_ca_elements = < yes | no >
|
|
Default: no
|
|
|
|
Setting to "yes" allows you to define a location info template
|
|
with channel variables that may or may not exist.
|
|
|
|
For example, with:
|
|
location_info_refinement = FLR=${MyFlr}
|
|
suppress_empty_ca_elements = no ; the default
|
|
|
|
If the MyFlr channel variable weren't set, the outgoing PIDF-LO document
|
|
would have an empty <FLR/> element in it. If suppress_empty_ca_elements
|
|
were set to "yes", the FLR element would be dropped from the PIDF-LO
|
|
document altogether.
|
|
|
|
-- format, location_info, location_source, method, confidence ---------
|
|
You can 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.
|
|
|
|
-- Profile Example ----------------------------------------------------
|
|
|
|
[myprofile]
|
|
type = profile
|
|
location_reference = mylocation
|
|
location_info_refinement = floor=20, room=20a2
|
|
pidf_element = tuple
|
|
profile_action = discard_incoming
|
|
|
|
=======================================================================
|
|
--;
|
|
|
|
-- NOTE ---------------------------------------------------------------
|
|
There are 4 built-in profiles that can be assigned to endpoints:
|
|
"<prefer_config>"
|
|
"<discard_config>"
|
|
"<prefer_incoming>"
|
|
"<discard_incoming>"
|
|
The profiles are empty except for having their precedence
|
|
set.
|
|
|