Skip to content

API-Reference

This is an overview of all available commands of the remote interface. In case of an error, a specific Error value will be returned.

Warning

On devices using Android 10 (API level 29) and above, be sure to set the popup permission in the application permission settings. If you don't set it, the app will not come to foreground and some API functions will not work properly.

Commands listed here have to be used as described in this paragraph to work with Android 11 and above!

  • Load a preference file

    MSG_RI_LOAD_PREFERENCES = 129

    Description:

    Load a preferences_import.json file from an external directory.

    This interface copies the file to the 'files' directory of the Navigator (normally located under /sdcard/Android/data/com.ptv.navigation.app/files/) and imports it's values to the navigator.

    A file with the same name in the files directory will be overwritten by this function. The file name can be arbitrary.

    Attention

    • The client software must use a FileProvider to grant access to the file.
    • Loading preferences is only possible when there is currently no navigation running, otherwise, you first have to stop the navigation.

    Loading a file is done by using the android FileProvider class to be able to grant the foreign navigator app access to files of this client (needed for Android >= 10/11). The steps to grant a permission is as following:

    • Create a xml file in the res/xml folder of your project and list all directories in your app namespace that should be able to be accessed from outside, see the res/xml/filepaths.xml file in this project as an example.
    • Add a FileProvider to the manifest file (in the application section). Set the android:resource to above created xml file 
      <provider
     android:name="androidx.core.content.FileProvider"
     android:authorities="com.ptv.navigation.ritest.fileprovider"
     android:exported="false"
     android:grantUriPermissions="true">
     <meta-data
         android:name="android.support.FILE_PROVIDER_PATHS"
         android:resource="@xml/filepaths" />
</provider>
    • Create a file object with the file you want to transfer/share
    • Create an uri for that file with FileProvider.getUriForFile()
    • Grant access permissions to this file for a specific package (here we use the navigator as the receiver) with getContext().grantUriPermission(). Use FLAG_GRANT_READ_URI_PERMISSION for minimal reading permission
    • If wanted, you can revoke the permission after the navigator sent back the response that the file was loaded (the navigator will copy the file to the navigator files directory (files with the same name will be overwritten) to be able to access it, and therefore it is save to revoke the permission after the navigator response).

    For more implementation details, please see the RITest demo app.

    Sending bundle:

    Key Value Type Info
    FileName The name of the preference file with path as uri String

    Returned error codes:

    • RI_ERROR_NONE if everything is ok.
    • RI_ERROR_RI_DISABLED if the Remote Interface service is disabled and/or not licensed.
    • RI_ERROR_NOT_INITIALIZED if the Remote Interface service is not initialized yet.
    • RI_ERROR_FILE_ACCESS if the file could not be loaded (either because of not granted permissions or of other load error).
    • RI_ERROR_NOT_DURING_NAVIGATION if the app is currently navigating.
    • RI_ERROR_NO_LICENSE if the navigator has no valid license.
  • Load a given BCR file and set the target stops according to the stops

    MSG_RI_LOAD_BCR_FROM_EXTERNAL_DIR = 303

    Description:

    Load a BCR file from an external directory.

    This interface copies the file to the temporary bcr directory of the Navigator (normally located under /sdcard/Android/data/com.ptv.navigation.app/files/bcr/) converts it to a json tour file, copies this to the tours directory, deletes the copied bcr file and fills the target stop vector with the stops found in the BCR. A file with the same name in the bcr directory and in the json directory will be overwritten by this function.

    Attention

    The client software must use a FileProvider to grant access to the file.

    Loading a bcr is done by using the android FileProvider class to be able to grant the foreign navigator app access to files of this client (needed for Android >= 10). The steps to grant a permission is as following:

    • Create an xml file in the res/xml folder of your project and list all directories in your app namespace that should be able to be accessed from outside, see the res/xml/filepaths.xml file in this project as an example.
    • Add a FileProvider to the manifest file (in the application section). Set the android:resource to above created xml file 
      <provider
     android:name="androidx.core.content.FileProvider"
     android:authorities="com.ptv.navigation.ritest.fileprovider"
     android:exported="false"
     android:grantUriPermissions="true">
     <meta-data
         android:name="android.support.FILE_PROVIDER_PATHS"
         android:resource="@xml/filepaths" />
</provider>
    • Create a file object with the file you want to transfer/share
    • Create an uri for that file with FileProvider.getUriForFile()
    • Grant access permissions to this file for a specific package (here we use the navigator as the receiver) with getContext().grantUriPermission(). Use FLAG_GRANT_READ_URI_PERMISSION for minimal reading permission
    • If wanted, you can revoke the permission after the navigator sent back the response that the bcr was loaded (the navigator will copy the bcr to the navigator bcr directory (files with the same name will be overwritten) to be able to access it, and therefore it is save to revoke the permission after the navigator response).

    For more implementation details, please see the RITest demo app.

    The visited flags of the target stops will also be set as found.

    Sending bundle:

    Key Value Type Info
    FileName The name of the BCR file with path as uri String

    Returned error codes:

    • RI_ERROR_NONE if everything is ok.
    • RI_ERROR_RI_DISABLED if the Remote Interface service is disabled and/or not licensed.
    • RI_ERROR_NOT_INITIALIZED if the Remote Interface service is not initialized yet.
    • RI_ERROR_NO_LICENSE if the navigator has no valid license.
    • RI_ERROR_NOT_ALLOWED if the start is not allowed in the current fragment.
    • RI_ERROR_FILE_ACCESS if the file could not be loaded (either because of not granted permissions or of other load error).

