<p>George Joseph <strong>submitted</strong> this change.</p><p><a href="https://gerrit.asterisk.org/c/asterisk/+/19194">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:
George Joseph: Looks good to me, approved; Approved for Submit
</div><pre style="font-family: monospace,monospace; white-space: pre-wrap;">Geolocation: Wiki Documentation<br><br>Change-Id: I68ba22db0a69d9e2eabcc2141b48a2395f7f1a23<br>---<br>A res/res_geolocation/wiki/AsteriskImplementation.md<br>A res/res_geolocation/wiki/CivicAddress.md<br>A res/res_geolocation/wiki/GML.md<br>A res/res_geolocation/wiki/Geolocation.md<br>A res/res_geolocation/wiki/ReferenceInformation.md<br>A res/res_geolocation/wiki/URI.md<br>6 files changed, 606 insertions(+), 0 deletions(-)<br><br></pre>
<pre style="font-family: monospace,monospace; white-space: pre-wrap;"><span>diff --git a/res/res_geolocation/wiki/AsteriskImplementation.md b/res/res_geolocation/wiki/AsteriskImplementation.md</span><br><span>new file mode 100644</span><br><span>index 0000000..e818c72</span><br><span>--- /dev/null</span><br><span>+++ b/res/res_geolocation/wiki/AsteriskImplementation.md</span><br><span>@@ -0,0 +1,177 @@</span><br><span style="color: hsl(120, 100%, 40%);">+{section:border=false}</span><br><span style="color: hsl(120, 100%, 40%);">+{column:width=70%}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+h1. Introduction</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The Geolocation capabilities are implemented in Asterisk with the res_geolocation and res_pjsip_geolocation modules and the geolocation.conf configuration file. There are also dialplan functions which allow you to manipulate location information as it's passed through the dialplan.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+h1. Location Information Flow</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Location information can be supplied to Asterisk from several sources during the call flow...</span><br><span style="color: hsl(120, 100%, 40%);">+* Sent by a caller in a SIP INVITE message.</span><br><span style="color: hsl(120, 100%, 40%);">+* Provided by a geolocation profile attached to the caller's endpoint.</span><br><span style="color: hsl(120, 100%, 40%);">+* Provided by the dialplan via the Geolocation apps and functions.</span><br><span style="color: hsl(120, 100%, 40%);">+* Provided by a geolocation profile attached to the callee's endpoint.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+These sources aren't mutually exclusive and may, in fact, provide conflicting information or present the same information in multiple formats. Given that, there's no way for Asterisk to merge information nor is there a way for Asterisk to automatically determine which source should take precedence. However, you can use the geolocation profiles and the dialplan functions to tell Asterisk what to do with the location information received from the previous step in the call flow.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+h1. Core Configuration</span><br><span style="color: hsl(120, 100%, 40%);">+The bulk of the geolocation support is implemented in the res_geolocation module and configured in the geolocation.conf file. The file contains two main objects, Location and Profile.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+h2. Common Behavior</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+h3. Sub-parameters</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.</span><br><span style="color: hsl(120, 100%, 40%);">+{code}</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%);">+{code}</span><br><span style="color: hsl(120, 100%, 40%);">+Spaces around the equals signs and commas are ignored so you must double quote sub-parameter values with spaces or commas in them.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+For readability, parameters that use sub-parameters can be split over more than one line. For example:</span><br><span style="color: hsl(120, 100%, 40%);">+{code}</span><br><span style="color: hsl(120, 100%, 40%);">+location_info = country=US,A1="New York"</span><br><span style="color: hsl(120, 100%, 40%);">+location_info = house_number=1633,PRD=W,street=46th</span><br><span style="color: hsl(120, 100%, 40%);">+{code}</span><br><span style="color: hsl(120, 100%, 40%);">+would be equivalent to:</span><br><span style="color: hsl(120, 100%, 40%);">+{code}</span><br><span style="color: hsl(120, 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%);">+{code}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+h3. Variable substitution</span><br><span style="color: hsl(120, 100%, 40%);">+Some of the parameters can contain references to channel variables and dialplan functions. For example, you might have a URI location object that contains a reference to the {{EXTEN}} channel variable:</span><br><span style="color: hsl(120, 100%, 40%);">+{code}</span><br><span style="color: hsl(120, 100%, 40%);">+location_info = URI=http://some.example.com?key=${EXTEN}</span><br><span style="color: hsl(120, 100%, 40%);">+{code}</span><br><span style="color: hsl(120, 100%, 40%);">+When a call is processed that uses this location object, {{$\{EXTEN\}}} would be replaced with the channel's extension and would result in a URI such as {{http://some.example.com?key=1000}}. You'd set up your web server to return a location document based on the value of "key".</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+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 style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+h2. Location</span><br><span style="color: hsl(120, 100%, 40%);">+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(120, 100%, 40%);">+||Parameter||Required?||Uses Channel\\Variables?||Uses Sub\\Parameters?||Usage||</span><br><span style="color: hsl(120, 100%, 40%);">+|type|yes|no|no|Must be "location"|</span><br><span style="color: hsl(120, 100%, 40%);">+|format|yes|no|no|"civicAddress", "GML" or "URI" to indicate how the location is expressed.|</span><br><span style="color: hsl(120, 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(120, 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(120, 100%, 40%);">+See [RFC8787|Geolocation Reference Information#rfc8787] for the exact definition of this parameter.|</span><br><span style="color: hsl(120, 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(120, 100%, 40%);">+* URI: A single {{URI}} sub-parameter with the URI.</span><br><span style="color: hsl(120, 100%, 40%);">+Example: {{location_info = URI=http://some.example.com}}</span><br><span style="color: hsl(120, 100%, 40%);">+See the [URI] page for more info.</span><br><span style="color: hsl(120, 100%, 40%);">+* civicAddress: A set of sub-parameters that describe the location.</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%);">+location_info = country=US,A1="New York",A3="New York"</span><br><span style="color: hsl(120, 100%, 40%);">+location_info = house_number=1633,PRD=W,street=46th</span><br><span style="color: hsl(120, 100%, 40%);">+location_info = street_suffix = Street,postal_code=10222</span><br><span style="color: hsl(120, 100%, 40%);">+{code}</span><br><span style="color: hsl(120, 100%, 40%);">+See the [Civic Address] page for more info.</span><br><span style="color: hsl(120, 100%, 40%);">+* GML: A set of sub-parameters that describe the location.</span><br><span style="color: hsl(120, 100%, 40%);">+Example: {{location_info = shape=Circle, pos="39.12345 -105.98766", radius=100}}</span><br><span style="color: hsl(120, 100%, 40%);">+See the [GML] page for more info.|</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+h2. Profile</span><br><span style="color: hsl(120, 100%, 40%);">+The Profile object defines how a location is used and is referenced by channel drivers.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+||Parameter||Required?||Uses Channel\\Variables?||Uses Sub\\Parameters?||Usage||</span><br><span style="color: hsl(120, 100%, 40%);">+|type|yes|no|no|Must be "profile"|</span><br><span style="color: hsl(120, 100%, 40%);">+|location_reference|no|no|no|Specifies the id of a Location object to use.|</span><br><span style="color: hsl(120, 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(120, 100%, 40%);">+|allow_use_for_routing|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(120, 100%, 40%);">+See [RFC6442|Geolocation Reference Information#rfc6442] for more information.|</span><br><span style="color: hsl(120, 100%, 40%);">+|action|no|no|no|Specifies what should be done with any incoming location descriptions received by a channel referencing this profile.\\</span><br><span style="color: hsl(120, 100%, 40%);">+* {{discard}}: Discard any incoming location descriptions and use only the location description specified by {{location_reference}} (if any).\\</span><br><span style="color: hsl(120, 100%, 40%);">+* {{append}}: Append any incoming location descriptions to the one specified by {{location_reference}} (if any).\\</span><br><span style="color: hsl(120, 100%, 40%);">+* {{prepend}}: Prepend any incoming location descriptions to the one specified by {{location_reference}} (if any).\\</span><br><span style="color: hsl(120, 100%, 40%);">+* {{replace}}: Replace the location description specified by {{location_reference}} (if any) with the ones received.\\</span><br><span style="color: hsl(120, 100%, 40%);">+*WARNING*: Using the {{append}} or {{prepend}} options can cause _multiple_ location objects to be sent to a recipient. [RFC5491|Geolocation Reference Information#rfc5491] discourages the use of multiple location objects but has rules that should be followed if it's necessary. Unfortunately, as is typical for RFCs, there are many "SHOULD"s and very few "MUST"s in the rules so you should read that RFC carefully before you allow multiple locations.|</span><br><span style="color: hsl(120, 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(120, 100%, 40%);">+* {{retransmission-allowed}}: Must be "yes" or "no". The default is "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. For example, to set the timestamp to 1 hour after the request is sent, use:</span><br><span style="color: hsl(120, 100%, 40%);">+{{retention-expires="$\{STRFTIME($[$\{EPOCH\}+3600],UTC,%FT%TZ)\}"}}\\</span><br><span style="color: hsl(120, 100%, 40%);">+See [RFC4119|Geolocation Reference Information#rfc4119] for the exact definition of this parameter.</span><br><span style="color: hsl(120, 100%, 40%);">+|</span><br><span style="color: hsl(120, 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(120, 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(120, 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%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+h1. chan_pjsip Configuration</span><br><span style="color: hsl(120, 100%, 40%);">+Two new parameters have been added to pjsip endpoints:</span><br><span style="color: hsl(120, 100%, 40%);">+||Parameter||Usage||</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.|</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.|</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+h1. Dialplan Applications and Functions</span><br><span style="color: hsl(120, 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%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+h2. GeolocProfileCreate</span><br><span style="color: hsl(120, 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%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+h2. GeolocProfileDelete</span><br><span style="color: hsl(120, 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%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+h2. GEOLOC_PROFILE</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.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+h1. Example Call Flows</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+h2. Simple Example 1</span><br><span style="color: hsl(120, 100%, 40%);">+Alice and Bob work in the same building so in geolocation.conf, we can define a location that describes the building and profiles for Bob and Alice that add floor and room. We're assuming here that Bob's and Alice's phones don't send any location information themselves.</span><br><span style="color: hsl(120, 100%, 40%);">+{code}</span><br><span style="color: hsl(120, 100%, 40%);">+[building1]</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%);">+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 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%);">+[alice]</span><br><span style="color: hsl(120, 100%, 40%);">+type = profile</span><br><span style="color: hsl(120, 100%, 40%);">+location_reference = building1</span><br><span style="color: hsl(120, 100%, 40%);">+location_refinement = FLR=4, ROOM=4B20</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+[bob]</span><br><span style="color: hsl(120, 100%, 40%);">+type = profile</span><br><span style="color: hsl(120, 100%, 40%);">+location_reference = building1</span><br><span style="color: hsl(120, 100%, 40%);">+location_refinement = FLR=32, ROOM=32A6</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%);">+In pjsip.conf, we can now associate those profiles to endpoints.</span><br><span style="color: hsl(120, 100%, 40%);">+{code}</span><br><span style="color: hsl(120, 100%, 40%);">+[bob]</span><br><span style="color: hsl(120, 100%, 40%);">+type = endpoint</span><br><span style="color: hsl(120, 100%, 40%);">+geoloc_incoming_call_profile = bob</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+[alice]</span><br><span style="color: hsl(120, 100%, 40%);">+type = endpoint</span><br><span style="color: hsl(120, 100%, 40%);">+geoloc_incoming_call_profile = alice</span><br><span style="color: hsl(120, 100%, 40%);">+{code}</span><br><span style="color: hsl(120, 100%, 40%);">+You'll notice that neither bob nor alice set {{geoloc_outgoing_call_profile}} because we never want to send location information _to_ them.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Now when Alice makes a call, Asterisk will construct an effective profile (including any defaults and variable substitutions) that looks like this...</span><br><span style="color: hsl(120, 100%, 40%);">+{code}</span><br><span style="color: hsl(120, 100%, 40%);">+format = civicAddress</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, RD=46th, STS=Street, PC=10222, FLR=4, ROOM=4B20</span><br><span style="color: hsl(120, 100%, 40%);">+method = Manual</span><br><span style="color: hsl(120, 100%, 40%);">+usage_rules = retransmission-allowed=no</span><br><span style="color: hsl(120, 100%, 40%);">+usage_rules = retention-expires="${STRFTIME($[${EPOCH}+86400],UTC,%FT%TZ)}"</span><br><span style="color: hsl(120, 100%, 40%);">+allow_routing = no</span><br><span style="color: hsl(120, 100%, 40%);">+pidf_element = device</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%);">+Bob's effective profile would be exactly the same except for {{FLR}} and {{ROOM}}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+This effective profile will then be forwarded to the dialplan. The dialplan application can then use GEOLOC_PROFILE to make changes before the effective profile is forwarded to the outgoing channel. It can also use GeolocProfileDelete to just delete the effective profile and pass nothing.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+{column}</span><br><span style="color: hsl(120, 100%, 40%);">+{column:width=30%}</span><br><span style="color: hsl(120, 100%, 40%);">+Table of Contents:</span><br><span style="color: hsl(120, 100%, 40%);">+{toc}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Geolocation:</span><br><span style="color: hsl(120, 100%, 40%);">+{pagetree:root=Geolocation|expandCollapseAll=true}</span><br><span style="color: hsl(120, 100%, 40%);">+{column}</span><br><span style="color: hsl(120, 100%, 40%);">+{section}</span><br><span>diff --git a/res/res_geolocation/wiki/CivicAddress.md b/res/res_geolocation/wiki/CivicAddress.md</span><br><span>new file mode 100644</span><br><span>index 0000000..f18c027</span><br><span>--- /dev/null</span><br><span>+++ b/res/res_geolocation/wiki/CivicAddress.md</span><br><span>@@ -0,0 +1,167 @@</span><br><span style="color: hsl(120, 100%, 40%);">+{section:border=false}</span><br><span style="color: hsl(120, 100%, 40%);">+{column:width=70%}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+h1. Introduction</span><br><span style="color: hsl(120, 100%, 40%);">+For static locations, using Civic Address location descriptions would be the easiest method. As stated earlier though, you and your partners must agree on which description formats are acceptable.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The following tables list the IANA registered element names that are currently accepted. The complete list of codes is defined in:</span><br><span style="color: hsl(120, 100%, 40%);">+[https://www.iana.org/assignments/civic-address-types-registry/civic-address-types-registry.xhtml]</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+These codes were originally defined in [RFC4119|Geolocation Reference Information#rfc4119] and [RFC4776|Geolocation Reference Information#rfc4776]</span><br><span style="color: hsl(120, 100%, 40%);">+|| Label || Description || Example |</span><br><span style="color: hsl(120, 100%, 40%);">+| country | The country is identified by the two-letter ISO 3166 code.|US|</span><br><span style="color: hsl(120, 100%, 40%);">+| A1 | national subdivisions (state, region, province, prefecture)|New York|</span><br><span style="color: hsl(120, 100%, 40%);">+| A2 | county, parish, gun (JP), district (IN)|King's County|</span><br><span style="color: hsl(120, 100%, 40%);">+| A3 | city, township, shi (JP)|New York|</span><br><span style="color: hsl(120, 100%, 40%);">+| A4 | city division, borough, city, district, ward, chou (JP)|Manhattan|</span><br><span style="color: hsl(120, 100%, 40%);">+| A5 | neighborhood, block | Morningside Heights |</span><br><span style="color: hsl(120, 100%, 40%);">+| A6 | street\\NOTE: This code has been deprecated in favor of {{RD}}, defined below. | Broadway |</span><br><span style="color: hsl(120, 100%, 40%);">+| PRD | Leading street direction| N, W |</span><br><span style="color: hsl(120, 100%, 40%);">+| POD | Trailing street direction| SW |</span><br><span style="color: hsl(120, 100%, 40%);">+| STS | Street suffix | Avenue, Platz, Street|</span><br><span style="color: hsl(120, 100%, 40%);">+| HNO | House number, numeric part only|123|</span><br><span style="color: hsl(120, 100%, 40%);">+| HNS | House number suffix | A, 1/2 |</span><br><span style="color: hsl(120, 100%, 40%);">+| LMK | Landmark or vanity address|Low Library |</span><br><span style="color: hsl(120, 100%, 40%);">+| LOC | Additional location information\\NOTE: {{ROOM}} was added below.| Room 543 |</span><br><span style="color: hsl(120, 100%, 40%);">+| FLR | Floor | 5 |</span><br><span style="color: hsl(120, 100%, 40%);">+| NAM | Name (residence, business or office occupant)|Joe's Barbershop |</span><br><span style="color: hsl(120, 100%, 40%);">+| PC | Postal code | 10027-0401 |</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+These codes were added in [RFC5139|Geolocation Reference Information#rfc5139]</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+|| Label || Description || Example |</span><br><span style="color: hsl(120, 100%, 40%);">+| BLD | Building (structure) | Hope Theatre |</span><br><span style="color: hsl(120, 100%, 40%);">+| UNIT | Unit (apartment, suite) | 12a |</span><br><span style="color: hsl(120, 100%, 40%);">+| ROOM | Room | 450F |</span><br><span style="color: hsl(120, 100%, 40%);">+| PLC | Place-type | office |</span><br><span style="color: hsl(120, 100%, 40%);">+| PCN | Postal community name | Leonia |</span><br><span style="color: hsl(120, 100%, 40%);">+| POBOX | Post office box (P.O. box) | U40 |</span><br><span style="color: hsl(120, 100%, 40%);">+| ADDCODE | Additional Code | 13203000003 |</span><br><span style="color: hsl(120, 100%, 40%);">+| SEAT | Seat (desk, cubicle, workstation) | WS 181 |</span><br><span style="color: hsl(120, 100%, 40%);">+| RD | Primary road or street | Broadway |</span><br><span style="color: hsl(120, 100%, 40%);">+| RDSEC | Road section | 14 |</span><br><span style="color: hsl(120, 100%, 40%);">+| RDBR | Road branch | Lane 7 |</span><br><span style="color: hsl(120, 100%, 40%);">+| RDSUBBR | Road sub-branch | Alley 8 |</span><br><span style="color: hsl(120, 100%, 40%);">+| PRM | Road pre-modifier | Old |</span><br><span style="color: hsl(120, 100%, 40%);">+| POM | Road post-modifier | Service |</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+These codes were added in [RFC6848|Geolocation Reference Information#rfc6848]</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+|| Label || Description || Example |</span><br><span style="color: hsl(120, 100%, 40%);">+|PN|Post number that is attributed to a lamp post or utility pole.|21344567|</span><br><span style="color: hsl(120, 100%, 40%);">+|MP|Milepost: a marker indicating distance to or from a place (often a town)</span><br><span style="color: hsl(120, 100%, 40%);">+May actually be expressed in "miles" or "kilometers".|237.4|</span><br><span style="color: hsl(120, 100%, 40%);">+|STP|Street Type Prefix.|Boulevard|</span><br><span style="color: hsl(120, 100%, 40%);">+|HNP|House Number Prefix.|Z|</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+h1. Example Configurations</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+h2. Simple Example 1</span><br><span style="color: hsl(120, 100%, 40%);">+In geolocation.conf, we can define a location that describes a building and profiles for Bob and Alice that add floor and room. We're assuming here that Bob's and Alice's phones don't send any location information themselves.</span><br><span style="color: hsl(120, 100%, 40%);">+{code}</span><br><span style="color: hsl(120, 100%, 40%);">+[building1]</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%);">+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 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%);">+[alice]</span><br><span style="color: hsl(120, 100%, 40%);">+type = profile</span><br><span style="color: hsl(120, 100%, 40%);">+location_reference = building1</span><br><span style="color: hsl(120, 100%, 40%);">+location_refinement = FLR=4, ROOM=4B20</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+[bob]</span><br><span style="color: hsl(120, 100%, 40%);">+type = profile</span><br><span style="color: hsl(120, 100%, 40%);">+location_reference = building1</span><br><span style="color: hsl(120, 100%, 40%);">+location_refinement = FLR=32, ROOM=32A6</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. PIDF-LO XML Examples</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Here's what Alice's PIDF-LO would look like:</span><br><span style="color: hsl(120, 100%, 40%);">+{code}</span><br><span style="color: hsl(120, 100%, 40%);">+<?xml version="1.0" encoding="UTF-8"?></span><br><span style="color: hsl(120, 100%, 40%);">+<presence entity="pres:alice@example.com"</span><br><span style="color: hsl(120, 100%, 40%);">+ xmlns="urn:ietf:params:xml:ns:pidf"</span><br><span style="color: hsl(120, 100%, 40%);">+ xmlns:ca="urn:ietf:params:xml:ns:pidf:geopriv10:civicAddr"</span><br><span style="color: hsl(120, 100%, 40%);">+ xmlns:dm="urn:ietf:params:xml:ns:pidf:data-model"</span><br><span style="color: hsl(120, 100%, 40%);">+ xmlns:gbp="urn:ietf:params:xml:ns:pidf:geopriv10:basicPolicy"</span><br><span style="color: hsl(120, 100%, 40%);">+ xmlns:gml="http://www.opengis.net/gml"</span><br><span style="color: hsl(120, 100%, 40%);">+ xmlns:gp="urn:ietf:params:xml:ns:pidf:geopriv10"</span><br><span style="color: hsl(120, 100%, 40%);">+ xmlns:gs="http://www.opengis.net/pidflo/1.0"></span><br><span style="color: hsl(120, 100%, 40%);">+ <dm:device></span><br><span style="color: hsl(120, 100%, 40%);">+ <gp:geopriv></span><br><span style="color: hsl(120, 100%, 40%);">+ <gp:location-info></span><br><span style="color: hsl(120, 100%, 40%);">+ <ca:civicAddress xml:lang="en-AU"></span><br><span style="color: hsl(120, 100%, 40%);">+ <ca:country>US</ca:country></span><br><span style="color: hsl(120, 100%, 40%);">+ <ca:A1>New York</ca:A1></span><br><span style="color: hsl(120, 100%, 40%);">+ <ca:A3>New York</ca:A3></span><br><span style="color: hsl(120, 100%, 40%);">+ <ca:HNO>1633</ca:HNO></span><br><span style="color: hsl(120, 100%, 40%);">+ <ca:PRD>W</ca:PRD></span><br><span style="color: hsl(120, 100%, 40%);">+ <ca:RD>46th</ca:RD></span><br><span style="color: hsl(120, 100%, 40%);">+ <ca:STS>Street</ca:STS></span><br><span style="color: hsl(120, 100%, 40%);">+ <ca:PC>10222</ca:PC></span><br><span style="color: hsl(120, 100%, 40%);">+ <ca:FLR>4</ca:FLR></span><br><span style="color: hsl(120, 100%, 40%);">+ <ca:ROOM>4B20</ca:ROOM></span><br><span style="color: hsl(120, 100%, 40%);">+ </ca:civicAddress></span><br><span style="color: hsl(120, 100%, 40%);">+ </gp:location-info></span><br><span style="color: hsl(120, 100%, 40%);">+ <gp:usage-rules></span><br><span style="color: hsl(120, 100%, 40%);">+ </gp:usage-rules></span><br><span style="color: hsl(120, 100%, 40%);">+ <gp:method>manual</gp:method></span><br><span style="color: hsl(120, 100%, 40%);">+ </gp:geopriv></span><br><span style="color: hsl(120, 100%, 40%);">+ <dm:deviceID>mac:1234567890ab</dm:deviceID></span><br><span style="color: hsl(120, 100%, 40%);">+ <dm:timestamp>2022-04-22T20:57:29Z</dm:timestamp></span><br><span style="color: hsl(120, 100%, 40%);">+ </dm:device></span><br><span style="color: hsl(120, 100%, 40%);">+</presence></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%);">+Here's what Bob's PIDF-LO would look like:</span><br><span style="color: hsl(120, 100%, 40%);">+{code}</span><br><span style="color: hsl(120, 100%, 40%);">+<?xml version="1.0" encoding="UTF-8"?></span><br><span style="color: hsl(120, 100%, 40%);">+<presence entity="pres:bob@example.com"</span><br><span style="color: hsl(120, 100%, 40%);">+ xmlns="urn:ietf:params:xml:ns:pidf"</span><br><span style="color: hsl(120, 100%, 40%);">+ xmlns:ca="urn:ietf:params:xml:ns:pidf:geopriv10:civicAddr"</span><br><span style="color: hsl(120, 100%, 40%);">+ xmlns:dm="urn:ietf:params:xml:ns:pidf:data-model"</span><br><span style="color: hsl(120, 100%, 40%);">+ xmlns:gbp="urn:ietf:params:xml:ns:pidf:geopriv10:basicPolicy"</span><br><span style="color: hsl(120, 100%, 40%);">+ xmlns:gml="http://www.opengis.net/gml"</span><br><span style="color: hsl(120, 100%, 40%);">+ xmlns:gp="urn:ietf:params:xml:ns:pidf:geopriv10"</span><br><span style="color: hsl(120, 100%, 40%);">+ xmlns:gs="http://www.opengis.net/pidflo/1.0"></span><br><span style="color: hsl(120, 100%, 40%);">+ <dm:device></span><br><span style="color: hsl(120, 100%, 40%);">+ <gp:geopriv></span><br><span style="color: hsl(120, 100%, 40%);">+ <gp:location-info></span><br><span style="color: hsl(120, 100%, 40%);">+ <ca:civicAddress xml:lang="en-AU"></span><br><span style="color: hsl(120, 100%, 40%);">+ <ca:country>US</ca:country></span><br><span style="color: hsl(120, 100%, 40%);">+ <ca:A1>New York</ca:A1></span><br><span style="color: hsl(120, 100%, 40%);">+ <ca:A3>New York</ca:A3></span><br><span style="color: hsl(120, 100%, 40%);">+ <ca:HNO>1633</ca:HNO></span><br><span style="color: hsl(120, 100%, 40%);">+ <ca:PRD>W</ca:PRD></span><br><span style="color: hsl(120, 100%, 40%);">+ <ca:RD>46th</ca:RD></span><br><span style="color: hsl(120, 100%, 40%);">+ <ca:STS>Street</ca:STS></span><br><span style="color: hsl(120, 100%, 40%);">+ <ca:PC>10222</ca:PC></span><br><span style="color: hsl(120, 100%, 40%);">+ <ca:FLR>32</ca:FLR></span><br><span style="color: hsl(120, 100%, 40%);">+ <ca:ROOM>32A6</ca:ROOM></span><br><span style="color: hsl(120, 100%, 40%);">+ </ca:civicAddress></span><br><span style="color: hsl(120, 100%, 40%);">+ </gp:location-info></span><br><span style="color: hsl(120, 100%, 40%);">+ <gp:usage-rules></span><br><span style="color: hsl(120, 100%, 40%);">+ </gp:usage-rules></span><br><span style="color: hsl(120, 100%, 40%);">+ <gp:method>manual</gp:method></span><br><span style="color: hsl(120, 100%, 40%);">+ </gp:geopriv></span><br><span style="color: hsl(120, 100%, 40%);">+ <dm:deviceID>mac:1234567890ab</dm:deviceID></span><br><span style="color: hsl(120, 100%, 40%);">+ <dm:timestamp>2022-04-22T20:57:29Z</dm:timestamp></span><br><span style="color: hsl(120, 100%, 40%);">+ </dm:device></span><br><span style="color: hsl(120, 100%, 40%);">+</presence></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%);">+Note that the only civicAddress difference between the two are the {{FLR}} and {{ROOM}}.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+{column}</span><br><span style="color: hsl(120, 100%, 40%);">+{column:width=30%}</span><br><span style="color: hsl(120, 100%, 40%);">+Table of Contents:</span><br><span style="color: hsl(120, 100%, 40%);">+{toc}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Geolocation:</span><br><span style="color: hsl(120, 100%, 40%);">+{pagetree:root=Geolocation|expandCollapseAll=true}</span><br><span style="color: hsl(120, 100%, 40%);">+{column}</span><br><span style="color: hsl(120, 100%, 40%);">+{section}</span><br><span>diff --git a/res/res_geolocation/wiki/GML.md b/res/res_geolocation/wiki/GML.md</span><br><span>new file mode 100644</span><br><span>index 0000000..394f1c2</span><br><span>--- /dev/null</span><br><span>+++ b/res/res_geolocation/wiki/GML.md</span><br><span>@@ -0,0 +1,60 @@</span><br><span style="color: hsl(120, 100%, 40%);">+{section:border=false}</span><br><span style="color: hsl(120, 100%, 40%);">+{column:width=70%}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+h1. Introduction</span><br><span style="color: hsl(120, 100%, 40%);">+All compliant participants are required to support GML as the description language but it's really only suitable for mobile devices. As stated earlier though, you and your partners must agree on which description formats are acceptable.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The language itself is fairly simple. There are 8 shapes that can be used to describe a location and they share a common set of attributes described below. Determining the actual values for those attributes though can be quite complex and is not covered here.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+h2. References:</span><br><span style="color: hsl(120, 100%, 40%);">+* [Open Geospatial Consortium Geography Markup Language|gml]</span><br><span style="color: hsl(120, 100%, 40%);">+* [GML 3.1.1 PIDF-LO Shape Application Schema|geoshape]</span><br><span style="color: hsl(120, 100%, 40%);">+* [Universal Geographical Area Description (GAD)|gad] (for background)</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+h2. Coordinate Reference Systems</span><br><span style="color: hsl(120, 100%, 40%);">+The coordinate reference system (crs) for a shape specifies whether the points that define a shape express a two dimensional or three dimensional point in space. It does NOT specify whether the shape itself is 2D or 3D. For instance, a Point is a one dimensional "shape" but it can be specified with just a latitude and longitude (2d) or latitude, longitude and altitude (3d). The `crs` is specified for each shape with the `crs` attribute whose value can be either `2d` or `3d`.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+h2. Units of Measure</span><br><span style="color: hsl(120, 100%, 40%);">+h3. 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 `posList` are the two attributes that specify position.</span><br><span style="color: hsl(120, 100%, 40%);">+h3. Distance</span><br><span style="color: hsl(120, 100%, 40%);">+Distance is _always_ specified in meters. `height`, `radius` and the altitude component of `pos` are some of the distance attributes.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+*A special note about altitude:* As of the date of this writing (May 2022) we couldn't find any mention in the RFCs concerning the altitude reference. Is it above:</span><br><span style="color: hsl(120, 100%, 40%);">+# Ground Level (AGL)</span><br><span style="color: hsl(120, 100%, 40%);">+# Mean Sea Level (MSL)</span><br><span style="color: hsl(120, 100%, 40%);">+# A Geoid reference (which one?)</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+h3. Angle</span><br><span style="color: hsl(120, 100%, 40%);">+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 style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+h2. Shapes</span><br><span style="color: hsl(120, 100%, 40%);">+h3. Point</span><br><span style="color: hsl(120, 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%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+|| Shape || Attributes || Description ||</span><br><span style="color: hsl(120, 100%, 40%);">+| Point | pos or pos3d | A single point |</span><br><span style="color: hsl(120, 100%, 40%);">+| Circle | pos or pos3d, radius | A two dimensional circle around a point |</span><br><span style="color: hsl(120, 100%, 40%);">+| Sphere | pos3d, radius | A 3 dimensional sphere around a point |</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+|| Attribute || Description || Units || Example ||</span><br><span style="color: hsl(120, 100%, 40%);">+| pos | A two dimensional point | Decimal degrees | pos="39.12345 -105.98766" |</span><br><span style="color: hsl(120, 100%, 40%);">+| pos3d | A three dimensional point | Decimal degrees + altitude in meters | pos="39.12345 -105.98766 1690" |</span><br><span style="color: hsl(120, 100%, 40%);">+| radius | Distance | Meters | radius="20" |</span><br><span style="color: hsl(120, 100%, 40%);">+| height | Distance | Meters | height="45" |</span><br><span style="color: hsl(120, 100%, 40%);">+| orientation | Angle | Degrees (default) or Radians | orientation="90", orientation="25 radians" |</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+{column}</span><br><span style="color: hsl(120, 100%, 40%);">+{column:width=30%}</span><br><span style="color: hsl(120, 100%, 40%);">+Table of Contents:</span><br><span style="color: hsl(120, 100%, 40%);">+{toc}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Geolocation:</span><br><span style="color: hsl(120, 100%, 40%);">+{pagetree:root=Geolocation|expandCollapseAll=true}</span><br><span style="color: hsl(120, 100%, 40%);">+{column}</span><br><span style="color: hsl(120, 100%, 40%);">+{section}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span>diff --git a/res/res_geolocation/wiki/Geolocation.md b/res/res_geolocation/wiki/Geolocation.md</span><br><span>new file mode 100644</span><br><span>index 0000000..8921978</span><br><span>--- /dev/null</span><br><span>+++ b/res/res_geolocation/wiki/Geolocation.md</span><br><span>@@ -0,0 +1,74 @@</span><br><span style="color: hsl(120, 100%, 40%);">+{section:border=false}</span><br><span style="color: hsl(120, 100%, 40%);">+{column:width=70%}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+{warning:title=Please Read!}</span><br><span style="color: hsl(120, 100%, 40%);">+Before you go off on a geolocation configuration spree, you'll need to understand a few things about Geolocation itself.</span><br><span style="color: hsl(120, 100%, 40%);">+* It's not a single specification.</span><br><span style="color: hsl(120, 100%, 40%);">+While a good part of the implementation is covered in RFCs, some of it is documented in the Geography Markup Language Specification, the 3GPP Technical Specifications, national organizations like the FCC and National Emergency Number Association in the US, and probably your interfacing carriers. The last is the most important as you don't want emergency calls dropped or routed to incorrect emergency service centers because of a configuration incompatibility.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+* It's been around a while.</span><br><span style="color: hsl(120, 100%, 40%);">+The first references I could find date back to 2002. Since then there have been innumerable changes including IETF drafts that expired 15 years ago that are still being returned by Google searches.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+With that in mind, please do your own research and coordinate closely with your partners to validate your configuration.</span><br><span style="color: hsl(120, 100%, 40%);">+{warning}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+h1. Introduction</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+As it applies to Asterisk, Geolocation is the process of...</span><br><span style="color: hsl(120, 100%, 40%);">+* A channel driver accepting location information in an incoming SIP INVITE, either by reference or by value, then using a geolocation profile to determine the disposition of that information and/or possibly add or delete information.</span><br><span style="color: hsl(120, 100%, 40%);">+* Passing the resulting information (if any) to the dialplan which can also determine the disposition of that information and/or possibly add or delete information.</span><br><span style="color: hsl(120, 100%, 40%);">+* Passing the information from the dialplan to the outgoing channel driver which can also use a geolocation profile to determine the disposition of that information and/or possibly add or delete information.</span><br><span style="color: hsl(120, 100%, 40%);">+* Finally sending the information to another party, either by reference or by value.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+h1. What's a "location"?</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+h2. Describing a Location</span><br><span style="color: hsl(120, 100%, 40%);">+There are currently two ways to describe a location.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+h3. Geography Markup Language (GML)</span><br><span style="color: hsl(120, 100%, 40%);">+GML allows you to express a location in terms of shapes, coordinates, lengths, angles, etc. For example, a Point with a latitude, longitude and altitude, or a Sphere with a latitude, longitude, altitude and radius. Other shapes include, Circle, Polygon, Ellipse, Ellipsoid, and Prism. See [GeoShape|Geolocation Reference Information#geoshape].</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+GML would most often be used by mobile systems where the originator's location is determined dynamically such as base station, sector antenna, distance, etc. According to [RFC4119|Geolocation Reference Information#rfc4119] GML is considered to be the "baseline" format and MUST be supported by all implementations. The _level_ of support is not well defined however. For instance, a specific implementation may only support a subset of shapes.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+h3. Civic Address</span><br><span style="color: hsl(120, 100%, 40%);">+For fixed locations, Civic Address is probably the most used location description method. It's described with terms like Country, State/Province, City, Neighborhood, Street, House Number, Floor, Room, etc. Oddly enough, support for Civic Address is NOT required by [RFC4119|Geolocation Reference Information#rfc4119].</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Both methods are expressed in XML but which location description method you use is entirely between you and your partners.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+h3. Encapsulation</span><br><span style="color: hsl(120, 100%, 40%);">+The IETF chose the "Presence Information Data Format" (PIDF) as the wrapper document for location information which can be placed in {{<tuple>}}, {{<device>}}, or {{<person>}} sub-elements. BTW, this is the same PIDF used to convey SIP subscription information but Asterisk is only supporting PIDF-LO in INVITE requests at this time.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The specification allows multiple locations in each element, multiple elements in a single PIDF-LO document, _and_ multiple PIDF-LO documents in a single request. Dealing with multiple locations however is such an extraordinarily complex process that it's not support by Asterisk at this time. Please read the reference information for the applicable rules. [RFC5491|Geolocation Reference Information#rfc5491] is a good starting point.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+h2. Conveying a Location via SIP</span><br><span style="color: hsl(120, 100%, 40%);">+There are currently two ways to convey a location description regardless of which description method you use. Both use the {{Geolocation}} SIP message header to indicate where to get the location description document.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+h3. By Reference</span><br><span style="color: hsl(120, 100%, 40%);">+This one's simple. The "reference" is actually URI that the recipient can access that will return an XML document containing the description. "http" and "https" are the most common URI schemes but there are others. See [RFC6442|Geolocation Reference Information#rfc6442] above. An example {{Geolocation}} header might look like: {{Geolocation: <https://geoloc.example.com?location=some_location_reference>}}.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+With this method, you are entirely responsible for retrieving location descriptions from URIs you receive and for serving location descriptions for URIs you send. Asterisk does not attempt to retrieve any information from those URIs.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+When sending information to an upstream carrier, it's possible they may give _you_ special URIs to place in Geolocation headers you send them.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+h3. By Value</span><br><span style="color: hsl(120, 100%, 40%);">+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 style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+h3. Multiple URIs</span><br><span style="color: hsl(120, 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%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+h3. Geolocation-Routing</span><br><span style="color: hsl(120, 100%, 40%);">+[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 style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Some carriers ignore this header altogether.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+{column}</span><br><span style="color: hsl(120, 100%, 40%);">+{column:width=30%}</span><br><span style="color: hsl(120, 100%, 40%);">+Table of Contents:</span><br><span style="color: hsl(120, 100%, 40%);">+{toc}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Geolocation:</span><br><span style="color: hsl(120, 100%, 40%);">+{pagetree:root=Geolocation|expandCollapseAll=true}</span><br><span style="color: hsl(120, 100%, 40%);">+{column}</span><br><span style="color: hsl(120, 100%, 40%);">+{section}</span><br><span>diff --git a/res/res_geolocation/wiki/ReferenceInformation.md b/res/res_geolocation/wiki/ReferenceInformation.md</span><br><span>new file mode 100644</span><br><span>index 0000000..b949aaf</span><br><span>--- /dev/null</span><br><span>+++ b/res/res_geolocation/wiki/ReferenceInformation.md</span><br><span>@@ -0,0 +1,33 @@</span><br><span style="color: hsl(120, 100%, 40%);">+{section:border=false}</span><br><span style="color: hsl(120, 100%, 40%);">+{column:width=70%}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+There is no single document that has the complete, current specification so please follow and read any "updated by" references in these documents.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+|| RFC || Title ||</span><br><span style="color: hsl(120, 100%, 40%);">+|[RFC3693|https://www.rfc-editor.org/rfc/rfc3693]|Geopriv Requirements|</span><br><span style="color: hsl(120, 100%, 40%);">+|[RFC4119|https://www.rfc-editor.org/rfc/rfc4119]|A Presence-based GEOPRIV Location Object Format|</span><br><span style="color: hsl(120, 100%, 40%);">+|[RFC5139|https://www.rfc-editor.org/rfc/rfc5139]|Revised Civic Location Format for\\Presence Information Data Format Location Object (PIDF-LO)|</span><br><span style="color: hsl(120, 100%, 40%);">+|{anchor:rfc5491} [RFC5491|https://www.rfc-editor.org/rfc/rfc5491]|GEOPRIV Presence Information Data Format\\Location Object (PIDF-LO) Usage Clarification, Considerations, and Recommendations|</span><br><span style="color: hsl(120, 100%, 40%);">+|[RFC5808|https://www.rfc-editor.org/rfc/rfc5808]|Requirements for a Location-by-Reference Mechanism|</span><br><span style="color: hsl(120, 100%, 40%);">+|[RFC6280|https://www.rfc-editor.org/rfc/rfc6280]|An Architecture for Location and Location\\Privacy in Internet Applications|</span><br><span style="color: hsl(120, 100%, 40%);">+|{anchor:rfc6442} [RFC6442|https://www.rfc-editor.org/rfc/rfc6442]|Location Conveyance for the Session Initiation Protocol|</span><br><span style="color: hsl(120, 100%, 40%);">+|[RFC6848|https://www.rfc-editor.org/rfc/rfc6848]|Specifying Civic Address Extensions in the\\Presence Information Data Format Location Object (PIDF-LO)|</span><br><span style="color: hsl(120, 100%, 40%);">+|[RFC7459|https://www.rfc-editor.org/rfc/rfc7459]|Representation of Uncertainty and Confidence\\in the Presence Information Data Format Location Object (PIDF-LO)|</span><br><span style="color: hsl(120, 100%, 40%);">+|[RFC8787|https://www.rfc-editor.org/rfc/rfc8787]|Location Source Parameter for the SIP Geolocation Header Field|</span><br><span style="color: hsl(120, 100%, 40%);">+|{anchor:gml} [OGC GML|https://www.ogc.org/standards/gml]|Open Geospatial Consortium Geography Markup Language|</span><br><span style="color: hsl(120, 100%, 40%);">+|{anchor:geoshape} [GeoShape|https://portal.ogc.org/files/?artifact_id=21630#:~:text=This%20GML%203.1.,uses%20the%20separately%20specified%20geoshape]|GML 3.1.1 PIDF-LO Shape Application Schema\\for use by the Internet Engineering Task Force (IETF)|</span><br><span style="color: hsl(120, 100%, 40%);">+|{anchor:gad} [3GPP TS 23.032|https://www.3gpp.org/ftp/Specs/archive/23_series/23.032/]|3GPP Technical Specification: Universal Geographical Area Description (GAD)\\Use version [23.032-h20|https://www.3gpp.org/ftp/Specs/archive/23_series/23.032/23032-h20.zip]\\This document is NOT specific to Geopriv so use with caution|</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+{column}</span><br><span style="color: hsl(120, 100%, 40%);">+{column:width=30%}</span><br><span style="color: hsl(120, 100%, 40%);">+Table of Contents:</span><br><span style="color: hsl(120, 100%, 40%);">+{toc}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Geolocation:</span><br><span style="color: hsl(120, 100%, 40%);">+{pagetree:root=Geolocation|expandCollapseAll=true}</span><br><span style="color: hsl(120, 100%, 40%);">+{column}</span><br><span style="color: hsl(120, 100%, 40%);">+{section}</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>new file mode 100644</span><br><span>index 0000000..91d832f</span><br><span>--- /dev/null</span><br><span>+++ b/res/res_geolocation/wiki/URI.md</span><br><span>@@ -0,0 +1,86 @@</span><br><span style="color: hsl(120, 100%, 40%);">+{section:border=false}</span><br><span style="color: hsl(120, 100%, 40%);">+{column:width=70%}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+h1. Introduction</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+As mentioned in other pages, Geolocation descriptions can be passed "by-value" using a GML or Civic Address XML document, or "by-reference" using a URI. This page discusses the latter.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+h1. Concepts</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+h2. Outgoing Calls</span><br><span style="color: hsl(120, 100%, 40%);">+Passing location descriptions using URIs is fairly simple from an Asterisk perspective. It does however, require the implementer to establish and maintain infrastructure to handle the serving of those URIs. Given the critical nature of the information, setting up such infrastructure is not trivial and is beyond the scope of Asterisk and this documentation.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+h2. Incoming calls</span><br><span style="color: hsl(120, 100%, 40%);">+On incoming calls, Asterisk will make any "pass-by-reference" URIs available to the dialplan via the {{GEOLOC_PROFILE}} function but will NOT attempt to retrieve any documents from that URI. It's the dialplan author's responsibility to retrieve, interpret and process such documents.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+h1. Example 1</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Let's say that every extension in your organization has a public DID associated with it, you have a database that cross references DIDs and office locations, and you have a web server that can be queried with a "GET" request and an "DID" query parameter ({{https://my.company.com/location_query?DID=<did>}}) to get the DID's location. When someone in your organization dials 911, you want a link sent in the outgoing SIP INVITE that the recipient can call to get the caller's location.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+In geolocation.conf, you'd create Location and Profile objects as follows:</span><br><span style="color: hsl(120, 100%, 40%);">+{code}</span><br><span style="color: hsl(120, 100%, 40%);">+[did-xref]</span><br><span style="color: hsl(120, 100%, 40%);">+type = location</span><br><span style="color: hsl(120, 100%, 40%);">+format = URI</span><br><span style="color: hsl(120, 100%, 40%);">+location = URI='https://my.company.com/location_query?DID=${CALLERID(num)}'</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+[employees-outbound]</span><br><span style="color: hsl(120, 100%, 40%);">+type = profile</span><br><span style="color: hsl(120, 100%, 40%);">+location_reference = did-xref</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%);">+In pjsip.conf, you'd add a {{geoloc_outgoing_call_profile}} parameter to your _outgoing_ endpoint definition:</span><br><span style="color: hsl(120, 100%, 40%);">+{code}</span><br><span style="color: hsl(120, 100%, 40%);">+[my-provider]</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_outgoing_call_profile = employees-outbound</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%);">+Now let's say that Bob has DID {{12125551212}} assigned to him and he makes an outgoing call which is routed to "my-provider". Asterisk would automatically add the following header to the INVITE:</span><br><span style="color: hsl(120, 100%, 40%);">+{code}</span><br><span style="color: hsl(120, 100%, 40%);">+Geolocation: <https://my.company.com/location_query?DID=12125551212></span><br><span style="color: hsl(120, 100%, 40%);">+{code}</span><br><span style="color: hsl(120, 100%, 40%);">+The recipient could then make a simply query using that URI and get Bob's location in whatever format was agreed upon with you and them.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Of course, this is a _very_ simple example that would add the Geolocation header to _all_ calls made via "my-provider". If you only routed emergency calls to "my-provider" this would work fine but you probably don't want to leak location information on non-emergency calls.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+h1. Example 2</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+In this example, we'll use the dialplan apps and functions to decide if we want to send location information to the recipient or not. In fact, we're not going to use geolocation.conf at all.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+In extensions.conf:</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%);">+; The pre dial handler adds a new profile with a URI location to</span><br><span style="color: hsl(120, 100%, 40%);">+; the outgoing channel when 911 is dialed and does nothing if another number is dialed.</span><br><span style="color: hsl(120, 100%, 40%);">+[pre-dial-handler]</span><br><span style="color: hsl(120, 100%, 40%);">+exten = 911,1,NoOp(Entering PDH for Outgoing Channel)</span><br><span style="color: hsl(120, 100%, 40%);">+same = n,GeolocProfileCreate(geoloc.example@myserver.com)</span><br><span style="color: hsl(120, 100%, 40%);">+same = n,Set(GEOLOC_PROFILE(format,0)=URI)</span><br><span style="color: hsl(120, 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,Return(0)</span><br><span style="color: hsl(120, 100%, 40%);">+exten = _X.,1,Return(0)</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+[default]</span><br><span style="color: hsl(120, 100%, 40%);">+exten = _X.,1,NoOp(Outgoing call)</span><br><span style="color: hsl(120, 100%, 40%);">+; 'b' will run the pre-dial-handler on the outgoing channel.</span><br><span style="color: hsl(120, 100%, 40%);">+same = n,Dial(PJSIP/${EXTEN},5,b(pre-dial-handler))</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%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+{column}</span><br><span style="color: hsl(120, 100%, 40%);">+{column:width=30%}</span><br><span style="color: hsl(120, 100%, 40%);">+Table of Contents:</span><br><span style="color: hsl(120, 100%, 40%);">+{toc}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Geolocation:</span><br><span style="color: hsl(120, 100%, 40%);">+{pagetree:root=Geolocation|expandCollapseAll=true}</span><br><span style="color: hsl(120, 100%, 40%);">+{column}</span><br><span style="color: hsl(120, 100%, 40%);">+{section}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span></span><br></pre><p>To view, visit <a href="https://gerrit.asterisk.org/c/asterisk/+/19194">change 19194</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/+/19194"/><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: I68ba22db0a69d9e2eabcc2141b48a2395f7f1a23 </div>
<div style="display:none"> Gerrit-Change-Number: 19194 </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: Friendly Automation </div>
<div style="display:none"> Gerrit-Reviewer: George Joseph <gjoseph@digium.com> </div>
<div style="display:none"> Gerrit-MessageType: merged </div>