Settings API

Overview

Settings API provides functions GetApplicationOptions and SetApplicationOptions, which allow reading and overwriting some application settings. Alternatively there is the initialization file settings.ini, which allows you to configure some parameters in a hardwired way. This API is about a runtime flexibility.

GetApplicationOptions

GetApplicationOptions retrieves all currently reportable application setttings output in a json string.
Check the structure of the json string in the section Json Application Settings

Check details of GetApplicationOptions in the reference manual.
The function will officialy be available with the release 13.7.7.

Example

In this sample code you can see how to read some of the application settings, namely: volume, voice and truck length.

    import com.sygic.sdk.remoteapi.ApiOptions;
    import com.sygic.sdk.remoteapi.exception.GeneralException;

    void demo() {

        String options;
        try {
            options = ApiOptions.getApplicationOptions(0);
        } catch (GeneralException e) {
            Log.d("Error", e.getMessage());
            return;
        }

        int volume;
        String voice;
        int truckLength;
        try {
            JSONObject obj = new JSONObject(options);
            volume = obj.getInt("Volume");
            voice = obj.getString("Voice");
            truckLength = obj.getJSONObject("TruckSettings").getInt("Length");
        } catch (JSONException e) {
            Log.d("Error", e.getMessage());
            return;
        }
        Log.d("Info", voice + ":" + volume + "/" + truckLength);

    }

SetApplicationOptions

SetApplicationOptions can write all or some selected parameters.
The mechanism for writing is to create the json string, which contains only the attributes to be changed.

Check details of SetApplicationOptions in the reference manual.
The function will officialy be available with the release 13.7.7.

Example

In this sample code you can see how to set few applications attributes, namely: planning option, sound for exceeding the speed and the flag avoid motorways.

    import com.sygic.sdk.remoteapi.ApiOptions;
    import com.sygic.sdk.remoteapi.exception.GeneralException;

    void demo()
    {
        JSONObject obj = new JSONObject();
        try {
            obj.put("PlanningSettings", 2);
            obj.put("MaxSpeedSoundName", "/sounds/ding.ogg");
            obj.put("AvoidMotorways", true);

        } catch (JSONException e) {
            Log.d("Error", e.getMessage());
            return;
        }

        String options = obj.toString();
        try {
            ApiOptions.setApplicationOptions(options, 0);
        } catch (GeneralException e) {
            Log.d("Error", e.getMessage());
            return;
        }
    }

ChangeApplicationOptions

ChangeApplicationOptions can read all or write some selected parameters.
The mechanism for writing is to create a new Options instance, which sets by default all parameters as "dont-touch". And then, by filling only selected parameters the settings update affects only those.

Check details of ChangeApplicationOptions in the reference manual.
Please note this function becomes deprecated since the release 13.7.7.

Example

In this sample code you can see how to set truck attributes. The dimensions are passed in millimeters and weight in kilograms.

import com.sygic.sdk.remoteapi.ApiOptions;
import com.sygic.sdk.remoteapi.exception.GeneralException;
import com.sygic.sdk.remoteapi.model.Options;

try
{
    Options truckOptions = new Options();
    int maxTime = 0;

    //setting up truck attributes
    truckOptions.bUseTruckAtt = 1; //1 for using truck attributes, else -1
    truckOptions.nTruckHeight = 3500; //mm
    truckOptions.nTruckWidth = 2300; //mm
    truckOptions.nTruckLenght = 9000; //mm
    truckOptions.nTruckWeightTotal = 16000; //kg

    ApiOptions.changeApplicationOptions(truckOptions, maxTime);
}
catch (GeneralException e) {
    e.printStackTrace();
}

Example

This example shows how you can dynamically set planning preference (3 means calculate shortest routes) and avoid toll preferences (3 means never avoid toll roads) and read the values back using null argument.

Check details of Options parametrization in the reference manual.

    void demo {
        try
        {
            Options options = new Options();
            Options changedOptions;

            options.nPlanningSettings = 3;
            options.nAvoidTollRoads = 3;
            ApiOptions.changeApplicationOptions(options, 0);
            changedOptions = ApiOptions.changeApplicationOptions(null, 0);
            assertEquals("test_planning", options.nPlanningSettings, changedOptions.nPlanningSettings);
            assertEquals("test_tolls", options.nAvoidTollRoads, changedOptions.nAvoidTollRoads);
        }
        catch(GeneralException e) {
            e.printStackTrace();
        }
    }

ImportFile

ImportFile can transfer any sort of stream into a file residing within Sygic navigation folder structure, so that it is accessible to Sygic navigation when necessary. This function has been introduced to overcome Android limitations (starting from KitKat) of file access permissions between two applications.
With the function it is possible to cut the stream into multiple chunks and transfer it successively, typically applicable with large size transfers. For this there is the third argument of the function specifying the append option.

Check details of ImportFile in the reference manual.
Please note the function is currently availabe only in a beta release and will appear in the coming release 13.7.2.

Example

This example shows transfer of a short text message into a file inside Sygic navigation folder space so that Sygic navigation can access it. The file will appear in the root folder of Sygic, e.g. SygicNavigation/Res/import/my.txt in case the Sygic Fleet version is used. In a real world this could be an itinerary for routing or a custom icon picture for a custom POI visualization. The example shows the transfer in one shot, but it is possible to be split in several chunks using the append flag.

void demo()
{
        String destFileName = "Res/import/my.txt";

        try {
            String str = "This text gets transferred into Navigation space";
            InputStream is = new ByteArrayInputStream(str.getBytes());
            byte[] buffer = new byte[5000];
            if (is.read(buffer) == -1)
                return;
            String base64 = Base64.encodeToString(buffer, Base64.DEFAULT);
            is.close();
            boolean append = false;
            String filepath = Api.importFile(base64, destFileName, append);
            Log.i("Info", "resource file placement: " + filepath);
        }
        catch(IOException e) {
            Log.e("Error", "resource transfer problem");
        }

}

Json Application settings object

The json specification of the supported structure is shown bellow.

{
  "SoundEnabled" : true,
  "Volume" : 5,
  "Voice" : "english_woman",
  ...
  "TruckSettings" :
  {
     "MaxSpeed" : 90,
     "Length" : 4575,
     ...
     "HazmatUS" : 
     {
        "Explosives" : true,
        ...
     }
  }
}

The full list of attributes is enlisted in the tables bellow

Root

TruckSettings

HazmatUS