// 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 : MapMatchedPosition = This interface offers functions to retrieve the map matched position and to simulate positioning
	  If NavigationCore is not in Simulation Mode (Simulation Status is SIMULATION_STATUS_NO_SIMULATION), it is using the EnhancedPosition from the Positioning component.
	  In Simulation Mode it is not using this position, instead it uses FixedPosition or FollowActiveRoute to determine the position.
	  With FixedPosition (Simulation Status is SIMULATION_STATUS_FIXED_POSITION), the position is fixed, unless it is changed by a call to setPosition().
	  This supports use cases like: setting the current car position in a demo mode, or replay a position log file (where setPosition() is called for each logged location).
	  In Follow Active Route mode, NavigationCore is generating positions itself.
	  These positions follow the current active route. When the end of the route is reached, the position jumps back to the starting point of the route.
	  There are two sub states: Running (Simulation Status is SIMULATION_STATUS_RUNNING) and Paused (Simulation Status is SIMULATION_STATUS_PAUSED).
	  By default the ‘driving speed’ will be equal to the free flow speed of each road segment. However a speed factor can be set via the method SetSimulationSpeed.
**>

interface MapMatchedPosition {
	version {
		major 4 
		minor 0
	}

	enumeration PositionItemKey extends PositionStatus { //Base 0x00a0
		HEADING				= 163
		SPEED				= 164
		CLIMB				= 165
	}
	
	enumeration AddressItemKey  extends TimeStampedEnum {
		TIMEZONE_OFFSET		= 17
		DAYLIGHT_OFFSET		= 18
		COUNTRY			= 166 //Base 0x00a0
		STATE			= 167
		CITY			= 168
		STREET			= 170
		HOUSENUMBER		= 171
		CROSSING		= 172
		DISTRICT		= 173
		PHONENUMBER		= 174
		POINAME			= 175
		TOWNCENTER		= 176
		LOCATION_INPUT		= 177
		FULL_ADDRESS		= 178
		COUNTRYCODE		= 179
		HOUSENAME		= 180
		POSTAL_CODE		= 181
		ROAD_NUMBER		= 334
		MATCH_TYPE		= 240
		ROADSHIELDS		= 182
	}
		
	enumeration PositionStatus extends GeoLocalizedEnum { //Base 0x00e0
		GNSS_FIX_STATUS			= 224
		DR_STATUS			= 225
		MM_STATUS			= 226
		SIMULATION_MODE			= 227
	}
	
	enumeration MatchMode { //Base 0x00f0
		MATCH_TYPE			= 240
		ON_ROAD				= 241
		OFF_ROAD			= 242
		ON_FERRY			= 243
		IN_TUNNEL			= 244
		ON_CARPARK			= 245
	}		
		
	 enumeration GnnsFixStatus extends BasicEnum { //Base 0x0100
	 	NO_FIX				= 256
	 	TIME_FIX			= 257
	 	FIX_2D				= 258 //2D_FIX is prohibited 
	 	FIX_3D				= 259
	}
		
	enumeration PositionOnSegmentKey extends TimeStampedEnum { //Base 0x0110
		SEGMENT_ID			= 272
		DIRECTION_ON_SEGMENT		= 274
		DISTANCE_ON_SEGMENT		= 275
	}
	
	enumeration SimulationStatus extends BasicEnum { //Base 0x0220
		SIMULATION_STATUS_NO_SIMULATION		= 544 //means that NavigationCore is using the EnhancedPosition
		SIMULATION_STATUS_RUNNING		= 545 //means that positions are generated along the active route
		SIMULATION_STATUS_PAUSED		= 546 //means that the generation of positions along the active route is paused
		SIMULATION_STATUS_FIXED_POSITION	= 547 //means that the position is fixed
	}
	
	union PositionItemValue {
		Timestamp timestamp
		Boolean status
		GnnsFixStatus fix
		Double doubleValue
		Int32 intValue
	}	
		
	map PositionItemDict {
		PositionItemKey to PositionItemValue
	}
	
	union AddressItemValue {
		String addressField
		Int16 offset
		Timestamp timestamp
		MatchMode matchMode
		RoadShield[] roadShields
	}
	
	map AddressItemDict {
		AddressItemKey to AddressItemValue
	}
	
	union PositionOnSegmentValue {
		Boolean directionOnSegment
		Double distanceOnSegment //to be fixed, use of DistanceInMeters preferred ?
		ByteBuffer segment
		Timestamp timestamp
	}
	
	map PositionOnSegmentDict {
		PositionOnSegmentKey to PositionOnSegmentValue
	}
	
	union PositionStatusValue {
		Boolean statusValue
		GnnsFixStatus fixStatus
		Timestamp timestamp
	}
	
	map PositionStatusDict {
		PositionStatus to PositionStatusValue
	}

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

	<**
		@description : setSimulationMode = This method activates or deactivates the simulation mode
	**>
	method setSimulationMode {
		in {

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

			<**
				@description : activate = flag. TRUE means that the simulation mode is activated.
			**>
			Boolean activate
		}
	}