General commands

  • Set compatibility mode

    MSG_RI_SET_COMPATIBILITY_MODE = 3000

    Description:

    Set the compatibility mode to on/off.

    If on, all bundles returned to the client will have the names and types like in the previous navigator API. If off, the returned bundle includes more information, no deprecated values like MercPosX and in some cases renamed fields and corrected types. We highly recommend to use the non compatible mode because it offers more information and corrected fields.

    Sending bundle:

    Key Value Type Info
    CompatibilityMode Set the compatibility mode boolean

    Returned bundle:

    Key Value Type Info
    CompatibilityMode The set compatibility mode boolean

    Returned error codes:

    • RI_ERROR_NONE if the license key was set.
    • RI_ERROR_RI_DISABLED if the Remote Interface service is disabled and/or not licensed.
    • RI_ERROR_NOT_INITIALIZED if the Remote Interface service is not initialized yet.
    • RI_ERROR_NO_LICENSE if the navigator has no valid license.
  • Bring the Navigator to front

    MSG_BRING_NAVIGATOR_TO_FRONT = 601

    Description:

    Bring the current fragment of the PTV Navigator to the front.

    Returned error codes:

    • RI_ERROR_NONE if everything is ok.
  • Goto start fragment

    MSG_RI_GO_TO_MAIN = 600

    Description:

    Switch the current fragment of the PTV Navigator to the main fragment.

    If the app is already in the main activity, nothing happens. If the app is in a navigation, the navigation will be stopped.

    Returned error codes:

    • RI_ERROR_NONE if everything is ok.
    • RI_ERROR_RI_DISABLED if the Remote Interface service is disabled and/or not licensed.
    • RI_ERROR_NOT_INITIALIZED if the Remote Interface service is not initialized yet.
    • RI_ERROR_LONGTIME_OPERATION_IN_PROGRESS when the navigator is in long running progress like route calculation.
  • Get the Id of the device

    MSG_RI_GET_DEVICE_ID = 1000

    Description:

    Get the Installation ID of the device.

    Returned bundle:

    Key Value Type Info
    DeviceId Installation ID of the device String

    Returned error codes:

    • RI_ERROR_NONE if everything is ok.
    • RI_ERROR_RI_DISABLED if the Remote Interface service is disabled and/or not licensed.
    • RI_ERROR_NOT_INITIALIZED if the Remote Interface service is not initialized yet.
    • RI_ERROR_NO_LICENSE if the navigator has no valid license
  • Set the connection mode (online/hybrid)

    MSG_SET_CONNECTION_MODE = 602

    Description:

    Set the connection mode (online, hybrid) of the navigator.

    Attention

    The navigator will be restarted after setting the mode.

    Sending bundle:

    Key Value Type Info
    ConnectionMode Connection mode, see table below for valid values String

    Valid modes:

    Name
    online
    hybrid

    Returned error codes:

    • RI_ERROR_NONE if everything is ok.
    • RI_ERROR_RI_DISABLED if the Remote Interface service is disabled and/or not licensed.
    • RI_ERROR_NOT_INITIALIZED if the Remote Interface service is not initialized yet.
    • RI_ERROR_NOT_ALLOWED if the switching is not allowed because of a running navigation or switching is forbidden.
    • RI_ERROR_INVALID_PARAMETER in case the mode is invalid.
    • RI_ERROR_NO_LICENSE if the navigator has no valid license.
  • Allow/Forbid connection mode switching

    MSG_ALLOW_CONNECTION_MODE_SWITCHING = 603

    Description:

    Allow/Lock connection mode switching.

    Sending bundle:

    Key Value Type Info
    AllowConnectionModeSwitching True if the mode shall be manually switchable, else false Boolean

    Returned error codes:

    • RI_ERROR_NONE if everything is ok.
    • RI_ERROR_RI_DISABLED if the Remote Interface service is disabled and/or not licensed.
    • RI_ERROR_NOT_INITIALIZED if the Remote Interface service is not initialized yet.
    • RI_ERROR_NO_LICENSE if the navigator has no valid license
  • Allow/Forbid user interaction

    MSG_BLOCK_USER_INTERACTION = 604

    Description:

    Allow/Lock user interaction.

    Sending bundle:

    Key Value Type Info
    BlockUserInteraction True if the user interaction should be blocked, else false Boolean

    Returned error codes:

    • RI_ERROR_NONE if everything is ok.
    • RI_ERROR_RI_DISABLED if the Remote Interface service is disabled and/or not licensed.
    • RI_ERROR_NOT_INITIALIZED if the Remote Interface service is not initialized yet.
    • RI_ERROR_NO_LICENSE if the navigator has no valid license
  • Set external app resources

    MSG_RI_SET_EXTAPP_RESOURCES = 2001

    Description:

    Set the resources for an ExtApp button.

    An ExtApp button is a button shown on the main navigation screens that allows the user to switch to an external application.

    Attention

    The client software must use a FileProvider to grant access to the file.

    The icon for the button must be provided through an android FileProvider class to be able to grant the navigator app access to the file (needed for Android >= 10). The steps to grant a permission is as following:

    • Create an xml file in the res/xml folder of your project and list all directories in your app namespace that should be able to be accessed from outside, see the res/xml/filepaths.xml file in this project as an example.
    • Add a FileProvider to the manifest file (in the application section). Set the android:resource to the above created xml file. 
       <provider
     android:name="androidx.core.content.FileProvider"
     android:authorities="com.ptvag.navigation.ritest.fileprovider"
     android:exported="false"
     android:grantUriPermissions="true">
     <meta-data
         android:name="android.support.FILE_PROVIDER_PATHS"
         android:resource="@xml/filepaths" />
</provider>
    • Create a file object with the file you want to transfer/share
    • Create an uri for that file with FileProvider.getUriForFile()
    • Grant access permissions to this file for a specific package (here we use the navigator as the receiver) with getContext().grantUriPermission(). Use FLAG_GRANT_READ_URI_PERMISSION for minimal reading permission
    • If wanted, you can revoke the permission after the navigator sent back the response that the bcr was loaded (the navigator will copy the file to the navigator (files with the same name will be overwritten) to be able to access it, and therefore it is save to revoke the permission after the navigator response).

    For more implementation details, please see the RITest demo app.

    Sending bundle:

    Key Value Type Info
    IconName The name of the ExtApp icon String
    ClassName The class name of the external app String
    PackageName The package name of the external app String

    Returned error codes:

    • RI_ERROR_NONE if everything is ok.
    • RI_ERROR_RI_DISABLED if the Remote Interface service is disabled and/or not licensed.
    • RI_ERROR_NOT_INITIALIZED if the Remote Interface service is not initialized yet.
    • RI_ERROR_NO_LICENSE if the navigator has no valid license

