<p>Friendly Automation <strong>submitted</strong> this change.</p><p><a href="https://gerrit.asterisk.org/c/asterisk/+/19376">View Change</a></p><pre style="font-family: monospace,monospace; white-space: pre-wrap;"><span></span><br></pre><div style="white-space:pre-wrap">Approvals:
Joshua Colp: Looks good to me, but someone else must approve
Benjamin Keith Ford: Looks good to me, but someone else must approve
George Joseph: Looks good to me, approved
Friendly Automation: Approved for Submit
</div><pre style="font-family: monospace,monospace; white-space: pre-wrap;">res_geolocation: Update wiki documentation<br><br>Also added a note to the geolocation.conf.sample file<br>and added a README to the res/res_geolocation/wiki<br>directory.<br><br>Change-Id: I89c3c5db8c0701b33127993622d5e4f904bddfbc<br>---<br>M configs/samples/geolocation.conf.sample<br>M res/res_geolocation/wiki/AsteriskImplementation.md<br>M res/res_geolocation/wiki/GML.md<br>M res/res_geolocation/wiki/Geolocation.md<br>A res/res_geolocation/wiki/README.txt<br>M res/res_geolocation/wiki/URI.md<br>6 files changed, 269 insertions(+), 73 deletions(-)<br><br></pre>
<pre style="font-family: monospace,monospace; white-space: pre-wrap;"><span>diff --git a/configs/samples/geolocation.conf.sample b/configs/samples/geolocation.conf.sample</span><br><span>index 5b0052f..fdb9614 100644</span><br><span>--- a/configs/samples/geolocation.conf.sample</span><br><span>+++ b/configs/samples/geolocation.conf.sample</span><br><span>@@ -1,6 +1,8 @@</span><br><span> ;--</span><br><span> Geolocation Profile Sample Configuration</span><br><span> </span><br><span style="color: hsl(120, 100%, 40%);">+ Please see https://wiki.asterisk.org/wiki/display/AST/Geolocation</span><br><span style="color: hsl(120, 100%, 40%);">+ for the most current information.</span><br><span> --;</span><br><span> </span><br><span> ;--</span><br><span>diff --git a/res/res_geolocation/wiki/AsteriskImplementation.md b/res/res_geolocation/wiki/AsteriskImplementation.md</span><br><span>index ec1dad6..095e051 100644</span><br><span>--- a/res/res_geolocation/wiki/AsteriskImplementation.md</span><br><span>+++ b/res/res_geolocation/wiki/AsteriskImplementation.md</span><br><span>@@ -21,7 +21,7 @@</span><br><span> h2. Common Behavior</span><br><span> </span><br><span> h3. Sub-parameters</span><br><span style="color: hsl(0, 100%, 40%);">-Some of the parameters in each object are actually lists of comma-separated name-value "sub-parameters". For example, the {{location_info}} parameter in the Location object contains a list of sub-parameters that are specific to the location type.</span><br><span style="color: hsl(120, 100%, 40%);">+Some of the parameters in each object are actually lists of comma-separated name-value "sub-parameters". For example, the {{location_info}} parameter in the Location object contains a list of sub-parameters that are specific to the location type. For instance, a GML Circle might look like this:</span><br><span> {code}</span><br><span> location_info = shape=Circle, pos="39.12345 -105.98766", radius=100</span><br><span> {code}</span><br><span>@@ -30,11 +30,11 @@</span><br><span> For readability, parameters that use sub-parameters can be split over more than one line. For example:</span><br><span> {code}</span><br><span> location_info = country=US,A1="New York"</span><br><span style="color: hsl(0, 100%, 40%);">-location_info = house_number=1633,PRD=W,street=46th</span><br><span style="color: hsl(120, 100%, 40%);">+location_info = HNO=1633,PRD=W,RD=46th</span><br><span> {code}</span><br><span> would be equivalent to:</span><br><span> {code}</span><br><span style="color: hsl(0, 100%, 40%);">-location_info = country=US,A1="New York",house_number=1633,PRD=W,street=46th</span><br><span style="color: hsl(120, 100%, 40%);">+location_info = country=US,A1="New York",HNO=1633,PRD=W,RD=46th</span><br><span> {code}</span><br><span> </span><br><span> h3. Variable substitution</span><br><span>@@ -46,79 +46,208 @@</span><br><span> </span><br><span> You can also use dialplan functions such as {{CURL}} and {{ODBC_SQL}} to supply values just as you would in extensions.conf.</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-h2. Location</span><br><span style="color: hsl(120, 100%, 40%);">+h2. Configuration Objects</span><br><span style="color: hsl(120, 100%, 40%);">+h3. Location</span><br><span> The Location object defines a discrete location or defines a template that can be used to define a discrete location on a per-call basis.</span><br><span style="color: hsl(0, 100%, 40%);">-||Parameter||Required?||Uses Channel\\Variables?||Uses Sub\\Parameters?||Usage||</span><br><span style="color: hsl(0, 100%, 40%);">-|type|yes|no|no|Must be "location"|</span><br><span style="color: hsl(0, 100%, 40%);">-|format|yes|no|no|"civicAddress", "GML" or "URI" to indicate how the location is expressed.|</span><br><span style="color: hsl(0, 100%, 40%);">-|method|no|no|no|If provided, it MUST be one of "GPS", "A-GPS", "Manual", "DHCP", "Triangulation", "Cell", "802.11"|</span><br><span style="color: hsl(0, 100%, 40%);">-|location_source|no|no|no|If provided, it MUST be a fully qualified domain name. IP addresses are specifically not allowed.</span><br><span style="color: hsl(0, 100%, 40%);">-See [RFC8787|Geolocation Reference Information#rfc8787] for the exact definition of this parameter.|</span><br><span style="color: hsl(0, 100%, 40%);">-|location_info|yes|yes|yes|The sub-parameters of location_info are dependent on the location's format:</span><br><span style="color: hsl(0, 100%, 40%);">-* URI: A single {{URI}} sub-parameter with the URI.</span><br><span style="color: hsl(0, 100%, 40%);">-Example: {{location_info = URI=http://some.example.com}}</span><br><span style="color: hsl(0, 100%, 40%);">-See the [URI] page for more info.</span><br><span style="color: hsl(0, 100%, 40%);">-* civicAddress: A set of sub-parameters that describe the location.</span><br><span style="color: hsl(0, 100%, 40%);">-Example:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+h4. Parameters</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+* *type*: Object type. Must be "location"</span><br><span style="color: hsl(120, 100%, 40%);">+** Required: yes</span><br><span style="color: hsl(120, 100%, 40%);">+** Uses channel variables: no</span><br><span style="color: hsl(120, 100%, 40%);">+** Sub-parameters: none</span><br><span style="color: hsl(120, 100%, 40%);">+** Default: none</span><br><span style="color: hsl(120, 100%, 40%);">+** Example:</span><br><span style="color: hsl(120, 100%, 40%);">+ {{type=location}}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+* *format*: Must be one of "civicAddress", "GML" or "URI" to indicate how the location is expressed.</span><br><span style="color: hsl(120, 100%, 40%);">+** Required: yes</span><br><span style="color: hsl(120, 100%, 40%);">+** Uses channel variables: no</span><br><span style="color: hsl(120, 100%, 40%);">+** Sub-parameters: none</span><br><span style="color: hsl(120, 100%, 40%);">+** Default: none</span><br><span style="color: hsl(120, 100%, 40%);">+** Example:</span><br><span style="color: hsl(120, 100%, 40%);">+ {{format=civicAddress}}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+* *method*: If provided, it MUST be one of "GPS", "A-GPS", "Manual", "DHCP", "Triangulation", "Cell", "802.11"</span><br><span style="color: hsl(120, 100%, 40%);">+** Required: no</span><br><span style="color: hsl(120, 100%, 40%);">+** Uses channel variables: no</span><br><span style="color: hsl(120, 100%, 40%);">+** Sub-parameters: none</span><br><span style="color: hsl(120, 100%, 40%);">+** Default: none</span><br><span style="color: hsl(120, 100%, 40%);">+** Example:</span><br><span style="color: hsl(120, 100%, 40%);">+ {{method=Manual}}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+* *location_source*: If provided, it MUST be a fully qualified domain name. IP addresses are specifically not allowed. See [RFC8787|Geolocation Reference Information#rfc8787] for the exact definition of this parameter.</span><br><span style="color: hsl(120, 100%, 40%);">+** Required: no</span><br><span style="color: hsl(120, 100%, 40%);">+** Uses channel variables: no</span><br><span style="color: hsl(120, 100%, 40%);">+** Sub-parameters: none</span><br><span style="color: hsl(120, 100%, 40%);">+** Default: none</span><br><span style="color: hsl(120, 100%, 40%);">+** Example:</span><br><span style="color: hsl(120, 100%, 40%);">+ {{location_source=some.domain.net}}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+* *location_info*: Sub-parameters that describe the location. Dependent on the format selected.</span><br><span style="color: hsl(120, 100%, 40%);">+** Required: yes</span><br><span style="color: hsl(120, 100%, 40%);">+** Uses channel variables: yes</span><br><span style="color: hsl(120, 100%, 40%);">+** Sub-parameters: yes</span><br><span style="color: hsl(120, 100%, 40%);">+** Default: none</span><br><span style="color: hsl(120, 100%, 40%);">+** Examples:</span><br><span style="color: hsl(120, 100%, 40%);">+*** [URI] format: (see the [URI] page for more info)</span><br><span style="color: hsl(120, 100%, 40%);">+ {{location_info = URI=http://some.example.com}}</span><br><span style="color: hsl(120, 100%, 40%);">+*** [civicAddress|Civic Address] format: ( See the [civicAddress|Civic Address] page for more info)</span><br><span style="color: hsl(120, 100%, 40%);">+ {{location_info = country=US, A1="New York", A3="New York", ...}}</span><br><span style="color: hsl(120, 100%, 40%);">+*** [GML|Geography Markup Language] format: (See the [GML|Geography Markup Language] page for more info)</span><br><span style="color: hsl(120, 100%, 40%);">+ {{location_info = shape=Circle, pos="39.12345 -105.98766", radius=100}}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+* *confidence*: This is a rarely used field in the specification that would indicate the confidence in the location specified. See [RFC7459|https://www.rfc-editor.org/rfc/rfc7459] for exact details.</span><br><span style="color: hsl(120, 100%, 40%);">+** Required: no</span><br><span style="color: hsl(120, 100%, 40%);">+** Uses channel variables: no</span><br><span style="color: hsl(120, 100%, 40%);">+** Sub-parameters: yes</span><br><span style="color: hsl(120, 100%, 40%);">+*** *pdf*: One of: "unknown", "normal", "rectangular".</span><br><span style="color: hsl(120, 100%, 40%);">+*** *value*: 0-100 percent indicating the confidence level.</span><br><span style="color: hsl(120, 100%, 40%);">+** Default: none</span><br><span style="color: hsl(120, 100%, 40%);">+** Example:</span><br><span style="color: hsl(120, 100%, 40%);">+ {{confidence = pdf=normal, confidence=95</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+h4. Example</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span> {code}</span><br><span style="color: hsl(0, 100%, 40%);">-location_info = country=US,A1="New York",A3="New York"</span><br><span style="color: hsl(0, 100%, 40%);">-location_info = house_number=1633,PRD=W,street=46th</span><br><span style="color: hsl(0, 100%, 40%);">-location_info = street_suffix = Street,postal_code=10222</span><br><span style="color: hsl(120, 100%, 40%);">+[mylocation]</span><br><span style="color: hsl(120, 100%, 40%);">+type = location</span><br><span style="color: hsl(120, 100%, 40%);">+format = civicAddress</span><br><span style="color: hsl(120, 100%, 40%);">+method = Manual</span><br><span style="color: hsl(120, 100%, 40%);">+location_info = country=US, A1="New York", A3="New York",</span><br><span style="color: hsl(120, 100%, 40%);">+location_info = HNO=1633, PRD=W, RD=46th, STS=Street, PC=10222</span><br><span> {code}</span><br><span style="color: hsl(0, 100%, 40%);">-See the [Civic Address] page for more info.</span><br><span style="color: hsl(0, 100%, 40%);">-* GML: A set of sub-parameters that describe the location.</span><br><span style="color: hsl(0, 100%, 40%);">-Example: {{location_info = shape=Circle, pos="39.12345 -105.98766", radius=100}}</span><br><span style="color: hsl(0, 100%, 40%);">-See the [GML] page for more info.|</span><br><span style="color: hsl(0, 100%, 40%);">-|confidence|no|no|yes|This is a rarely used field in the specification that would indicate the confidence in the location specified. See [RFC7459|https://www.rfc-editor.org/rfc/rfc7459] for exact details.</span><br><span style="color: hsl(0, 100%, 40%);">-Sub-parameters:</span><br><span style="color: hsl(0, 100%, 40%);">-* {{pdf}}: One of: "unknown", "normal", "rectangular".</span><br><span style="color: hsl(0, 100%, 40%);">-* {{value}}: A percentage indicating the confidence.</span><br><span style="color: hsl(0, 100%, 40%);">-|</span><br><span> </span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-h2. Profile</span><br><span style="color: hsl(120, 100%, 40%);">+h3. Profile</span><br><span> The Profile object defines how a location is used and is referenced by channel drivers.</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-||Parameter||Required?||Uses Channel\\Variables?||Uses Sub\\Parameters?||Usage||</span><br><span style="color: hsl(0, 100%, 40%);">-|type|yes|no|no|Must be "profile"|</span><br><span style="color: hsl(0, 100%, 40%);">-|location_reference|no|no|no|Specifies the id of a Location object to use.|</span><br><span style="color: hsl(0, 100%, 40%);">-|pidf_element|no|no|no|For Civic Address and GML location formats, this parameter specifies the PIDF element that will carry the location description on outgoing SIP requests. Must be one of "tuple", "device" or "person". The default is "device".|</span><br><span style="color: hsl(0, 100%, 40%);">-|allow_routing_use|no|no|no|This value controls the value of the {{Geolocation-Routing}} header sent on SIP requests, Must be "yes" or "no". The default is "no".</span><br><span style="color: hsl(0, 100%, 40%);">-See [RFC6442|Geolocation Reference Information#rfc6442] for more information.|</span><br><span style="color: hsl(0, 100%, 40%);">-|profile_precedence|no|no|no|Specifies which of the available profiles (configured or incoming) takes precedence.\\</span><br><span style="color: hsl(0, 100%, 40%);">-NOTE: On an incoming call leg/channel, the "incoming" profile is the one received by the channel driver from the calling party in the SIP INVITE and the "configured" profile is the one attached to the calling party's pjsip endpoint. On an outgoing call segment/channel, the "incoming" profile is the one received by the channel driver from the Asterisk core/dialplan and the "configured" profile one is the one attached to the called party's pjsip endpoint.</span><br><span style="color: hsl(0, 100%, 40%);">-* {{prefer_incoming}}: Use the incoming profile if it exists and has location information, otherwise use the configured profile if it has location information. If neither profile has location information, nothing is sent.</span><br><span style="color: hsl(0, 100%, 40%);">-* {{force_incoming}}: 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.</span><br><span style="color: hsl(0, 100%, 40%);">-* {{prefer_config}}: 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.</span><br><span style="color: hsl(0, 100%, 40%);">-* {{force_config}}: 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.</span><br><span style="color: hsl(0, 100%, 40%);">-|</span><br><span style="color: hsl(0, 100%, 40%);">-|usage_rules|no|yes|yes|For Civic Address and GML location formats, this parameter specifies the contents of the {{usage-rules}} PIDF-LO element.\\</span><br><span style="color: hsl(0, 100%, 40%);">-* {{retransmission-allowed}}: Must be "yes" or "no". The default is "no".\\</span><br><span style="color: hsl(0, 100%, 40%);">-* {{retention-expires}}: An ISO-format timestamp after which the recipient MUST discard and location information associated with this request. The default is 24 hours after the request was sent. You can use dialplan functions to create a timestamp yourself if needed. For example, to set the timestamp to 1 hour after the request is sent, use:</span><br><span style="color: hsl(0, 100%, 40%);">-{{retention-expires="$\{STRFTIME($[$\{EPOCH\}+3600],UTC,%FT%TZ)\}"}}\\</span><br><span style="color: hsl(0, 100%, 40%);">-See [RFC4119|Geolocation Reference Information#rfc4119] for the exact definition of this parameter.</span><br><span style="color: hsl(0, 100%, 40%);">-|</span><br><span style="color: hsl(0, 100%, 40%);">-|location_info_refinement|no|yes|yes|This parameter can be used to refine referenced location by adding these sub-parameters to the {{location_info}} parameter of the referenced location object. For example, you could have Civic Address referenced object describe a building, then have this profile refine it by adding floor, room, etc. Another profile could then also reference the same location object and refine it by adding a different floor, room, etc.</span><br><span style="color: hsl(0, 100%, 40%);">-|location_variables|no|yes|yes|Any parameter than can use channel variables can also use the arbitrary variables defined in this parameter. For example {{location_variables = MYVAR1=something, MYVAR2="something else"}} would allow you to use {{$\{MYVAR1\}}} and {{$\{MYVAR2\}}} in any other parameter that can accept channel variables|</span><br><span style="color: hsl(0, 100%, 40%);">-|notes|no|no|no|The specifications allow a free-form "note-well" element to be added to the location description. Any text entered here will be present on all outgoing Civic Address and GML requests.|</span><br><span style="color: hsl(120, 100%, 40%);">+h4. Parameters</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+* *type*: Object type. Must be "profile"</span><br><span style="color: hsl(120, 100%, 40%);">+** Required: yes</span><br><span style="color: hsl(120, 100%, 40%);">+** Uses channel variables: no</span><br><span style="color: hsl(120, 100%, 40%);">+** Sub-parameters: none</span><br><span style="color: hsl(120, 100%, 40%);">+** Default: none</span><br><span style="color: hsl(120, 100%, 40%);">+** Example:</span><br><span style="color: hsl(120, 100%, 40%);">+ {{type=profile}}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+* *location_reference*: Specifies the id of a Location object to use.</span><br><span style="color: hsl(120, 100%, 40%);">+** Required: no</span><br><span style="color: hsl(120, 100%, 40%);">+** Uses channel variables: no</span><br><span style="color: hsl(120, 100%, 40%);">+** Sub-parameters: none</span><br><span style="color: hsl(120, 100%, 40%);">+** Default: none</span><br><span style="color: hsl(120, 100%, 40%);">+** Example:</span><br><span style="color: hsl(120, 100%, 40%);">+ {{location_reference=mylocation}}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+* *pidf_element*: For Civic Address and GML location formats, this parameter specifies the PIDF element that will carry the location description on outgoing SIP requests. Must be one of "tuple", "device" or "person".</span><br><span style="color: hsl(120, 100%, 40%);">+** Required: no</span><br><span style="color: hsl(120, 100%, 40%);">+** Uses channel variables: no</span><br><span style="color: hsl(120, 100%, 40%);">+** Sub-parameters: none</span><br><span style="color: hsl(120, 100%, 40%);">+** Default: device</span><br><span style="color: hsl(120, 100%, 40%);">+** Example:</span><br><span style="color: hsl(120, 100%, 40%);">+ {{pidf_element = tuple}}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+* *allow_routing_use*: This value controls the value of the {{Geolocation-Routing}} header sent on SIP requests, Must be "yes" or "no". See [RFC6442|Geolocation Reference Information#rfc6442] for more information.</span><br><span style="color: hsl(120, 100%, 40%);">+** Required: no</span><br><span style="color: hsl(120, 100%, 40%);">+** Uses channel variables: no</span><br><span style="color: hsl(120, 100%, 40%);">+** Sub-parameters: none</span><br><span style="color: hsl(120, 100%, 40%);">+** Default: no</span><br><span style="color: hsl(120, 100%, 40%);">+** Example:</span><br><span style="color: hsl(120, 100%, 40%);">+ {{allow_routing_use = yes}}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+* *profile_precedence*: Specifies which of the available profiles (configured or incoming) takes precedence. NOTE: On an incoming call leg/channel, the "incoming" profile is the one received by the channel driver from the calling party in the SIP INVITE and the "configured" profile is the one attached to the calling party's pjsip endpoint. On an outgoing call segment/channel, the "incoming" profile is the one received by the channel driver from the Asterisk core/dialplan and the "configured" profile one is the one attached to the called party's pjsip endpoint.</span><br><span style="color: hsl(120, 100%, 40%);">+** Valid values:</span><br><span style="color: hsl(120, 100%, 40%);">+*** {{prefer_incoming}}: Use the incoming profile if it exists and has location information, otherwise use the configured profile if it has location information. If neither profile has location information, nothing is passed on.</span><br><span style="color: hsl(120, 100%, 40%);">+*** {{prefer_config}}: Use the configured profile if it exists and has location information, otherwise use the incoming profile if it has location information. If neither profile has location information, nothing is passed on.</span><br><span style="color: hsl(120, 100%, 40%);">+*** {{discard_incoming}}: Discard the incoming profile and use the configured profile if it has location information. If it doesn't, nothing is passed on.</span><br><span style="color: hsl(120, 100%, 40%);">+*** {{discard_config}}: Discard the configured profile and use the incoming profile if it has location information. If it doesn't, nothing is passed on.</span><br><span style="color: hsl(120, 100%, 40%);">+** Required: no</span><br><span style="color: hsl(120, 100%, 40%);">+** Uses channel variables: no</span><br><span style="color: hsl(120, 100%, 40%);">+** Sub-parameters: none</span><br><span style="color: hsl(120, 100%, 40%);">+** Default: discard_incoming</span><br><span style="color: hsl(120, 100%, 40%);">+** Example:</span><br><span style="color: hsl(120, 100%, 40%);">+ {{profile_precedence = prefer_incoming}}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+* *usage_rules*: For Civic Address and GML location formats, this parameter specifies the contents of the {{usage-rules}} PIDF-LO element. See [RFC4119|Geolocation Reference Information#rfc4119] for the exact definition of this parameter.</span><br><span style="color: hsl(120, 100%, 40%);">+** Required: no</span><br><span style="color: hsl(120, 100%, 40%);">+** Uses channel variables: yes</span><br><span style="color: hsl(120, 100%, 40%);">+** Sub-parameters: yes</span><br><span style="color: hsl(120, 100%, 40%);">+*** *retransmission-allowed*: Must be "yes" or "no".</span><br><span style="color: hsl(120, 100%, 40%);">+*** *retention-expires*: An ISO-format timestamp after which the recipient MUST discard and location information associated with this request. The default is 24 hours after the request was sent. You can use dialplan functions to create a timestamp yourself if needed.</span><br><span style="color: hsl(120, 100%, 40%);">+** Default: retransmission-allowed=no, retention-expires=<current time + 24 hours></span><br><span style="color: hsl(120, 100%, 40%);">+** Example:</span><br><span style="color: hsl(120, 100%, 40%);">+ {{usage_rules = retransmission-allowed=yes,retention-expires="$\{STRFTIME($[$\{EPOCH\}+3600],UTC,%FT%TZ)\}"}}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+* *suppress_empty_ca_elements*: For Civic Address outgoing PIDF-LO documents, don't output empty elements. This can be useful when you dynamically set values of elements in the dialplan that could evaluate to an empty string. For instance, if you set the street suffix STS element from a dialplan variable and it happens to be empty, the default behavior would be to send an empty {{<STS/>}} element. If this parameter is set to "yes" however, we'd just not print the element at all.</span><br><span style="color: hsl(120, 100%, 40%);">+** Required: no</span><br><span style="color: hsl(120, 100%, 40%);">+** Uses channel variables: no</span><br><span style="color: hsl(120, 100%, 40%);">+** Sub-parameters: no</span><br><span style="color: hsl(120, 100%, 40%);">+** Default: no</span><br><span style="color: hsl(120, 100%, 40%);">+** Example</span><br><span style="color: hsl(120, 100%, 40%);">+ {{suppress_empty_ca_elements = yes}}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+* *location_info_refinement*: This parameter can be used to refine referenced location by adding these sub-parameters to the {{location_info}} parameter of the referenced location object. For example, you could have Civic Address referenced object describe a building, then have this profile refine it by adding floor, room, etc. Another profile could then also reference the same location object and refine it by adding a different floor, room, etc.</span><br><span style="color: hsl(120, 100%, 40%);">+** Required: no</span><br><span style="color: hsl(120, 100%, 40%);">+** Uses channel variables: yes</span><br><span style="color: hsl(120, 100%, 40%);">+** Sub-parameters: yes (any that can appear in a location's location_info parameter)</span><br><span style="color: hsl(120, 100%, 40%);">+** Default: none</span><br><span style="color: hsl(120, 100%, 40%);">+** Example:</span><br><span style="color: hsl(120, 100%, 40%);">+ Add a room to the civicAddress specified by location_reference.</span><br><span style="color: hsl(120, 100%, 40%);">+ {{location_reference = myCivicAddress = ROOM=23A4}}</span><br><span style="color: hsl(120, 100%, 40%);">+ {{location_info_refinement = ROOM=23A4}}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+* *location_variables*: Any parameter than can use channel variables can also use the arbitrary variables defined in this parameter. For example {{location_variables = MYVAR1=something, MYVAR2="something else"}} would allow you to use {{$\{MYVAR1\}}} and {{$\{MYVAR2\}}} in any other parameter that can accept channel variables.</span><br><span style="color: hsl(120, 100%, 40%);">+** Required: no</span><br><span style="color: hsl(120, 100%, 40%);">+** Uses channel variables: yes</span><br><span style="color: hsl(120, 100%, 40%);">+** Sub-parameters: yes (one or more name=value pairs)</span><br><span style="color: hsl(120, 100%, 40%);">+** Default: none</span><br><span style="color: hsl(120, 100%, 40%);">+** Example:</span><br><span style="color: hsl(120, 100%, 40%);">+ {{location_variables = MYVAR1=something, MYVAR2="something else"}}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+* *notes*: The specifications allow a free-form "note-well" element to be added to the location description. Any text entered here will be present on all outgoing Civic Address and GML requests.</span><br><span style="color: hsl(120, 100%, 40%);">+** Required: no</span><br><span style="color: hsl(120, 100%, 40%);">+** Uses channel variables: no</span><br><span style="color: hsl(120, 100%, 40%);">+** Sub-parameters: no</span><br><span style="color: hsl(120, 100%, 40%);">+** Default: none</span><br><span style="color: hsl(120, 100%, 40%);">+** Example:</span><br><span style="color: hsl(120, 100%, 40%);">+ {{notes = "anything you want"}}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+h4. Additional Parameters</span><br><span style="color: hsl(120, 100%, 40%);">+In addition to the profile-specific parameters defined above, any location-object parameters can be specified as well. This is a convenient shortcut if you have a 1<>1 relationship between profile and location.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+h4. Built-in Profiles</span><br><span style="color: hsl(120, 100%, 40%);">+In addition to the profiles you define in geolocation.conf, 4 built-in profiles are also available They're named after their profile_precedence setting:</span><br><span style="color: hsl(120, 100%, 40%);">+* *<prefer_incoming>*</span><br><span style="color: hsl(120, 100%, 40%);">+* *<prefer_config>*</span><br><span style="color: hsl(120, 100%, 40%);">+* *<discard_incoming>*</span><br><span style="color: hsl(120, 100%, 40%);">+* *<discard_config>*</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The rest of the profile parameters are set to their defaults.</span><br><span> </span><br><span> h1. chan_pjsip Configuration</span><br><span> Two new parameters have been added to pjsip endpoints:</span><br><span style="color: hsl(0, 100%, 40%);">-||Parameter||Usage||</span><br><span style="color: hsl(0, 100%, 40%);">-|geoloc_incoming_call_profile|Should be set to the name of a geolocation profile to use for calls coming into Asterisk from this remote endpoint. If not set, no geolocation processing will occur and any location descriptions present on the incoming request will be silently dropped.|</span><br><span style="color: hsl(0, 100%, 40%);">-|geoloc_outgoing_call_profile|Should be set to the name of a geolocation profile to use for calls Asterisk sends to this remote endpoint. If not set, no geolocation processing will occur and any location descriptions coming from the associated incoming channel or the dialplan will be silently dropped and not conveyed to the endpoint.|</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-h1. Dialplan Applications and Functions</span><br><span style="color: hsl(0, 100%, 40%);">-Two new dialplan applications and one dialplan function have been added to allow a dialplan author to manipulate geolocation information.</span><br><span style="color: hsl(120, 100%, 40%);">+h2. Parameters</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-h2. GeolocProfileCreate</span><br><span style="color: hsl(0, 100%, 40%);">-This application creates a new Geolocation profile on the channel in addition to any others that may already exist. It tasks a profile name and an index as its arguments. Callers must use the {{GEOLOC_PROFILE}} function to set its actual location description.</span><br><span style="color: hsl(120, 100%, 40%);">+* *geoloc_incoming_call_profile*: Should be set to the name of a geolocation profile to use for calls coming into Asterisk from this remote endpoint. If not set, no geolocation processing will occur and any location descriptions present on the incoming request will be silently dropped. Any of the 4 built-in profiles can be used.</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-h2. GeolocProfileDelete</span><br><span style="color: hsl(0, 100%, 40%);">-This application deletes the existing Geolocation profile at the specified index from the channel's list of profiles.</span><br><span style="color: hsl(120, 100%, 40%);">+* *geoloc_outgoing_call_profile*: Should be set to the name of a geolocation profile to use for calls Asterisk sends to this remote endpoint. If not set, no geolocation processing will occur and any location descriptions coming from the associated incoming channel or the dialplan will be silently dropped and not conveyed to the endpoint. Any of the 4 built-in profiles can be used.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Example:</span><br><span style="color: hsl(120, 100%, 40%);">+{code}</span><br><span style="color: hsl(120, 100%, 40%);">+[myendpoint]</span><br><span style="color: hsl(120, 100%, 40%);">+type = endpoint</span><br><span style="color: hsl(120, 100%, 40%);">+...</span><br><span style="color: hsl(120, 100%, 40%);">+geoloc_incoming_call_profile = <discard_incoming></span><br><span style="color: hsl(120, 100%, 40%);">+geoloc_outgoing_call_profile = myendpoint_profile</span><br><span style="color: hsl(120, 100%, 40%);">+{code}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+h1. Dialplan Function</span><br><span style="color: hsl(120, 100%, 40%);">+A new dialplan function has been added to allow a dialplan author to manipulate geolocation information.</span><br><span> </span><br><span> h2. GEOLOC_PROFILE</span><br><span style="color: hsl(0, 100%, 40%);">-This function can get or set any of the fields in a specific profile. The available fields are those in _both_ the Location and Profile configuration objects.</span><br><span style="color: hsl(120, 100%, 40%);">+This function can get or set any of the fields in a specific profile. The available fields are those in _both_ the Location and Profile configuration objects. See the fuinction help for more information.</span><br><span> </span><br><span> h1. Example Call Flows</span><br><span> </span><br><span>diff --git a/res/res_geolocation/wiki/GML.md b/res/res_geolocation/wiki/GML.md</span><br><span>index 394f1c2..c1b1a71 100644</span><br><span>--- a/res/res_geolocation/wiki/GML.md</span><br><span>+++ b/res/res_geolocation/wiki/GML.md</span><br><span>@@ -16,7 +16,7 @@</span><br><span> </span><br><span> h2. Units of Measure</span><br><span> h3. Position</span><br><span style="color: hsl(0, 100%, 40%);">-Positions are always specified in decimal degrees latitude and longitude. A 3d position adds the altitude in meters. `pos` and `posList` are the two attributes that specify position.</span><br><span style="color: hsl(120, 100%, 40%);">+Positions are always specified in decimal degrees latitude and longitude. A 3d position adds the altitude in meters. `pos` and `pos3d` are the two attributes that specify position.</span><br><span> h3. Distance</span><br><span> Distance is _always_ specified in meters. `height`, `radius` and the altitude component of `pos` are some of the distance attributes.</span><br><span> </span><br><span>@@ -29,22 +29,44 @@</span><br><span> Angle may be specified in either degrees or radians by specifying the `degrees` or `radians` suffix to the angle value. The default it `degrees` if no suffix is provided. `orientation`, `startAngle` and `openingAngle` are some of the angle attributes.</span><br><span> </span><br><span> h2. Shapes</span><br><span style="color: hsl(0, 100%, 40%);">-h3. Point</span><br><span style="color: hsl(0, 100%, 40%);">-A Point isn't really a "shape" because it's a one dimensional construct but we'll ignore that. It's simply a point in space specified with either two or three dimensions.</span><br><span style="color: hsl(120, 100%, 40%);">+See the references above for the exact shape definitions.</span><br><span> </span><br><span style="color: hsl(120, 100%, 40%);">+|| Shape || Attributes ||</span><br><span style="color: hsl(120, 100%, 40%);">+| Point | pos or pos3d |</span><br><span style="color: hsl(120, 100%, 40%);">+| Circle | pos or pos3d, radius |</span><br><span style="color: hsl(120, 100%, 40%);">+| Sphere | pos3d, radius |</span><br><span style="color: hsl(120, 100%, 40%);">+| Ellipse| pos or pos3d, semiMajorAxis, semiMinorAxis, orientation |</span><br><span style="color: hsl(120, 100%, 40%);">+| ArcBand | pos or pos3d, innerRadius, outerRadius, startAngle, openingAngle |</span><br><span style="color: hsl(120, 100%, 40%);">+| Ellipsoid | pos3d, semiMajorAxis, semiMinorAxis, verticalAxis, orientation |</span><br><span style="color: hsl(120, 100%, 40%);">+| Polygon | 3 or more pos or pos3d |</span><br><span style="color: hsl(120, 100%, 40%);">+| Prism | 3 or more pos3d, height |</span><br><span> </span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-|| Shape || Attributes || Description ||</span><br><span style="color: hsl(0, 100%, 40%);">-| Point | pos or pos3d | A single point |</span><br><span style="color: hsl(0, 100%, 40%);">-| Circle | pos or pos3d, radius | A two dimensional circle around a point |</span><br><span style="color: hsl(0, 100%, 40%);">-| Sphere | pos3d, radius | A 3 dimensional sphere around a point |</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span> || Attribute || Description || Units || Example ||</span><br><span> | pos | A two dimensional point | Decimal degrees | pos="39.12345 -105.98766" |</span><br><span> | pos3d | A three dimensional point | Decimal degrees + altitude in meters | pos="39.12345 -105.98766 1690" |</span><br><span> | radius | Distance | Meters | radius="20" |</span><br><span> | height | Distance | Meters | height="45" |</span><br><span> | orientation | Angle | Degrees (default) or Radians | orientation="90", orientation="25 radians" |</span><br><span style="color: hsl(120, 100%, 40%);">+| semiMajorAxis | Distance | Meters | semiMajorAxis="145" |</span><br><span style="color: hsl(120, 100%, 40%);">+| semiMinorAxis | Distance | Meters | semiMinorAxis="145" |</span><br><span style="color: hsl(120, 100%, 40%);">+| innerRadius | Distance | Meters | innerRadius="350" |</span><br><span style="color: hsl(120, 100%, 40%);">+| outerRadius | Distance | Meters | outerRadius="350" |</span><br><span style="color: hsl(120, 100%, 40%);">+| verticalAxis | Distance | Meters | verticalAxis="20" |</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+h2. Examples:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+{code}</span><br><span style="color: hsl(120, 100%, 40%);">+location_info = shape=Point, crs=2d, pos="39.12345 -105.98766"</span><br><span style="color: hsl(120, 100%, 40%);">+location_info = shape=Point, crs=3d, pos="39.12345 -105.98766 1892.0"</span><br><span style="color: hsl(120, 100%, 40%);">+location_info = shape=Circle, crs=2d, pos="39.12345 -105.98766" radius="45"</span><br><span style="color: hsl(120, 100%, 40%);">+location_info = shape=Sphere, crs=3d, pos="39.12345 -105.98766 1902" radius="20"</span><br><span style="color: hsl(120, 100%, 40%);">+location_info = shape=Ellipse, crs=2d, pos="39.12345 -105.98766" semiMajorAxis="20", semiMinorAxis="10", orientation="25 radians"</span><br><span style="color: hsl(120, 100%, 40%);">+location_info = shape=ArcBand, crs=2d, pos="39.12345 -105.98766" innerRadius="1200", outerRadius="1500", startAngle="90", openingAngle="120"</span><br><span style="color: hsl(120, 100%, 40%);">+location_info = shape=Polygon, crs=2d, pos="39.12345 -105.98766", pos=40.7890 -105.98766", pos="40.7890 -106.3456", pos=39.12345 -106.3456"</span><br><span style="color: hsl(120, 100%, 40%);">+location_info = shape=Prism, crs=3d, pos="39.12345 -105.98766 1890", pos="40.7890 -105.98766 1890", pos="40.7890 -106.3456 1890", pos=39.12345 -106.3456 1890", height="45"</span><br><span style="color: hsl(120, 100%, 40%);">+{code}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span> </span><br><span> {column}</span><br><span> {column:width=30%}</span><br><span>diff --git a/res/res_geolocation/wiki/Geolocation.md b/res/res_geolocation/wiki/Geolocation.md</span><br><span>index 8921978..f43343f 100644</span><br><span>--- a/res/res_geolocation/wiki/Geolocation.md</span><br><span>+++ b/res/res_geolocation/wiki/Geolocation.md</span><br><span>@@ -55,7 +55,7 @@</span><br><span> This method involves sending or receiving a PIDF-LO document attached to a SIP message. For details on how this works generally, See [RFC6442|Geolocation Reference Information#rfc6442] and [RFC5491|Geolocation Reference Information#rfc5491]. An example {{Geolocation}} header might look like: {{Geolocation: <cid:gyytfr@your.pbx.com>}}. The {{cid}} scheme indicates that the recipient should look in the SIP message body (or bodies since there could also be an SDP for example) for the location document.</span><br><span> </span><br><span> h3. Multiple URIs</span><br><span style="color: hsl(0, 100%, 40%);">-The {{Geolocation}} header can contain multiple URIs and they can be a mix of "by-reference" and "by-value". As mentioned above though, the process of dealing with multiple location references is pretty complex and should be avoided.</span><br><span style="color: hsl(120, 100%, 40%);">+Technically, the {{Geolocation}} header can contain multiple URIs and they can be a mix of "by-reference" and "by-value". The process of dealing with multiple location references is _very_ complex however and should be avoided.</span><br><span> </span><br><span> h3. Geolocation-Routing</span><br><span> [RFC6442|Geolocation Reference Information#rfc6442] also defines the {{Geolocation-Routing}} header which indicates to a recipient that the location information may or may not be used for call routing purposes. If set to "no" (the default if absent), the recipient MUST NOT use the location information for routing purposes. If set to "yes", the recipient MAY use the location information for routing purposes and may also reset the value to "no" to prevent downstream systems from using the location information for routing.</span><br><span>diff --git a/res/res_geolocation/wiki/README.txt b/res/res_geolocation/wiki/README.txt</span><br><span>new file mode 100644</span><br><span>index 0000000..534b82b</span><br><span>--- /dev/null</span><br><span>+++ b/res/res_geolocation/wiki/README.txt</span><br><span>@@ -0,0 +1,31 @@</span><br><span style="color: hsl(120, 100%, 40%);">+README</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Don't post this file to the Wiki. It's developer information for maintaining</span><br><span style="color: hsl(120, 100%, 40%);">+these markup files.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+These files are written in Confluence flavored markup so they can be</span><br><span style="color: hsl(120, 100%, 40%);">+uploaded to the public wiki directly.</span><br><span style="color: hsl(120, 100%, 40%);">+See https://confluence.atlassian.com/doc/confluence-wiki-markup-251003035.html</span><br><span style="color: hsl(120, 100%, 40%);">+for syntax.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Many editors have plugins to render previews in this format so check around</span><br><span style="color: hsl(120, 100%, 40%);">+for your particular editor. For Eclipse, the Mylyn WikiText plugin does the</span><br><span style="color: hsl(120, 100%, 40%);">+trick.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+To upload these files to Confluence, you'll need to edit the corresponding</span><br><span style="color: hsl(120, 100%, 40%);">+live page and paste the contents of the edited file.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+* Edit the page corresponding to the file that's been edited.</span><br><span style="color: hsl(120, 100%, 40%);">+* Delete the contents:</span><br><span style="color: hsl(120, 100%, 40%);">+ ** If there's an existing "Wiki Markup" section with markup in it, select</span><br><span style="color: hsl(120, 100%, 40%);">+ the contents of the section and delete it. This should leave you with an</span><br><span style="color: hsl(120, 100%, 40%);">+ empty "Wiki Markup" section.</span><br><span style="color: hsl(120, 100%, 40%);">+ ** If the page is the traditional WYSIWYG Confluence editor, delete the</span><br><span style="color: hsl(120, 100%, 40%);">+ entire contents of the page then type "{markup}" and press return. Now</span><br><span style="color: hsl(120, 100%, 40%);">+ delete the "{markup}" placeholder that was automatically added to the</span><br><span style="color: hsl(120, 100%, 40%);">+ new "Wiki Markup" section.</span><br><span style="color: hsl(120, 100%, 40%);">+* Copy the entire contents of the edited file into your clipboard.</span><br><span style="color: hsl(120, 100%, 40%);">+* Back in Confluence, paste the contents of your clipboard into the</span><br><span style="color: hsl(120, 100%, 40%);">+ "Wiki Markup" section.</span><br><span style="color: hsl(120, 100%, 40%);">+* Preview if you like then save.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span>diff --git a/res/res_geolocation/wiki/URI.md b/res/res_geolocation/wiki/URI.md</span><br><span>index 91d832f..ad4b83a 100644</span><br><span>--- a/res/res_geolocation/wiki/URI.md</span><br><span>+++ b/res/res_geolocation/wiki/URI.md</span><br><span>@@ -56,9 +56,8 @@</span><br><span> ; the outgoing channel when 911 is dialed and does nothing if another number is dialed.</span><br><span> [pre-dial-handler]</span><br><span> exten = 911,1,NoOp(Entering PDH for Outgoing Channel)</span><br><span style="color: hsl(0, 100%, 40%);">-same = n,GeolocProfileCreate(geoloc.example@myserver.com)</span><br><span style="color: hsl(0, 100%, 40%);">-same = n,Set(GEOLOC_PROFILE(format,0)=URI)</span><br><span style="color: hsl(0, 100%, 40%);">-same = n,Set(GEOLOC_PROFILE(location_info,0)=URI=https://my.company.com/location_query?DID=${CALLERID(num)})</span><br><span style="color: hsl(120, 100%, 40%);">+same = n,Set(GEOLOC_PROFILE(format)=URI)</span><br><span style="color: hsl(120, 100%, 40%);">+same = n,Set(GEOLOC_PROFILE(location_info)=URI=https://my.company.com/location_query?DID=${CALLERID(num)})</span><br><span> same = n,Return(0)</span><br><span> exten = _X.,1,Return(0)</span><br><span> </span><br><span></span><br></pre><p>To view, visit <a href="https://gerrit.asterisk.org/c/asterisk/+/19376">change 19376</a>. To unsubscribe, or for help writing mail filters, visit <a href="https://gerrit.asterisk.org/settings">settings</a>.</p><div itemscope itemtype="http://schema.org/EmailMessage"><div itemscope itemprop="action" itemtype="http://schema.org/ViewAction"><link itemprop="url" href="https://gerrit.asterisk.org/c/asterisk/+/19376"/><meta itemprop="name" content="View Change"/></div></div>
<div style="display:none"> Gerrit-Project: asterisk </div>
<div style="display:none"> Gerrit-Branch: certified/18.9 </div>
<div style="display:none"> Gerrit-Change-Id: I89c3c5db8c0701b33127993622d5e4f904bddfbc </div>
<div style="display:none"> Gerrit-Change-Number: 19376 </div>
<div style="display:none"> Gerrit-PatchSet: 2 </div>
<div style="display:none"> Gerrit-Owner: George Joseph <gjoseph@digium.com> </div>
<div style="display:none"> Gerrit-Reviewer: Benjamin Keith Ford <bford@digium.com> </div>
<div style="display:none"> Gerrit-Reviewer: Friendly Automation </div>
<div style="display:none"> Gerrit-Reviewer: George Joseph <gjoseph@digium.com> </div>
<div style="display:none"> Gerrit-Reviewer: Joshua Colp <jcolp@sangoma.com> </div>
<div style="display:none"> Gerrit-MessageType: merged </div>