path: root/api/franca/navigation/poiservice/POIContentAccessModule.fidl

// SPDX-License-Identifier: MPL-2.0
// Copyright (C) 2018, Groupe PSA, 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.poiservice

import org.genivi.CommonTypes.* from "../../CommonTypes.fidl"
import org.genivi.navigation.NavigationTypes.* from "../NavigationTypes.fidl"
import org.genivi.navigation.poiservice.POIServiceTypes.* from "POIServiceTypes.fidl"


<** @description : This interface offers methods that implement the POI search functionality of a navigation system.**>
interface POIContentAccessModule {
	version {
		major 2 
		minor 0
	}
	
	<**	@description : This method returns the API version implemented by the content access module.**>
	method getVersion {
		out {
			<** @description: .**>
			Version ^version				
		}	
	}		
	
	<**	@description : Set the current language set for the search by poi provider module.
        The language defines the poi and categories name and details language. If the language is not supported, the default details will be returned in the native language.**>
	method setLocale {
		in {
			<** @description : the language to be used. ISO 639‐3 language code (lower case)**>
			String languageCode				
			<** @description : the country specific variant for the language to be used. ISO 3166‐1 alpha 3 country code (upper case)**>
			String countryCode				
			<** @description : the script specific variant for the language to be used. ISO 15924 alpha 4 script code (upper case)**>
			String scriptCode				
		}	
	}	

	<**	@description : Get the current language set for the search by poi provider module.**>
	method getLocale {
		out {
			<** @description : the language used. ISO 639‐3 language code (lower case)**>
			String languageCode				
			<** @description : the country specific variant for the language used. ISO 3166‐1 alpha 3 country code (upper case)**>
			String countryCode				
			<** @description : the script specific variant for the language used. ISO 15924 alpha 4 script code (upper case)**>
			String scriptCode				
		}	
	}	

	<**	@description : Get the supported set of locales for the search by poi provider module.**>
	method getSupportedLocales {
		out {
			<** @description : array[struct(languageCode,countryCode,scriptCode)]**>
			Locale[] localeList				
		}	
	}	

	<**	@description : This method retrieves the list od POI categories available (pre-defined and custom).**>
	method getAvailableCategories {
		out {
			<** @description : List of categories (id, name and top_level).**>
			CategoryAndName[] categories				
		}
	}
	
	<**	@description : Get the root category id. That would be ALL_CATEGORIES.**>
	method getRootCategory {
		out {
			<** @description : The root category is a top level one by design.**>
			CategoryID category				
		}
	}
	
	<**	@description : Get the children categories id and type (top level) from the a parent unique id.**>
	method getChildrenCategories {
		in {
			<** @description : unique category id.**>
			CategoryID category				
		}	
		out {
			<** @description : List of categories (id and top_level).**>
			CategoryAndLevel[] categories				
		}
	}
	
	<**	@description : Get the parent categories id and type (top level) from the a unique id.**>
	method getParentCategories {
		in {
			<** @description : unique category id.**>
			CategoryID category				
		}	
		out {
			<** @description : List of categories (id and top_level).**>
			CategoryAndLevel[] categories				
		}
	}

	<**	@description : Creates a category by name and return an unique id.**>
	method createCategory {
		in {
			<** @description : List of details for the category to create.**>
			CAMCategory category				
		}	
		out {
			<** @description : Category unique id.**>
			CategoryID unique_id				
		}	
	}
	
	<**	@description : Removes a list of categories. Because of required time to remove it from the database, a signal is emitted when the deletion is done.**>
	method removeCategories {
		in {
			<** @description : List of categories to be removed.**>
			CategoryID[] categories				
		}
	}

	<**	@description : Adds a list of POIs to a category. Because of required time to add it to the database, a signal is emitted when the update is done, that gives the id of the elements added**>
	method addPOIs {
		in {
			<** @description : Category unique id.**>
			CategoryID unique_id	

			<** @description : List of POIs and all their content. Note that there's no id sent, because it's up to the component to give it**>
			PoiAddedDetails[] poiList			
		}	
		
	}
	
	<**	@description : Removes a list of POIs to a category. Because of required time to remove it from the database, a signal is emitted when the update is done.**>
	method removePOIs {
		in {
			<** @description : List of unique ids of POIs to remove.**>
			POI_ID[] ids				
		}
	}

