Tizen App Inside Out Guide

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

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
int
main(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
int
main(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

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 for
the 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 UI
static bool
app_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
enlightenment
1. request to show app’s window
2. window manager
changes window stack
3. send events for window
visibility 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

Appendix:
Tizen Application Framework Native APIs

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
• 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
• 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 handler
data_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 callback
map_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 callback
data_control_map_register_response_cb(ad->provider_h, &map_callback, NULL);
// Get value
data_control_map_get(ad->provider_h, “mytestkey”, &req_id);
}

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

Tizen App Inside Out Guide

Recommended

Recommended

More Related Content

What's hot

What's hot (20)

Similar to Tizen App Inside Out Guide

Similar to Tizen App Inside Out Guide (20)

Recently uploaded

Recently uploaded (20)

Tizen App Inside Out Guide