summaryrefslogtreecommitdiff
path: root/api/franca/navigation/freetextsearch/FreeTextSearch.fidl
blob: f735e8982d44f333380defe101b26c86e76b8175 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
/* 
SPDX-License-Identifier: MPL-2.0
Copyright (C) 2015-2016, 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, Harman-Becker 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.freetextsearch

import org.genivi.navigation.NavigationTypes.* from "../NavigationTypes.fidl"
import org.genivi.navigation.freetextsearch.FreeTextSearchTypes.* from "FreeTextSearchTypes.fidl"


<** @description : This interface offers methods that implement the free text search functionality of a navigation system.**>
interface FreeTextSearch {
	version {
		major 0 
		minor 1
	}

	<**	
		@description : This method returns the API version implemented.
	**>
	method getVersion {
		out {
			<** @description: .**>
			Version ^version				
		}	
	}	

	<** @description : Perform a free text search.
    	The search is associated to a given sessionHandle
    	The method returns a freeTextSearchHandle, an identifier to match a response with a request 
        A single search request will trigger zero or more FtsResultXxx responses followed by an FtsDone response.
        Each response will contain 1 page of results.
        A next page of results can be retrieved with the FtsNextPage request.      
        When you send a new request before receiving a done response on the previous request,
        then the previous request will be canceled.
        You will still get a done response on the previous request.
        This way each request gets a response.
    **>
    method FtsRequest {
        in {
			<**
				@description : Session handle. Range[0x0:0x7fffffff]. 0x0 is reserved as an invalid handle value
			**>
			Handle sessionHandle
    	 	<** @description: Text to match. **>
    	 	FtsString inputString
    	 	<** @description: Location for scoring the search results.
    	 	    A result closer to this location gets a higher score than a result further away.
    	 	**>
    	 	Coordinate2D searchLocation
    	 	<** @description: Limit the search to the union of several shapes (each can be a circle or a rectangle).
    	 	    Pass an empty list to search the whole map.
    	 	**>
    	 	ShapeList searchShapes
    	 	<** @description: The maximum number of addresses and POIs that will be returned. **>
    	 	PageSize pageSize
    	 	<** @description: Options to indicate what to search for.
    	 	    One or more values of TFTSSearchOption can be added together.
    	 	**>
    	 	SearchOptions searchOptions
    	 	<** @description: Additional search conditions, space separated.
    	 	    The string can be empty when the POI search is not limited by categories
    	 	    and not limited by countries/states.
    	 	    Supported conditions:
    	 	        "category:nnnn"  Limit the POI search to a one or more POI categories,
    	 	                         where 'nnnn' is a comma-separated list of numerical POI category ids.
    	 	        "country:aaaaa"  Limit the search to one or more countries (or states),
    	 	                         where 'aaaaa' is a comma-separated list of ISO-3166-1 alpha 3
    	 	                         country code concatenated with an optional ISO-3166-2 state code.
    	 	    Examples:
    	 	    "category:9373,9374": limits the POI search to the union of categories 9373 and 9374.
    	 	    "country:USACA": limits the search to the state of California.
    	 	    "category:6315 country:USACA,MEX": limits the POI search to category 6315
    	 	    and limits the search to the union of California state and Mexico.
    	 	**>
    	 	FtsString searchConditions
    	 	<** @description: Indication of how fuzzy the search shall be performed. **>
    	 	FuzzyLevel fuzzyLevel
    	}
		out {
			<**
				@description : freeTextSearchHandle = free text search handle. Range[0x0:0x7fffffff]. 0x0 is reserved as an invalid handle value
			**>
			Handle freeTextSearchHandle
		}
		error {
			NoMoreFtsHandles
		}
    }

    <** @description : Get next result page for the last performed search.
        This request will trigger zero or more FtsResultXxx responses followed by an FtsDone response.
        If there is no search request done before or if a search request is still in progress
        then the FtsDone response will return a EStatusNoSearchToContinue status.
        To be consistent with POIsearch, the page size can be set to another value if needed
    **>
    method FtsNextPage {
    	in {
			<**
				@description : free text search handle. Range[0x0:0x7fffffff]. 0x0 is reserved as an invalid handle value.
			**>
			Handle freeTextSearchHandle
    	 	<** @description: The maximum number of addresses and POIs that will be returned. **>
    	 	PageSize pageSize
    	 	<** @description: Options to indicate what to search for.
    	 	    One or more values of TFTSSearchOption can be added together.
    	 	    You can only get results for options that have been passed to the initial FtsRequest.
    	 	**>
    	 	SearchOptions searchOptions
    	}
    }
	
	<**
		@description : This method cleans a free text search handle and allows to keep some associated resources if needed.
	**>
	method FtsClean {
		in {
			<**
				@description : session handle. Range[0x0:0x7fffffff]. 0x0 is reserved as an invalid handle value.
			**>
			Handle sessionHandle
			<**
				@description : freeTextSearchHandle = free text search handle. Range[0x0:0x7fffffff]. 0x0 is reserved as an invalid handle value
			**>
			Handle freeTextSearchHandle
    	 	<** 
    	 		@description : list of handles to keep (can be empty). 
    	 	**>
    	 	LocationHandleList locationHandleList
		}
	}
	    
     <** @description: Cancel the last FTS request. **>
    method FtsCancel {
    	
    }

	<**	@description : Response indicating that the search is done. **>	
	broadcast FtsDone selective {
		out {
			<**
				@description : freeTextSearchHandle = free text search handle. Range[0x0:0x7fffffff]. 0x0 is reserved as an invalid handle value.
			**>
			Handle freeTextSearchHandle
    	 	<** @description: Status of the search request. **>
    	 	FtsStatus ftsStatus
		}
	}
		
	<**	@description : Response with address results. **>	
	broadcast FtsResultAddresses selective {
		out {
			<**
				@description : freeTextSearchHandle = free text search handle. Range[0x0:0x7fffffff]. 0x0 is reserved as an invalid handle value.
			**>
			Handle freeTextSearchHandle
    	 	<** @description: Matching addresses.
    	 	    The order of the addresses is the order of matching relevance.
    	 	    The first address is a better match than the last result.
    	 	**>
    	 	Addresses addresses
    	 	<** @description: Flag to indicate if more addresses might be available in a next page. **>
    	 	Boolean moreAvailable
		}
	}
	
	<**	@description : Response with POI results. **>	
	broadcast FtsResultPois selective {
		out {
			<**
				@description : freeTextSearchHandle = free text search handle. Range[0x0:0x7fffffff]. 0x0 is reserved as an invalid handle value
			**>
			Handle freeTextSearchHandle
    	 	<** @description: Matching POIs.
    	 	    The order of the POIs is the order of matching relevance.
    	 	    The first POI is a better match than the last result.
    	 	**>
    	 	POIs pois
    	 	<** @description: Flag to indicate if more POIs might be available in a next page. **>
    	 	Boolean moreAvailable
		}
	}
		
	<**	@description : Response with POI category suggestions. **>	
	broadcast FtsResultPoiCategorySuggestions selective {
		out {
			<**
				@description : freeTextSearchHandle = free text search handle. Range[0x0:0x7fffffff]. 0x0 is reserved as an invalid handle value
			**>
			Handle freeTextSearchHandle
    	 	<** @description: POI category suggestions. **>
    	 	POICategories poiCategories
		}
	}
		
}