Tizen Native API  8.0

The Service Component API provides functions for handling Service Component state changes or system events.

Required Header

#include <service_component.h>

Overview

The Service Component API provides functions for handling Service Component of Component Based Application state changes or system events.

Registering Callbacks for Service Component State Change Events

The service component state change events include the following:

State Description
service_component_create_cb() The callback function called after the service component instance is created.
service_component_start_command_cb() The callback function called when the service component instance is started.
service_component_destroy_cb() The callback function called before the service component instance is destroyed.
service_component_restore_content_cb() The callback function called when the content information of the service component instance is restored.
service_component_save_content_cb() The callback function called before the content information of the service component instance is saved.
service_component_action_cb() The callback function called when another application sends a launch request to the component.
service_component_device_orientation_changed_cb() The callback function called when the device orientation is changed.
service_component_language_changed_cb() The callback function called when the system language is changed.
service_component_region_format_changed_cb() The callback function called when the system region format is changed.
service_component_low_battery_cb() The callback function called when the battery status is changed.
service_component_low_memory_cb() The callback function called when the memory status is changed.
service_component_suspended_state_changed_cb() The callback function called when the suspended state of the service component is changed.

Please refer to the following state diagram to see the possible transitions and callbacks that are called while transition.

service_component_lifecycle.png
Service Component States

Typedefs

typedef bool(* service_component_create_cb )(component_h context, void *user_data)
 Called when the service component instance is created.
typedef void(* service_component_start_command_cb )(component_h context, app_control_h app_control, bool restarted, void *user_data)
 Called when the service component instance is started.
typedef void(* service_component_destroy_cb )(component_h context, void *user_data)
 Called before the service component instance is destroyed.
typedef void(* service_component_restore_content_cb )(component_h context, bundle *content, void *user_data)
 Called after the content information of the service component instance is restored.
typedef void(* service_component_save_content_cb )(component_h context, bundle *content, void *user_data)
 Called before the content information of the service component instance is saved.
typedef void(* service_component_action_cb )(component_h context, const char *action, app_control_h app_control, void *user_data)
 Called when another application sends a launch request to the component.
typedef void(* service_component_device_orientation_changed_cb )(component_h context, component_device_orientation_e orientation, void *user_data)
 Called when the device orientation is changed.
typedef void(* service_component_language_changed_cb )(component_h context, const char *language, void *user_data)
 Called when the system language is changed.
typedef void(* service_component_region_format_changed_cb )(component_h context, const char *region, void *user_data)
 Called when the system region format is changed.
typedef void(* service_component_low_battery_cb )(component_h context, component_low_battery_status_e status, void *user_data)
 Called when the battery status is changed.
typedef void(* service_component_low_memory_cb )(component_h context, component_low_memory_status_e status, void *user_data)
 Called when the memory status is changed.
typedef void(* service_component_suspended_state_changed_cb )(component_h context, component_suspended_state_e state, void *user_data)
 Called when the suspended state of the service component is changed.
typedef void(* service_component_time_zone_changed_cb )(component_h context, const char *time_zone, const char *time_zone_id, void *user_data)
 Called when the time zone of the service component is changed.

Typedef Documentation

typedef void(* service_component_action_cb)(component_h context, const char *action, app_control_h app_control, void *user_data)

Called when another application sends a launch request to the component.

Before calling service_component_start_command_cb(), this callback function is called.

Since :
5.5
Remarks:
After this callback function returns, the handler of the app_control is released. Therefore, if you want to use the handle after returning this callback function, you MUST copy it by using app_control_clone() function.
The action must not be deallocated by the component. The action is managed by the platform and will be released when the app_control action is unregistered.
The context should not be released. The context can be used only in the callback.
The app_control should not be released. The app_control can be used only in the callback. To use outside, make a copy using app_control_clone().
Parameters:
[in]contextThe context of the service component instance
[in]actionThe name of the app_control action
[in]app_controlThe handle of the app_control
[in]user_dataThe user data passed from component_based_app_add_service_component() function
See also:
component_register_action()
component_deregister_action()
typedef bool(* service_component_create_cb)(component_h context, void *user_data)

Called when the service component instance is created.

Since :
5.5
Remarks:
The context should not be released. The context can be used only in the callback.
Parameters:
[in]contextThe context of the service component instance
[in]user_dataThe user data passed from component_based_app_add_service_component() function
Returns:
true on success, otherwise false on failure.
typedef void(* service_component_destroy_cb)(component_h context, void *user_data)

Called before the service component instance is destroyed.

