path: root/api/franca/navigation/poiservice/POISearch.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 POISearch {
	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 : This method allows the application to validate that POI categories are supported by the POI component and the Content access modules.**>
	method validateCategories {
		in {
			<** @description : list of categories enum(INVALID,ALL_CATEGORIES,AIRPORT,RESTAURANT,HOTEL,GAZ_STATION,CAR_PARK, ...)
            Note: A POI category is a unique ID. It could be a predifined category or a custom one defined by a POI plug-in.**>
			CategoryID[] categories				
		}	
		out {
			<** @description : List of status for all the POI categories.**>
			CategoryAndStatus[] results				
		}
	}
	
	<**	@description : This method retrieves the list of 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 : Get the categories that are marked with the given standard category. **>
	method getCategoriesWithStandardCategoryId {
		in {
			<** @description : Categories marked with "standardCategoryId" should be returned. **>
			StandardCategory standardCategoryId			
		} out {
			<** @description : List of categories that are marked with the requested standard category. **>
			CategoryID[] categories
		}
	}
	
	<**	@description : This method retrieves the details associated to one or more POI categories.
        It contains the name, the parent categories, the top level attribute, the list of attributes, the icons, ... .**>
	method getCategoriesDetails {
		in {
			<** @description : list of categories enum(INVALID,ALL_CATEGORIES,AIRPORT,RESTAURANT,HOTEL,GAZ_STATION,CAR_PARK, ...)
            Note: A POI category is a unique ID. It could be a predefined category or a custom one defined by a POI plug-in. **>
			CategoryID[] categories				
		}	
		out {
			<** @description : List of details for all the POI categories.**>
			Category[] results
		}
	}
	
	<** @description : This method creates a new search input and retrieves a handle .**>
	method createPoiSearchHandle {
		out {
			<** @description : poi search unique handle.**>
			Handle poiSearchHandle				
		}
	}

	<**	@description : This method deletes a search input and its associated resources.**>
	method deletePoiSearchHandle {
		in {
			<** @description : poi search unique handle.**>
			Handle poiSearchHandle				
		}	
	}

	<**	@description : This method sets the location to start the search around.
        If a route handle was defined before, it will be replaced by this location.**>
	method setCenter {
		in {
			<** @description : poi search unique handle.**>
			Handle poiSearchHandle				
			<** @description : location of the center.**>
			Coordinate3D location				
		}	
	}
	
	<**	@description : This method allows to start a POI search along a guided route.
        The route handle must be valid or the POI search will failed.
        If a search location was defined before, it will be replaced by the route.**>
	method setRouteHandle {
		in {
			<** @description : poi search unique handle.**>
			Handle poiSearchHandle				
			<** @description : session handle.**>
			Handle sessionHandle
			<** @description : route handle.**>
			Handle routeHandle
			<** @description : (optional) Distance from vehicle (in meters) from where to start the search along. 0 or invalid distance means start from vehicle.**>
			UInt32 startSearchOffset				
			<** @description : (optional) Length of the route (in meters) from where to start the search along. 0 or invalid lenght means end is the destination.**>
			UInt32 endSearchOffset				
		}		
	}
	
	<**	@description : This method sets the POI categories for the current search input and the corresponding result-lists for the current session .**>
	method setCategories {
		in {
			<** @description : poi search unique handle.**>
			Handle poiSearchHandle				
			<** @description: array[struct(id,radius)].**>						
			CategoryAndRadius[] poiCategories		
			}	
	}
	<**	@description : This method set POI attributes (optional) for the current search input and the corresponding result-lists for the current session
        An attribute is attached to a category.**>
	method setAttributes {
		in {
			<** @description : poi search unique handle.**>
			Handle poiSearchHandle				
			<** @description : array[struct(name, poiCategory, type, value, operator, mandatory)].**>
			AttributeDetails[] poiAttributes 
		}
	}	
	
	<**	@description : This method sends the search input for the search handle.
        The search will start with the either the location or the route handle.
        If no positon or route handle were configured, the search will use the vehicle position are center location.**>
	method startPoiSearch {
		in {
			<** @description : poi search unique handle.**>
			Handle poiSearchHandle				
			<** @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 session.**>
	method cancelPoiSearch {
		in {
			<** @description : poi search unique handle.**>
			Handle poiSearchHandle				
		}
	}
	
	<**	@description : This method starts to check for POI aound vehicle according to the criteria defined with the unique handle.
        By default, it will search for POI around vehicle position with default radius defined for each categories.
        If a route handle was defined, it will search along the route with default categorie's radius.**>
	method startPoiProximityAlert {
		in {
			<** @description : poi alert unique handle.**>
			Handle poiSearchHandle				
			<** @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 session.**>
	method cancelPoiProximityAlert {
		in {
			<** @description : poi alert unique handle.**>
			Handle poiSearchHandle				
		}
	}
	
	<**	@description : This method gets the poi result list (e.g. after a Search/Scroll call) .**>
	method requestResultList {
		in {
			<** @description : poi search unique handle.**>
			Handle poiSearchHandle				
			<** @description : starting offset of the newly requested list elements. If invalid (more that total list for instance) it starts from the begining.**>
			UInt16 offset				
			<** @description : maximum number of elements that should be returned as result.**>
			UInt16 maxWindowSize				
			<** @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[unique_id, distance, route_status, attributes].**>
			SearchResult[] resultListWindow				
		}
	}
	
	<**	@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 getPoiDetails {
		in {
			<** @description : list of poi.**>
			POI_ID[] id				
		}	
		out {
			<** @description : array[details, categories, attributes].**>
			SearchResultDetails[] results				
		}
	}	
		
	<**	@description : This signal indicates that one or more POI categories were added, updated or removed.**>	
	broadcast categoriesUpdated {
		out {
			<**	@description : List of POI categories modified or added.**>
			CategoryAndReason[] poiCategories			
		}
	}
	
	<**	@description : This signal updates the search or proximity alert status of the specified handle.**>	
	broadcast poiStatus {
		out {
			<** @description : poi search unique handle.**>
			Handle poiSearchHandle				
			<** @description : enum(INVALID,NOT_STARTED,SEARCHING,FINISHED, ... ).**>
			SearchStatusState statusValue				
		}
	}
	
	<**	@description : This signal updates in the poi results list.**>	
	broadcast resultListChanged {
		out {
			<** @description : poi search unique handle.**>
			Handle poiSearchHandle				
			<** @description : Number of items of the results list.**>
			UInt16 resultListSize				
		}
	}
}