	<**
		@description : getSimulationStatus = This method retrieves the simulation status
	**>
	method getSimulationStatus {
		out {

			<**
				@description : simulationStatus = enum(SIMULATION_STATUS_NO_SIMULATION, SIMULATION_STATUS_RUNNING, SIMULATION_STATUS_PAUSED, SIMULATION_STATUS_FIXED_POSITION)
			**>
			SimulationStatus simulationStatus
		}
	}

	method setSimulationSpeed {
		in {

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

			<**
				@description : speedFactor = speed factor. unit is x0.25. Normal speed x1 is 4
			**>
			UInt8 speedFactor
		}
	}

	<**
		@description : getSimulationSpeed = returns the speed factor for the simulation mode
	**>
	method getSimulationSpeed {
		out {

			<**
				@description : speedFactor = speed factor
			**>
			UInt8 speedFactor
		}
	}

	<**
		@description : startSimulation = This method starts, or resumes, a Follow Active Route simulation
        	If the current Simulation Status is SIMULATION_STATUS_PAUSED, the simulation is resumed from the current location.
		Otherwise the simulation is started from the starting point of the route. In both cases the new status will be SIMULATION_STATUS_RUNNING
	**>
	method startSimulation {
		in {

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

	<**
		@description : pauseSimulation = This method freezes the current location
	**>
	method pauseSimulation {
		in {

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

	<**
		@description : getPosition = This method returns the current position
	**>
	method getPosition {
		in {
			PositionItemKey[] valuesToReturn
		}
		out {
			PositionItemDict position
		}
		error {
			OK
			MAPMATCHEDPOSITION_ERROR_NOPOSITION //no position is available
		}
	}

	<**
		@description : setPosition = This method sets the position to a specific location
        		Independent of the current Simulation Status, the new status will be SIMULATION_STATUS_FIXED_POSITION.
        		This method can be used to replay a position log file (with positions obtained via calls to GetPosition()) by calling this method for each position in the log file.
        		It is of course also possible to call this method just once with e.g. a 'current location' entered by the user (via the HMI).
	**>
	method setPosition {
		in {

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

	<**
		@description : getCurrentAddress = This method returns the current address
	**>
	method getCurrentAddress {
		in {
			AddressItemKey[] valuesToReturn
		}
		out {
			AddressItemDict address
		}
		error {
			OK
			MAPMATCHEDPOSITION_ERROR_NOMAP //no map is available
			MAPMATCHEDPOSITION_ERROR_OUTOFKNOWNMAP //the vehicle is located in a position outside of the known map
		}
	}

	<**
		@description : positionOnSegment = This method returns the vehicle position on a route segment
	**>
	method getPositionOnSegment {
		in {
			PositionOnSegmentKey [] valuesToReturn
		}
		out {
			PositionOnSegmentDict positionOnSegment
		}
	}

	<**
		@description : getStatus = This method returns the current status
	**>
	method getStatus {
		in {
			PositionStatus [] valuesToReturn
		}
		out {
			PositionStatusDict status
		}
	}

	<**
		@description : simulationStatusChanged = This signal is emitted when the Simulation Status has changed
	**>
	broadcast simulationStatusChanged selective {
		out {

			<**
				@description : simulationStatus = enum(SIMULATION_STATUS_NO_SIMULATION, SIMULATION_STATUS_RUNNING, SIMULATION_STATUS_PAUSED, SIMULATION_STATUS_FIXED_POSITION)
			**>
			SimulationStatus simulationStatus
		}
	}

	<**
		@description : simulationSpeedChanged = This signal is emitted when the simulation speed factor has changed
		NavigationCore will only send out a SimulationSpeedChanged signal if there is at least one node listening to these changes
	**>
	broadcast simulationSpeedChanged selective {
		out {

			<**
				@description : speedFactor = speed factor
			**>
			UInt8 speedFactor
		}
	}

	<**
		@description : positionUpdate = This signal is called to notify a client application of a position change. The update frequency is implementation specific. The maximal allowed frequency is 10Hz
	**>
	broadcast positionUpdate {
		out {
			PositionItemKey [] changedValues
		}
	}

	<**
		@description : addressUpdate = This signal is called to notify a client application that the current address changed
	**>
	broadcast addressUpdate {
		out {
			AddressItemKey[] changedValues
		}
	}

	<**
		@description : positionOnSegmentUpdate = This signal is called to notify the client that the vehicle position on the route segment changed
	**>
	broadcast positionOnSegmentUpdate {
		out {
			PositionOnSegmentKey[] changedValues
		}
	}

	<**
		@description : statusUpdate = This signal is emitted to notifiy a client application that the current status changed
	**>
	broadcast statusUpdate {
		out {
			PositionStatus [] changedValues
		}
	}

	<**
		@description : offroadPositionChanged = This signal is emitted when the heading and the distance to the closest point on the road network changes
	**>
	broadcast offRoadPositionChanged {
		out {

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

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