Version: Smart Feature Phone 3.0

SystemMessage API

System messages are messages from the system, they are sent by the system based on their types, for example, a system message with name alarm is sent to its subscriber when a timer goes off; a system message with name sms-received is sent when the system receives an sms message. SystemMessage API gives applications the ability to subscribe system messages of particular names, and events SystemMessageEvent will dispatched to its registered ServiceWorker in different scenarios.

Message types#

NamePermission
activity
alarmalarms
bluetooth-dialer-commandbluetooth-privileged
bluetooth-map-requestbluetooth-privileged
bluetooth-opp-receiving-file-confirmationbluetooth-privileged
bluetooth-opp-transfer-completebluetooth-privileged
bluetooth-opp-transfer-startbluetooth-privileged
bluetooth-opp-update-progressbluetooth-privileged
bluetooth-pairing-abortedbluetooth-privileged
bluetooth-pairing-requestbluetooth-privileged
bluetooth-pbap-requestbluetooth-privileged
cellbroadcast-receivedcellbroadcast
data-sms-receivedsms
icc-stkcommandsettings:read, settings:write
media-button
sms-delivery-errorsms
sms-delivery-successsms
sms-failedsms
sms-receivedsms
sms-sentsms
system-time-changesystem-time:read
telephony-call-endedtelephony
telephony-hac-mode-changedtelephony
telephony-new-calltelephony
telephony-tty-mode-changedtelephony
ussd-receivedmobileconnection
wappush-receivedwappush

For front-end and application developers#

To subscribe and receive system messages, an app has to have an active service worker.

Subscribe system messages from application manifest#

First, we need to specify the registration info of service worker in manifest, the format is as follows

"serviceworker": {
"script_url": "script_url",
"options": {
"scope": "scope_of_sw",
"update_via_cache": "value_of_update_via_cache"
}
},

The options object is optional, as defined in ServiceWorkerContainer.register()#Syntax, for example:

"serviceworker": {
"script_url": "sw.js"
},

In the most case the above example is good enough.

Second, subscribe the names of system messages in manifest.

"messages": [
"alarm",
"sms-received"
],

Since now that system messages are dispatched to service worker, the field of target page ("/index.html" in the above example) in gecko48 does not affect the receiving of system messages.

Subscribe system messages from service worker#

Apps can use SystemMessageManager.subscribe() to subscribe system messages on an active service worker. systemMessageManager is a property of ServiceWorkerRegistration, which returns a reference to the SystemMessageManager interface.

Use from main scripts#
navigator.serviceWorker.register("sw.js").then(registration => {
registration.systemMessageManager.subscribe("alarm").then(
rv => {
console.log('Successfully subscribe system messages of name "alarm".');
},
error => {
console.log("Fail to subscribe system message, error: " + error);
}
);
});
Use from service worker script#
self.registration.systemMessageManager.subscribe("alarm").then(
rv => {
console.log('Successfully subscribe system messages of name "alarm".');
},
error => {
console.log("Fail to subscribe system message, error: " + error);
}
);

Receive system messages#

System messages are delivered to the ServiceWorkerGlobalScope.onsystemmessage event handler, in the format of SystemMessageEvent.

SystemMessageEvent
name
The type of this system message.
data
Returns an object SystemMessageData which wraps the details of this system message.
SystemMessageData
json()
Extracts the message data as a JSON object, not available for activity messages.
WebActivityRequestHandler()
Only available for activity messages, details stated in WebActivity API.
self.onsystemmessage = evt => {
console.log("Receive systemmessage event with name: " + evt.name);
console.log(" message data: " + evt.data);
console.log(" data detail:");
try {
console.log(evt.data.json());
} catch (err) {
console.log(err);
}
};

For gecko developers#

SystemMessageService provides an interface for module developers to send system messages to target applications, or broadcasting messages to all subscribers.

Syntax

void sendMessage(in AString messageName, in jsval message, in ACString origin);
void broadcastMessage(in AString messageName, in jsval message);

Example

let sm = Cc["@mozilla.org/systemmessage-service;1"].getService(
Ci.nsISystemMessageService
);
let msg = { test1: "aaa", test2: "bbb" };
let appOrigin = "http://calculator.localhost";
sm.sendMessage("alarm", msg, appOrigin);