Tizen application inside out

Tizen Application Inside Out

2016-01-23 Tizen Talks

Semun Lee

Software R&D Center

Samsung Electronics

Copyright © 2016 Samsung Electronics, Co., Ltd. All rights reserved. 2

Tizen Architecture


Tizen Native API

https://developer.tizen.org/development

https://developer.tizen.org/development

Tizen Native Application Model


Tizen Native Application

• Written in C / C++

– Can use Tizen Native APIs

• Usually, use EFL as the UIFW

• Follows Tizen application lifecycle

– app-core library controls application’s lifecycle

• Two types of application

– UI Application

• An application that has UI

– Service Application

• An application that doesn’t have UI.

• Supports UI application in background


Application Lifecycle

intmain(int argc, char *argv[]){

appdata_s ad = {0,};int ret = 0;

ui_app_lifecycle_callback_s event_callback = {0,};

event_callback.create = app_create;event_callback.terminate = app_terminate;event_callback.pause = app_pause;event_callback.resume = app_resume;event_callback.app_control = app_control;

ret = ui_app_main(argc, argv, &event_callback, &ad);if (ret != APP_ERROR_NONE) {

dlog_print(DLOG_ERROR, LOG_TAG, "app_main() is failed. err = %d", ret);}

return ret;}

Example:





• app_create

– called when the process starts

– recommend to create UI components

• app_control

– called after the app_create when the process starts or called when a

launch request is received while the process is running

– can receive app_control data (parameters for launching the application)

– recommend to implement parameter specific actions of the application

• app_resume (UI application only)

– called when the window of the application is shown

• app_pause (UI application only)

– called when the window of the application is totally hidden

• app_terminate

– called while the process of the application is terminating

– called after the main loop quits


App Control

• Provides functions for launching other

applications

• Explicit launch

– Launch the application with the application ID

• Implicit launch

– Launch the application with

an operation, URI, or MIME type


App Control


App Control – Explicit Launch

#include <app.h>#include <dlog.h>

#define TAG "MY_TAG"

app_control_h app_control;

app_control_create(&app_control);app_control_set_operation(app_control, APP_CONTROL_OPERATION_DEFAULT);

app_control_set_app_id(app_control, "org.tizen.calculator");

if (app_control_send_launch_request(app_control, NULL, NULL) ==

APP_CONTROL_ERROR_NONE) {

dlog_print(DLOG_INFO, TAG, "Succeeded to launch a calculator app.");} else {

dlog_print(DLOG_ERROR, TAG, "Failed to launch a calculator app.");}

app_control_destroy(app_control);


App Control – Implicit Launch

#include <app.h>#include <dlog.h>

#define TAG "MY_TAG"

app_control_h app_control;

app_control_create(&app_control);

app_control_set_operation(app_control, APP_CONTROL_OPERATION_VIEW);app_control_set_uri(app_control,

"file:///home/myhome/Photos/1_photo.jpg");app_control_set_mime(app_control, "image/*");app_control_add_extra_data(app_control, “show_mode”, “auto”);

if (app_control_send_launch_request(app_control, NULL, NULL) == APP_CONTROL_ERROR_NONE) {

dlog_print(DLOG_INFO, TAG, "Succeeded to launch a viewer app.");} else {

dlog_print(DLOG_ERROR, TAG, "Failed to launch a viewer app.");}

app_control_destroy(app_control);


Exporting App Control Functionality

• An application exn export app control functionality by adding <app-

control> tag to the manifest xml file

<app-control><mime name="application/xhtml+xml"/><operation name="http://tizen.org/appcontrol/operation/view"/><uri name="http://test.com"/>

</app-control>


Handling Launch Options From App Control

• An application can receive extra data in the app control callback

