.. _RoadMapPlanner:

RoadMapPlanner
==============

.. cpp:namespace:: pilot::RoadMapPlanner

Module
------

The `RoadMapPlanner` module provides navigation support based on a :ref:`RoadMap`.

Most functions require a special permission, see :ref:`pilot.permission_e`.


Functions
---------

Common Parameters
^^^^^^^^^^^^^^^^^

``goal_options_t options``
	Optional goal options, see :ref:`pilot.goal_options_t`. If not specified will use default values.
	
``Hash64 job``
	Optional job id, to identify the new goal. If not specified (or set to zero) will generate a new random id. See :ref:`vnx.Hash64`.

General Functions
^^^^^^^^^^^^^^^^^

.. cpp:function:: RoadMapData* get_road_map() const
	
	Returns the currently used :ref:`RoadMap`, if any. See :ref:`pilot.RoadMapData`.
	
.. cpp:function:: MapStation* find_station(string name) const
	
	Returns the corresponding map station by that name, if any. See :ref:`pilot.MapStation`.
	
Movement Functions
^^^^^^^^^^^^^^^^^^

.. cpp:function:: void set_goal_station(string name, goal_options_t options, Hash64 job)
	
	Sets a new goal using the provided station ``name`` and returns immediately.
	Any pending goals are canceled beforehand. The station must exist in the current :ref:`RoadMap`.
	Requires permission ``MOVE``.
	
.. cpp:function:: void move_to_station(string name, goal_options_t options, Hash64 job)
	
	Same as ``set_goal_station(...)`` but will block until goal is reached or canceled.
	Requires permission ``MOVE``.