Stop and waypoint management commands

  • Add a stop to the target stop list

    MSG_RI_ADD_STOP = 100

    Description:

    Add a stop with the given name and position (in geodecimal format) to the stop list. Please note that stops can not be added in some situations:

    • During an active navigation -> please stop the navigation by using the StopNavigation message and then try again to add stops.

    Attention

    • The PTV Navigator will not check the plausibility of the coordinates, so for example be sure to not mix up longitude and latitude, or something similar, otherwise the route the PTV Navigator calculates will not be the desired one.
    • The fields "GeoDezPosX" and "GeoDezPosY" are deprecated, use "Longitude" and "Latitude" instead.
    • If both position fields are set, only the "Longitude" and "Latitude" fields will be used.
    • The adding of stops is only allowed when the navigator is in the main fragment and no navigation is running.

    Adding a stop will alter the current tour by adding the stop at the end of the tour. Be sure to delete all stops from a previous route calculation to ensure that only the added stops are used for routing.

    Sending bundle:

    Key Value Type Info
    Name Name of the stop String
    MercPosX Deprecated, use Longitude instead. Mercator x position of the stop int
    MercPosY Deprecated, use Latitude instead. Mercator y position of the stop int
    GeoDezPosX Deprecated, use Longitude instead. Geodecimal x position (longitude) of the stop double
    GeoDezPosY Deprecated, use Latitude instead. Geodecimal y position (latitude) of the stop double
    Longitude Longitude of the stop double
    Latitude Latitude of the stop double

    Returned error codes:

    • RI_ERROR_NONE if everything is ok.
    • RI_ERROR_RI_DISABLED if the Remote Interface service is disabled and/or not licensed.
    • RI_ERROR_NOT_INITIALIZED if the Remote Interface service is not initialized yet.
    • RI_ERROR_INVALID_PARAMETER if one parameter is not valid.
    • RI_ERROR_NOT_ALLOWED if the adding is not allowed in the current activity.
    • RI_ERROR_NO_LICENSE if the navigator has no valid license.
  • Delete all stops in the target stop list

    MSG_RI_DELETE_ALL_STOPS = 101

    Description:

    Delete all stops of the current tour. Please note that stops can not be deleted in some situations: - In route overview -> please goto main fragment first - During an active navigation -> please stop the navigation by using the StopNavigation message and then try again to delete all stops.

    Returned error codes:

    • RI_ERROR_NONE if everything is ok.
    • RI_ERROR_RI_DISABLED if the Remote Interface service is disabled and/or not licensed.
    • RI_ERROR_NOT_INITIALIZED if the Remote Interface service is not initialized yet.
    • RI_ERROR_NOT_ALLOWED if the deletion is not allowed in the current activity.
    • RI_ERROR_NO_LICENSE if the navigator has no valid license.
  • Get all stops of the current tour

    MSG_RI_GET_CURRENT_TOUR = 310

    Description:

    Get all stops set in the PTV Navigator.

    The stop list will be returned as a ParcelableArray of Stop.

    Use the class definitions given in the RITest (with the same package name) for recreating the stop list and the position of a stop (just copy the files to your project in the correct path that matches the package name in the classes).

    The Stop and Position classes are used when the compatibility mode was set to true, the position will be returned as mercator coordinates. If the compatibility mode is set to false, the StopG2 and the PositionG2 classes will be used and the position is returned as Latitude/Longitude.

    Compatibility mode (MSG_RI_SET_COMPATIBILITY_MODE) set to true:

    The Stop class has the following fields:

    Field Type Info
    name String The name of the stop
    isFavorite Boolean Not used yet, always set to false
    favoriteName String Not used yet, always set to null
    image String Not used yet, always set to null
    isOffice Boolean Not used yet, always set to false
    isHome Boolean Not used yet, always set to false
    isVisited Boolean True if stop is marked as visited
    course Int Not used yet, always set to 0
    position Position The position of the stop, see Position class later
    isSKipped Boolean True if stop is marked as skipped
    id Int Not used yet, always set to 0
    timeToTarget Long Not used yet, always set to 0

    The position class has the following fields:

    Field Type Info
    x Int Mercator pos x
    y Int Mercator pos y

    Returned bundle:

    Key Value Type Info
    Stops The list of all stops ParcelableArray

    Compatibility mode (MSG_RI_SET_COMPATIBILITY_MODE) set to false:

    The StopG2 class has the following fields:

    Field Type Info
    name String The name of the stop
    isFavorite Boolean Not used yet, always set to false
    favoriteName String Not used yet, always set to null
    image String Not used yet, always set to null
    isOffice Boolean Not used yet, always set to false
    isHome Boolean Not used yet, always set to false
    isVisited Boolean True if stop is marked as visited
    course Int Not used yet, always set to 0
    position Position The position of the stop, see Position class later
    isSKipped Boolean True if stop is marked as skipped
    timeToTarget Long Not used yet, always set to 0

    The PositionG2 class has the following fields:

    Field Type Info
    x Int Mercator pos x
    y Int Mercator pos y

    Returned bundle:

    Key Value Type Info
    Stops The list of all stops ParcelableArray

    Returned error codes:

    • RI_ERROR_NONE if everything is ok.
    • RI_ERROR_RI_DISABLED if the Remote Interface service is disabled and/or not licensed.
    • RI_ERROR_NOT_INITIALIZED if the Remote Interface service is not initialized yet.
    • RI_ERROR_INVALID_PARAMETER if one parameter is not valid.
    • RI_ERROR_NOT_ALLOWED if the adding is not allowed in the current activity.
    • RI_ERROR_NO_LICENSE if the navigator has no valid license.
  • Load a given BCR file and set the target stops according to the stops

    MSG_RI_LOAD_BCR_FROM_EXTERNAL_DIR = 303

    Description:

    Load a BCR file from an external directory.

    This interface copies the file to the temporary bcr directory of the Navigator (normally located under /sdcard/Android/data/com.ptv.navigation.app/files/bcr/) converts it to a json tour file, copies this to the tours directory, deletes the copied bcr file and fills the target stop vector with the stops found in the BCR. A file with the same name in the bcr directory and in the json directory will be overwritten by this function.

    Attention

    The client software must use a FileProvider to grant access to the file.

    Loading a bcr is done by using the android FileProvider class to be able to grant the foreign navigator app access to files of this client (needed for Android >= 10). The steps to grant a permission is as following:

    • Create an xml file in the res/xml folder of your project and list all directories in your app namespace that should be able to be accessed from outside, see the res/xml/filepaths.xml file in this project as an example.
    • Add a FileProvider to the manifest file (in the application section). Set the android:resource to above created xml file 
      <provider
     android:name="androidx.core.content.FileProvider"
     android:authorities="com.ptv.navigation.ritest.fileprovider"
     android:exported="false"
     android:grantUriPermissions="true">
     <meta-data
         android:name="android.support.FILE_PROVIDER_PATHS"
         android:resource="@xml/filepaths" />
