1.0.0 (19-12-2012) This interface offers a set of common methods to the POI components to deal with all the content access modules (CAM). The CAM provide and update POI and categories information from remote sources to the POIService modules GetVersion = This method returns the API version implemented by the content access module. 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) SetLocale = This method sets the current language and country languageCode = ISO 639‐3 language code (lower case) countryCode = ISO 3166‐1 alpha 3 country code (upper case) scriptCode= ISO 15924 alpha 4 script code (upper case) GetLocale = This method retrieves the current language and country languageCode = ISO 639‐3 language code (lower case) countryCode = ISO 3166‐1 alpha 3 country code (upper case) scriptCode= ISO 15924 alpha 4 script code (upper case) GetSupportedLocales = This method retrieves the supported languages and countries localeList = array[struct(languageCode,countryCode)] languageCode = ISO 639-3 language code (lower case) countryCode = ISO 3166-1 alpha 3 country code (upper case) scriptCode = ISO 15924 alpha 4 script code (upper case) 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. createCategory = Creates a category by name and return an unique id. category (of type CAMCategory) = List of details for the category to create. CAMCategory struct[details, attributeList, sortOptions] = 0: CAMCategory.details ('?') = struct(list of parents_id, icons, name, short_desc, media). 1: CAMCategory.attributeList ('?') = array[struct(name, type, array[struct(operator_id, operator_name)])]. 2: CAMCategory.sortOptions ('?') = array[struct(id, name)]. unique_id (of type CategoryID) = Category unique id. lineComment to be defined removeCategories = Removes a list of categories. Because of required time to remove it from the database, a signal is emitted when the deletion is done. categories (of type CategoryID) = List of categories to be removed. lineComment to be defined addPOIs = 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 unique_id (of type CategoryID) = Category unique id. lineComment to be defined poiList (of type PoiAddedDetails) = 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 struct[name, location, attributeList] = 0: PoiAddedDetails.name ('s') = POI name 1: PoiAddedDetails.location ('?') = POI location. 2: PoiAddedDetails.attributeList ('?') = array[struct(id,type,value)]. removePOIs = 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. ids (of type POI_ID) = List of unique ids of POIs to remove. lineComment to be defined PoiSearchStarted = 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. poiSearchHandle = poi search unique handle. It must be used by the CAM to send the list of results to the component. maxSize = max size of the results list 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 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. 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. 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. PoiSearchCanceled = This method cancels the search for the current id poiSearchHandle = poi search unique handle ResultListRequested = 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. camId = Content access module unique id as known by the POI service component. poiSearchHandle = poi search unique handle 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 resultList = array[source_id,name, category, location, distance, attributeList] source_id = POI unique id as known by the content access module. This id will be used by POI service to request POI details. name = POI name category = POI category unique id location = struct(lat,lon,alt) POI location 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 distance = distance in meters to poi from center of the search attributeList = array[struct(name, 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 send data to the POI service component but the CAM id is not registered. This error is generated if an application tries to use a poi search unique handle that is not available or not valid The category associated to a POI is not valid or was not added by the CAM to the component. PoiDetailsRequested = 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 source poi id results = array[details, categories, attributeList] results = List of details for all the POI. details = struct(unique id, name, location) source id = POI 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)] id = attribute unique name (see data model) type = enum(INVALID,STRING,INTEGER,COORDINATES ...) value = value. The value depends on the attribute specifications and type. Note: This list only contains the available attributes. If there is no value for an optional attributes, it is not returned. This error is generated if an application tries to send data to the POI service component but the CAM id is not registered. The poi unique source id is not valid for the content access module. ConfigurationChanged = This signal is sent to the clients when one or more configuration settings changes changedSettings = array[setting] setting = enum(INVALID,UNITS_OF_MEASUREMENT,LOCALE,TIME_FORMAT,COORDINATES_FORMAT, ... ) CategoriesRemoved = CategoriesRemoved = This signal is emitted when a list of categories and associated content has been removed from the database. categories (of type CategoryID) = List of categories removed. lineComment to be defined POIAdded = POIAdded = This signal is emitted when a list of POIs and associated content has been added to the database. It returns the ids. pois (of type POI_ID) = List of unique ids of POIs added. The order is the same as the order in the AddPOIs method. lineComment to be defined POIRemoved = POIRemoved = This signal is emitted when a list of POIs and associated content has been removed from the database. pois (of type POI_ID) = List of unique ids of POIs removed. lineComment to be defined SearchStatusChanged = SearchStatusChanged = This signal updates the search or proximity alert status of the specified handle. poiSearchHandle (of type Handle) = poi search unique handle. lineComment to be defined statusValue (of type SearchStatusState) = enum(INVALID,NOT_STARTED,SEARCHING,FINISHED, ... ). enum[INVALID (org.franca.core.franca.impl.FIntegerConstantImpl@12babf4 (val: 0)), NOT_STARTED (org.franca.core.franca.impl.FIntegerConstantImpl@1a3c8e3 (val: 1296)), SEARCHING (org.franca.core.franca.impl.FIntegerConstantImpl@1f53788 (val: 1297)), FINISHED (org.franca.core.franca.impl.FIntegerConstantImpl@bdae21 (val: 1298))] pois (of type POI_ID) = List of pois that match the search (only valid if status is set to SEARCHING or FINISHED, by default empty list). lineComment to be defined