path: root/api/poi-service/genivi-poiservice-contentaccessmodule.xml

<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="introspect.xsl"?>
<!-- SPDX-License-Identifier: MPL-2.0
     Copyright (C) 2014, BMW Car IT GmbH, Continental Automotive GmbH, PCA Peugeot Citroën, XS Embedded GmbH, TomTom International B.V., Alpine Electronics R&D Europe GmbH, AISIN AW CO., LTD.,  Neusoft Technology Solutions GmbH, Jaguar Land Rover Limited, Visteon Corporation
     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/.
-->
<node xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" name="/org/genivi/poiservice" xsi:noNamespaceSchemaLocation="introspect.xsd">
  <interface name="org.genivi.poiservice.POIContentAccessModule">
    <version>1.0.0 (19-12-2012)</version>
    <doc>
      <line>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</line>
    </doc>
    <method name="GetVersion">
      <doc>
        <line>GetVersion = This method returns the API version implemented by the content access module.</line>
      </doc>
      <arg name="version" type="(qqqs)" direction="out">
        <doc>
          <line>version = struct(major,minor,micro,date)</line>
          <line>major = when the major changes, then backward compatibility with previous releases is not granted</line>
          <line>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)</line>
          <line>micro = when the micro changes, then backward compatibility with previous releases is granted (bug fixes or documentation modifications)</line>
          <line>date = release date (e.g. 22-05-2012)</line>
        </doc>
      </arg>
    </method>
    <method name="SetLocale">
      <doc>
        <line>SetLocale = This method sets the current language and country</line>
      </doc>
      <arg name="languageCode" type="s" direction="in">
        <doc>
          <line>languageCode = ISO 639‐3 language code (lower case)</line>
        </doc>
      </arg>
      <arg name="countryCode" type="s" direction="in">
        <doc>
          <line>countryCode = ISO 3166‐1 alpha 3 country code (upper case)</line>
        </doc>
      </arg>
      <arg name="scriptCode" type="s" direction="in">
        <doc>
          <line>scriptCode= ISO 15924 alpha 4 script code (upper case)</line>
        </doc>
      </arg>
    </method>
    <method name="GetLocale">
      <doc>
        <line>GetLocale = This method retrieves the current language and country</line>
      </doc>
      <arg name="languageCode" type="s" direction="out">
        <doc>
          <line>languageCode = ISO 639‐3 language code (lower case)</line>
        </doc>
      </arg>
      <arg name="countryCode" type="s" direction="out">
        <doc>
          <line>countryCode = ISO 3166‐1 alpha 3 country code (upper case)</line>
        </doc>
      </arg>
      <arg name="scriptCode" type="s" direction="out">
        <doc>
          <line>scriptCode= ISO 15924 alpha 4 script code (upper case)</line>
        </doc>
      </arg>
    </method>
    <method name="GetSupportedLocales">
      <doc>
        <line>GetSupportedLocales = This method retrieves the supported languages and countries</line>
      </doc>
      <arg name="localeList" type="a(sss)" direction="out">
        <doc>
          <line>localeList = array[struct(languageCode,countryCode)]</line>
          <line>languageCode = ISO 639-3 language code (lower case)</line>
          <line>countryCode = ISO 3166-1 alpha 3 country code (upper case)</line>
          <line>scriptCode = ISO 15924 alpha 4 script code (upper case)</line>
        </doc>
      </arg>
    </method>
    <method name="GetAvailableCategories">
      <doc>
        <line>GetAvailableCategories = This method retrieves the list of POI categories available (pre-defined and custom).</line>
      </doc>
      <arg name="categories" type="a(usb)" direction="out">
        <doc>
          <line>categories = array[struct(id, name, top_level)]</line>
          <line>id = enum(INVALID,ALL_CATEGORIES,AIRPORT,RESTAURANT,HOTEL,GAZ_STATION,CAR_PARK, ...)</line>
          <line>name = name to be displayed by application</line>
          <line>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.</line>
          <line>Note: A POI category is a unique ID.</line>
        </doc>
      </arg>
    </method>
    <method name="GetRootCategory">
      <doc>
        <line>GetRootCategory = Get the root category id. That would be ALL_CATEGORIES.</line>
      </doc>
      <arg name="category" type="u" direction="out">
        <doc>
          <line>id = ALL_CATEGORIES</line>
          <line>The root category is a top level one by design.</line>
        </doc>
      </arg>
    </method>
    <method name="GetChildrenCategories">
      <doc>
        <line>GetChildrenCategories = Get the children categories id and type (top level) from the a parent unique id.</line>
      </doc>
      <arg name="category" type="u" direction="in">
        <doc>
          <line>unique category id</line>
        </doc>
      </arg>
      <arg name="categories" type="a(ub)" direction="out">
        <doc>
          <line>categories = array[struct(id, top_level)]</line>
          <line>id = enum(INVALID,ALL_CATEGORIES,AIRPORT,RESTAURANT,HOTEL,GAZ_STATION,CAR_PARK, ...)</line>
          <line>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.</line>
        </doc>
      </arg>
      <error name="org.genivi.poiservice.poiSearch.Error.InvalidCategory">
        <doc>
          <line>The category is not available.</line>
        </doc>
      </error>
    </method>
    <method name="GetParentCategories">
      <doc>
        <line>GetParentCategories = Get the parent categories id and type (top level) from the a unique id.</line>
      </doc>
      <arg name="category" type="u" direction="in">
        <doc>
          <line>unique category id</line>
        </doc>
      </arg>
      <arg name="categories" type="a(ub)" direction="out">
        <doc>
          <line>categories = array[struct(id, top_level)]</line>
          <line>id = enum(INVALID,ALL_CATEGORIES,AIRPORT,RESTAURANT,HOTEL,GAZ_STATION,CAR_PARK, ...)</line>
          <line>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.</line>
        </doc>
      </arg>
      <error name="org.genivi.poiservice.poiSearch.Error.InvalidCategory">
        <doc>
          <line>The category is not available.</line>
        </doc>
      </error>
    </method>
    <method name="createCategory">
      <doc>
        <line>createCategory = Creates a category by name and return an unique id.</line>
      </doc>
      <arg direction="in" name="category" type="((au(yv)ss(yv))a(usia(is(yv)))a(us))">
        <doc>
          <line>category (of type CAMCategory) = List of details for the category to create.</line>
          <line>CAMCategory struct[details, attributeList, sortOptions] = </line>
          <line>0: CAMCategory.details ('?') = struct(list of parents_id, icons, name, short_desc, media).</line>
          <line>1: CAMCategory.attributeList ('?') = array[struct(name, type, array[struct(operator_id, operator_name)])].</line>
          <line>2: CAMCategory.sortOptions ('?') = array[struct(id, name)].</line>
        </doc>
      </arg>
      <arg direction="out" name="unique_id" type="u">
        <doc>
          <line>unique_id (of type CategoryID) = Category unique id.</line>
          <line>lineComment to be defined</line>
        </doc>
      </arg>
    </method>
    <method name="removeCategories">
      <doc>
        <line>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.</line>
      </doc>
      <arg direction="in" name="categories" type="au">
        <doc>
          <line>categories (of type CategoryID) = List of categories to be removed.</line>
          <line>lineComment to be defined</line>
        </doc>
      </arg>
    </method>
    <method name="addPOIs">
      <doc>
        <line>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</line>
      </doc>
      <arg direction="in" name="unique_id" type="u">
        <doc>
          <line>unique_id (of type CategoryID) = Category unique id.</line>
          <line>lineComment to be defined</line>
        </doc>
      </arg>
      <arg direction="in" name="poiList" type="a(s(ddd)a(ui(yv)))">
        <doc>
          <line>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</line>
          <line>PoiAddedDetails struct[name, location, attributeList] = </line>
          <line>0: PoiAddedDetails.name ('s') = POI name</line>
          <line>1: PoiAddedDetails.location ('?') = POI location.</line>
          <line>2: PoiAddedDetails.attributeList ('?') = array[struct(id,type,value)].</line>
        </doc>
      </arg>
    </method>
    <method name="removePOIs">
      <doc>
        <line>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.</line>
      </doc>
      <arg direction="in" name="ids" type="au">
        <doc>
          <line>ids (of type POI_ID) = List of unique ids of POIs to remove.</line>
          <line>lineComment to be defined</line>
        </doc>
      </arg>
    </method>
    <method name="PoiSearchStarted">
      <doc>
        <line>PoiSearchStarted = This method is sent by the POI service component to inform all the CAM that a new POI search was started.</line>
        <line>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.</line>
      </doc>
      <arg name="poiSearchHandle" type="u" direction="in">
        <doc>
          <line>poiSearchHandle = poi search unique handle. It must be used by the CAM to send the list of results to the component.</line>
        </doc>
      </arg>
      <arg name="maxSize" type="q" direction="in">
        <doc>
          <line>maxSize = max size of the results list</line>
        </doc>
      </arg>
      <arg name="location" type="(ddd)" direction="in">
        <doc>
          <line>location = struct(lat,lon,alt)</line>
          <line>lat = latitude of a vertex of the polygon in format %3.6f. Range [-90:+90]. Example: 48.053250</line>
          <line>lon = longitude of a vertex of the polygon in format %3.6f. Range [-180:+180]. Example: 48.053250</line>
          <line>alt = altitude above the sea level of the current position in meters</line>
        </doc>
      </arg>
      <arg name="poiCategories" type="a(uu)" direction="in">
        <doc>
          <line>poiCategories = array[struct(category, radius)]</line>
          <line>category = enum(INVALID,ALL_CATEGORIES,AIRPORT,RESTAURANT,HOTEL,GAZ_STATION,CAR_PARK, ...)</line>
          <line>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.</line>
          <line>Note: A POI category is a unique ID. It could be a predifined category or a custom one defined by a POI plug-in.</line>
        </doc>
      </arg>
      <arg name="poiAttributes" type="a(uui(yv)ib)" direction="in">
        <doc>
          <line>poiAtttributes = array[struct(id, categoryId, type, value, oper, mandatory)]</line>
          <line>id = attribute unique id (see data model)</line>
          <line>categoryId = enum(INVALID,ALL_CATEGORIES,AIRPORT,RESTAURANT,HOTEL,GAZ_STATION,CAR_PARK, ...)</line>
          <line>type = enum(INVALID,STRING,INTEGER,COORDINATES ...)</line>
          <line>value = value or partial value. The value depends on the attribute specifications and type.</line>
          <line>oper = enum(INVALID,MORE_THAN,LESS_THAN,EQUAL, ....)</line>
          <line>mandatory = true if the attribute is mandatory for the search and false for optional.</line>
        </doc>
      </arg>
      <arg name="inputString" type="s" direction="in">
        <doc>
          <line>inputString = contains the name of the poi that is searched. It could be a partial name or an empty string.</line>
        </doc>
      </arg>
      <arg name="sortOption" type="q" direction="in">
        <doc>
          <line>sortOption = enum(SORT_DEFAULT,SORT_BY_DISTANCE,SORT_BY_TIME,ATTRIBUTE_CUSTOM, ... )</line>
          <line>If more than one category was defined for this search, the sort criteria should be compliant with all categories.</line>
        </doc>
      </arg>
    </method>
    <method name="PoiSearchCanceled">
      <doc>
        <line>PoiSearchCanceled = This method cancels the search for the current id</line>
      </doc>
      <arg name="poiSearchHandle" type="u" direction="in">
        <doc>
          <line>poiSearchHandle = poi search unique handle</line>
        </doc>
      </arg>
    </method>
    <method name="ResultListRequested">
      <doc>
        <line>ResultListRequested = This method provides the poi results list found by the CAM.</line>
        <line>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.</line>
      </doc>
      <arg name="camId" type="y" direction="in">
        <doc>
          <line>camId = Content access module unique id as known by the POI service component.</line>
        </doc>
      </arg>
      <arg name="poiSearchHandle" type="u" direction="in">
        <doc>
          <line>poiSearchHandle = poi search unique handle</line>
        </doc>
      </arg>
      <arg name="attributeList" type="au" direction="in">
        <doc>
          <line>attributeList = List of attributes id to retrieve. This is optional and the list could be empty.</line>
        </doc>
      </arg>
      <arg name="statusValue" type="q" direction="out">
        <doc>
          <line>statusValue = enum(INVALID,NOT_STARTED,SEARCHING,FINISHED, ... )</line>
        </doc>
      </arg>
      <arg name="resultListSize" type="q" direction="out">
        <doc>
          <line>resultListSize = Number of items of the results list</line>
        </doc>
      </arg>
      <arg name="resultList" type="a(usu(ddd)qa(ui(yv)))" direction="out">
        <doc>
          <line>resultList = array[source_id,name, category, location, distance, attributeList]</line>
          <line>source_id = POI unique id as known by the content access module. This id will be used by POI service to request POI details.</line>
          <line>name = POI name</line>
          <line>category = POI category unique id</line>
          <line>location = struct(lat,lon,alt)</line>
          <line>POI location</line>
          <line>lat = latitude of a vertex of the polygon in format %3.6f. Range [-90:+90]. Example: 48.053250</line>
          <line>lon = longitude of a vertex of the polygon in format %3.6f. Range [-180:+180]. Example: 48.053250</line>
          <line>alt = altitude above the sea level of the current position in meters</line>
          <line>distance = distance in meters to poi from center of the search</line>
          <line>attributeList = array[struct(name, type, value)]</line>
          <line>List of attributes requested. It could be empty.</line>
          <line>id = attribute unique id (see data model)</line>
          <line>type = enum(INVALID,STRING,INTEGER,COORDINATES ...)</line>
          <line>value = value. The value depends on the attribute specifications and type.</line>
        </doc>
      </arg>
      <error name="org.genivi.poiservice.poiContentAccess.Error.CamNotAvailable">
        <doc>
          <line>This error is generated if an application tries to send data to the POI service component but the CAM id is not registered.</line>
        </doc>
      </error>
      <error name="org.genivi.poiservice.poiSearch.Error.HandleNotAvailable">
        <doc>
          <line>This error is generated if an application tries to use a poi search unique handle that is not available or not valid</line>
        </doc>
      </error>
      <error name="org.genivi.poiservice.poiContentAccess.Error.InvalidCategory">
        <doc>
          <line>The category associated to a POI is not valid or was not added by the CAM to the component.</line>
        </doc>
      </error>
    </method>
    <method name="PoiDetailsRequested">
      <doc>
        <line>PoiDetailsRequested = This method retrieves the details associated to one or more POI.</line>
        <line>It contains the name, the parent categories, the list of attributes, the icons, ... .</line>
      </doc>
      <arg name="source_id" type="au" direction="in">
        <doc>
          <line>list of poi = Unique source poi id</line>
        </doc>
      </arg>
      <arg name="results" type="a((us(ddd))aua(ui(yv)))" direction="out">
        <doc>
          <line>results = array[details, categories, attributeList]</line>
          <line>results = List of details for all the POI.</line>
          <line>details = struct(unique id, name, location)</line>
          <line>source id = POI id</line>
          <line>name = POI name</line>
          <line>location = struct(lat,lon,alt)</line>
          <line>lat = latitude of a vertex of the polygon in format %3.6f. Range [-90:+90]. Example: 48.053250</line>
          <line>lon = longitude of a vertex of the polygon in format %3.6f. Range [-180:+180]. Example: 48.053250</line>
          <line>alt = altitude above the sea level of the current position in meters</line>
          <line>categories = array[id]</line>
          <line>id = enum(INVALID,ALL_CATEGORIES,AIRPORT,RESTAURANT,HOTEL,GAZ_STATION,CAR_PARK, ...)</line>
          <line>attributeList = array[struct(id, type, value)]</line>
          <line>id = attribute unique name (see data model)</line>
          <line>type = enum(INVALID,STRING,INTEGER,COORDINATES ...)</line>
          <line>value = value. The value depends on the attribute specifications and type.</line>
          <line>Note: This list only contains the available attributes. If there is no value for an optional attributes, it is not returned.</line>
        </doc>
      </arg>
      <error name="org.genivi.poiservice.poiContentAccess.Error.CamNotAvailable">
        <doc>
          <line>This error is generated if an application tries to send data to the POI service component but the CAM id is not registered.</line>
        </doc>
      </error>
      <error name="org.genivi.poiservice.poiContentAccess.Error.InvalidPoiSourceId">
        <doc>
          <line>The poi unique source id is not valid for the content access module.</line>
        </doc>
      </error>
    </method>
    <signal name="ConfigurationChanged">
      <doc>
        <line>ConfigurationChanged = This signal is sent to the clients when one or more configuration settings changes</line>
      </doc>
      <arg name="changedSettings" type="aq">
        <doc>
          <line>changedSettings = array[setting]</line>
          <line>setting = enum(INVALID,UNITS_OF_MEASUREMENT,LOCALE,TIME_FORMAT,COORDINATES_FORMAT, ... )</line>
        </doc>
      </arg>
    </signal>
    <signal name="CategoriesRemoved">
      <doc>
        <line>CategoriesRemoved = CategoriesRemoved = This signal is emitted when a list of categories and associated content has been removed from the database.</line>
      </doc>
      <arg direction="out" name="categories" type="au">
        <doc>
          <line>categories (of type CategoryID) = List of categories removed.</line>
          <line>lineComment to be defined</line>
        </doc>
      </arg>
    </signal>
    <signal name="POIAdded">
      <doc>
        <line>POIAdded = POIAdded = This signal is emitted when a list of POIs and associated content has been added to the database. It returns the ids.</line>
      </doc>
      <arg direction="out" name="pois" type="au">
        <doc>
          <line>pois (of type POI_ID) = List of unique ids of POIs added. The order is the same as the order in the AddPOIs method.</line>
          <line>lineComment to be defined</line>
        </doc>
      </arg>
    </signal>
    <signal name="POIRemoved">
      <doc>
        <line>POIRemoved = POIRemoved = This signal is emitted when a list of POIs and associated content has been removed from the database.</line>
      </doc>
      <arg direction="out" name="pois" type="au">
        <doc>
          <line>pois (of type POI_ID) = List of unique ids of POIs removed.</line>
          <line>lineComment to be defined</line>
        </doc>
      </arg>
    </signal>
    <signal name="SearchStatusChanged">
      <doc>
        <line>SearchStatusChanged = SearchStatusChanged = This signal updates the search or proximity alert status of the specified handle.</line>
      </doc>
      <arg direction="out" name="poiSearchHandle" type="u">
        <doc>
          <line>poiSearchHandle (of type Handle) = poi search unique handle.</line>
          <line>lineComment to be defined</line>
        </doc>
      </arg>
      <arg direction="out" name="statusValue" type="i">
        <doc>
          <line>statusValue (of type SearchStatusState) = enum(INVALID,NOT_STARTED,SEARCHING,FINISHED, ... ).</line>
          <line>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))]</line>
        </doc>
      </arg>
      <arg direction="out" name="pois" type="au">
        <doc>
          <line>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).</line>
          <line>lineComment to be defined</line>
        </doc>
      </arg>
    </signal>
  </interface>
</node>