Developer

Managing settings

Request Access

Managing settings

The SettingsManager provides access to user settings in the system. It allows you to observe and modify settings, see Available settings for a list of available settings. All settings are readable, but only settings marked as writable can be changed.

Observing settings

Subscribe to receive updates when a setting value changes. The SettingsManager provides type-specific observation methods: observeBooleanSetting, observeStringSetting, observeIntSetting, and observeFloatSetting.

1import android.util.Log
2import com.tomtom.automotive.integration.client.api.settings.SettingsManager
3import com.tomtom.automotive.integration.client.api.settings.observesettings.ObserveSettingFailure
4import com.tomtom.automotive.integration.client.api.settings.observesettings.ObserveSettingListener
5import com.tomtom.automotive.integration.client.api.settings.observesettings.ObserveSettingParameters
6import com.tomtom.automotive.integration.client.common.Callback
7import com.tomtom.automotive.integration.client.common.Result
8import com.tomtom.automotive.integration.client.common.SdkReleasable
9

10private val TAG = "Settings"
11private var observeSettingReleasable: SdkReleasable? = null
12

13fun observeStringSetting(settingsManager: SettingsManager, settingKey: String) {
14    observeSettingReleasable = settingsManager.observeStringSetting(
15        ObserveSettingParameters(settingKey),
16        object : ObserveSettingListener<String?> {
17            override fun onValueChanged(value: Result<String?, ObserveSettingFailure>) {
18                when (value) {
19                    is Result.Success -> {
20                        val settingValue = value.value
21                        Log.d(TAG, "Setting '$settingKey' changed to: $settingValue")
22                    }
23                    is Result.Failure -> {
24                        when (value.failure) {
25                            ObserveSettingFailure.NOT_EXIST -> {
26                                Log.e(TAG, "Setting '$settingKey' does not exist")
27                            }
28                            ObserveSettingFailure.WRONG_TYPE -> {
29                                Log.e(TAG, "Setting '$settingKey' is not a string type")
30                            }
31                        }
32                    }
33                }
34            }
35            
36            override fun onFunctionalityUnavailable(reason: Callback.Reason) {
37                Log.e(TAG, "Settings unavailable: ${reason.devMessage}")
38            }
39        }
40    )
41}
42

43fun unObserveSetting() {
44    observeSettingReleasable?.release()
45    observeSettingReleasable = null
46}

Saving settings

Modify writable settings using the type-specific save methods: saveBooleanSetting, saveStringSetting, saveIntSetting, and saveFloatSetting. Only settings marked as writable can be changed.

1import android.util.Log
2import com.tomtom.automotive.integration.client.api.settings.SettingsManager
3import com.tomtom.automotive.integration.client.api.settings.savesettings.SaveSettingCallback
4import com.tomtom.automotive.integration.client.api.settings.savesettings.SaveSettingFailure
5import com.tomtom.automotive.integration.client.api.settings.savesettings.SaveSettingParameters
6import com.tomtom.automotive.integration.client.common.Callback
7import com.tomtom.automotive.integration.client.common.Result
8

9private val TAG = "Settings"
10

11fun saveStringSetting(settingsManager: SettingsManager, settingKey: String, value: String) {
12    settingsManager.saveStringSetting(
13        SaveSettingParameters(settingKey, value),
14        object : SaveSettingCallback {
15            override fun onSaveCompleted(result: Result<Unit, SaveSettingFailure>) {
16                when (result) {
17                    is Result.Success -> {
18                        Log.d(TAG, "Setting '$settingKey' saved to: $value")
19                    }
20                    is Result.Failure -> {
21                        when (result.failure) {
22                            SaveSettingFailure.NOT_EXIST -> {
23                                Log.e(TAG, "Setting '$settingKey' does not exist")
24                            }
25                            SaveSettingFailure.READ_ONLY -> {
26                                Log.e(TAG, "Setting '$settingKey' is read-only")
27                            }
28                            SaveSettingFailure.WRONG_TYPE -> {
29                                Log.e(TAG, "Setting '$settingKey' is not a string type")
30                            }
31                        }
32                    }
33                }
34            }
35            
36            override fun onFunctionalityUnavailable(reason: Callback.Reason) {
37                Log.e(TAG, "Settings unavailable: ${reason.devMessage}")
38            }
39        }
40    )
41}

Error handling

Observation failures

The ObserveSettingFailure enum describes possible failure reasons when observing settings:

  • NOT_EXIST - A setting with the given key doesn't exist
  • WRONG_TYPE - The key references a setting of a different type

Save failures

The SaveSettingFailure enum describes possible failure reasons when saving settings:

  • NOT_EXIST - A setting with the given key doesn't exist
  • READ_ONLY - The setting is defined as read-only and cannot be modified
  • WRONG_TYPE - The key references a setting of a different type