1.0.0 (19-12-2012) This interface offers methods that implement the POI search functionality of a navigation system GetVersion = This method returns the API version implemented by the server application version = struct(major,minor,micro,date) major = when the major changes, then backward compatibility with previous releases is not granted minor = when the minor changes, then backward compatibility with previous releases is granted, but something changed in the implementation of the API (e.g. new methods may have been added) micro = when the micro changes, then backward compatibility with previous releases is granted (bug fixes or documentation modifications) date = release date (e.g. 22-05-2012) ValidateCategories = This method allows the application to validate that POI categories are supported by the POI component and the Content access modules. categories = array[id] id = enum(INVALID,ALL_CATEGORIES,AIRPORT,RESTAURANT,HOTEL,GAZ_STATION,CAR_PARK, ...) Note: A POI category is a unique ID. results = array[unique_id, status] results = List of status for all the POI categories. unique id = category id status = true if the category is available. GetAvailableCategories = This method retrieves the list of POI categories available (pre-defined and custom). categories = array[struct(id, name, top_level)] id = enum(INVALID,ALL_CATEGORIES,AIRPORT,RESTAURANT,HOTEL,GAZ_STATION,CAR_PARK, ...) name = name to be displayed by application top_level = true if the category is a pre-defined one (top level with only ALL_CATEGORIES as parent), false for customized categories created by plug-in. Note: A POI category is a unique ID. GetRootCategory = Get the root category id. That would be ALL_CATEGORIES. id = ALL_CATEGORIES The root category is a top level one by design. GetChildrenCategories = Get the children categories id and type (top level) from the a parent unique id. unique category id categories = array[struct(id, top_level)] id = enum(INVALID,ALL_CATEGORIES,AIRPORT,RESTAURANT,HOTEL,GAZ_STATION,CAR_PARK, ...) top_level = true if the category is a pre-defined one (top level with only ALL_CATEGORIES as parent), false for customized categories created by plug-in. The category is not available. GetParentCategories = Get the parent categories id and type (top level) from the a unique id. unique category id categories = array[struct(id, top_level)] id = enum(INVALID,ALL_CATEGORIES,AIRPORT,RESTAURANT,HOTEL,GAZ_STATION,CAR_PARK, ...) top_level = true if the category is a pre-defined one (top level with only ALL_CATEGORIES as parent), false for customized categories created by plug-in. The category is not available. GetCategoriesWithStandardCategoryId = Get the categories that are marked with the given standard category. Categories marked with "standardCategoryId" should be returned. List of categories that are marked with the requested standard category. GetCategoriesDetails = 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, ... . 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. results = array[details, attributeList, sortOptions] results = List of details for all the POI categories. details = struct(unique_id, list of parents_id, icons, name, top_level, short_desc, media)] unique_id = Category unique id standardCategoryId = enum(...) Identifier for the POI Standard Category that describes the semantic meaning of the POI Category. parents_id = list of parent categories unique id icons = visual icons set name = name top_level = true if the category is a predefined one (top level), false for customized categories created by plug-in. short_desc = short category description (optional) media = media associated (html web site, audio, video, ...) (optional) attributeList = array[struct(id, name, type, array[struct(operator_type, operator_name, operator_value)]) id = attribute unique id name = attribute unique name type = enum(INVALID,STRING,INTEGER,COORDINATES ...) operator_type = enum(INVALID,MORE_THAN,LESS_THAN,EQUAL, ....) operator_name = attribute operator name operator_value = attribute value sortOptions = array[struct(id, name)] id = enum(SORT_DEFAULT,SORT_BY_DISTANCE,SORT_BY_TIME,ATTRIBUTE_CUSTOM, ... ) name = name to be displayed by application The category is not available. If there are more than one category and one of them is not available, no detailed will be returned for this category but there will be no error. CategoriesUpdated = This signal indicates that one or more POI categories were added, updated or removed. poiCategories = array[struct(unique_id, reason)] List of POI categories modified or added. unique_id = Unique category id reason = enum(ADDED,REMOVED,ATTR_ADDED,ATTR_MODIFIED,ATTR_REMOVED, ... ) CreatePoiSearchHandle = This method creates a new location input and retrieves a handle poiSearchHandle = poi search unique handle This error is generated if no more poi search unique handles are available DeletePoiSearchHandle = This method deletes a location input and its associated resources poiSearchHandle = poi search unique handle This error is generated if an application tries to delete a poi search unique handle that is not available SetCenter = This method sets the location to start the search around. If a route handle was defined before, it will be replaced by this location. poiSearchHandle = poi search unique handle location = struct(lat,lon,alt) lat = latitude of a vertex of the polygon in format %3.6f. Range [-90:+90]. Example: 48.053250 lon = longitude of a vertex of the polygon in format %3.6f. Range [-180:+180]. Example: 48.053250 alt = altitude above the sea level of the current position in meters This error is generated if an application tries to set invalid coordinates. This error is generated if an application tries to change the search criteria but the search is on-going and could not be updated. This error is generated if an application tries to use a poi search unique handle that is not available or not valid SetRouteHandle = 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. poiSearchHandle = poi search unique handle sessionHandle = session handle routeHandle = route handle. startSearchOffset (optional) = Distance from vehicle (in meters) from where to start the search along. 0 or invalid distance means start from vehicle. endSearchOffset (optional) = Lenght of the route (in meters) from where to start the search along. 0 or invalid lenght means end is the destination. This error is generated if an application tries to set invalid route handle. This error is generated if an application tries to change the search criteria but the search is on-going and could not be updated. This error is generated if an application tries to use a poi search unique handle that is not available or not valid SetCategories = This method sets the POI categories for the current search input and the corresponding result-lists for the current session poiSearchHandle = poi search unique handle poiCategories = array[struct(category, radius)] category = enum(INVALID,ALL_CATEGORIES,AIRPORT,RESTAURANT,HOTEL,GAZ_STATION,CAR_PARK, ...) radius = activation or search radius around the position (in 10 meters) for the category. If value is 0 (zero), the default radius (defined for a category) is applied. Note: A POI category is a unique ID. It could be a predifined category or a custom one defined by a POI plug-in. This error is generated if an application tries to set one or more invalid poi categories. This error is generated if an application tries to change the search criteria but the search is on-going and could not be updated. This error is generated if an application tries to use a poi search unique handle that is not available or not valid SetAttributes = 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 poiSearchHandle = poi search unique handle poiAtttributes = array[struct(id, categoryId, type, value, oper, mandatory)] id = attribute unique id (see data model) categoryId = enum(INVALID,ALL_CATEGORIES,AIRPORT,RESTAURANT,HOTEL,GAZ_STATION,CAR_PARK, ...) type = enum(INVALID,STRING,INTEGER,COORDINATES ...) value = value or partial value. The value depends on the attribute specifications and type. oper = enum(INVALID,MORE_THAN,LESS_THAN,EQUAL, ....) mandatory = true if the attribute is mandatory for the search and false for optional. This error is generated if an application tries to set one or more invalid poi attributes. This error is generated if an application tries to change the search criteria but the search is on-going and could not be updated. This error is generated if an application tries to use a poi search unique handle that is not available or not valid StartPoiSearch = 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. poiSearchHandle = poi search unique handle inputString = contains the name of the poi that is searched. It could be a partial name or an empty string. sortOption = 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. This error is generated if an application tries to use a poi search unique handle that is not available or not valid This error is generated if an application tries to start a search without, at least, one poi category defined. This error is generated if an application tries to start a search without a valid location (coordinates or route handle) defined. CancelPoiSearch = This method cancels the search for the current session poiSearchHandle = poi search unique handle This error is generated if an application tries to use a poi search unique handle that is not available or not valid StartPoiProximityAlert = This method starts to check for POI aound vehicle according to the criteria defined with the unique handle. Bt 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. poiSearchHandle = poi alert unique handle inputString = contains the name of the poi that is searched. It could be a partial name or an empty string. sortOption = 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. This error is generated if an application tries to use a poi search unique handle that is not available or not valid This error is generated if an application tries to start a search without, at least, one poi category defined. CancelPoiProximityAlert = This method cancels the search for the current session poiSearchHandle = poi alert unique handle This error is generated if an application tries to use a poi search unique handle that is not available or not valid PoiStatus = This signal updates the search or proximity alert status of the specified handle. poiSearchHandle = poi search unique handle statusValue = enum(INVALID,NOT_STARTED,SEARCHING,FINISHED, ... ) ResultListChanged = This signal updates in the poi results list poiSearchHandle = poi search unique handle resultListSize = Number of items of the results list RequestResultList = This method gets the poi result list (e.g. after a Search/Scroll call) poiSearchHandle = poi search unique handle offset = starting offset of the newly requested list elements. If invalid (more that total list for instance) it starts from the begining. maxWindowSize = maximum number of elements that should be returned as result attributeList = List of attributes id to retrieve. This is optional and the list could be empty. statusValue = enum(INVALID,NOT_STARTED,SEARCHING,FINISHED, ... ) resultListSize = Number of items of the results list resultListWindow = array[unique_id, distance, route_status, attributeList] unique_id = POI unique id distance = distance in meters to poi from center of the search or from vehicle if search along route_status = enum(OFF_ROUTE,ON_ROUTE,INSIDE_CORRIDOR, ... ) attributeList = array[struct(id, type, value)] List of attributes requested. It could be empty. id = attribute unique id (see data model) type = enum(INVALID,STRING,INTEGER,COORDINATES ...) value = value. The value depends on the attribute specifications and type. This error is generated if an application tries to use a poi search unique handle that is not available or not valid This error is generated if an application tries to get one or more invalid poi attributes. GetPoiDetails = This method retrieves the details associated to one or more POI. It contains the name, the parent categories, the list of attributes, the icons, ... . list of poi[unique_id] unique_id = POI unique id results = array[details, categories, attributeList] results = List of details for all the POI. details = struct(unique id, name, location) unique_id = POI unique id name = POI name location = struct(lat,lon,alt) lat = latitude of a vertex of the polygon in format %3.6f. Range [-90:+90]. Example: 48.053250 lon = longitude of a vertex of the polygon in format %3.6f. Range [-180:+180]. Example: 48.053250 alt = altitude above the sea level of the current position in meters categories = array[id] id = enum(INVALID,ALL_CATEGORIES,AIRPORT,RESTAURANT,HOTEL,GAZ_STATION,CAR_PARK, ...) attributeList = array[struct(id, type, value)] List of attributes requested. It could be empty. id = attribute unique id (see data model) type = enum(INVALID,STRING,INTEGER,COORDINATES ...) value = value. The value depends on the attribute specifications and type. The poi unique id is not valid.