Basics

webOS OSE services are provided as LS2 APIs. These APIs can be consumed by clients such as apps, components, and other API.  

Let us understand some basic concepts of LS2 API.

Basic Terminology

Definition of some terms that you will come across when using LS2 API.

Address

Each LS2 service provides some functionality and is accessible at a unique address which follows the format "luna://servicename"

For example: The systemservice provides access to system settings and is accessible on the LS2 bus at the address "luna://com.webos.service.systemservice"

We use this service as a reference point to present the rest of the LS2 concepts.
Methods

Each LS2 service consists of one or more methods that are categorized by the function they perform.

For example: The systemservice provides time-based functionality and you can get and set system times using the following methods:

  • luna://com.webos.service.systemservice/time/getSystemTime
  • luna://com.webos.service.systemservice/time/setSystemTime

 

The methods can accept one or more parameters and also return a result. Let us see examples of the above two methods:

  • getSystemTime 
    • Does not require any input parameters. 
    • Returns status of the operation and also the current time.
  • setSystemTime 
    • Accepts the Unix time as an input parameter.
    • Returns the status of the operation.
Messages

Data which is sent (request) and received from a method (response) is called a message.

LS2 messages are provided in JSON format.

Due to the way in which the LS2 bus is implemented, the order of messages cannot be guaranteed to be same as the order it is sent in.
Public and private API

Private (internal) APIs can only be accessed by internal webOS components.

Public APIs can be accessed by internal as well as third-party applications and services.

 

Static and dynamic API

Static APIs are loaded at boot-time and stay resident.

Dynamic APIs are loaded on-demand. 

Unless your service needs to be running all the time, it is preferable to make it a dynamic service in order to save memory and reduce load for the system.

Sleepd is an example of a static LS2 API. See API Reference for more information.

Invoking Methods

Clients can make a request to a method which provides a response in JSON format. The section below provides an example of calling the getSystemTime method using the luna-send tool.

The curly braces below ('{}') indicate that no parameters are passed to the method.
The response returned by the API method is shown in the lines after the '==>' characters within the curly braces.
luna-send -P -n 1 -f luna://com.webos.service.systemservice/time/getSystemTime '{}'
==>
{
    "timeZoneFile": "/var/luna/preferences/localtime",
    "utc": 1418745990,
    "localtime": {
        "month": 12,
        "day": 16,
        "hour": 11,
        "minute": 6,
        "year": 2014,
        "second": 30
    },
    "offset": -300,
    "timezone": "Asia/Seoul",
    "TZ": "EST",
    "systemTimeSource": "sdp"
}

Subscribing for Notifications

Clients can subscribe for notifications of some methods. In this case, the client makes a request to the method and the client is notified when any updates are available. This works well for operations where the information is likely to change and where the client needs the latest information.

For example, client can subscribe to the getSystemTime method as follows:

luna-send -P -n 1 -f luna://com.webos.service.systemservice/time/getSystemTime '{"subscribe": true}'

By setting the subscribe parameter to true, the client subscribes to get notifications in the following situations:

  • Everytime the system time changes by more than 5 minutes
  • When the timezone changes
In most cases, subscription is only supported on methods that accept the subscribe parameter. However, some methods are subscription-only; meaning that they are automatically subscribed and do not have the subscribe parameter.

To stop notifications, you must unsubscribe from the method. In the above example, set "subscribe": false.

Except as noted, this content is licensed under Creative Commons Attribution 4.0 and sample code is licensed under Apache License 2.0.