IviSetting

Exposes an IVI property as a setting with accessMode.

A setting may only be a val property. A setting with IviSettingAccessMode.READ_WRITE has a corresponding update member function.

This annotation only takes effect on an (outer) interface annotated with an IviService or IviDiscoverableService annotation.

When this annotation is used in an interface it prohibits any other member functions and event listener interface in the same interface. It also prohibits any other properties without this annotation. In other words, when this annotation is used, the interface may only have other properties that are annotated with this annotation.

The <Interface>Base class contains a few member functions for a property:

• init<Property> to initialize a property, called from initSettingsService. It has a default implementation if the property type is supported by the settings management API.

• read<Property>FromStorage to read a property value from the persistent storage. It has a default implementation if the property type is supported by the settings management API.

• (Writable properties only) write<Property>ToStorage to write a property value to the persistent storage. It has a default implementation if the property type is supported by the settings management API.

• (Writable properties only) update<Property> is a member function to update the property value. It has a default implementation if the property type is supported by the settings management API.

Default implementations for property's methods pass the property's value to the settings management API and take the result of the API calls without conversion. Custom implementations should convert values from and to supported types.

Example

@IviService(
    serviceId = "org.example.services.foo"
)
interface FooSettingsService {
    @IviSetting(accessMode = IviSettingAccessMode.READ_ONLY)
    val foo: Int

    @IviSetting(accessMode = IviSettingAccessMode.READ_WRITE)
    val bar: String
}

The <Interface>Api class in the example has the following public members:

class FooSettingsServiceApi {
    val serviceAvailable: LiveData<Boolean>

    val foo: LiveData<Int>
    val bar: LiveData<String>

    fun updateBarAsync(newValue: String, onResult: ...)
    suspend fun coUpdateBar(newValue: String)
}

The <Interface>Base class in the example has the following members:

class FooSettingsServiceBase {
    // Generated because `Int` type is supported by the settings management API.
    protected abstract val fooConfigurationKey: IntDynamicConfigurationKey?
    protected abstract val fooSettingKey: IntSettingKey?
    // Generated because `String` type is supported by the settings management API.
    protected abstract val barConfigurationKey: StringDynamicConfigurationKey?
    protected abstract val barSettingKey: StringSettingKey?

    protected abstract fun initFoo(storedSettingsVersion: Int)
    protected abstract fun initBar(storedSettingsVersion: Int)

    protected open suspend fun readFooFromStorage(): Int = ...
    protected open suspend fun readBarFromStorage(): String = ...

    protected open suspend fun writeFooToStorage(newValue: Int) = ...
    protected open suspend fun writeBarToStorage(newValue: String) = ...

    override suspend fun updateFoo(newValue: Int) { ... }
    override suspend fun updateBar(newValue: String) { ... }
}