path: root/api/franca/navigation/navigationcore/LocationInput.fidl

// 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 : LocationInput = This interface offers functions that implement the location-input functionality of a navigation system
**>

interface LocationInput {
	version {
		major 4 
		minor 0
	}

	
	enumeration SearchStatus extends BasicEnum { //Base 0x00c0
  		SEARCHING		= 193
  		FINISHED 		= 194		
	}
	
	enumeration ValidationType extends BasicEnum { 
		OK				= 208
		UNKNOWN			= 209
		AMBIGUOUS		= 210
		INCONSISTENT	= 211
	}
	
	array AddressAttributeList of AddressAttribute

	enumeration AddressAttribute extends GeoLocalizedEnum { 
		COUNTRY			= 166 //value of type String, that identifies the country name
		COUNTRYCODE		= 179 //value of type String, ISO 3166‐1 alpha 3 country code (upper case)
		STATE			= 167
		CITY			= 168 //value of type String, that identifies the city name
		STREET			= 170 //value of type String, that identifies the street name
		ROAD_NUMBER		= 182 //value of type String, that identifies the road number
		HOUSENUMBER		= 171 //value of type String, that identifies the house number
		HOUSENAME		= 180 //value of type String, that identifies the house name
		CROSSING		= 172 //value of type String, that identifies the crossing
		DISTRICT		= 173 //value of type String, that identifies the district name
		PHONENUMBER		= 174 //value of type String, that identifies a phone number
		POINAME			= 175 //value of type String, that identifies a POI name
		TOWNCENTER		= 176
		LOCATION_INPUT  = 177
		FULL_ADDRESS	= 178
		POSTAL_CODE		= 181
		ROADSHIELDS		= 182
	}

    union AddressValue {
	    Int32 intValue
	    Double doubleValue
	    String stringValue
	    Coordinate3D coordinate3DValue
	    UInt8[] internalData
	    RoadShield[] roadShields
    }

	map Address {
		AddressAttribute to AddressValue
	}

	map ValidationStatus {
		AddressAttribute to ValidationType
	}	

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

	<**
		@description : createLocationInput = This method creates a new location input and retrieves a handle
	**>
	method createLocationInput {
		in {

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

			<**
				@description : Location input handle. Range[0x0:0x7fffffff]. 0x0 is reserved as an invalid handle value
			**>
			LocationHandle locationInputHandle
		}
		error {
			OK
			LOCATIONINPUT_ERROR_NOMORELOCATIONINPUTHANDLES //no more location input handles are available
		}
	}

	<**
		@description : deleteLocationInput = This method deletes a location input and its associated resources
	**>
	method deleteLocationInput {
		in {

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

			<**
				@description : locationInpuHandle = Location input handle. Range[0x0:0x7fffffff]. 0x0 is reserved as an invalid handle value
			**>
			LocationHandle locationInputHandle
		}
		error {
			OK
			LOCATIONINPUT_ERROR_LOCATIONINPUTNOTAVAILABLE //an application tries to delete a location input handle that is not available
		}
	}

	<**
		@description : getSupportedAddressAttributes = This method retrieves the supported address attributes
	**>
	method getSupportedAddressAttributes {
		out {
			AddressAttributeList addressAttributesList
		}
	}

	<**
		@description : setAddress = This method sets the address to start with for the LocationInput identified by the given handle
	**>
	method setAddress {
		in {

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

			<**
				@description : locationInpuHandle = Location input handle. Range[0x0:0x7fffffff]. 0x0 is reserved as an invalid handle value
			**>
			LocationHandle locationInputHandle
			
			Address address
		}
	}

	<**
		@description : setSelectionCriterion = This method sets the selection criterion for the current speller, search input and the corresponding result-lists for the current session
	**>
	method setSelectionCriterion {
		in {

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

			<**
				@description : locationInpuHandle = Location input handle. Range[0x0:0x7fffffff]. 0x0 is reserved as an invalid handle value
			**>
			LocationHandle locationInputHandle

			<**
				@description : selectionCriterion = enum(INVALID,LATITUDE,LONGITUDE,ALTITUDE,FULL_ADDRESS,COUNTRY,COUNTRYCODE,STATE,CITY,STREET,ROAD_NUMBER,HOUSENUMBER,HOUSENAME,CROSSING,DISTRICT,PHONENUMBER,POINAME,TOWNCENTER, ... )
			**>
			AddressAttribute selectionCriterion
		}
	}