</provider>
    • Create a file object with the file you want to transfer/share
    • Create an uri for that file with FileProvider.getUriForFile()
    • Grant access permissions to this file for a specific package (here we use the navigator as the receiver) with getContext().grantUriPermission(). Use FLAG_GRANT_READ_URI_PERMISSION for minimal reading permission
    • If wanted, you can revoke the permission after the navigator sent back the response that the bcr was loaded (the navigator will copy the bcr to the navigator bcr directory (files with the same name will be overwritten) to be able to access it, and therefore it is save to revoke the permission after the navigator response).

    For more implementation details, please see the RITest demo app.

    The visited flags of the target stops will also be set as found.

    Sending bundle:

    Key Value Type Info
    FileName The name of the BCR file with path as uri String

    Returned error codes:

    • RI_ERROR_NONE if everything is ok.
    • RI_ERROR_RI_DISABLED if the Remote Interface service is disabled and/or not licensed.
    • RI_ERROR_NOT_INITIALIZED if the Remote Interface service is not initialized yet.
    • RI_ERROR_NO_LICENSE if the navigator has no valid license.
    • RI_ERROR_NOT_ALLOWED if the start is not allowed in the current fragment.
    • RI_ERROR_FILE_ACCESS if the file could not be loaded (either because of not granted permissions or of other load error).
  • Geocode a given address (retrieve the position)

    MSG_RI_GEOCODE = 500

    Description:

    Geocode (return geocoded address and the mercator position) from a given address.

    The quality of the result will be returned as a string describing the quality (available from version >= 1.1.87):

    Quality Description
    Town The town was found (the town matched in the way that the result town starts with the searched town string), the street and the house number does not match
    Street The town and the street matched (the street matched in the way that the result street starts with the searched street string), the house number not
    HouseNumber Town, Street and the house number matched
    Unknown Nothing has matched

    Sending bundle:

    Not all keys have to be set to get a valid result.

    Key Value Type Info
    CC The country code of the country to search in (e.g. "DE") String
    PostCode The postcode to search for String
    TownName The town name to search String
    StreetName The street name to search String
    HNr The house number to search for String

    Compatibility mode (MSG_RI_SET_COMPATIBILITY_MODE) set to true:

    Returned bundle:

    Key Value Type Info
    PosX The found mercator x position of the address int
    PosY The found mercator y position of the address int
    CC The found country code String
    PostCode The found postcode String
    TownName The found town name String
    StreetName The found street name String
    HNr The found house number String
    Quality The quality of the result, see Quality values for details String

    Compatibility mode (MSG_RI_SET_COMPATIBILITY_MODE) set to false:

    Returned bundle:

    Key Value Type Info
    Longitude The longitude of the address double
    Latitude The latitude of the address double
    CC The found country code String
    PostCode The found postcode String
    TownName The found town name String
    StreetName The found street name String
    HNr The found housenumber String
    Quality The quality of the result, see Quality values for details String

    Returned error codes:

    • RI_ERROR_NONE if everything is ok.
    • RI_ERROR_INVALID_PARAMETER if the received bundle is empty.
    • RI_ERROR_RI_DISABLED if the Remote Interface service is disabled and/or not licensed.
    • RI_ERROR_NOT_INITIALIZED if the Remote Interface service is not initialized yet.
    • RI_ERROR_NO_RESULT_FOUND if the address couldn't be found.
    • RI_ERROR_NO_STREET_FOUND and a bundle of data if the search succeeded, but no street was found (return position is the town center).
    • RI_ERROR_NO_LICENSE if the navigator has no valid license.
  • Inverse geocode (get the address from a position)

    MSG_RI_INVGEOCODE = 501

    Description:

    Inverse geocode (return town name, street name and so on) from a given mercator or geodecimal position.

    Sending bundle

    Compatibility mode (MSG_RI_SET_COMPATIBILITY_MODE) set to true:

    Key Value Type Info
    MercPosX The mercator x position to search an address for int
    MercPosY The mercator y position to search an address for int
    GeoDezPosX The geodecimal x (longitude) position to search an address for double optional
    GeoDezPosY The geodecimal y (latitude) position to search an address for double optional

    Compatibility mode (MSG_RI_SET_COMPATIBILITY_MODE) set to false:

    Key Value Type Info
    Latitude The latitude of the search position double
    Longitude The longitude of the search position double

    Returned bundle:

    Depending on the position, not all fields will return a result.

    Key Value Type Info
    CC The found country code String
    ISO3166a2 The found country code as ISO3166a2 standard String
    PostCode The found postcode String
    TownName The found town name String
    StreetName The found street name String
    HNr The found housenumber String

    Returned error codes:

    • RI_ERROR_NONE if everything is ok.
    • RI_ERROR_RI_DISABLED if the Remote Interface service is disabled and/or not licensed.
    • RI_ERROR_NOT_INITIALIZED if the Remote Interface service is not initialized yet.
    • RI_ERROR_LONGTIME_OPERATION_IN_PROGRESS as long as the PTV Navigator is searching the result.
    • RI_ERROR_INVGEOCODE_FAILED on error.
    • RI_ERROR_NO_RESULT_FOUND if no result was found.
    • RI_ERROR_NO_LICENSE if the navigator has no valid license.
  • Add a marker to the map

    MSG_RI_ADD_MARKER = 906

    Description:

    Draw a marker onto the map.

    The marker has to be given as a png file and must be sent with a FileProvider:

    Attention

    The client software must use a FileProvider to grant access to the file.

    To grant the navigator access to the image that should be set, the "ImageName" must be filled with the uri of the image file generated by a FileProvider(needed for Android >= 10). The steps to grant a permission is as following:

    • Create an xml file in the res/xml folder of your project and list all directories in your app namespace that should be able to be accessed from outside, see the res/xml/filepaths.xml file in this project as an example.
    • Add a FileProvider to the manifest file (in the application section). Set the android:resource to above created xml file 
      <provider
     android:name="androidx.core.content.FileProvider"
     android:authorities="com.ptv.navigation.ritest.fileprovider"
     android:exported="false"
     android:grantUriPermissions="true">
     <meta-data
         android:name="android.support.FILE_PROVIDER_PATHS"
         android:resource="@xml/filepaths" />
</provider>
    • Create a file object with the file you want to transfer/share
    • Create an uri for that file with FileProvider.getUriForFile()
    • Grant access permissions to this file for a specific package (here we use the navigator as the receiver) with getContext().grantUriPermission(). Use FLAG_GRANT_READ_URI_PERMISSION for minimal reading permission
    • If wanted, you can revoke the permission after the navigator sent back the response that the file was loaded (the navigator will copy the file to the specific navigator directory to be able to access it, and therefore it is save to revoke the permission after the navigator response).

    The "Tag" field describes a string identifier for one or multiple markers. Removing markers will be done by this identifier. Multiple markers can have the same tag. The tag is used in MSG_RI_REMOVE_MARKER to identify which markers should be removed. If no tag is given, the marker will get a default tag (to remove these tags, also omit the tag in MSG_RI_REMOVE_MARKER).

    The image anchor represents the point where the real world coordinate is located on the image. It is in the upper left corner of the image per default. The "ImageOffsetX/ImageOffsetY" fields are float parameters that move the image anchor relatively by the offset. Positive values will move the anchor to the right / down, negative offsets will move it to the left / up. An offset of (0.5, 0.5) will move the anchor to the center of the image. Default is (0.5, 0.5).

    If a "Label" ist given, a text will be shown at the marker depending of the "LabelAlignment" and the "LabelOffset". The "LabelAlignment" parameter describes how the label is aligned to the image anchor. Valid values are "left,right,center". Default is "center". The label can be moved relatively to the image anchor by setting the LabelOffsetX/LabelOffsetY parameters. Default is LabelOffsetX: 0.0, LabelOffsetY: 25.0 The label can be sized with "LabelSize", the default size is 16.0.

    Sending bundle:

    Key Value Type Info
    Tag Tag for the marker, will be used as an identifier for later removal of the marker, optional, if not set, a default tag will be set String
    ImageName The file provider path of the image that should be shown as a marker (mandatory) String
    Latitude The Latitude of the marker (mandatory) Double
    Longitude The longitude of the marker (mandatory) Double
    ImageOffsetX X image offset relative to the image anchor, default is 0.5 (optional) Float
    ImageOffsetY Y image offset relative to the image anchor, default is 0.5 (optional) Float
    Label A label text (optional) String
    LabelOffsetX X label offset relative to the image anchor (optional) Float
    LabelOffsetY Y label offset relative to the image anchor, default is 25.0 (optional) Float
    LabelAlignment Alignment of the label relative to the image anchor, valid values are "left,right,center", default is "center" (optional) String
    LabelSize Size of the label, default is 16.0 (optional) Double

    Returned error codes:

    • RI_ERROR_NONE if everything is ok.
    • RI_ERROR_RI_DISABLED if the Remote Interface service is disabled and/or not licensed.
    • RI_ERROR_NOT_INITIALIZED if the Remote Interface service is not initialized yet.
    • RI_ERROR_INVALID_PARAMETER if one of the input variables are not correct.
    • RI_ERROR_FILE_ACCESS if the image cannot be accessed.
    • RI_ERROR_NO_LICENSE if the navigator has no valid license.
  • Add a polyline to the map

    MSG_RI_ADD_POLYLINE = 908

    Description:

    Draw a polyline onto the map.

    The polyline has to be given as a double array of latitude, longitude values for every point of the polyline.

    The "Tag" field describes a string identifier for one or multiple polylines. Multiple polylines can have the same tag. The tag is used in MSG_RI_REMOVE_POLYLINE to identify which polylines should be removed. If no tag is given, the polyline will get a default tag (to remove these tags, also omit the tag in MSG_RI_REMOVE_POLYLINE).

    The "Color" field is an integer representing the color of the polyline (in ARGB format).

    Sending bundle:

    Key Value Type Info
    Tag Tag for the polyline, will be used as an identifier for later removal of the polyline, optional, if not set, a default tag will be set String
    Coordinates A double array of latitude, longitude values for each point of the polyline (mandatory) String
    Color The color of the polyline as ARGB integer (optional, if not set, color will be 0) Double

    Returned error codes:

    • RI_ERROR_NONE if everything is ok.
    • RI_ERROR_RI_DISABLED if the Remote Interface service is disabled and/or not licensed.
    • RI_ERROR_NOT_INITIALIZED if the Remote Interface service is not initialized yet.
    • RI_ERROR_INVALID_PARAMETER if one of the input variables are not correct.
    • RI_ERROR_NO_LICENSE if the navigator has no valid license.
  • Add a polygon to the map

    MSG_RI_ADD_POLYGON = 910

    Description:

    Draw a polygon onto the map.

    The polygon has to be given as a double array of latitude, longitude values for every point of the polygon.

    The "Tag" field describes a string identifier for one or multiple polygons. Multiple polygons can have the same tag. The tag is used in MSG_RI_REMOVE_POLYGON to identify which polygons should be removed. If no tag is given, the polygon will get a default tag (to remove these tags, also omit the tag in MSG_RI_REMOVE_POLYGON).

    The "Color" field is an integer representing the color of the polygon (in ARGB format).

    The "ImageName" field can be used to show an image inside the polygon. If no image is wanted, do not send an "ImageName" bundle field.

    Attention

    The client software must use a FileProvider to grant access to the file.

    To grant the navigator access to the image that should be set, the "ImageName" must be filled with the uri of the image file generated by a FileProvider(needed for Android >= 10). The steps to grant a permission is as following:

    • Create an xml file in the res/xml folder of your project and list all directories in your app namespace that should be able to be accessed from outside, see the res/xml/filepaths.xml file in this project as an example.
    • Add a FileProvider to the manifest file (in the application section). Set the android:resource to above created xml file 
      <provider
     android:name="androidx.core.content.FileProvider"
     android:authorities="com.ptv.navigation.ritest.fileprovider"
     android:exported="false"
     android:grantUriPermissions="true">
     <meta-data
         android:name="android.support.FILE_PROVIDER_PATHS"
         android:resource="@xml/filepaths" />
