mirror of
https://github.com/asterisk/asterisk.git
synced 2025-10-31 02:37:10 +00:00
f491355384
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
265 lines
9.2 KiB
Plaintext
265 lines
9.2 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
|
|
|
|
-- 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_action (optional) ------------------------------------------
|
|
Sets how to reconcile incoming and configured profiles.
|
|
profile_action = < 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_action = prefer_config
|
|
|
|
-- pidf_element (optional) --------------------------------------------
|
|
PIDF-LO element in which to place the location description.
|
|
pidf_element = < tuple | device | person >
|
|
|
|
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
|
|
|
|
-- geolocation_routing (optional) -------------------------------------
|
|
Sets whether the "Geolocation-Routing" header is added to outgoing
|
|
requests.
|
|
geolocation_routing = < yes | 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:
|
|
geolocation_routing = 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 -------------------------------------------------
|
|
|
|
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
|
|
|
|
-- Profile Example ----------------------------------------------------
|
|
|
|
[myprofile]
|
|
type = profile
|
|
location_reference = mylocation
|
|
location_info_refinement = floor=20, room=20a2
|
|
pidf_element = tuple
|
|
profile_action = discard_incoming
|
|
|
|
=======================================================================
|
|
--;
|