	<**
		@description : spell = This method sends the next spell input for the current session
		Note: when a spell is started the entries of the search are removed
	**>
	method spell {
		in {

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

			<**
				@description : locationInpuHandle = Location input handle. Range[0x0:0x7fffffff]. 0x0 is reserved as an invalid handle value
			**>
			LocationHandle locationInputHandle

			<**
				@description : inputString = last input character (UTF-8) (0x08(Backspace) for delete last character, 0x0D(Carriage Return) for delete entire input)
			**>
			String inputCharacter

			<**
				@description : maxWindowSize = maximum number of elements that should be returned as result
			**>
			UInt16 maxWindowSize
		}
	}

	<**
		@description : search = This method sends the search input for the current session
		Note: when a search is started the entries of the spell input are removed
	**>
	method search {
		in {

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

			<**
				@description : locationInpuHandle = Location input handle. Range[0x0:0x7fffffff]. 0x0 is reserved as an invalid handle value
			**>
			LocationHandle locationInputHandle

			<**
				@description : inputString = contains the String, that is searched
			**>
			String inputString

			<**
				@description : maxWindowSize = maximum number of elements that should be returned as result
			**>
			UInt16 maxWindowSize
		}
	}

	<**
		@description : requestListUpdate = This method sends a request for more list elements for the current session
	**>
	method requestListUpdate {
		in {

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

			<**
				@description : locationInpuHandle = Location input handle. Range[0x0:0x7fffffff]. 0x0 is reserved as an invalid handle value
			**>
			LocationHandle locationInputHandle

			<**
				@description : offset = starting offset of the newly requested list elements
			**>
			UInt16 offset

			<**
				@description : maxWindowSize = maximum number of elements that should be returned as result
			**>
			UInt16 maxWindowSize
		}
	}

	<**
		@description : selectEntry = This method triggers selection of a result list entry by index
		Note: the update of the input content will be notified in signal ContentUpdated
	**>
	method selectEntry {
		in {

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

			<**
				@description : locationInpuHandle = Location input handle. Range[0x0:0x7fffffff]. 0x0 is reserved as an invalid handle value
			**>
			LocationHandle locationInputHandle

			<**
				@description : index = absolute list index of the entry to be selected
			**>
			UInt16 index
		}
	}

	<**
		@description : getEntry = This method synchronously gets the address for the given result list entry
	**>
	method getEntry {
		in {

			<**
				@description : locationInpuHandle = Location input handle. Range[0x0:0x7fffffff]. 0x0 is reserved as an invalid handle value
			**>
			LocationHandle locationInputHandle

			<**
				@description : index = list index of the entry to be returned
			**>
			UInt16 index
		}
		out {
			Address address
		}
	}

	<**
		@description : validateAddress = This method validates an address from different sources than Navigation
	**>
	method validateAddress {
		in {

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

			<**
				@description : locationInpuHandle = Location input handle. Range[0x0:0x7fffffff]. 0x0 is reserved as an invalid handle value
			**>
			LocationHandle locationInputHandle
			
			Address inputAddress
		}
	}

	<**
		@description : reverseGeocode = This method transforms a geocoordinate into an address
		Note: the update of the input content will be notified in signal ContentUpdated
	**>
	method reverseGeocode {
		in {

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

			<**
				@description : locationInpuHandle = Location input handle. Range[0x0:0x7fffffff]. 0x0 is reserved as an invalid handle value
			**>
			LocationHandle locationInputHandle
			
			Coordinate2D coordinate
		}
	}

