Overview

Version added 07-Mar-2018| Modified 20-Jun-2018

Before we explain the creation of a native service, it is important to understand LS2.

LS2 provides a bus-based IPC mechanism used between components in webOS. It is composed of:

  • Client library - Provides API support to register on the bus and communicate with other components. The types and functions of the client library are explained in the tables below.

  • Central hub daemon - Provides a central clearing house for all communication. Utilities for monitoring and debugging the bus are included.

Since LS2 is based on GLib, you need to understand GLib. For more information about GLib, please see GLib Reference Manual.

 

Static and Dynamic Services

Depending on its registration on the LS2 bus, services can be categorized as static or dynamic services. This configuration can be done in the service configuration file (explained below).

  • Static services - Most static services are started at boot by systemd.

This is only an option for native services written in C/C++.

If the service crashes, the LS2 library will buffer requests to the service and deliver them to the service after it has restarted (assuming it is re-spawned by systemd).

If the service does not need to be running all the time, it is preferable to make it a dynamic service in order to save memory and reduce system load.

  • Dynamic services - A dynamic service is one that is launched on demand. This "lazy launching" behavior allows us to improve boot time by staggering out service launch and reduce the memory footprint by only running necessary services.

For example, if you create a dynamic service called com.example.service.foo, it will be automatically launched the first time someone attempts to send a message to it. 

Furthermore, less critical services will often timeout and exit after an extended period of inactivity.

 

Type Definitions

Description of the typedefs that are used in this example.

Definition Description

LSHandle

Handle to the service.

LSMessage

Message object.

  • Contains information about methods, connection tokens, client payload (request arguments), and whether a subscription is requested.
  • It is necessary to pass the response to the client.
  • Functions that can obtain the information are LSMessageGetMethod (), LSMessageGetPayload (), and so on.

LSMethodFunction

typedef bool(*)(LSHandle sh, LSMessage msg, void *category_context) LSMethodFunction

Table registration of callbacks.

Parameters:

  • sh - handle to service
  • msg - message object
  • category_context - category context

Returns:

  • bool - true on success, otherwise false

LSError

Error object which contains information about first error since it was initialized via LSErrorInit.

 

Function Definitions

Description of the methods that are used in this example.

Definition Description

bool LSErrorInit (LSError* lserror)

Initializes a LSError.

Parameters:

  • lserror - LSError structure to initialize

Returns:

  • bool - true on success, otherwise false

void LSErrorPrint (LSError *lserror, FILE *out);

Prints a LSError.

Parameters:

  • lserror - LSError structure to print
  • out - handle to file

bool LSMessageReply (LSHandle *sh, LSMessage *msg, const char *json, LSError * lserror)

Sends a reply to a message using the bus identified by LSHandle.

Parameters:

  • sh - handle to service
  • msg - message
  • json - json as payload
  • lserror - set one error

Returns:

  • bool - true on success, otherwise false

bool LSRegister (const char *name, LSHandle **sh, LSError *lserror)

Registers a service on the LS2 bus.

Parameters:

  • name - service name
  • sh - handle to service
  • lserror - set on error

Returns:

  • bool - true on success, otherwise false

bool LSRegisterCategory (LSHandle *sh, const char *category, LSMethod  *methods, LSSignal *signals, LSProperty *properties, LSError *lserror)

Registers tables of callbacks associated with the message category.

Parameters:

  • sh - handle to service
  • category - may be NULL for default '/' category.
  • methods - table of methods
  • signals - table of signals
  • properties - table of properties
  • lserror - set on error

Returns:

  • bool - true on success, otherwise false

bool LSGmainAttach (LSHandle *sh, GMainLoop *mainLoop, LSError *lserror)

Attaches a service to a glib mainloop.

Parameters:

  • sh - handle to service
  • mainLoop - loop to attach
  • lserror - set on error

Returns:

  • bool - true on success, otherwise false

bool LSUnregister (LSHandle *sh, LSError *lserror)

Unregisters a service.

Parameters:

  • service - handle to service
  • lserror - set on error

Returns:

  • bool - true on success, otherwise false
Except as noted, this content is licensed under Creative Commons Attribution 4.0 and sample code is licensed under Apache License 2.0.