static void app_control(app_control_h app_control, void *user_data){

struct appdata *ad = (struct appdata *)user_data;char *operation;char *uri;char *mime_type;char *show_mode;

app_control_get_operation(app_control, operation);

if (!strcmp(operation, APP_CONTROL_OPERATION_VIEW)){

app_control_get_uri(app_control, &uri);app_control_get_mime(app_control, &mime_type);

app_control_get_extra_data(app_control, “show_mode”, &show_mode);

if (uri && !strcmp(mime_type, "image/jpg")){

display_image_file(ad, uri, show_mode); // Display a specific image file}

}

if (ad->win)elm_win_activate(ad->win);

}


Handling System Events

intmain(int argc, char *argv[]){

……

app_event_handler_h handlers[5] = {NULL, };

ui_app_add_event_handler(&handlers[APP_EVENT_LOW_BATTERY],APP_EVENT_LOW_BATTERY, ui_app_low_battery, &ad);

ui_app_add_event_handler(&handlers[APP_EVENT_LOW_MEMORY],APP_EVENT_LOW_MEMORY, ui_app_low_memory, &ad);

ui_app_add_event_handler(&handlers[APP_EVENT_DEVICE_ORIENTATION_CHANGED],APP_EVENT_DEVICE_ORIENTATION_CHANGED, ui_app_orient_changed, &ad);

ui_app_add_event_handler(&handlers[APP_EVENT_LANGUAGE_CHANGED],APP_EVENT_LANGUAGE_CHANGED, ui_app_lang_changed, &ad);

ui_app_add_event_handler(&handlers[APP_EVENT_REGION_FORMAT_CHANGED],APP_EVENT_REGION_FORMAT_CHANGED, ui_app_region_changed, &ad);

……}

Example:


Application Manifest XML

<?xml version="1.0" encoding="UTF-8" standalone="no"?><manifest xmlns="http://tizen.org/ns/packages" api-version="2.4“

package="org.example.appcontrol1" version="1.0.0"><ui-application appid="org.example.appcontrol1“

exec="appcontrol1" multiple="false“nodisplay="false" taskmanage="true" type="capp">

<label>appcontrol1</label><icon>appcontrol1.png</icon><metadata key="http://developer.samsung.com/tizen/metadata/legacylifecycle"/>

</ui-application><privileges>

<privilege>http://tizen.org/privilege/appmanager.launch</privilege><privilege>http://tizen.org/privilege/alarm.set</privilege>

</privileges></manifest>

• manifest xml (e.g. org.tizen.tv-viewer.xml) contains

information about the application

• package id, app id, executable path, etc

• can declare metadata or privileges


Application Privilege

• Some APIs need certain privileges for calling the API

– app_control_send_launch_request() API needs

http://tizen.org/privilege/appmanager.launch privilege

• So, applications should declare proper privileges to use

some APIs

http://tizen.org/privilege/appmanager.launch

Life of Tizen Application Process


Launching Application

• App-control API

– API for launching application

– homescreen uses app-control API

to launch an application

• AMD

– Application management daemon

– Manages information about installed applications

– Manages status of application processes

• launchpad

– Parent process of all applications

– Handles launch request from amd

– Manages launchpad-loaders

• launchpad-loader

– Pre-initialized process for applications

– launchpad-loader is changed to real application


Launching Application

homescreen app

amd

launchpad

launchpad-loader 0 launchpad-loader 1 wrt-oader

*wrt: web runtime

org.tizen.calcualtor

1. request launching an application

2. amd validates the request and find information about the app

3. amd passes the request to the launchpad

4. launchpad find proper launchpad-loader forthe request type

5. launchpad requests launchpad-loader to run the application

6. launchpad-loader loades application’s executable file and calls main()

same process


launchpad and launchpad-loader

• Application launching should be fast!!

– launchpad and launchpad-loader was introduced for it.

• launchpad forks launchpad-loaders for each application type

– EFL native application

– EFL native application with pre-initialized basic window

– Web application

• launchpad-loader pre-initialize the parts all applications share

– preloads shared libraries all application share

– calls basic init function (e.g. elm_init)

– creates basic type window for most applications

– dlopen() application’s executable file and call main directly to run the application

• application can use pre-initialized parts because it starts from pre-initialized launchpad-loader process


Creating UI

• app-core

– library for control application lifecycle

– works in ui_app_main()

application process

app-core

ui_app_main()

before_loop()- initialize app common things- create app_create() callback

elm_run()- starts main event loop


Creating UIstatic boolapp_create(void *data){

appdata_s *ad = data;

/* Window *//* Create and initialize elm_win.

elm_win is mandatory to manipulate window. */

ad->win = elm_win_util_standard_add(PACKAGE, PACKAGE);

…/* Label *//* Create an actual view of the base gui.

Modify this part to change the view. */ad->label = elm_label_add(ad->conform);elm_object_text_set(ad->label, "<align=center>Hello Tizen</align>");evas_object_size_hint_weight_set(ad->label, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);elm_object_content_set(ad->conform, ad->label);

/* Show window after base gui is set up */

evas_object_show(ad->win);

return true;}


Pause / Resume

• app-core revisited

– app-core library listens window event

and changes application’s state from

running and paused

• Window manager (enlightenment)

– Manages windows

– Sends events for window visibility changes

application process

app-core

enlightenment1. request to show app’s window

2. window managerchanges window stack

3. send events for windowvisibility changes

4. listen window visibility event.- change app’s state to running if the window is shown- change app’s state to running if the window is hidden


App Control

• app-core again

– app-core handles app-control request

– applications can send

app-control to request

an operation to another application

• amd

– amd checks if the operation can be handled by running application or

needs to launch a new application process

– If the operation can be handled by running application the request is

relayed to the application’s process


App Control

application

amd

launchpad

launchpad-loader

1. request launching an application (send app-control)

2. amd validates the request and find information about the app

3. if the request can be handled running application,

the request is relayed to the running application

application process

app-core 4. app-core calls app_control_cb


Terminate

• Application can be terminated

– by itself calling ui_app_exit()

– by request from the platform

application process

app-core

ui_app_exit()

elm_exit()

after_loop()- release resources- call app_pause_cb() if its state is ‘running’- call app_terminate_cb()

termination request from the platform


Cast

• Applications

• app-core: platform/core/appfw/app-core, platform/core/api/application

• amd: platform/core/appfw/amd, platform/core/appfw/aul-1

• launchpad: projects/platform/core/appfw/launchpad

• launchpad-loader: projects/platform/core/appfw/launchpad

• guest appearance

– EFL

– Enlightenment Window Manager

Thank You!

Appendix:Tizen Application Framework Native APIs

Tizen Event System


Tizen Event System

• Event Publication/Subscription

– Application can broadcast own event to all the listeners.

– Application can receive pre-defined events from the platform. (system-event)

• “Launch On Event” (Service-application only)

– Applications can be launched when the interested event occurs.

• Event Type

– System-Event

• System-wide event from the platform.

• Only platform modules can broadcast the system-event.

– User-Event

• User-defined event.

• Applications(UI and Service) can broadcast own event.


For Typical Tizen Application

• Application can add/remove event-handler using API.

• Application can add multiple event-handler per one Event.

• Service-application can be launched by the event triggering.– The APP_CONTROL_OPERATION_LAUNCH_ON_EVENT must be defined in the manifest file.

– This operation can not be requested via app_control_send_launch_request().

– Only service-application can define this operation.

– The uri name represents event name for “Launch On Event”. (format: “event://{Event_Name}”)

– For more information, refer to ‘Launch_On_Event’ slide.

• Application can send user-event only. (not system-event)

• Application can receive both user-event and system-event.

• Application can send trusted user-event.– Only applications which have same signature with sender application can receive sender’s event.

• Event System Daemon (ESD)– ESD manages the event list for “Launch On Event”.

– ESD launch the requested applications when the interested event occurs.

<app-control><operation name="http://tizen.org/appcontrol/operation/launch_on_event"/><uri name=“event://tizen.system.event.battery_level_status"/>

</app-control><app-control>

<operation name="http://tizen.org/appcontrol/operation/launch_on_event"/><uri name=“event://event.org.tizen.senderapp.user_event"/>

</app-control


Predefined System Events

• SYSTEM_EVENT_BATTERY_CHARGER_STATUS

• SYSTEM_EVENT_BATTERY_LEVEL_STATUS

• SYSTEM_EVENT_USB_STATUS

• SYSTEM_EVENT_EARJACK_STATUS

• SYSTEM_EVENT_DISPLAY_STATE

• SYSTEM_EVENT_BOOT_COMPLETED

• SYSTEM_EVENT_SYSTEM_SHUTDOWN

• SYSTEM_EVENT_LOW_MEMORY

• SYSTEM_EVENT_WIFI_STATE

• SYSTEM_EVENT_BT_STATE

• SYSTEM_EVENT_LOCATION_ENABLE_STATE

• SYSTEM_EVENT_GPS_ENABLE_STATE

• SYSTEM_EVENT_NPS_ENABLE_STATE


• SYSTEM_EVENT_INCOMMING_MSG

• SYSTEM_EVENT_TIME_CHANGED

• SYSTEM_EVENT_TIME_ZONE

• SYSTEM_EVENT_HOUR_FORMAT

• SYSTEM_EVENT_LANGUAGE_SET

• SYSTEM_EVENT_REGION_FORMAT

• SYSTEM_EVENT_SILENT_MODE

• SYSTEM_EVENT_VIBRATION_STATE

• SYSTEM_EVENT_SCREEN_AUTOROTATE_STATE

• SYSTEM_EVENT_MOBILE_DATA_STATE

• SYSTEM_EVENT_DATA_ROAMING_STATE

• SYSTEM_EVENT_FONT_SET


For Internal-Use (for daemon or special app)

• Use low-level API directly .

– eventsystem_send_system_event()

– eventsystem_request_sending_system_event()

• This is only for privileged application which can not use

evensystem_send_system_event() API because of d-bus policy. (e.g. setting,

quick panel)

– eventsystem_register_event()

– eventsystem_unregister_event()

App Group Launching Management


App Group Launching Management

• App 실행시 sub-view 개념으로실행하고싶은경우 group launch

feature 제공

App 1

App 2

group launch

home

App 1

App 2

Home

launch app 1

App 1

App 2

Home


App Group API

• APIs provide methods to set and get launching mode

– The new APIs

• enum app_control_launch_mode_e {

APP_CONTROL_LAUNCH_MODE_SINGLE,

APP_CONTROL_LAUNCH_MODE_GROUP

}

1

App_control.c

int app_control_set_launch_mode(app_control_h app_control, app_control_launch_mode_e mode)

int app_control_get_launch_mode(app_control_h app_control, app_control_launch_mode_e *mode)


Launch Mode Attribute

• The new attribute in tizen-manifest.xml is available

– ‘launch_mode’ in ‘ui-application’ tag

• single

– This app will not be attached on caller app

– Default 'launch_mode' is ‘single’.

• group

– This app will be attached on caller app

• caller

– Caller app can set the launch mode.

– Example

<ui-application appid="org.tizen.test“ launch_mode=“caller”/>


Note on App Group Launching

• Group launch된 callee app은각각별도 process로실행됨.

• Group launch된 app은 App 상태관리에나타나지않음

– app running 상태에표시되지않음

– RUA history 에추가되지않음 -> task manager에표시되지않음

– app 상태관리는항상 group leader 단위로이루어짐

App 1

App 2

group launch

App 3

App 2

group launch

different process

Message Port API


Message Port

• Applications can send and receive messages through message port

communication

• Local port is used to register your message port and prepare to

receive messages from another application

• Remote port is used to send messages to other applications


Message Port - Example

void message_port_cb(int local_port_id, const char *remote_app_id, bundle *message){

char *command = NULL;char *data = NULL;bundle_get_str(message, "command", &command);bundle_get_str(message, "data", &data);

dlog_print(DLOG_INFO, TAG,"Message from %s, command: %s data: %s", remote_app_id, command, data);

}……

int port_id = message_port_register_local_port(“mytestport”, message_port_cb, NULL);if (port_id < 0) {

dlog_print(DLOG_ERROR, LOG_TAG, "Port register error : %d", port_id);} else {

dlog_print(DLOG_INFO, LOG_TAG, "port_id : %d", port_id);}……

Registering local port (in org.tizen.mytestapp)


Message Port - Example

void send_message(void){

int ret;bundle *b = bundle_create ();bundle_add_str (b, "command", "begin");bundle_add_str (b, "data", "dummy");ret = message_port_send_message (“org.tizen.mytestapp”, “mytestport”, b);if (ret != MESSAGE_PORT_ERROR_NONE) {

dlog_print(DLOG_ERROR, TAG, "message_port_check_remote_port error : %d", ret);}else {

dlog_print(DLOG_INFO, TAG, "Send message done");}bundle_free (b);

}

Sending message (in org.tizen.anotherapp)


Trusted Communication

• Applications that are developed by the same developer can send and

receive messages using trusted message port

Data Control API


Data Control

• Data control is a mechanism for exchanging specific data between

applications

• Provider provides data to the consumer

• Provider is identified by the provider ID

• Two types of data

– Map : <key, value> data access

– SQL : SQL query type data access


Providing Data Control

• Service applications can provide data control with <datacontrol> tag in

the manifest xml file

• When a consumer app request data control to the provider id, the

provider app is launched and can response for the data control

request

<?xml version="1.0" encoding="UTF-8" standalone="no"?><manifest xmlns="http://tizen.org/ns/packages" api-version="2.4“

package="org.example.service" version="1.0.0"><profile name="wearable"/><service-application appid="org.example.service“

exec="service" multiple="false" nodisplay="true" taskmanage="false" type="capp"><label>service</label><icon>service.png</icon><datacontrol access="ReadWrite“

providerid="http://samsung.com/datacontrol/provider/service" type="Map"/></service-application>

</manifest>


Data Control Provider - Example

data_control_provider_map_cb map_callback;void initialize_datacontrol_provider(){

map_repository_test = g_hash_table_new_full(g_str_hash, g_str_equal, __free_key, __free_data);

map_callback.get_cb = get_value_request_cb;map_callback.add_cb = add_value_request_cb;map_callback.remove_cb = remove_value_request_cb;map_callback.set_cb = set_value_request_cb;

int result = data_control_provider_map_register_cb(&map_callback);if(result != DATA_CONTROL_ERROR_NONE){

dlog_print(DLOG_ERROR, LOG_TAG, "data_control_provider_map_register_cb failed with error: %d", result);}else {

dlog_print(DLOG_INFO, LOG_TAG, "Provider map register success");}

}


Data Control Provider - Example

static GHashTable *map_repository_test;void get_value_request_cb(int request_id, data_control_h provider,

const char *key, void *user_data){

map_data_s* map_data =(map_data_s*)g_hash_table_lookup(map_repository_test, key);

int ret_value_count = 0;char **val_arr = NULL;if (map_data != NULL){

val_arr = map_data->str_arr;ret_value_count = map_data->arr_size;

}

int ret = data_control_provider_send_map_get_value_result(request_id, val_arr,ret_value_count);

if (ret != DATA_CONTROL_ERROR_NONE){

dlog_print(DLOG_ERROR, LOG_TAG, "send_map_get_result failed with error: %d", ret);

}else{

dlog_print(DLOG_INFO, LOG_TAG, "Get value success request_id : %d", request_id);

}}


Data Control Consumer - Example

data_control_map_response_cb map_callback;void initialize_datacontrol_consumer(appdata_s *ad){

const char *provider_id = “http://samsung.com/datacontrol/provider/service”;const char *data_id = "table";int req_id;

// Create data control handlerdata_control_map_create(&(ad->provider_h));data_control_map_set_provider_id(ad->provider_h, provider_id);data_control_map_set_data_id(ad->provider_h, data_id);

// Set response callbackmap_callback.get_cb = map_get_response_cb;map_callback.set_cb = map_set_response_cb;map_callback.add_cb = map_add_response_cb;map_callback.remove_cb = map_remove_response_cb;

// Register response callbackdata_control_map_register_response_cb(ad->provider_h, &map_callback, NULL);

// Get valuedata_control_map_get(ad->provider_h, “mytestkey”, &req_id);

}

Package Manager API


Package Manager API

• Used to retrieve detailed information of the installed packages on the

device

• Can receive event for monitoring package status

– install / uninstall / upgrade


Getting Specific Package Information

char *version = NULL;char *label = NULL;char *type = NULL;package_info_h package_info = NULL;package_manager_get_package_info(“org.tizen.mytestapp", &package_info);

package_info_get_version(package_info, &version);package_info_get_label(package_info, &label);package_info_get_type(package_info, &type);

dlog_print(DLOG_INFO, TAG, "label \t= [%s]\n", label);dlog_print(DLOG_INFO, TAG, "icon \t= [%s]\n", icon);dlog_print(DLOG_INFO, TAG, "version \t= [%s]\n", version);

free(label);free(icon);free(version);


Listening to Package Events

void event_cb(const char *type, const char *package, package_manager_event_type_e event_type,

package_manager_event_state_e event_state, int progress, package_manager_error_e error, void *user_data)

{if (event_state == PACKAGE_MANAGER_EVENT_STATE_STARTED){

dlog_print(DLOG_INFO, LOG_TAG, "Started");}else if (event_state == PACKAGE_MANAGER_EVENT_STATE_PROCESSING){

dlog_print(DLOG_INFO, LOG_TAG, "Progress : %d", progress);}else if (event_state == PACKAGE_MANAGER_EVENT_STATE_COMPLETED){

dlog_print(DLOG_INFO, LOG_TAG, "Completed");}else{

dlog_print(DLOG_INFO, LOG_TAG, "Failed");}

}

………

package_manager_h manager;package_manager_create(&manager)package_manager_set_event_status(manager, PACKAGE_MANAGER_STATUS_TYPE_ALL);package_manager_set_event_cb(manager, event_cb, NULL);


References

• Tizen 2.4 API reference

– https://developer.tizen.org/development/api-references/api-reference-

2.4.0

• Tizen Native Application Programming Guide

– https://developer.tizen.org/development/guides/native-application

• Tizen Native Application API Tutorials

– https://developer.tizen.org/development/tutorials/native-application

https://developer.tizen.org/development/api-references/api-reference-2.4.0

https://developer.tizen.org/development/guides/native-application

https://developer.tizen.org/development/tutorials/native-application