	<**
		@description : currentSelectionCriterion = This signal notifies the SelectionCriterion for the current speller input or search.
	**>
	broadcast currentSelectionCriterion {
		out {

			<**
				@description : locationInpuHandle = Location input handle. Range[0x0:0x7fffffff]. 0x0 is reserved as an invalid handle value
			**>
			LocationHandle locationInputHandle

			<**
				@description : selectionCriterion = enum(INVALID,LATITUDE,LONGITUDE,ALTITUDE,FULL_ADDRESS,COUNTRY,COUNTRYCODE,STATE,CITY,STREET,ROAD_NUMBER,HOUSENUMBER,HOUSENAME,CROSSING,DISTRICT,PHONENUMBER,POINAME,TOWNCENTER, ... )
			**>
			AddressAttribute selectionCriterion
		}
	}

	<**
		@description : searchStatus = This signal updates the search status of the specified session
	**>
	broadcast searchStatus {
		out {

			<**
				@description : locationInpuHandle = Location input handle. Range[0x0:0x7fffffff]. 0x0 is reserved as an invalid handle value
			**>
			LocationHandle locationInputHandle

			<**
				@description : statusValue = enum(INVALID,NOT_STARTED,SEARCHING,FINISHED, ... )
			**>
			SearchStatus statusValue
		}
	}

	<**
		@description : spellResult = This signal notifies the result of the previous Spell method
	**>
	broadcast spellResult {
		out {

			<**
				@description : locationInpuHandle = Location input handle. Range[0x0:0x7fffffff]. 0x0 is reserved as an invalid handle value
			**>
			LocationHandle locationInputHandle

			<**
				@description : uniqueString = unique string derived from spell input (i.e. including auto-completion if applicable)
			**>
			String uniqueString

			<**
				@description : validCharacters = set of (UTF-8 encoded) characters valid for next input (unified in a single string). A Backspace(0x08) is returned if the input character passed to the Spell method was invalid
			**>
			String validCharacters

			<**
				@description : fullMatch = flag indicating whether the value in UniqueCharacters is already a full match for an existing list entry
			**>
			Boolean fullMatch
		}
	}

	<**
		@description : searchResultList = This signal updates the address result list (e.g. after a Search/Spell/Scroll call)
	**>
	broadcast searchResultList {
		out {

			<**
				@description : locationInpuHandle = Location input handle. Range[0x0:0x7fffffff]. 0x0 is reserved as an invalid handle value
			**>
			LocationHandle locationInputHandle

			<**
				@description : totalSize = total size of the result list
			**>
			UInt16 totalSize

			<**
				@description : windowOffset = window offset within the complete list
			**>
			UInt16 windowOffset

			<**
				@description : windowSize = size of the provided window
			**>
			UInt16 windowSize
			
			Address [] resultListWindow
		}
	}

	<**
		@description : searchResultListSizeChanged = This signal updates the size of the address result list
	**>
	broadcast searchResultListSizeChanged {
		out {

			<**
				@description : locationInpuHandle = Location input handle. Range[0x0:0x7fffffff]. 0x0 is reserved as an invalid handle value
			**>
			LocationHandle locationInputHandle

			<**
				@description : totalSize = total size of the result list
			**>
			UInt16 totalSize
		}
	}

	<**
		@description : contentUpdated = This signal updates the input content data for the specified session
	**>
	broadcast contentUpdated {
		out {

			<**
				@description : locationInpuHandle = Location input handle. Range[0x0:0x7fffffff]. 0x0 is reserved as an invalid handle value
			**>
			LocationHandle locationInputHandle

			<**
				@description : guidable = flag indicating whether the current address is guidable
			**>
			Boolean guidable
			
			AddressAttribute [] availableSelectionCriteria
			
			Address address
		}
	}

	<**
		@description : addressValidationResult = This signal notifies the validation result of a former ValidateAddress call
	**>
	broadcast addressValidationResult {
		out {

			<**
				@description : locationInpuHandle = Location input handle. Range[0x0:0x7fffffff]. 0x0 is reserved as an invalid handle value
			**>
			LocationHandle locationInputHandle
			
			Address [] validatedAddressList
			
			ValidationStatus [] validationStatusList
		}
	}
}