Commit dd462c67 authored by Frédéric Dalleau's avatar Frédéric Dalleau

Geolocation: describe routing preferences

Define routing preferences that influences navigation routing.
Those are vehicle to select a subset of routing parameters suitable for
a vehicle and type to optimize some characteristics of generated routes.

Apertis: https://phabricator.apertis.org/T3027Reviewed-by: default avatarPhilip Withnall <philip.withnall@collabora.co.uk>
Signed-off-by: default avatarFrédéric Dalleau <frederic.dalleau@collabora.com>
Differential Revision: https://phabricator.apertis.org/D4857
parent b23c1e78
......@@ -593,6 +593,10 @@ address or as a city.
It must support systems where no navigation application is installed,
returning an error code to the caller.
It must provide a way to request navigation routing suitable for walking or
cycling, so that the driver knows how to reach a point of interest after they
leave the vehicle.
See [](#navigating-to-a-location),
[](#changing-destination-during-navigation),
[](#navigating-via-waypoints),
......@@ -2424,6 +2428,56 @@ via-places may be interleaved — they form a single route. The
destination place always forms the final point in this route. The `way`
and `via` parameters may each appear zero or more times.
Additional routing specific parameters can be added.
If those parameters are not provided, the default value is left to the routing
engine. It may be different for each type of vehicle, or due to other logic in
the routing engine.
Many parameters represent a single value; for example, it is not meaningful to
specify both `optimize=fastest` and `optimize=shortest`. URIs with multiple values
for a single-valued parameter, for example
`place:Home;optimize=fastest;optimize=shortest`, should be treated as though
that parameter was not present.
Apertis does not currently define multi-valued preferences. All values should be
specified at most once. However, OEMs may define and use their own multi-valued
properties. The naming convention is defined below.
Boolean values can be specified as `1` and `0` (or equivalently `true` and
`false`). Other values are considered invalid.
- `vehicle`: vehicle for which the route should be calculated. Apertis defines
`car`, `walk`, and `bike`.
`car` routes are optimized for being used by car.
`walk` routes are optimized for walking.
`bicycle` routes are optimized for being ridden by bicycles.
- `optimize`: Optimizes route calculation towards a set of criteria. Apertis
defines `fastest`, and `shortest` criteria.
`fastest` routes are optimized to minimize travel duration.
`shortest` routes are optimized to minimize travel distance.
- `avoid-tolls`: Boolean. If true, the calculated route should avoid tolls.
If usage can't be avoided, the handler application is responsible for
informing the user.
- `avoid-motorways`: Boolean. If true, the generated route should avoid motorways.
If usage can't be avoided, the handler application is responsible for
informing the user.
- `avoid-ferries`: Boolean. If true, the generated route should avoid ferries.
If usage can't be avoided, the handler application is responsible for
informing the user.
Additionally, vendor specific parameters can be provided for vendor specific
features.
To avoid contradictory definitions for the same parameter in different
implementations, vendor-specific parameters must be named in the form
`x-vendorname-paramname`, similar to
[the convention for extending `.desktop` files](https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html#extending).
Note that unlike keys in `.desktop` files, parameter names in `nav:` URIs are
not case-sensitive: consistently using lower-case is encouraged.
For instance, one of the [examples] below assumes that a manufacturer has
introduced a boolean option `x-batmobile-avoid-detection`, and a string-valued
parameter `x-batmobile-auto-pilot-mode`.
### Examples
This section is non-normative. Each example is given as a fully encoded
......@@ -2462,6 +2516,25 @@ string, followed by it split up into its un-encoded components.
- `postal-code`: LA63EB
- `country`: GB
- `nav:geo%3A51.531621%2C-0.124372;vehicle=walk;optimize=shortest`
- Destination place: `geo:51.531621,-0.124372`
- Parameters:
- `vehicle`: `walk`
- `optimize`: `shortest`
- `nav:geo%3A51.531621%2C-0.124372;vehicle=car;avoid-tolls=false;x-batmobile-auto-pilot-mode=full;x-batmobile-avoid-detection=true`
- Destination place: `geo:51.531621,-0.124372`
- Parameters:
- `vehicle`: `car`
- `avoid-tolls`: `false`
- `x-batmobile-avoid-detection`: `true`
- `x-batmobile-auto-pilot-mode`: `full`
- `nav:place:Cambridge;x-myvendor-avoid-road=A14;x-myvendor-avoid-road=M11`
- Destination place: Cambridge
- Parameters:
- `x-myvendor-avoid-road`: multi-valued: A14, M11
[automotive domain]: https://wiki.apertis.org/mediawiki/index.php/Glossary#automotive-domain
[point of interest stream]: https://wiki.apertis.org/Points_of_interest#General_POI_providers
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment