// SPDX-License-Identifier: MPL-2.0
// Copyright (C) 2014, PCA Peugeot Citro�n, XS Embedded GmbH, TomTom International B.V., Continental Automotive GmbH, BMW Car IT GmbH,  Alpine Electronics R&D Europe GmbH, AISIN AW CO., LTD.,  Neusoft Technology Solutions GmbH, Jaguar Land Rover Limited, Visteon Corporation, Elektrobit Automotive GmbH
// This Source Code Form is subject to the terms of the
// Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with
// this file, you can obtain one at http://mozilla.org/MPL/2.0/.

package org.genivi.navigation.navigationcore
	
import org.genivi.CommonTypes.* from "../../CommonTypes.fidl"
import org.genivi.navigation.NavigationTypes.* from "../NavigationTypes.fidl"
import org.genivi.navigation.navigationcore.NavigationCoreTypes.* from "./NavigationCoreTypes.fidl"

<**
	@description : Guidance = This interface offers functions that implement the route-guidance functionality of a navigation system
**>

interface Guidance {
	version {
		major 4 
		minor 0
	}

	enumeration Side extends BasicEnum {
		LEFT = 128
		RIGHT = 131
		NOT_AVAILABLE = 2
	}

	enumeration LaneType extends BasicEnum {
		LANE_INFO_BITMASK_STRAIGHT		= 1
		LANE_INFO_BITMASK_SLIGHTRIGHT	= 2
		LANE_INFO_BITMASK_RIGHT			= 4
		LANE_INFO_BITMASK_SHARPRIGHT	= 8
		LANE_INFO_BITMASK_RIGHTUTURN	= 16
		LANE_INFO_BITMASK_SLIGHTLEFT	= 32
		LANE_INFO_BITMASK_LEFT			= 64
		LANE_INFO_BITMASK_SHARPLEFT		= 128
		LANE_INFO_BITMASK_LEFTUTURN		= 256
	}
	
	enumeration PromptMode extends BasicEnum { //Base 0x0040
		DISABLED_PROMPT					= 65
		AUTOMATIC_PROMPT				= 66
		MANUAL_PROMPT					= 67
	}
	
	enumeration ManeuverPhase extends BasicEnum { //Base 0x0050
		CRUISE 				= 80
		MANEUVER_APPEARED 	= 81
		PRE_ADVICE 			= 82
		ADVICE 				= 83
		PASSED 				= 84
	}

	enumeration GuidanceStatus extends BasicEnum { //Base 0x0060
		ACTIVE							= 96
		INACTIVE						= 97
	}
	
	enumeration ManeuverType extends BasicEnum { //Base 0x0070
		STRAIGHT_ON					= 112
		CROSSROAD					= 113
		ROUNDABOUT					= 114
		HIGHWAY_ENTER				= 115
		HIGHWAY_EXIT				= 116
		FOLLOW_SPECIFIC_LANE		= 117
		DESTINATION					= 118
		WAYPOINT					= 119
		TURN						= 120
		BIFURCATION					= 121
	}
	
	enumeration ManeuverDirection extends BasicEnum { //Base 0x0080
		STRAIGHT_ON					    = 127
		LEFT							= 128
		SLIGHT_LEFT						= 129
		HARD_LEFT						= 130
		RIGHT							= 131
		SLIGHT_RIGHT					= 132
		HARD_RIGHT						= 133
		UTURN_RIGHT						= 134
		UTURN_LEFT						= 135
	}
	
	enumeration CalculationMode extends BasicEnum { //Base 0x0090
		ALL_MANUAL						= 144
		ALL_AUTOMATIC					= 145
		TRAFFIC_MANUAL					= 146
		OFF_ROUTE_MANUAL				= 147
	}

	enumeration RoadProperty extends BasicEnum { //Base 0x0100
		UNDEFINED   					= 256
		TOLL_ROADS   					= 257
	}
	enumeration RouteChangedCause extends BasicEnum { //Base 0x0210
		TRAFFIC							= 528
		OFF_ROUTE						= 529
		MANUAL							= 530
	}