</provider>
    • Create a file object with the file you want to transfer/share
    • Create an uri for that file with FileProvider.getUriForFile()
    • Grant access permissions to this file for a specific package (here we use the navigator as the receiver) with getContext().grantUriPermission(). Use FLAG_GRANT_READ_URI_PERMISSION for minimal reading permission
    • If wanted, you can revoke the permission after the navigator sent back the response that the file was loaded (the navigator will copy the file to the specific navigator directory to be able to access it, and therefore it is save to revoke the permission after the navigator response).

    Sending bundle:

    Key Value Type Info
    Tag Tag for the polyline, will be used as an identifier for later removal of the polyline, optional, if not set, a default tag will be set String
    Coordinates A double array of latitude, longitude values for each point of the polyline (mandatory) String
    ImageName An image, given as a file provider path that can be shown inside of the polygon(optional) String
    Color The color of the polyline as ARGB integer (optional, if not set, color will be 0) Double

    Returned error codes:

    • RI_ERROR_NONE if everything is ok.
    • RI_ERROR_RI_DISABLED if the Remote Interface service is disabled and/or not licensed.
    • RI_ERROR_NOT_INITIALIZED if the Remote Interface service is not initialized yet.
    • RI_ERROR_INVALID_PARAMETER if one of the input variables are not correct.
    • RI_ERROR_FILE_ACCESS if the image cannot be accessed.
    • RI_ERROR_NO_LICENSE if the navigator has no valid license.
  • Remove a marker from the map

    MSG_RI_REMOVE_MARKER = 907

    Description:

    Remove markers with a given tag from the map.

    The "Tag" field describes a string identifier for one or multiple markers to be removed. If no tag is given, all markers with the default tag will be removed.

    Sending bundle:

    Key Value Type Info
    Tag Tag to identify markers which should be removed. Optional, if not set, markers with the default tag will be removed. String

    Returned error codes:

    • RI_ERROR_NONE if everything is ok.
    • RI_ERROR_RI_DISABLED if the Remote Interface service is disabled and/or not licensed.
    • RI_ERROR_NOT_INITIALIZED if the Remote Interface service is not initialized yet.
    • RI_ERROR_INVALID_PARAMETER if one of the input variables are not correct.
    • RI_ERROR_NO_LICENSE if the navigator has no valid license.
  • Remove a polyline from the map

    MSG_RI_REMOVE_POLYLINE = 909

    Description:

    Remove polylines with a given tag from the map.

    The "Tag" field describes a string identifier for one or multiple polylines to be removed. If no tag is given, all polylines with the default tag will be removed.

    Sending bundle:

    Key Value Type Info
    Tag Tag to identify polylines which should be removed. Optional, if not set, polylines with the default tag will be removed. String

    Returned error codes:

    • RI_ERROR_NONE if everything is ok.
    • RI_ERROR_RI_DISABLED if the Remote Interface service is disabled and/or not licensed.
    • RI_ERROR_NOT_INITIALIZED if the Remote Interface service is not initialized yet.
    • RI_ERROR_INVALID_PARAMETER if one of the input variables are not correct.
    • RI_ERROR_NO_LICENSE if the navigator has no valid license.
  • Remove a polygon from the map

    MSG_RI_REMOVE_POLYGON = 911

    Description:

    Remove polygons with a given tag from the map.

    The "Tag" field describes a string identifier for one or multiple polygons to be removed. If no tag is given, all polygons with the default tag will be removed.

    Sending bundle:

    Key Value Type Info
    Tag Tag to identify polygons which should be removed. Optional, if not set, polygons with the default tag will be removed. String

    Returned error codes:

    • RI_ERROR_NONE if everything is ok.
    • RI_ERROR_RI_DISABLED if the Remote Interface service is disabled and/or not licensed.
    • RI_ERROR_NOT_INITIALIZED if the Remote Interface service is not initialized yet.
    • RI_ERROR_INVALID_PARAMETER if one of the input variables are not correct.
    • RI_ERROR_NO_LICENSE if the navigator has no valid license.
  • Check if the safety warner is active

    MSG_RI_IS_SAFETY_WARNER_ACTIVE = 313

    #Description:

    Get the status of the safety warner (activated, not activated).

    Return bundle:

    Key Value Type Info
    Active True, if the safety warner is active, else false DoubleArray

    Returned error codes:

    • RI_ERROR_NONE if everything is ok.
    • RI_ERROR_RI_DISABLED if the Remote Interface service is disabled and/or not licensed.
    • RI_ERROR_NOT_INITIALIZED if the Remote Interface service is not initialized yet.
    • RI_ERROR_NO_LICENSE if the navigator has no valid license
  • Set the safety warner active

    MSG_RI_SET_SAFETY_WARNER_ACTIVE = 312

    Description:

    Activate the safety warner in the Settings/Assistants Menu and in the navigation.

    Sending bundle:

    Key Value Type Info
    Activate If set to true, activate the SafetyWarner else deactivate it Boolean

    Return bundle:

    Key Value Type Info
    Activate True, if the safety warner is active, else false DoubleArray

    Returned error codes:

    • RI_ERROR_NONE if everything is ok.
    • RI_ERROR_RI_DISABLED if the Remote Interface service is disabled and/or not licensed.
    • RI_ERROR_NOT_INITIALIZED if the Remote Interface service is not initialized yet.
    • RI_ERROR_NO_LICENSE if the navigator has no valid license
  • Download a set of maps

    MSG_RI_DOWNLOAD_MAPS = 1201

    Description:

    Download a set of maps given by their ISO codes.

    This function will trigger a map download based on the given ISO codes. Already downloaded maps will not be downloaded again.

    For valid ISO codes, see the Preferences documentation

    Sending bundle:

    Key Value Type Info
    IsoCodes An array of strings, representing the iso codes of the maps to be downloaded StringArrayList

    Returned error codes:

    • RI_ERROR_NONE if everything is ok.
    • RI_ERROR_RI_DISABLED if the Remote Interface service is disabled and/or not licensed.
    • RI_ERROR_NOT_INITIALIZED if the Remote Interface service is not initialized yet.
    • RI_ERROR_INVALID_PARAMETER if the boolean array contains not all values.
    • RI_ERROR_NO_LICENSE if the navigator has no valid license.
  • Start a navigation

    MSG_RI_START_NAVIGATION = 300

    Description:

    Start a navigation.

    Be sure to first add target stops with AddStop. If more than one stop is present in the current tour, the navigator will calculate a route over all tour stops from the first to the last.

    The route overview screen can be skipped by setting 'ShowRouteOverview' to false.

    Please note that start navigation cannot be used in some situations:

    • During an active navigation -> please stop the navigation by using the StopNavigation message and then try again start the navigation.
    • If the navigator is not in the main fragment.

    Sending bundle:

    Key Value Type Info
    ShowRouteOverview Flag whether the route overview should be shown or not Boolean

    Returned error codes:

    • RI_ERROR_NONE if everything is ok.
    • RI_ERROR_RI_DISABLED if the Remote Interface service is disabled and/or not licensed.
    • RI_ERROR_NOT_INITIALIZED if the Remote Interface service is not initialized yet.
    • RI_ERROR_NOT_ALLOWED if the start is not allowed in the current fragment.
    • RI_ERROR_LONGTIME_OPERATION_IN_PROGRESS as long as the PTV Navigator is calculating the route.
    • RI_ERROR_FAILED if the app is not completely initialized.
    • RI_ERROR_NO_LICENSE if the navigator has no valid license.
  • Stop the current running navigation

    MSG_RI_STOP_NAVIGATION = 305

    Description:

    Stop navigation.

    Stops a currently running navigation. The stop list will not be altered. If a current route calculation is in progress, the error RI_ERROR_LONGTIME_OPERATION_IN_PROGRESS will be returned. Please wait until the calculation process is finished.

    Returned error codes:

    • RI_ERROR_LONGTIME_OPERATION_IN_PROGRESS as long as the PTV Navigator is calculating a route.
    • RI_ERROR_NONE if everything is ok.
    • RI_ERROR_RI_DISABLED if the Remote Interface service is disabled and/or not licensed.
    • RI_ERROR_NOT_INITIALIZED if the Remote Interface service is not initialized yet.
    • RI_ERROR_NO_LICENSE if the navigator has no valid license
  • Get the current route trace

    MSG_RI_GET_ROUTE_TRACE_AHEAD = 308

    Description:

    Return the current route trace.

    This interface will return the current used route trace (if the Navigator is in an active navigation). The trace is returned as a list of WGS84 coordinates. Always two consecutive values of the list represent one coordinate of the trace in the order latitude followed by longitude.

    Sending bundle:

    Key Value Type Info
    OnlyToNextStop Not supported anymore. Flag whether the trace should end at the next stop or at the last stop Boolean

    Return bundle:

    Key Value Type Info
    Positions The latitude and longitude ordinates of the route trace DoubleArray

    Returned error codes:

    • RI_ERROR_NONE if everything is ok.
    • RI_ERROR_RI_DISABLED if the Remote Interface service is disabled and/or not licensed.
    • RI_ERROR_NOT_INITIALIZED if the Remote Interface service is not initialized yet.
    • RI_ERROR_NO_ROUTE_FOUND if no route trace is currently available.
    • RI_ERROR_NO_LICENSE if the navigator has no valid license
  • Stop map matcher after destination reached

    MSG_RI_STOP_MAP_MATCHER_AFTER_DESTINATION_REACHED = 912

    Description:

    Stop the gps position to be matched to the road network and zoom to a defined end zoom level after destination has been reached.

    This function disables or enables the map matcher and changes zooming behavior after the destination has been arrived. This can be useful when the driver should drive along an off road trace set with "AddPolyLine" after reaching the destination.

    If set to true, the map matcher will be stopped and the standard gps location provider will be used to show the position on the map. Also, the zoom will be set to a defined value. If set to false (the default behavior), the gps position is matched to the road network and the zoom will be set automatically.

    Sending bundle:

    Key Value Type Info
    StopMapMatcher If true, stop the gps map matcher and use the standard gps position, if false, use the map matcher Boolean

    Returned error codes:

    • RI_ERROR_NONE if everything is ok.
    • RI_ERROR_RI_DISABLED if the Remote Interface service is disabled and/or not licensed.
    • RI_ERROR_NOT_INITIALIZED if the Remote Interface service is not initialized yet.
    • RI_ERROR_NO_LICENSE if the navigator has no valid license
  • Get all available vehicle profiles

    MSG_RI_QUERY_PROFILES = 400

    Description:

    Get a list of all available vehicle profiles as a StringArray of their file names.

    Returned bundle:

    Key Value Type Info
    Profiles The list of all profiles StringArray

    Returned error codes:

    • RI_ERROR_NONE if everything is ok.
    • RI_ERROR_RI_DISABLED if the Remote Interface service is disabled and/or not licensed.
    • RI_ERROR_NOT_INITIALIZED if the Remote Interface service is not initialized yet.
    • RI_ERROR_NO_LICENSE if the navigator has no valid license
  • Get the currently active vehicle profile

    MSG_RI_GET_CURRENT_PROFILE = 401

    ###Description: Get the currently active vehicle profile (identified by the file name).

    Returned bundle:

    Key Value Type Info
    Profile The current profile String

    Returned error codes:

    • RI_ERROR_NONE if everything is ok.
    • RI_ERROR_RI_DISABLED if the Remote Interface service is disabled and/or not licensed.
    • RI_ERROR_NOT_INITIALIZED if the Remote Interface service is not initialized yet.
    • RI_ERROR_NO_LICENSE if the navigator has no valid license
  • Set an existing vehicle profile as active

    MSG_RI_SET_CURRENT_PROFILE = 402

    Description:

    Set an existing vehicle profile as active.

    Sending bundle:

    Key Value Type Info
    Profile The profile to set (identified by the file name) String

    Returned error codes:

    • RI_ERROR_NONE if the profile was set correctly.
    • RI_ERROR_RI_DISABLED if the Remote Interface service is disabled and/or not licensed.
    • RI_ERROR_NOT_INITIALIZED if the Remote Interface service is not initialized yet.
    • RI_ERROR_NO_SUCH_PROFILE if no such profile exists.
    • RI_ERROR_INVALID_PARAMETER if the bundle is empty or the key "Profile" was not set.
    • RI_ERROR_NO_LICENSE if the navigator has no valid license
  • Import a profile

    MSG_RI_IMPORT_PROFILE = 403

    Description:

    Import a profile by sending the file base64 encoded to the navigator.

    If the profile with the given name already exists than it will be overwritten. If this profile is the currently used profile while navigation, the possible changes have no impact till the next route calculation.

    Sending bundle:

    Key Value Type Info
    Data base64 encoded profile file data String
    FileName Filename the profile will be stored on device. Without extension, just name. String

    Returned bundle:

    The sent bundle will returned and in case of an error, it may be enriched by additional information.

    Key Value Type Info
    ErrorDescription Description of error String

    Returned error codes:

    • RI_ERROR_NONE if the profile was set correctly.
    • RI_ERROR_RI_DISABLED if the Remote Interface service is disabled and/or not licensed.
    • RI_ERROR_NOT_INITIALIZED if the Remote Interface service is not initialized yet.
    • RI_ERROR_INVALID_PARAMETER if the bundle keys "FileName" or "Data" have not been set.
    • RI_ERROR_NO_LICENSE if the navigator has no valid license.
  • Import a profile from an external directory

    MSG_RI_LOAD_PROFILE_FROM_EXTERNAL_DIR = 404

    ###Description: Import a profile file from an external directory.

    This call copies a profile file to the profiles directory of the Navigator (normally located under /sdcard/Android/data/com.ptv.navigation.app/files/profiles/) and reinitializes the profiles list. A file with the same name in the profiles directory will be overwritten by this function.

    Attention

    The client software must use a FileProvider to grant access to the file.

    Copying the profile is done by using the android FileProvider class to be able to grant the foreign navigator app access to files of this client (needed for Android >= 10). The steps to grant a permission is as following:

    • Create an xml file in the res/xml folder of your project and list all directories in your app namespace that should be able to be accessed from outside, see the res/xml/filepaths.xml file in this project as an example.
    • Add a FileProvider to the manifest file (in the application section). Set the android:resource to above created xml file 
      <provider
     android:name="androidx.core.content.FileProvider"
     android:authorities="com.ptv.navigation.ritest.fileprovider"
     android:exported="false"
     android:grantUriPermissions="true">
     <meta-data
         android:name="android.support.FILE_PROVIDER_PATHS"
         android:resource="@xml/filepaths" />
