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.

Example

In this sample code you can see how to read some of the application settings, namely: volume, voice and truck length.
For a convenient working with json structure we use widespread NewtonSoft C# library.

class TruckSettings
{
    public int Length { get; set; }
}
class AppSettings
{
    public int Volume { get; set; }
    public string Voice { get; set; }
    public TruckSettings TruckSettings { get; set;}
}

void demo()
{
    SError err;
    String json;
    CApplicationAPI.GetApplicationOptions(out err, out json, 0);
    var apo = Newtonsoft.Json.JsonConvert.DeserializeObject<AppSettings>(json);
    Console.WriteLine("sound volume {0}", apo.Volume);
    Console.WriteLine("sound voice  {0}", apo.Voice);
    Console.WriteLine("truck length {0}", apo.TruckSettings.Length);
}        

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.

Example

In this sample code you can see how to set few applications attributes, namely: volume, voice and truck length.
For a convenient working with json structure we use widespread NewtonSoft C# library.

class TruckSettings
{
    public int Length { get; set; }
}
class AppSettings
{
    public int Volume { get; set; }
    public string Voice { get; set; }
    public TruckSettings TruckSettings { get; set;}
}

void demo()
{
    SError err;
    var apo = new AppSettings();
    apo.Volume = 6;
    apo.Voice = "english_woman";
    apo.TruckSettings = new TruckSettings();
    apo.TruckSettings.Length = 9999;
    String json = Newtonsoft.Json.JsonConvert.SerializeObject(apo);
    CApplicationAPI.SetApplicationOptions(out err, json, 0);
}

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.

Example

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

void SetTruck()
{
    SError err;
    SChangeOption options = new SChangeOption(); // to define options for truck

    options.bUseTruckAtt = 1; // truck attributes approved
    options.nTruckWeightTotal = 16000;
    options.nTruckLenght = 9000;
    options.nTruckWidth = 2300;
    options.nTruckHeight = 3500;
    int ret = CApplicationAPI.ChangeApplicationOptions(out err, ref options, 0);
}

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
{
    SError err;
    int ret;

    SChangeOption options = new SChangeOption(); // to define options for planning preferences change
    options.nPlanningSettings = 3;
    options.nAvoidTollRoads = 3;
    ret = CApplicationAPI.ChangeApplicationOptions(out err, ref options, 0);

    Options changedOptions = new SChangeOption();           
    ret = CApplicationAPI.ChangeApplicationOptions(out err, changedOptions, 0);

    assertEquals("test_planning", options.nPlanningSettings, changedOptions.nPlanningSettings);
    assertEquals("test_tolls", options.nAvoidTollRoads, changedOptions.nAvoidTollRoads);
}

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