	enumeration ManeuverDirectionType extends BasicEnum { //Base 0x0240
		DIRECTION					= 576
		EXIT_NUMBER					= 577
		ROAD_FORM					= 578
		LANE_INFO					= 579
	}

	enumeration LaneDivider extends BasicEnum { //Base 0x0250
		DIVIDER_UNDEFINED				= 592
		DIVIDER_INTERRUPTEDLONG			= 593
		DIVIDER_INTERRUPTEDSHORT		= 594
		DIVIDER_SOLIDSINGLE				= 595
		DIVIDER_SOLIDDOUBLE				= 596
		DIVIDER_SOLIDINTERRUPTED		= 597
		DIVIDER_INTERRUPTEDSOLID		= 598
	}

	enumeration ManeuverDataAttribute extends BasicEnum { //Base 0x260
		LENGTH				= 608
		DIRECTION			= 609
		EXIT_NUMBER			= 610
		ROAD_FORM			= 611
		LANE_INFO			= 612
		LATITUDE			= 613
		LONGITUDE			= 614
		ALTITUDE			= 615
	}

    union ManeuverDataValue {
	    ManeuverDirection enumValue
	    String stringValue
	    LaneInfo[] laneInfoValue
	    Coordinate3D coordinate3DValue
    }
	
	map ManeuverData {
		ManeuverDataAttribute to ManeuverDataValue
	}	
	
	struct LaneInfo {
		UInt32 laneIndex
		ByteBuffer laneDirections
		LaneType directionToFollow
		LaneDivider divider
	}

	struct WaypointStruct {
		UInt32 waypointOffset
		UInt32 travelTime
		Int32 direction
		Side side
		Int16 timeZone
		Int16 daylightSavingTime
		Boolean isDestination
		UInt16 number
	}

	<**
		@description : struct generated for DBus argument GetManeuversList_maneuversListElem6
	**>
	struct ManeuverItem {
		UInt32 offsetOfManeuver
		UInt32 travelTime
		ManeuverDirectionType direction
		ManeuverType maneuver
		ManeuverData maneuverData
	}

	<**
		@description : struct generated for DBus argument GetManeuversList_maneuversList
	**>
	struct Maneuver {
		String roadNumberAfterManeuver
		String roadNameAfterManeuver
		RoadProperty roadPropertyAfterManeuver
		Side drivingSide
		UInt32 offsetOfNextManeuver
		ManeuverItem[] items
	}

	<**
		@description : getVersion = This method returns the API version implemented by the server application
	**>
	method getVersion {
		out {
			Version ^version
		}
	}

	<**
		@description : startGuidance = This method starts the guidance for a given route
	**>
	method startGuidance {
		in {

			<**
				@description : sessionHandle = Session handle. Range[0x0:0x7fffffff]. 0x0 is reserved as an invalid handle value
			**>
			Handle sessionHandle

			<**
				@description : routeHandle = Route handle. Range[0x0:0x7fffffff]. 0x0 is reserved as an invalid handle value
			**>
			Handle routeHandle
		}
	}

	<**
		@description : stopGuidance = This method stops the guidance
	**>
	method stopGuidance {
		in {

			<**
				@description : sessionHandle = Session handle. Range[0x0:0x7fffffff]. 0x0 is reserved as an invalid handle value
			**>
			Handle sessionHandle
		}
	}

	<**
		@description : setVoiceGuidance = This method switch on/off the voice guidance
	**>
	method setVoiceGuidance {
		in {

			<**
				@description : activation of the voice guidance
			**>
			Boolean activate

			<**
				@description : kind of voice (to be defined)
			**>
			String voice
		}
	}