</provider>
    • Create a file object with the file you want to transfer/share
    • Create an uri for that file with FileProvider.getUriForFile()
    • Grant access permissions to this file for a specific package (here we use the navigator as the receiver) with getContext().grantUriPermission(). Use FLAG_GRANT_READ_URI_PERMISSION for minimal reading permission
    • If wanted, you can revoke the permission after the navigator sent back the response that the profile was copied (the navigator will copy the profile to the navigator profiles directory (files with the same name will be overwritten) to be able to access it, and therefore it is save to revoke the permission after the navigator response).

    For more implementation details, please see the RITest demo app.

    The visited flags of the destination stops will also be set as found.

    Sending bundle:

    Key Value Type Info
    FileName The name of the profile file with path as uri String

    Returned error codes:

    • RI_ERROR_NONE if everything is ok.
    • RI_ERROR_RI_DISABLED if the Remote Interface service is disabled and/or not licensed.
    • RI_ERROR_NOT_INITIALIZED if the Remote Interface service is not initialized yet.
    • RI_ERROR_NO_LICENSE if the navigator has no valid license.
    • RI_ERROR_INVALID_PARAMETER if the sent bundle which should hold the file name is null
    • RI_ERROR_FILE_ACCESS if the file name is null or empty or the file could not be copied (either because of not granted permissions or of other copy error).
  • Get a preference value

    MSG_RI_GET_PREFERENCE = 127

    Get a preference value from the application.

    Sending bundle:

    Key Value Type Info
    Key Key of the preference String

    Return bundle:

    Key Value Type Info
    Key Key of the preference String
    Value Value of the preference Boolean|Int|Long|String

    Returned error codes:

    • RI_ERROR_NONE in case the preference was returned correctly.
    • RI_ERROR_RI_DISABLED if the Remote Interface service is disabled and/or not licensed.
    • RI_ERROR_NOT_INITIALIZED if the Remote Interface service is not initialized yet.
    • RI_ERROR_INVALID_PARAMETER in case the preference does not exist
    • RI_ERROR_NO_LICENSE if the navigator has no valid license.
  • Set preference values

    MSG_RI_SET_PREFERENCES = 126

    Description:

    Set a bundle of preferences in the application.

    Attention

    Some preferences like setting language or connection mode are only possible when there is currently no navigation running. Otherwise the settings will get rejected and an error is returned. In this case you first have to stop the navigation.

    Sending bundle:

    Key Value Type Info
    Preferences Key value pairs of the preferences to set Bundle

    Example

    Bundle preferences = new Bundle();
