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

Parameter Type Permitted Values
SoundEnabled bool
Volume int 0-10
DistanceUnits int 0 = Miles/Yards, 1 = Kilometers, 2 = Miles/Feet
ClockFormat int 0 = clock_eu (14:00), 1 = clock_us (2:00 PM), 2 = clock_uk
GPSUnits int 0 = Degrees (0.0), 1 = Minutes (00.0'), 2 = Seconds (00'0")
Language string valid name of the *.lang file residing in /Res/skin/langs/
Voice string valid name of the folder residing in /Res/skin/voices/
Person string based on OS name
DisableMenu bool
TollSettings bool
PlanningSettings int 1 = Fastest, 2 = Shortest, 3 = Economic
AvoidMotorways bool
AvoidUnpavedRoads bool
AvoidUturns bool
AvoidFerries bool
PreferRightTurn bool
DestInDrivingSide bool
AllowItineraryEdit bool
RadarWarning bool
RadarDistance int 1 - 20
RadarDistanceInCity int 1 - 5
SpeedExceed int 0-20
SpeedExceedInCity int (-10) - (+20)
MaxSpeedWarning bool
MaxSpeedSoundName string valid name of the *.ogg file residing in /Res/sounds/
View int 0 = 3D (North Up Disabled), 1 = 2D (North Up Off), 2 = 2D (North Up On)
Skin int 0 = Day, 1 = Night, 2 = Automatic
UseTruckAttributes int 0=car, 1=truck, 2=bus/camper, 3=van
TruckSettings struct

TruckSettings

Parameter Type Permitted Values
LoadRestrictions int
MaxSpeed int
Length int
Height int
Width int
WeightAxle int
WeightTotal int
TandemWeight int
TridemWeight int
OtherWeight int
UnladenWeight int
AxleLength int
TrailerLength int
TractorLength int
OtherLength int
KingpinLastAxle int
KingpinLastTandem int
KingpinEndTrailer int
LoadRestrictions int
TunnelCode string B,C,D,E
GeneralHazmat bool
ExplosiveHazmat bool
HarmfulToWater bool
HazmatUS struct
EmissionCategory int 1,2,3,4,5,6
EmissionProductionYear int

HazmatUS

Parameter Type Permitted Values
Explosives bool
FlamableGases bool
FlammableLiquids bool
FlammableSolids bool
Oxidizers bool
Poisonous bool
Radioactive bool
Corrosive bool
Hazardous bool
InhalationHazard bool