Version: Smart Feature Phone 3.0

SettingsManager service

Settings API is a way to access, change, and monitor changes to the device's settings. Because device settings can contain a lot of sensitive information that can jeopardize the system, only core applications with settings permission can use this API.

Starting from KaiOS 3.0, some APIs are moved to API daemon flexibility. API daemon is a stand-alone service which works closely with b2g.

To use settings API on KaiOS 3.0 and later, applications need to communicate with API daemon directly. All requests to API daemon are async, and returned by promise.

Note that on simulators, the host should be changed from http://127.0.0.1 to http://127.0.0.1:8081.

Load the utility scripts

<script src="http://127.0.0.1/api/v1/shared/core.js"></script>
<script src="http://127.0.0.1/api/v1/shared/session.js"></script>
<script src="http://127.0.0.1/api/v1/settings/service.js"></script>

Get token to create connections with api-daemon

navigator.b2g.externalapi.getToken().then(token => {
  let session = new lib_session.Session();
  let sessionstate = {};
  sessionstate.onsessionconnected = () => {
    lib_settings.SettingsManager.get(session)
        .then((service) => {
          // calling settings API with the service.

          // get one setting
          service.get('testing.setting1')
              .then((val) => { console.log(`get() ${val.name} ${val.value}`); },
                    (err) => {
                      if (err ==
                          lib_settings.GetErrorReason.NON_EXISTING_SETTING) {
                        console.log('The setting does not exist.');
                      } else {
                        console.log('Unexpected error.');
                      }
                    });

          // set settings
          service.set([
            {name : "testing.setting1", value : 42},
            {name : "testing.setting2", value : "test-string"}
          ]);

          // get batch settings
          service.getBatch([ "testing.setting1", "testing.setting2" ])
              .then(
                  (val) => {
                    val.forEach(v => {
                      console.log(`getBatch() resolve ${v.name} ${v.value}`);
                    });
                  },
                  (err) => { console.log('Unexpected error.'); });

          // observe one setting
          class MyObserver extends lib_settings.SettingObserverBase {
            constructor(service, session) { super(service.id, session); }

            display() { return "Setting observer"; }

            callback(val) {
              console.log(`MyObserver::callback ${val.name} ${
                  JSON.stringify(val.value)})`);
              return Promise.resolve();
            }
          }

          let observer = new MyObserver(service, session);
          service.addObserver("testing.setting1", observer);

          // listen to all change events
          let handler = (val) => {
            console.log(`handler ${val.name} ${JSON.stringify(val.value)})`);
          };
          service.addEventListener(service.CHANGE_EVENT, handler);

          // set settings to verify observer and event handler
          service
              .set([
                {name : "testing.setting1", value : {foo : "bar"}},
                {name : "testing.setting2", value : true}
              ])
              .then(() => {
                // remove observer and event handler
                service.removeObserver("testing.setting1", observer);
                service.removeEventListener(service.CHANGE_EVENT, handler);
              });
        })
        .catch(console.error);
  };
  sessionstate.onsessiondisconnected = () => {};
  session.open('websocket', '127.0.0.1', token, sessionstate, true);
});