	<**
		@description : getGuidanceDetails = This method retrieves guidance information 
	**>
	method getGuidanceDetails {
		out {

			<**
				@description : voiceGuidance = if TRUE voice guidance is active
			**>
			Boolean voiceGuidance

			<**
				@description : vehicleOnTheRoad = if TRUE the vehicle is located on the road network
			**>
			Boolean vehicleOnTheRoad

			<**
				@description : isDestinationReached = if TRUE the destination has been reached
			**>
			Boolean isDestinationReached

			<**
				@description : maneuver = enum(INVALID,CRUISE,MANEUVER_APPEARED,PRE_ADVICE,ADVICE,PASSED, ... )
			**>
			ManeuverPhase maneuver
		}
	}

	<**
		@description : playVoiceManeuver = This method plays or repeats the last voice guidance
		notify(GUIDANCE_ERROR_VOICENOTALLOWED) is emitted if the voice generation is inactive
	**>
	method playVoiceManeuver {
	}

	<**
		@description : getWaypointInformation = This method retrieves the information on the remaining way points of the route. A point can be the final destination as well as a stage defined by the user. The returned waypoints are ordered by their 'number'.
	**>
	method getWaypointInformation {
		in {

			<**
				@description : requestedNumberOfWaypoints = the number of requested waypoints. If 0, all waypoints will be returned.
			**>
			UInt16 requestedNumberOfWaypoints
		}
		out {

			<**
				@description : numberOfWaypoints = the number of retrieved waypoints(NOTE: the number corresponds to the number of elements in the array)
			**>
			UInt16 numberOfWaypoints
			WaypointStruct [] waypointsList
		}
	}

	<**
		@description : This method retrieves the information on the final destination
	**>
	method getDestinationInformation {
		out {

			<**
				@description : offset = offset of the destination in meter from the beginning of the route
			**>
			UInt32 offset

			<**
				@description : travelTime = time to reach the destination in second
			**>
			UInt32 travelTime

			<**
				@description : direction = direction of the destination in degree relatively to the North. Range [0:360]
			**>
			Int32 direction

			<**
				@description : side = enum(LEFT,RIGHT,NOT_AVAILABLE)
			**>
			Side side

			<**
				@description : timeZone = time zone of the destination. It is expressed as the time difference from the UTC in minutes
			**>
			Int16 timeZone

			<**
				@description : daylightSavingTime = daylight saving time of the destination. It is expressed as the time difference from the UTC in minutes
			**>
			Int16 daylightSavingTime
		}
	}

	<**
		@description : getManeuversList = This method retrieves the list of next maneuvers
		notify(GUIDANCE_ERROR_NOMANEUVER) is emitted in case there's no maneuver until the destination
	**>
	method getManeuversList {
		in {

			<**
				@description : requestedNumberOfManeuvers = the number of requested maneuvers
			**>
			UInt16 requestedNumberOfManeuvers

			<**
				@description : maneuverOffset = the offset of the first maneuver to retrieve
			**>
			UInt32 maneuverOffset
		}
		out {

			<**
				@description : numberOfManeuvers = the number of retrieved maneuvers
			**>
			UInt16 numberOfManeuvers
			
			Maneuver[] maneuversList
		}
	}

	<**
		@description : setRouteCalculationMode = This method configures the way the navigation application wants the navigation core to behave of reroute trigger
	**>
	method setRouteCalculationMode {
		in {

			<**
				@description : sessionHandle = Session handle. Range[0x0:0x7fffffff]. 0x0 is reserved as an invalid handle value
			**>
			Handle sessionHandle

			<**
				@description : routeCalculationMode = enum(INVALID,ALL_MANUAL,ALL_AUTOMATIC,TRAFFIC_MANUAL,OFF_ROUTE_MANUAL)
			**>
			CalculationMode routeCalculationMode
		}
	}

	<**
		@description : skipNextManeuver = This method allows to jump behind the current maneuver
		notify(GUIDANCE_ERROR_NOMANEUVER) is emitted in case there's no maneuver until the destination
	**>
	method skipNextManeuver {
		in {

			<**
				@description : sessionHandle = Session handle. Range[0x0:0x7fffffff]. 0x0 is reserved as an invalid handle value
			**>
			Handle sessionHandle
		}
	}