preferences.putString("map_day_night", "Nightly");
preferences.putBoolean("traffic_avoid", false);
Bundle data = new Bundle();
data.putBundle("Preferences", preferences);

    Returned error codes:

    • RI_ERROR_NONE in case the preference was set correctly.
    • RI_ERROR_RI_DISABLED if the Remote Interface service is disabled and/or not licensed.
    • RI_ERROR_NOT_INITIALIZED if the Remote Interface service is not initialized yet.
    • RI_ERROR_INVALID_PARAMETER in case the preference type is not correct
    • RI_ERROR_NOT_DURING_NAVIGATION if the app is currently navigating.
    • RI_ERROR_NO_LICENSE if the navigator has no valid license.
  • Load preferences from file

    MSG_RI_LOAD_PREFERENCES = 129

    Description:

    Load a preferences_import.json file from an external directory.

    This interface copies the file to the 'files' directory of the Navigator (normally located under /sdcard/Android/data/com.ptv.navigation.app/files/) and imports it's values to the navigator.

    A file with the same name in the files directory will be overwritten by this function. The file name can be arbitrary.

    Attention

    • The client software must use a FileProvider to grant access to the file.
    • Loading preferences is only possible when there is currently no navigation running, otherwise, you first have to stop the navigation.

    Loading a file is done by using the android FileProvider class to be able to grant the foreign navigator app access to files of this client (needed for Android >= 10/11). The steps to grant a permission is as following:

    • Create a xml file in the res/xml folder of your project and list all directories in your app namespace that should be able to be accessed from outside, see the res/xml/filepaths.xml file in this project as an example.
    • Add a FileProvider to the manifest file (in the application section). Set the android:resource to above created xml file 
      <provider
     android:name="androidx.core.content.FileProvider"
     android:authorities="com.ptv.navigation.ritest.fileprovider"
     android:exported="false"
     android:grantUriPermissions="true">
     <meta-data
         android:name="android.support.FILE_PROVIDER_PATHS"
         android:resource="@xml/filepaths" />
