Tizen Native API  9.0
Functions | Typedefs
Service Application
Application Framework

Launches or exits serviceApp.

Required Header

#include <service_app.h>

Overview

The Service Application API provides functions for handling Tizen service application state changes or system events. This API provides interfaces for the following three categories:

  • Starting or exiting the main event loop.
  • Registering callbacks for application state change events.
  • Registering callbacks for basic system events.

How to Use Service Application API

A service application is a Tizen native application without a graphical user interface that runs in the background. The following example demonstrates a basic service application structure:

 #include <service_app.h>
 #include <dlog.h>

 typedef struct {
     // Application data structure
     int some_data;
 } appdata_s;

 static bool
 service_app_create(void *user_data)
 {
     // Initialize application resources
     appdata_s *ad = (appdata_s *)user_data;
     
     // Initialize data
     ad->some_data = 0;
     
     dlog_print(DLOG_INFO, "SERVICE_APP", "Service application created");
     
     return true;
 }

 static void
 service_app_terminate(void *user_data)
 {
     // Release all resources
     appdata_s *ad = (appdata_s *)user_data;
     
     dlog_print(DLOG_INFO, "SERVICE_APP", "Service application terminated");
 }

 static void
 service_app_control(app_control_h app_control, void *user_data)
 {
     // Handle the launch request
     appdata_s *ad = (appdata_s *)user_data;
     char *operation = NULL;
     
     app_control_get_operation(app_control, &operation);
     
     if (operation) {
         dlog_print(DLOG_INFO, "SERVICE_APP", "Operation: %s", operation);
         free(operation);
     }
 }

 int
 main(int argc, char *argv[])
 {
     appdata_s ad = {0,};
     service_app_lifecycle_callback_s event_callback;
     
     event_callback.create = service_app_create;
     event_callback.terminate = service_app_terminate;
     event_callback.app_control = service_app_control;
     
     return service_app_main(argc, argv, &event_callback, &ad);
 }

Handling System Events

Service applications can register event handlers for various system events such as low memory, low battery, language changes, and region format changes:

 static void
 service_app_low_memory(app_event_info_h event_info, void *user_data)
 {
     // Handle low memory event
     // Free cached data and reduce memory usage
     dlog_print(DLOG_WARN, "SERVICE_APP", "Low memory event occurred");
 }

 static void
 service_app_low_battery(app_event_info_h event_info, void *user_data)
 {
     // Handle low battery event
     // Reduce power consumption
     dlog_print(DLOG_WARN, "SERVICE_APP", "Low battery event occurred");
 }

 static void
 service_app_language_changed(app_event_info_h event_info, void *user_data)
 {
     // Handle language change event
     // Reload localized resources, update UI text, etc.
     dlog_print(DLOG_INFO, "SERVICE_APP", "Language changed event occurred");
 }

 static bool
 service_app_create(void *user_data)
 {
     app_event_handler_h handler;
     
     // Register event handlers
     service_app_add_event_handler(&handler, APP_EVENT_LOW_MEMORY, 
                                   service_app_low_memory, user_data);
     service_app_add_event_handler(&handler, APP_EVENT_LOW_BATTERY, 
                                   service_app_low_battery, user_data);
     service_app_add_event_handler(&handler, APP_EVENT_LANGUAGE_CHANGED, 
                                   service_app_language_changed, user_data);
     
     return true;
 }

Handling App Control

Service applications can receive and process app control requests from other applications:

 static void
 service_app_control(app_control_h app_control, void *user_data)
 {
     char *operation = NULL;
     char *uri = NULL;
     char *extra_data = NULL;
     
     // Get operation
     app_control_get_operation(app_control, &operation);
     
     if (operation) {
         dlog_print(DLOG_INFO, "SERVICE_APP", "Operation: %s", operation);
         
         // Get URI if available
         app_control_get_uri(app_control, &uri);
         if (uri) {
             dlog_print(DLOG_INFO, "SERVICE_APP", "URI: %s", uri);
             free(uri);
         }
         
         // Get extra data
         app_control_get_extra_data(app_control, "my_key", &extra_data);
         if (extra_data) {
             dlog_print(DLOG_INFO, "SERVICE_APP", "Extra data: %s", extra_data);
             free(extra_data);
         }
         
         free(operation);
     }
 }

