SDK Concepts

This section explains some of the basic concepts of the SDK. It provides you an overview what the SDK needs to be used and what common assumptions are made

Runtime Data

The SDK requires access to a specific set of files accessible on the device at runtime. This includes the map data resource files and various configuration files. Those are located in the external_storage folder of the SDK package. The files and folders have to be present on the device where the SDK is executed at initialization time. In the following list, the individual files and folders are described briefly:

mapservices.xml (required): This file configures the map appearance - this includes colors, line, street appearance and visibility
data (required): This folder contains the map data or what is required to show a coarse map shape for online usage before any online connection is made.
res/fonts/ (required): Contains fonts used to render texts in the map like street names, city names …
res/lngenglish/ (required): These lng folders store basic speech and language dependent files. Besides english, additional languages can be used with the naming scheme lnglanguagename
res/poi_icons/ (required): Icons that are used by the Mapviewer, e.g. for own position or road signs
res/realityview/ (required): Graphics that are used to generate reality views during a navigation
user/settings.ini (optional): This file is optional and stores configurations over the application lifetime as for example the POI visibility, map perspective and last position. It will be created / modified at runtime
user/favorite.xml (optional): stores the favorite Waypoints over application lifetime
user/history.xml (optional): stores the history of navigation destinations over application lifetime
user/POI.xml (optional): used to configure poi appearance and visibility
user/licence (required): Encrypted licence file that makes the SDK work for a specific application and configures the available features. Each application that uses the SDK needs its own licence file

The folder names (res, data, user) are passed to the SDK during initialisation an can be changed if desired.

Licensing

The SDK is licensed via a specific encrypted licence file that has to be present (user/licence) at runtime. It contains server and feature configurations as well as the product activation for a specific App.

Initialization / Uninitialization

In order to use the SDKs methods or instance methods of SDK objects, it has to be initialized. The Module Api provides the appropriate method. Without initialization you are only able to create instances of the various SDK Modules and configure the Logging Module. All other SDK methods (if not stated otherwise) will return an error code.

The initialization of the SDK requires the runtime data to be present on the device and its location has to be passed to the initialization call. Further, the computation site for the different modules (onboard or offboard) have to be declared at that time. After execution the configurations are applied and some of the map data is loaded into memory.

After finishing the App you have to execute the SDK's uninitialized method, to free the resources, close possible online connections and store persistent configuration data.

Computation Site

The individual modules of the SDK can either work offboard (online) or onboard (offline). Some modules, e.g. the Navigation, can use both (Hybrid Mode). The computation site has to be declared at the SDK's initialization. Certain methods of the SDK are only available in "Offboard" mode and others are only available in "Onboard" mode. An example where both limitations occur is the Geocoder. Those limitations are documented in the following way:

Attention

Offboard only

Method calls and events

Many of the SDK modules provide static methods that can directly be executed after initialization. One of the prominent examples is the Geocoder module. Other modules have to be instantiated like the Waypoint or Navigation .

For both cases, it is possible that the SDK Module indicates progress or state changes via events. Dependent on the type of module, the registration for the events take place at (static) class level (Geocoder) or at instance level (Navigation). Those callbacks inform for example about the Navigation state on every GPS signal, if speech advises will be played, or the progress of a Geocoder operation.

Asynchronous operations

Certain functionalities of the SDK are executed in an asynchronous thread because the calculation takes some time or involves server communication. Examples are the search for addresses, calculating routes or finding points of interest. All methods that spawn such a task will return an instance of the Task Module. The Task can be of various types (Template implementation Task) which depends on the Result it will generate. Every method that spawns a task will return the correct template instance of the task. Further, the module can register an event resp. task listener, that throws an continuous event indicating the progress, as well as an event that is thrown if the task is finished.

Error Handling

Most of the SDK methods return an errorcode to indicate if the call was successful or not. If an SDK call does not return an errorcode, its success state can be requested from the Api (see Api.getLastError() and Api.getLastErrorDescription()). Such error situations can occur e.g. if a route calculation is started without specifying a destination. Every SDK methods documentation contains the possible errorcodes.

Coordinate Frames

All method parameters and return values that provide / require geo coordinates are represented in internal coordinates. Those are currently in the Mercator projection but might be subject to change. In order to be compatible and independent of the Coordinate frame we provide conversions in our Projection module.

Object comparison

Objects can be compared to identity with the Object equals method.

Object validation

To test whether an object is valid it can be compared to null.

POI

The SDK allows you to show self defined POI icons on the map by adding a png icon to the Waypoint ( Waypoint.setPoiIcon()) and showing it on the map (Mapviewer.showWaypoint()). The icons are automatically scaled for the device resolution. You can configure a global scaling factor for all POI in the file mapservices.xml:

<tablets>
    <os desc="operating system">
        <android>
            <poiIconScale>0.3</poiIconScale>
        </android>
    </os>
</tablets>
<smartphones>
    <os desc="operating system">
        <android>
            <poiIconScale>0.3</poiIconScale>
        </android>
    </os>
</smartphones>

The global scaling factor can be defined for smartphones and tablets. The mapservices xml tag controls up to which size a device is interpreted as phone / tablet by the attribute maxPhoneSize=5.5 The scaling factor affects all POI no matter if manually created Waypoints or POI from an online or local source.

SDK Runtime Thread

The SDK runs on its own thread of execution to keep the GUI reactive. This thread is started on the ApiHelper.initialize(Context, ApiListener) method and is destroyed on the ApiHelper.uninitialize() method. All MapTrip SDK methods will automatically be synchronized to this thread and block until the execution is finished. Further, all callbacks from the MapTrip SDK are executed from this thread and if the GUI should be accessed in such a callback, you have to take care for executing such methods on the UI Thread. Due to the nature of synchronization, this procedure costs some execution time. This is especially noticeable if Methods are used that modify the map ( like showWaypoint) since here further synchronization is required between the rendering threads and the MapTrip SDK Thread. To speed up such consecutive calls, the ApiHelper class provides the Method queueApiCall. It allows to create a runnable that will execute on the MapTrip SDK thread and bundle multiple consecutive calls to be executed in a single Task, resp. thread run.

ApiHelper.Instance().queueApiCall(new Runnable() {
       @Override
       public void run() {
           for ( int i = 0; i < 20; ++i ){
               myMap.showWaypoint(wpt1)
           }
       }
   });

SDK extension Classes

In addition to the library itself, the MapTrip Android SDK library contains platform specific extension classes. The SDKs core is platform independent, but to make it comfortable to use on android, these extensions adopt the SDK to the platforms habits. The most important extensions that are essential to use with the SDK on Android are listed here.

ApiHelper

The ApiHelper class is a singleton implementation that handles the runtime of the SDK ( ApiHelper.initialize(), ApiHelper.uninitialize() ). It encapsulates the initialization and starts the runtime Thread of the SDK with the initialization

IwLocationManager

The IwLocationManager class provides a location that can originate from a GPS receiver (IwLocationManagerGPS ), from a log File (IwLocationManagerLog) or from user input (IwLocationManagerManual)

IwMapView

The IwMapView is the container for the map. It is an android view and lives with the android lifecycle. You can add it by XML to your views hierarchy and modify the map f.e. by the getter IwMapView.getMapviewer()

IwMapviewerConfig

The IwMapviewerConfig class allows you to access the MapViewer's state. This includes f.e. Position, zoomlevel, visible POI ... You can pass the config via Intents, apply it to any other MapViewer, or just use it to modify a map.