Service Applications

Service applications are Tizen native applications with no graphical user interface that run in the background. They can be very useful in performing activities (such as getting sensor data in the background) that need to run periodically or continuously, but do not require any user intervention.

The main Service Application API features include the following:

Application states

A Tizen native service application has several different states which it transitions through during its lifecycle.
Event callbacks

The service application can receive both basic system events and application state change events. You can register callbacks for these events to react to them.
Application behavior attributes

You can determine your application behavior at boot time and after abnormal terminations by using specific attributes which you can set in the application manifest file.

Service applications can be explicitly launched by a UI application. They can also be launched conditionally.

The user can check the running service applications in the task switcher; however, no events occur if the user selects a service application from the task switcher. The main menu does not contain icons for service applications. Multiple service applications can be running simultaneously with other service and UI applications.

Application states

The following figure and table describe the service application states.

Figure: Running service applications

Running service applications

Table: Service application states

State	Description
`READY`	Application is launched.
`CREATED`	Application starts the main loop.
`RUNNING`	Application runs in the background.
`TERMINATED`	Application is terminated.

Because a service application has no UI, neither does it have a pause state. Since Tizen 2.4, the service application can go into the suspended state. Basically, the service application is running in the background by its nature; so the platform does not allow running the service application unless the application has a background category defined in its manifest file. However, when the UI application that is packaged with the service application is running in the foreground, the service application is also regarded as a foreground application and it can be run without a designated background category. For more information on using and defining a background category, see Background categories.

Event callbacks

You can control the service application execution by monitoring and reacting to application state change and system events.

The following table lists the application state change events.

Table: Application states

Callback	Description
`service_app_create_cb()`	Used to take necessary actions before the main event loop starts. Place the initialization code (such as setting up the dbus connection) here.
`service_app_control_cb()`	Used to take necessary actions when a service call arrives from another application.
`service_app_terminate_cb()`	Used to take necessary actions when the application is terminating. Release all resources, especially any allocations and shared resources, so that other running applications can fully any shared resources.

The following table lists the system events.

Table: System events

Callback	Description
`service_app_low_memory_cb()`	Used to take necessary actions in low memory situations. Save data in the main memory to a persistent memory or storage, to avoid data loss in case the Tizen platform low memory killer kills your application to get more free memory. Release any cached data in the main memory to secure more free memory.
`service_app_low_battery_cb()`	Used to take necessary actions in low battery situations. Save data in the main memory to a persistent memory or storage, to avoid data loss in case the power goes off completely. Stop heavy CPU consumption or power consumption activities to save the remaining power.

Application attributes

Describe your service application attributes in the manifest file. The attributes determine the application behavior. The following code example illustrates how you can define the attributes:

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns="http://tizen.org/ns/packages" package="org.tizen.message" version="0.2.7"
          install-location="internal-only">
   <label>Message</label>
   <description>Message Application</description>
   <service-application appid="org.tizen.message" exec="/usr/apps/org.tizen.message/bin/message"
                        nodisplay="true" multiple="false" type="capp" taskmanage="false">
      <icon>org.tizen.message.png</icon>
      <label>Message</label>
   </service-application>
</manifest>

Prerequisites

To use the functions and data types of the Service Application API (in mobile and wearable applications), include the <service_app.h> header file in your application:

#include <service_app.h>

Monitor events

To monitor application state change and system events, proceed as follows:

Add callbacks for application state change events:
- Service application initialization callback
  
  This callback is called when the application is launched. Use the callback to write the necessary initialization code, such as setting up the dbus connection.
  
  The callback returns a Boolean value. If there is a critical error during the launch, the return is false, thereby cancelling the launch. Otherwise, the return is true:
```
bool
service_app_create(void *data)
{
    dlog_print(DLOG_DEBUG, LOG_TAG, "%s", __func__);

    return true;
}
```
- Service application termination callback
  
  This callback is called when the application terminates. Use the callback to release all resources, especially any allocations and shared resources used by other applications.
  
  The service_app_exit() function quits the application main loop internally:
```
void
service_app_terminate(void *data)
{
    dlog_print(DLOG_DEBUG, LOG_TAG, "%s", __func__);
    service_app_exit();

    return;
}
```
- Service request callback
  
  This callback is called when the service application receives an app_control service request from another application:
```
void
service_app_control(app_control_h app_control, void *data)
{
    dlog_print(DLOG_DEBUG, LOG_TAG, "%s", __func__);
    service_app_exit();

    return;
}
```

Add callbacks for system events:

Low memory callback

This callback is called when the device is low on memory:

void
service_app_low_memory_callback(void *data)
{
    dlog_print(DLOG_DEBUG, LOG_TAG, "%s", __func__);
    service_app_exit();

    return;
}

Low battery callback

This callback is called when the device is low on battery power:

void
service_app_low_battery_callback(void *data)
{
    dlog_print(DLOG_DEBUG, LOG_TAG, "%s", __func__);
    service_app_exit();

    return;
}

Set the application state change event callbacks in the service_app_event_callback_s structure. The structure is passed to the function that starts the service application.

You can register the system event callbacks with the service_app_add_event_handler() function:

int
main(int argc, char* argv[])
{
    appdata_s ad = {0,};
    service_app_lifecycle_callback_s event_callback = {0,};

    dlog_print(DLOG_DEBUG, LOG_TAG, "%s", __func__);

    event_callback.create = service_app_create;
    event_callback.terminate = service_app_terminate;
    event_callback.app_control = service_app_control;

    dlog_print(DLOG_DEBUG, LOG_TAG, "service_app_main() is called.");

    return service_app_main(argc, argv, &event_callback, &ad);
}

Dependencies
- Tizen 2.4 and Higher for Mobile
- Tizen 2.3.1 and Higher for Wearable