Functions

int service_app_add_event_handler (app_event_handler_h *handler, app_event_type_e event_type, app_event_cb callback, void *user_data)
 Adds the system event handler.
int service_app_remove_event_handler (app_event_handler_h event_handler)
 Removes registered event handler.
int service_app_main (int argc, char **argv, service_app_lifecycle_callback_s *callback, void *user_data)
 Runs the main loop of the application until service_app_exit() is called.
void service_app_exit (void)
 Exits the main loop of the application.

Typedefs

typedef bool(* service_app_create_cb )(void *user_data)
 Called at the start of the agent application.
typedef void(* service_app_terminate_cb )(void *user_data)
 Called once after the main loop of the agent application exits.
typedef void(* service_app_control_cb )(app_control_h app_control, void *user_data)
 Called when another application sends the launch request to the agent application.

Typedef Documentation

typedef void(* service_app_control_cb)(app_control_h app_control, void *user_data)

Called when another application sends the launch request to the agent application.

Since :
2.3
Parameters:
[in]app_controlThe handle to the app_control
[in]user_dataThe user data passed from the callback registration function
See also:
service_app_main()
service_app_lifecycle_callback_s
App Control API
typedef bool(* service_app_create_cb)(void *user_data)

Called at the start of the agent application.

Since :
2.3
Parameters:
[in]user_dataThe user data passed from the callback registration function
Returns:
true on success, otherwise false
Precondition:
service_app_main() will invoke this callback function.
See also:
service_app_main()
service_app_lifecycle_callback_s
typedef void(* service_app_terminate_cb)(void *user_data)

Called once after the main loop of the agent application exits.

Since :
2.3
Parameters:
[in]user_dataThe user data passed from the callback registration function
See also:
service_app_main()
service_app_lifecycle_callback_s

Function Documentation

int service_app_add_event_handler ( app_event_handler_h *  handler,
app_event_type_e  event_type,
app_event_cb  callback,
void *  user_data 
)

Adds the system event handler.

Since :
2.3
Remarks:
The service application can handle low memory event, low battery event, language setting changed event and region format changed event.
Parameters:
[out]handlerThe event handler
[in]event_typeThe system event type
[in]callbackThe callback function
[in]user_dataThe user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
APP_ERROR_NONESuccessful
APP_ERROR_INVALID_PARAMETERInvalid parameter
APP_ERROR_OUT_OF_MEMORYOut of memory
See also:
app_event_type_e
app_event_cb()
service_app_remove_event_handler()
void service_app_exit ( void  )

Exits the main loop of the application.

The main loop of the application stops and service_app_terminate_cb() is invoked.

Since :
2.3
See also:
service_app_main()
service_app_terminate_cb()
int service_app_main ( int  argc,
char **  argv,
service_app_lifecycle_callback_s *  callback,
void *  user_data 
)

Runs the main loop of the application until service_app_exit() is called.

This function is the main entry point of the Tizen service application. This main loop supports event handling for the GMainLoop and the Ecore Main Loop.

Since :
2.3
Parameters:
[in]argcThe argument count
[in]argvThe argument vector
[in]callbackThe set of callback functions to handle application events
[in]user_dataThe user data to be passed to the callback functions
Returns:
0 on success, otherwise a negative error value.
Return values:
APP_ERROR_NONESuccessful
APP_ERROR_INVALID_PARAMETERInvalid parameter
APP_ERROR_INVALID_CONTEXTThe application is launched illegally, not launched by the launch system.
APP_ERROR_ALREADY_RUNNINGThe main loop has already started
See also:
service_app_create_cb()
service_app_terminate_cb()
service_app_control_cb()
service_app_exit()
service_app_lifecycle_callback_s
int service_app_remove_event_handler ( app_event_handler_h  event_handler)

Removes registered event handler.

Since :
2.3
Parameters:
[in]event_handlerThe event handler
Returns:
0 on success, otherwise a negative error value
Return values:
APP_ERROR_NONESuccessful
APP_ERROR_INVALID_PARAMETERInvalid parameter
See also:
service_app_add_event_handler()