</provider>
    • Create a file object with the file you want to transfer/share
    • Create an uri for that file with FileProvider.getUriForFile()
    • Grant access permissions to this file for a specific package (here we use the navigator as the receiver) with getContext().grantUriPermission(). Use FLAG_GRANT_READ_URI_PERMISSION for minimal reading permission
    • If wanted, you can revoke the permission after the navigator sent back the response that the file was loaded (the navigator will copy the file to the navigator files directory (files with the same name will be overwritten) to be able to access it, and therefore it is save to revoke the permission after the navigator response).

    For more implementation details, please see the RITest demo app.

    Sending bundle:

    Key Value Type Info
    FileName The name of the preference file with path as uri String

    Returned error codes:

    • RI_ERROR_NONE if everything is ok.
    • RI_ERROR_RI_DISABLED if the Remote Interface service is disabled and/or not licensed.
    • RI_ERROR_NOT_INITIALIZED if the Remote Interface service is not initialized yet.
    • RI_ERROR_FILE_ACCESS if the file could not be loaded (either because of not granted permissions or of other load error).
    • RI_ERROR_NOT_DURING_NAVIGATION if the app is currently navigating.
    • RI_ERROR_NO_LICENSE if the navigator has no valid license.
  • Set map data permissions

    MSG_RI_SET_MAP_DATA_PERMISSIONS = 1101

    Description:

    Allow the user to manually download, update or delete maps.

    The permissions can be set through a boolean array with the following order of the flags in the array:

    • Download permission
    • Update permission
    • Deletion permission

    If the array does not contain all 3 values, an error will be returned.

    Sending bundle:

    Key Value Type Info
    Permissions A boolean array of the permissions. The order of the flags is "download, update, delete" BooleanArray

    Returned error codes:

    • RI_ERROR_NONE if everything is ok.
    • RI_ERROR_RI_DISABLED if the Remote Interface service is disabled and/or not licensed.
    • RI_ERROR_NOT_INITIALIZED if the Remote Interface service is not initialized yet.
    • RI_ERROR_INVALID_PARAMETER if the boolean array contains not all values.
    • RI_ERROR_NO_LICENSE if the navigator has no valid license.
  • Get the license key

    MSG_RI_GET_LICENSE_KEY = 131

    Description:

    Get the current license key.

    Returns the currently set license key of the PTV Navigator. Please note that this interface does not check if the returned license key is valid or not.

    Returned bundle:

    Key Value Type Info
    LicenseKey The current license key String

    Returned error codes:

    • RI_ERROR_NONE
  • Set the license key

    MSG_RI_SET_LICENSE_KEY = 130

    Description:

    Set the current license key for the PTV Navigator.

    This interface checks if the license key is valid or not and sends the appropriate error code back. When the PTV Navigator has no valid license key and waits in the login screen, the license key you insert with this interface will be added automatically into the license key edit field and after a successful check, the main fragment will be shown.

    Sending bundle:

    Key Value Type Info
    LicenseKey The license key to set String

    Returned error codes:

    • RI_ERROR_NONE if the license key was set.
  • Logout the navigator

    MSG_RI_LICENSE_LOGOUT = 132

    Description:

    Logout the PTV Navigator by setting the license key to "".

    Returned error codes:

    • RI_ERROR_NONE if the license key was set.
  • Get the device description

    MSG_RI_GET_DEVICE_DESCRIPTION = 133

    Description:

    Get the device description.

    Return bundle:

    Key Value Type Info
    Description The device description String

    Returned error codes:

    • RI_ERROR_NONE if everything is ok.
    • RI_ERROR_RI_DISABLED if the Remote Interface service is disabled and/or not licensed.
    • RI_ERROR_NOT_INITIALIZED if the Remote Interface service is not initialized yet.
    • RI_ERROR_NO_LICENSE if the navigator has no valid license.
  • Set the device description

    MSG_RI_SET_DEVICE_DESCRIPTION = 134

    Description:

    Set the device description.

    Sending bundle:

    Key Value Type Info
    Description The device description to set String

    Returned error codes:

    • RI_ERROR_NONE if everything is ok.
    • RI_ERROR_RI_DISABLED if the Remote Interface service is disabled and/or not licensed.
    • RI_ERROR_NOT_INITIALIZED if the Remote Interface service is not initialized yet.
    • RI_ERROR_INVALID_PARAMETER if there is no bundle attached or the bundle has no field "Description".
    • RI_ERROR_NO_LICENSE if the navigator has no valid license.

Push service commands

  • Register for event listening

    MSG_RI_REGISTER_EVENT_LISTENER = 701

    Description:

    Register an event listener.

    Starts listening to an event given by the bundle key "EventType". After sending this message, the navigation software will send frequently event information to the client, if possible. The sent back messages from the PTV Navigator will have the message id "MSG_RI_EVENT_DATA" and also have the "EventType" key set to let the client determine what event was actually received.

    For a list of available event types and the corresponding information which will be sent by the PTV Navigator, see EventTypes.

    Sending bundle:

    Key Value Type Info
    EventType The type of event to listen to int

    Returned error codes:

    • RI_ERROR_NONE if the registration succeeded.
    • RI_ERROR_RI_DISABLED if the Remote Interface service is disabled and/or not licensed.
    • RI_ERROR_NOT_INITIALIZED if the Remote Interface service is not initialized yet.
    • RI_ERROR_NO_LICENSE if the navigator has no valid license.
    • RI_ERROR_UNSUPPORTED_EVENT_TYPE if the given event type doesn't exist.
  • Unregister from event listening

    MSG_RI_UNREGISTER_EVENT_LISTENER = 702

    Description:

    Unregister the event information listener.

    Stops listening to an event given by the Bundle key "EventType". After sending this message, the navigation software will stop sending information to the client for the given event.

    Sending bundle:

    Key Value Type Info
    EventType The type of event to stop the listening for int

    Returned error codes:

    • RI_ERROR_NONE if the unregistration succeeded.
    • RI_ERROR_RI_DISABLED if the Remote Interface service is disabled and/or not licensed.
    • RI_ERROR_NOT_INITIALIZED if the Remote Interface service is not initialized yet.
    • RI_ERROR_NO_LICENSE if the navigator has no valid license.
    • RI_ERROR_UNSUPPORTED_EVENT_TYPE if the given event type doesn't exist.

  • List of available push service events