	<**	@description : This method is sent by the POI service component to inform all the CAM that a new POI search was started.
        It provides all the relevant search parameters. Of course the CAM will only be aware of the search if it registers one of the search categories.**>
	method poiSearchStarted {
		in {
			<** @description : poi search unique handle. It must be used by the CAM to send the list of results to the component.**>
			Handle poiSearchHandle	
			<** @description : max size of the results list.**>
			UInt16 maxSize				
			<** @description: struct(lat,lon,alt).**>			
			Coordinate3D location									
			<** @description: array[struct(id,radius)].**>						
			CategoryAndRadius[] poiCategories
			<** @description : array[struct(name, poiCategory, type, value, operator, mandatory)].**>
			AttributeDetails[] poiAttributes
			<** @description : contains the name of the poi that is searched. It could be a partial name or an empty string.**>
			String inputString				
			<** @description : enum(SORT_DEFAULT,SORT_BY_DISTANCE,SORT_BY_TIME,ATTRIBUTE_CUSTOM, ... )
            If more than one category was defined for this search, the sort criteria should be compliant with all categories.**>
			SortOption sortOption				
		}	
	}

	<**	@description : This method cancels the search for the current id.**>
	method poiSearchCanceled {
		in {
			<** @description : poi search unique handle.**>
			Handle poiSearchHandle				
		}	
	}

	<**	@description : This method provides the poi results list found by the CAM.
        As the POI unique id is managed by the POI component, the CAM only provides the POI name, the category and coordinates as well as all the relevant detailed information.**>
	method resultListRequested {
		in {
			<** @description : Content access module unique id as known by the POI service component.**>
			ContentAccessModuleID camId				
			<** @description : poi search unique handle.**>
			Handle poiSearchHandle				
			<** @description : List of attributes id to retrieve. This is optional and the list could be empty.**>
			AttributeID[] attributeList				
		}	
		out {
			<** @description : enum(INVALID,NOT_STARTED,SEARCHING,FINISHED, ... ).**>
			SearchStatusState statusValue
			<** @description : Number of items of the results list.**>
			UInt16 resultListSize
			<** @description : array[struct(source_id, name, category, location, distance, attributes)].**>
			PoiCAMDetails[] resultList
		}
	}
	
	<**	@description : This method retrieves the details associated to one or more POI.
        It contains the name, the parent categories, the list of attributes, the icons, ... .**>
	method poiDetailsRequested {
		in {
			<** @description : array[unique_poi_id].**>
			POI_ID[] source_id				
		}	
		out {
			<** @description : array[(details, categories, attributes)] .**>
			SearchResultDetails[] results				
		}	
	}
	
	<**	@description : configurationChanged = This signal is sent to the clients when one or more configuration settings changes.**>
	broadcast configurationChanged {
		out {
			<**	@description : changedSettings array[setting].**>
			Settings[] changedSettings
		}
	}

	<**	@description : categoriesRemoved = This signal is emitted when a list of categories and associated content has been removed from the database.**>
	broadcast categoriesRemoved {
		out {
			<**	@description : List of categories removed.**>
			CategoryID[] categories
		}
	}

	<**	@description : poiAdded = This signal is emitted when a list of POIs and associated content has been added to the database. It returns the ids.**>
	broadcast poiAdded {
		out {
			<**	@description : List of unique ids of POIs added. The order is the same as the order in the AddPOIs method.**>
			POI_ID[] pois
		}
	}

	<**	@description : poiRemoved = This signal is emitted when a list of POIs and associated content has been removed from the database.**>
	broadcast poiRemoved {
		out {
			<**	@description : List of unique ids of POIs removed.**>
			POI_ID[] pois
		}
	}

	<**	@description : SearchStatusChanged = This signal updates the search or proximity alert status of the specified handle.**>	
	broadcast searchStatusChanged {
		out {
			<** @description : poi search unique handle.**>
			Handle poiSearchHandle				
			<** @description : enum(INVALID,NOT_STARTED,SEARCHING,FINISHED, ... ).**>
			SearchStatusState statusValue		
			<** @description : List of pois that match the search (only valid if status is set to SEARCHING or FINISHED, by default empty list).**>
			POI_ID[] pois		
		}
	}
}