Since :
5.5
Remarks:
The context should not be released. The context can be used only in the callback.
Parameters:
[in]contextThe context of the service component instance
[in]user_dataThe user data passed from component_based_app_add_service_component() function
typedef void(* service_component_device_orientation_changed_cb)(component_h context, component_device_orientation_e orientation, void *user_data)

Called when the device orientation is changed.

Since :
5.5
Remarks:
The context should not be released. The context can be used only in the callback.
Parameters:
[in]contextThe context of the service component instance
[in]orientationThe device orientation
[in]user_dataThe user data passed from component_based_app_add_service_component() function
typedef void(* service_component_language_changed_cb)(component_h context, const char *language, void *user_data)

Called when the system language is changed.

Since :
5.5
Remarks:
The context should not be released. The context can be used only in the callback.
The language must not be deallocated by the component. The language can be used only in the callback.
Parameters:
[in]contextThe context of the service component instance
[in]languageThe language
[in]user_dataThe user data passed from component_based_app_add_service_component() function
typedef void(* service_component_low_battery_cb)(component_h context, component_low_battery_status_e status, void *user_data)

Called when the battery status is changed.

Since :
5.5
Remarks:
The context should not be released. The context can be used only in the callback.
Parameters:
[in]contextThe context of the service component instance
[in]statusThe low battery status
[in]user_dataThe user data passed from component_based_app_add_service_component() function
typedef void(* service_component_low_memory_cb)(component_h context, component_low_memory_status_e status, void *user_data)

Called when the memory status is changed.

Since :
5.5
Remarks:
The context should not be released. The context can be used only in the callback.
Parameters:
[in]contextThe context of the service component instance
[in]statusThe low memory status
[in]user_dataThe user data passed from component_based_app_add_service_component() function
typedef void(* service_component_region_format_changed_cb)(component_h context, const char *region, void *user_data)

Called when the system region format is changed.

Since :
5.5
Remarks:
The context should not be released. The context can be used only in the callback.
The region must not be deallocated by the component. The region can be used only in the callback.
Parameters:
[in]contextThe context of the service component instance
[in]regionThe region format
[in]user_dataThe user data passed from component_based_app_add_service_component() function
typedef void(* service_component_restore_content_cb)(component_h context, bundle *content, void *user_data)

Called after the content information of the service component instance is restored.

Since :
5.5
Remarks:
The content should not be released. The content can be used only in the callback. To use outside, make a copy using bundle_dup().
Parameters:
[in]contextThe context of the service component instance
[in]contentThe content information
[in]user_dataThe user data passed from component_based_app_add_service_component() function
typedef void(* service_component_save_content_cb)(component_h context, bundle *content, void *user_data)

Called before the content information of the service component instance is saved.

Since :
5.5
Remarks:
The content should not be released. The content can be used only in the callback. To use outside, make a copy using bundle_dup().
Parameters:
[in]contextThe context of the service component instance
[in]contentThe content information
[in]user_dataThe user data passed from component_based_app_add_service_component() function
typedef void(* service_component_start_command_cb)(component_h context, app_control_h app_control, bool restarted, void *user_data)

Called when the service component instance is started.

Since :
5.5
Remarks:
The context should not be released. The context can be used only in the callback.
The app_control should not be released. The app_control can be used only in the callback. To use outside, make a copy using app_control_clone().
Parameters:
[in]contextThe context of the service component instance
[in]app_controlThe app control handle
[in]restartedtrue, if the instance is restarted
[in]user_dataThe user data passed from component_based_app_add_service_component() function

Called when the suspended state of the service component is changed.

Since :
5.5
Remarks:
The context should not be released. The context can be used only in the callback.
Parameters:
[in]contextThe context of the service component instance
[in]stateThe suspended state
[in]user_dataThe user data passed from component_based_app_add_service_component() function
typedef void(* service_component_time_zone_changed_cb)(component_h context, const char *time_zone, const char *time_zone_id, void *user_data)

Called when the time zone of the service component is changed.

An application can obtain a changed time zone (e.g., "+9:00") and a time zone id (e.g., "Asia/Seoul").

Since :
8.0
Remarks:
The context should not be released. The context can be used only in the callback.
time_zone and time_zone_id must not be deallocated by the component. time_zone and time_zone_id can be used only in the callback.
Parameters:
[in]contextThe context of the service component instance
[in]time_zoneThe time zone
[in]time_zone_idThe time zone id
[in]user_dataThe user data passed from component_based_app_add_service_component() function