[Asterisk-code-review] res_geolocation: Add initial markdown for Geolocation wiki pages (asterisk[development/16/geolocation])
George Joseph
asteriskteam at digium.com
Fri Apr 1 09:29:56 CDT 2022
George Joseph has uploaded this change for review. ( https://gerrit.asterisk.org/c/asterisk/+/18360 )
Change subject: res_geolocation: Add initial markdown for Geolocation wiki pages
......................................................................
res_geolocation: Add initial markdown for Geolocation wiki pages
This is incomplete but I wanted to get them into Gerrit
since I'm going to be offline for a bit.
Change-Id: I85b239776209bff3fc3388cf9b0a322a1764db29
---
A res/res_geolocation/wiki/AsteriskImplementation.md
A res/res_geolocation/wiki/CivicAddress.md
A res/res_geolocation/wiki/GML.md
A res/res_geolocation/wiki/Geolocation.md
A res/res_geolocation/wiki/LocationConcepts.md
A res/res_geolocation/wiki/URI.md
6 files changed, 280 insertions(+), 0 deletions(-)
git pull ssh://gerrit.asterisk.org:29418/asterisk refs/changes/60/18360/1
diff --git a/res/res_geolocation/wiki/AsteriskImplementation.md b/res/res_geolocation/wiki/AsteriskImplementation.md
new file mode 100644
index 0000000..6c6a2b3
--- /dev/null
+++ b/res/res_geolocation/wiki/AsteriskImplementation.md
@@ -0,0 +1,153 @@
+{toc}
+
+h1. Core Configuration
+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.
+
+h2. Common Behavior
+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.
+{code}
+location_info = shape=Circle, pos="39.12345 -105.98766", radius=100
+{code}
+You must double quote sub-parameter values with spaces in them and spaces around the ","s or "="s are ignored.
+
+For readability, parameters that use sub-parameters can be split over more than one line. For example:
+{code}
+location_info = country=US,A1="New York",A3="New York"
+location_info = house_number=1633,PRD=W,street=46th,
+location_info = street_suffix = Street,postal_code=10222
+{code}
+would be equivalent to:
+{code}
+location_info = country=US,A1="New York",A3="New York",house_number=1633,PRD=W,street=46th,street_suffix = Street,postal_code=10222
+{code}
+
+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:
+{code}
+location_info = URI=http://some.example.com?key=${EXTEN}
+{code}
+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".
+
+h2. Location
+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.
+||Parameter||Required?||Uses Channel\\Variables?||Uses Sub\\Parameters?||Usage||
+|type|yes|no|no|Must be "location"|
+|format|yes|no|no|"civicAddress", "GML" or "URI" to indicate how the location is expressed.|
+|method|no|no|no|If provided, it MUST be one of "GPS", "A-GPS", "Manual", "DHCP", "Triangulation", "Cell", "802.11"|
+|location_source|no|no|no|If provided, it MUST be a fully qualified domain name. IP addresses are specifically not allowed.
+See [RFC8787|Geolocation#rfc8787] for the exact definition of this parameter.|
+|confidence|no|no|yes|Sub-parameters:
+* {{value}}: A percentage indicating the confidence or "unknown".
+* {{pdf}}: "unknown", "normal" or "rectangular"
+Example: {{confidence = value=80, pdf=unknown}}
+If no {{confidence}} parameter is specified, the default is 95%.
+See [RFC7459|Geolocation#rfc7459] for the exact definition of this parameter.|
+|location_info|yes|yes|yes|The sub-parameters of location_info are dependent on the location's format:
+* URI: A single {{URI}} sub-parameter with the URI.
+Example: {{location_info = URI=http://some.example.com}}
+\\
+* civicAddress: A set of sub-parameters that describe the location.
+Example: {{location_info = country=US,A1="New York",A3="New York",house_number=1633,PRD=W,street=46th,street_suffix = Street,postal_code=10222}}
+See the [Civic Address] page for more info.
+\\
+* GML: A set of sub-parameters that describe the location.
+Example: {{location_info = shape=Circle, pos="39.12345 -105.98766", radius=100}}
+See the [GML] page for more info.
+|
+
+h2. Profile
+The Profile object defines how a location is used and is referenced by channel drivers.
+
+||Parameter||Required?||Uses Channel\\Variables?||Uses Sub\\Parameters?||Usage||
+|type|yes|no|no|Must be "profile"|
+|location_reference|no|no|no|Specifies the id of a Location object to use.|
+|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".|
+|allow_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".
+See [RFC6442|Geolocation#rfc6442] for more informatrion.|
+|action|no|no|no|Specifies what should be done with any incoming location descriptions received by a channel referencing this profile.\\
+* {{discard}}: Discard any incoming location descriptions and use only the location description specified by {{location_reference}} (if any).\\
+* {{append}}: Append any incoming location descriptions to the one specified by {{location_reference}} (if any).\\
+* {{prepend}}: Prepend any incoming location descriptions to the one specified by {{location_reference}} (if any).\\
+* {{replace}}: Replace the location description specified by {{location_reference}} (if any) with the ones received.\\
+*WARNING*: Using the {{append}} or {{prepend}} options can cause _multiple_ location objects to be sent to a recipient. [RFC5491|Geolocation#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.
+|
+|usage_rules|no|yes|yes|For Civic Address and GML location formats, this parameter specifies the contents of the {{usage-rules}} PIDF-LO element.\\
+* {{retransmission-allowed}}: Must be "yes" or "no". The default is "no".\\
+* {{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:
+{{retention-expires="$\{STRFTIME($[$\{EPOCH\}+3600],UTC,%FT%TZ)\}"}}\\
+See [RFC4119|Geolocation#rfc4119] for the exact definition of this parameter.
+|
+|location_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.
+|location_variables|no|yes|yes|Any parameter than can use channel variables can also 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 pof those parameters|
+|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.
+
+h1. chan_pjsip Configuration
+Two new parameters have been added to pjsip endpoints:
+||Parameter||Usage||
+|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.|
+|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.|
+
+h1. Dialplan Functions
+Two new dialplan applications and one dialplan function have been adedd to allow a dialplan author to manipulate
+
+h2. GeolocProfileCreate
+
+h2. GeolocProfileDelete
+
+h2. GEOLOC_PROFILE
+
+h1. Call Flow
+
+h2. Simple Example 1
+Alice and Bob work in the same building so in geolocation.conf, we can define a location that descibes 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.
+{code}
+[building1]
+type = location
+format = civicAddress
+location_info = country=US, A1="New York", A3="New York",
+location_info = HNO=1633, PRD=W, RD=46th, STS=Street, PC=10222
+method = Manual
+
+[alice]
+type = profile
+location_reference = building1
+location_refinement = FLR=4, ROOM=4B20
+
+[bob]
+type = profile
+location_reference = building1
+location_refinement = FLR=32, ROOM=32A6
+{code}
+
+In pjsip.conf, we can now associate those profiles to endpoints.
+{code}
+[bob]
+type = endpoint
+geoloc_incoming_call_profile = bob
+
+[alice]
+type = endpoint
+geoloc_incoming_call_profile = alice
+{code}
+You'll notice that neither bob nor alice set {{geoloc_outging_call_profile}} because we never want to send location information _to_ them.
+
+Now when Alice makes a call, Asterisk will construct an effective profile (including any defaults and variable substitutions) that looks like this..
+{code}
+format = civicAddress
+location_info = country=US, A1="New York", A3="New York",
+location_info = HNO=1633, RD=46th, STS=Street, PC=10222, FLR=4, ROOM=4B20
+method = Manual
+usage_rules = retransmission-allowed=no, retention-expires="${STRFTIME($[${EPOCH}+86400],UTC,%FT%TZ)}"
+allow_routing = no
+pidf_element = device
+{code}
+
+Bob's effective profile would exactly the same except for {{FLR}} and {{ROOM}}
+
+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.
+
+
+
+
+
+
+
diff --git a/res/res_geolocation/wiki/CivicAddress.md b/res/res_geolocation/wiki/CivicAddress.md
new file mode 100644
index 0000000..84680bb
--- /dev/null
+++ b/res/res_geolocation/wiki/CivicAddress.md
@@ -0,0 +1,78 @@
+{toc}
+
+h1. Civic Address Codes
+The following tables list the IANA registered element names that are
+currently accepted. The complete list of codes is defined in:
+[https://www.iana.org/assignments/civic-address-types-registry/civic-address-types-registry.xhtml]
+
+These codes were originally defined in [RFC4119|Geolocation#rfc4119] and [RFC4776|Geolocation#rfc4776]
+|| Label || Description || Example |
+| country | The country is identified by the two-letter ISO 3166 code.|US|
+| A1 | national subdivisions (state, region, province, prefecture)|New York|
+| A2 | county, parish, gun (JP), district (IN)|King's County|
+| A3 | city, township, shi (JP)|New York|
+| A4 | city division, borough, city, district, ward, chou (JP)|Manhattan|
+| A5 | neighborhood, block | Morningside Heights |
+| A6 | street\\NOTE: This code has been deprecated in favor of {{RD}}, defined below. | Broadway |
+| PRD | Leading street direction| N, W |
+| POD | Trailing street direction| SW |
+| STS | Street suffix | Avenue, Platz, Street|
+| HNO | House number, numeric part only|123|
+| HNS | House number suffix | A, 1/2 |
+| LMK | Landmark or vanity address|Low Library |
+| LOC | Additional location information\\NOTE: {{ROOM}} was added below.| Room 543 |
+| FLR | Floor | 5 |
+| NAM | Name (residence, business or office occupant)|Joe's Barbershop |
+| PC | Postal code | 10027-0401 |
+
+These codes were added in [RFC5139|Geolocation#rfc5139]
+
+|| Label || Description || Example |
+| BLD | Building (structure) | Hope Theatre |
+| UNIT | Unit (apartment, suite) | 12a |
+| ROOM | Room | 450F |
+| PLC | Place-type | office |
+| PCN | Postal community name | Leonia |
+| POBOX | Post office box (P.O. box) | U40 |
+| ADDCODE | Additional Code | 13203000003 |
+| SEAT | Seat (desk, cubicle, workstation) | WS 181 |
+| RD | Primary road or street | Broadway |
+| RDSEC | Road section | 14 |
+| RDBR | Road branch | Lane 7 |
+| RDSUBBR | Road sub-branch | Alley 8 |
+| PRM | Road pre-modifier | Old |
+| POM | Road post-modifier | Service |
+
+These codes were added in [RFC6848|Geolocation#rfc6848]
+
+|| Label || Description || Example |
+|PN|Post number that is attributed to a lamp post or utility pole.|21344567|
+|MP|Milepost: a marker indicating distance to or from a place (often a town)
+May actually be expressed in "miles" or "kilometers".|237.4|
+|STP|Street Type Prefix.|Boulevard|
+|HNP|House Number Prefix.|Z|
+
+h1. Example Configurations
+
+h2. Simple Example 1
+In geolocation.conf, we can define a location that descibes 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.
+{code}
+[building1]
+type = location
+format = civicAddress
+location_info = country=US, A1="New York", A3="New York",
+location_info = HNO=1633, PRD=W, RD=46th, STS=Street, PC=10222
+method = Manual
+
+[alice]
+type = profile
+location_reference = building1
+location_refinement = FLR=4, ROOM=4B20
+
+[bob]
+type = profile
+location_reference = building1
+location_refinement = FLR=32, ROOM=32A6
+{code}
+
+h1. PIDF-LO XML Examples
\ No newline at end of file
diff --git a/res/res_geolocation/wiki/GML.md b/res/res_geolocation/wiki/GML.md
new file mode 100644
index 0000000..e69de29
--- /dev/null
+++ b/res/res_geolocation/wiki/GML.md
diff --git a/res/res_geolocation/wiki/Geolocation.md b/res/res_geolocation/wiki/Geolocation.md
new file mode 100644
index 0000000..7674dd2
--- /dev/null
+++ b/res/res_geolocation/wiki/Geolocation.md
@@ -0,0 +1,19 @@
+
+The Geolocation capabilities are inplmented in Asterisk with the res_geolocation and res_pjsip_geolocation modules
+and the geolocation.conf configuration file. Geolocation isn't a trivial concept however so before reading further, please familiarize yourself with the following documents:
+
+|| RFC || Title ||
+|[RFC3693|https://www.rfc-editor.org/rfc/rfc3693]|Geopriv Requirements|
+|[RFC4119|https://www.rfc-editor.org/rfc/rfc4119]|A Presence-based GEOPRIV Location Object Format|
+|[RFC5139|https://www.rfc-editor.org/rfc/rfc5139]|Revised Civic Location Format for\\Presence Information Data Format Location Object (PIDF-LO)|
+|{anchor:rfc5491}[RFC5491|https://www.rfc-editor.org/rfc/rfc5491]|GEOPRIV Presence Information Data Format\\Location Object (PIDF-LO) Usage Clarification, Considerations, and Recommendations|
+|[RFC5808|https://www.rfc-editor.org/rfc/rfc5808]|Requirements for a Location-by-Reference Mechanism|
+|[RFC6280|https://www.rfc-editor.org/rfc/rfc6280]|An Architecture for Location and Location\\Privacy in Internet Applications|
+|{anchor:rfc6442}[RFC6442|https://www.rfc-editor.org/rfc/rfc6442]|Location Conveyance for the Session Initiation Protocol|
+|[RFC6848|https://www.rfc-editor.org/rfc/rfc6848]|Specifying Civic Address Extensions in the\\Presence Information Data Format Location Object (PIDF-LO)|
+|[RFC7459|https://www.rfc-editor.org/rfc/rfc7459]|Representation of Uncertainty and Confidence\\in the Presence Information Data Format Location Object (PIDF-LO)|
+|[RFC8787|https://www.rfc-editor.org/rfc/rfc8787]|Location Source Parameter for the SIP Geolocation Header Field|
+|[OGC GML|https://www.ogc.org/standards/gml]|Open Geospatial Consortium Geography Markup Language|
+|{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)|
+
+There is no single document that has the complete, current specification so please follow and read any "updated by" references in these documents.
diff --git a/res/res_geolocation/wiki/LocationConcepts.md b/res/res_geolocation/wiki/LocationConcepts.md
new file mode 100644
index 0000000..cf2714d
--- /dev/null
+++ b/res/res_geolocation/wiki/LocationConcepts.md
@@ -0,0 +1,30 @@
+h2. Describing a Location
+There are currently two ways to describe a location.
+h3. Geography Markup Language (GML)
+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#geoshape] above.
+
+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#rfc4119] GML is considered to be the "baseline" format and MUST be supported by all implementations.
+
+h3. Civic Address
+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. Support for Civic Address is NOT required by [RFC4119|Geolocation#rfc4119].
+
+Both methods are expressed in XML but which location description method you use is entirely between you and your partners.
+
+h3. PIDF-LO
+The IETF chose the "Presence Information Data Format" (PIDF) as the wrapper document for location information and can be placed in {{<tuple>}}, {{<device>}}, or {{<person>}} elements. The specification allows multiple locatons in each element and also allows multiple elements in a single PIDF-LO document. Dealing with multiple locations however is an extraordinarily complex process and should be avoided when possible. Please read the reference information for the applicable rules. [RFC5491|Geolocation#rfc5491] is a good starting point.
+
+h2. Conveying a Location via SIP
+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.
+
+h3. By Reference
+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#rfc6442] above. An example {{Geolocation}} header might look like: {{Geolocation: <https://geoloc.example.com?location=some_location_reference>}}. More on {{location=some_location_reference}} later.
+With this method, you are entirely responsible for retrieving location descriptions from URIs you receive and for serving location descriptions for URIs you send.
+
+h3. By Value
+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#rfc6442] and [RFC5491|Geolocation#rfc5491] above. An example {{Geolocation}} header might look like: {{Geolocation: <cid:gyytfr at 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.
+
+h3. Multiple URIs
+The {{Geolocation}} header can contain multiple URIs and they can be a mix of "by-reference" and "by-value".
+
+h3. Geolocation-Routing
+[RFC6442|Geolocation#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.
diff --git a/res/res_geolocation/wiki/URI.md b/res/res_geolocation/wiki/URI.md
new file mode 100644
index 0000000..e69de29
--- /dev/null
+++ b/res/res_geolocation/wiki/URI.md
--
To view, visit https://gerrit.asterisk.org/c/asterisk/+/18360
To unsubscribe, or for help writing mail filters, visit https://gerrit.asterisk.org/settings
Gerrit-Project: asterisk
Gerrit-Branch: development/16/geolocation
Gerrit-Change-Id: I85b239776209bff3fc3388cf9b0a322a1764db29
Gerrit-Change-Number: 18360
Gerrit-PatchSet: 1
Gerrit-Owner: George Joseph <gjoseph at digium.com>
Gerrit-MessageType: newchange
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.digium.com/pipermail/asterisk-code-review/attachments/20220401/54b3879b/attachment-0001.html>
More information about the asterisk-code-review
mailing list