	<**
		@description : getGuidanceStatus = This method retrieves the guidance status
	**>
	method getGuidanceStatus {
		out {

			<**
				@description : guidanceStatus = enum(INVALID,ACTIVE,INACTIVE)
			**>
			GuidanceStatus guidanceStatus

			<**
				@description : routeHandle = Active route handle. Range[0x0:0x7fffffff]. 0x0 is reserved as an invalid handle value. Should be ignored when guidanceStatus=INACTIVE
			**>
			Handle routeHandle
		}
	}

	<**
		@description : setVoiceGuidanceSettings = This method sets the voice guidance settings
		notify(GUIDANCE_ERROR_VOICENOTALLOWED) is emitted if the voice generation is inactive
	**>
	method setVoiceGuidanceSettings {
		in {

			<**
				@description : mode = enum(INVALID,DISABLED_PROMPT,AUTOMATIC_PROMPT,MANUAL_PROMPT, ... )
			**>
			PromptMode promptMode
		}
	}

	<**
		@description : getVoiceGuidanceSettings = This method returns the used voice guidance settings
	**>
	method getVoiceGuidanceSettings {
		out {

			<**
				@description : mode = enum(INVALID,DISABLED_PROMPT,AUTOMATIC_PROMPT,MANUAL_PROMPT, ... )
			**>
			PromptMode promptMode
		}
	}

	<**
		@description : vehicleLeftTheRoadNetwork = This signal is emitted when the vehicle exits from the road network
	**>
	broadcast vehicleLeftTheRoadNetwork {
	}

	<**
		@description : guidanceStatusChanged = This signal is emitted when the guidance status changes
	**>
	broadcast guidanceStatusChanged {
		out {

			<**
				@description : guidanceStatus = enum(INVALID,ACTIVE,INACTIVE)
			**>
			GuidanceStatus guidanceStatus

			<**
				@description : routeHandle = Active route handle. Range[0x0:0x7fffffff]. 0x0 is reserved as an invalid handle value. Should be ignored when guidanceStatus=INACTIVE.
			**>
			Handle routeHandle
		}
	}

	<**
		@description : waypointReached = This signal is emitted when the destination is reached
	**>
	broadcast waypointReached {
		out {

			<**
				@description : isDestination = flag. TRUE means that the way point is the destination
			**>
			Boolean isDestination
		}
	}

	<**
		@description : This signal is emitted each time a maneuver event is going
	**>
	broadcast maneuverChanged {
		out {

			<**
				@description : maneuver = enum(INVALID,CRUISE,MANEUVER_APPEARED,PRE_ADVICE,ADVICE,PASSED, ... )
			**>
			ManeuverPhase maneuver
		}
	}

	<**
		@description : positionOnRouteChanged = This signal is emitted when the position on the route changes
	**>
	broadcast positionOnRouteChanged {
		out {

			<**
				@description : offsetOnRoute = the current offset on the route in meters from the beginning of the route
			**>
			UInt32 offsetOnRoute
		}
	}

	<**
		@description : vehicleLeftTheRoute = This signal is emitted when the vehicle has left the route
	**>
	broadcast vehicleLeftTheRoute {
	}

	<**
		@description : positionToRouteChanged = This signal is emitted when the vehicle is off-the-road network and either the heading or the distance (or both) to the closest point on the active route changes
	**>
	broadcast positionToRouteChanged {
		out {

			<**
				@description : distance = distance in meters to the closest point on the active route
			**>
			UInt32 distance

			<**
				@description : direction = direction in degrees relatively to the closest point on the active route. Range [0:360]
			**>
			Int32 direction
		}
	}

	<**
		@description : activeRouteChanged = This signal is emitted when the active route changes
	**>
	broadcast activeRouteChanged {
		out {

			<**
				@description : changeCause = enum(INVALID,TRAFFIC,OFF_ROUTE,MANUAL,...)
			**>
			RouteChangedCause changeCause
		}
	}

	<**
		@description : notify = This signal is emitted when something wrong occured when invoking the API 
	**>
	broadcast notify {
		out {
			Notification notification
		}
	}
}