Porting
The Tizen 2.3 release comes with a new version of the native API, created to give you a possibility to make fast and lightweight native applications. It replaces the native API used in the previous versions of Tizen (2.2.1). Combined with the Enlightenment Foundation libraries (EFL), the new native API provides powerful tools to create fantastic applications for Tizen.
This feature is supported in mobile applications only.
The purpose of this guide is to allow all the current Tizen application developers to port their current 2.2.1 native API-based applications to the new 2.3 native API as simply and quickly as possible. This guide contains basic guides on how to port your 2.2.1 native API application to the 2.3 native API. To fully understand the new API, familiarize yourself with the specifications and tutorials. This guide helps you to understand the main differences and start porting your applications.
For information about the differences between each module of the 2.2.1 and 2.3 version APIs, see API Comparison.
Application Model Comparison
The new API's application model is very similar to the one from the older version, so it is easy to adopt it.
The new 2.3 native API as well as the 2.2.1 version both support UI and service applications. UI applications have a graphical user interface, while service applications do not. Also, packaging applications follows same rules in both APIs. Only 1 UI application is allowed in one package. Applications in a package follow the same installation cycle but they have their own life-cycles. Each application in the package can be identified by its own ID. Applications can communicate with each other using the message port.
Multitasking in Tizen 2.3 works in a similar way as in Tizen 2.2.1, so only 1 application can work in the foreground. The rest are in a PAUSED state, so they are not visible for the user. Since service applications do not have a UI, they all run in the background the whole time.
Different scenarios for switching between UI application states include:
Basically, the scenarios are similar, and the same scenarios result in the same corresponding state transitions.
The main difference in developing UI applications is that the Tizen::Ui namespace has been replaced with the EFL. This change require you to recreate the user interface layer in your application. The EFL is very fast and customizable. Study its documentation to effectively use its features.
Application Life-cycle
The following figure shows the old 2.2.1 application life-cycle model.
Figure: 2.2.1 life-cycle model
The following figure shows the current application life-cycle model.
Figure: 2.3 life-cycle model
The following figures show the 2.2.1 and 2.3 state models.
Figure: 2.2.1 state model
Figure: 2.3 state model
The models have some differences, but basically they work very similarly. In both models, there are specific callbacks called during specific application states.
The main difference is that the old model has 2 life-cycles, one for the backend of the application and another one for the UI. The current model is more unified, so the backend code and the UI of the application are executed in the same callback functions.
First, the app_create_cb() function is called instead of OnAppInitializing(). Place the initialization code, such as loading and creating UI objects, there. After the initialization process (or the OnAppInitialized() callback in the 2.2.1 version), the application state becomes CREATED. Now the main event loop is being started and the app_control_cb() callback is called. The application state becomes RUNNING. This state is similar to the application state of the 2.2.1 version after OnAppInitialized() is executed.
When the application is running, the state can change to PAUSED or TERMINATED. Each state is preceded by a specific callback. Place your code in those callbacks to be executed before the application state changes. Those states are similar to the states from the 2.2.1 Native API, where the frame can be activated, deactivated, and minimized. If the state is PAUSED, it is possible to change it back to RUNNING. These situations are all described in the native Application API Reference.
Package Management
The package management during the porting process requires you to pay attention to the installation process and the actual application package structure.
Application Installation Process
The installation process in the new Native API is very similar to the one in the old API. The following figure shows the scheme.
Figure: Installation process
The installation process looks similar to the one from the 2.2.1 Native API. In the new API, the Package Manager is still responsible for managing packages. Use this API for installing, uninstalling, and updating the packages.
Application Package
In comparison with the 2.2.1 application package, the 2.3 native application package has fewer directories.
Figure: 2.2.1 package structure
Figure: 2.3 package structure
In the current package structure, there are no separate info, setting, and shared directories. Despite this change, the rest of the directories are the same. The file extension remains .tpk.
| Directory | Description |
|---|---|
| <package ID> | Fully qualified name of an application, such as org.tizen.calculator. |
| bin | Executable file of the application. |
| lib | Application library files. |
| res | Root directory in which all resource files are located.
The application cannot write and modify any resource files. |
| data | Root directory in which the application's private data is located.
The application can read and write its own data files in the application data directory. |
Application Launch and Termination
The process of launching a 2.2.1 native API application can be found here. A native application can also be launched from the Launcher or by another application.
The process of terminating a 2.2.1 native API application is described here. The possible scenarios for terminating the 2.3 native API application are the same as in the 2.2.1 API:
- Application calls the ui_app_exit() function to terminate the main event loop.
- Low Memory Killer terminates the application to free memory.
UI Applications
The main difference in creating UI applications is that the whole Tizen::Ui namespace has been replaced with the EFL. To create powerful applications for Tizen, study the EFL documentation.
Service Applications
The new native API has the same idea of service applications as the 2.2.1 version.
The guide for creating service applications in the 2.2.1 version can be found here, under Tizen Native App Programming > Programming Guide > App: Controlling Your Application > Service Application Fundamentals. Also, the tutorial for the 2.2.1 version is here, under Tizen Native App Programming > Tutorials > App Tutorial > Task: Multi Proc Service App.
The tutorial for the new 2.3 version is here.
I/O Overview
In the old Tizen 2.2.1 applications, the operations related to accessing the file system and managing input and output were all defined in the Tizen::Io namespace. Now, all the functionalities of this namespace have been discarded in favor of open source libraries and other modules of the native API. To provide the same functionality as the previous Tizen::Io namespace, the current version of Tizen uses sqlite3 and EGlibc open libraries. It also uses the Message Port and Storage (a System submodule) from the native API, so handle I/O operations using these libraries and API modules.
Object Ownership Policy
In the native API, the 'N' postfix for functions that return a new instance of an object with its ownership is no more supported. In this API, use the object_create() function, and free the memory with a function, such as object_destroy(). The following example is taken from the App Control module:
static app_control_h app_control; int error_code = app_control_create(&app_control); error_code = app_control_destroy(app_control);
Check from the function documentation whether you have to free the resource you are using. There are many other functions, such as get_something(), which usually allocates memory to store an object or a value that is obtained. For example:
char *uri;
error_code = app_control_get_uri(app_control, &uri);
if (uri != NULL)
{
free(uri);
uri = NULL;
}
In those cases, free memory as well. To be sure whether you need to release the resources to avoid memory leaks, check the API documentation.
Low Memory Level Events
When the memory levels in the system are extremely low, the system terminates the application and removes it from the memory. However, it is possible to save the application state or context right before this happens. In the 2.2.1 version, it was done using the Tizen::App::IAppCheckpointEventListener interface. In the new native API, every time when the low level memory situation occurs on the device and the system wants to terminate some application, the app_event_cb() callback in that application is called. When you create your application, remember to place the code that must be executed in case of a low memory level in this callback and set the callback using the ui_app_add_event_handler() function.
Scene Transitions
In the old 2.2.1 model, the UI scene transitions were handled by specific listeners, such as the Tizen::Ui::Controls::IFormBackEventListener and its OnFormBackRequested() event handler to listen to the Back key events for a backward scene transition. In the 2.3 model, all such actions are handled using the EFL and EFL Extension. The EFL has its own view manager for applications, called naviframe. A naviframe is a stack which holds views or pages as its items. When another view is launched, it is pushed on the top of the stack. Only the topmost view is displayed. The old views are stored on the stack. The EFL Extension provides functions to send key events to the naviframe top item or to pop it. Every time the user presses the Back key, the current view is removed from the stack and the view that was right under it becomes the topmost view and is displayed. The transition animation between views is handled by the EFL and depends on the theme applied to the UI component.
Hardware Keys
With the arrival of the EFL, handling the hardware key events has changed. Until now, the 2.2.1 model provided the Tizen::Ui::Controls::IFormMenuEventListener interface. This interface delivered the OnFormMenuRequested() event handler to listen to the hardware Menu key events. Now, all this functionality is obtained using the EFL. In the EFL Extension documentation, find functions which enable you to manipulate the key modifiers. Use them to add handling for the hardware key events.
Exceptions
Normally in the 2.3 API version, the exceptions model functions return an integer which indicates an error value. Usually, the value is 0 if there are no errors and the name format for this value is MODULE_NAME_ERROR_NONE. As in 2.2.1, the current API provides functions to get and set the last error value in the thread. In the 2.3 version, this functionality and the error enumerations are in the Base module. The following example shows how the current native API returns errors.
int error_code = app_control_create(&app_control); if (error_code != APP_CONTROL_ERROR_NONE) // Error occurred
Logs
The 2.3 native API provides a new method for managing logs. The dlog module is now responsible for these actions. It provides 2 functions to send data to the log output. It supports priority and tags, which can be used to easily filter log messages. The new logging system makes it easier to manage logs, since there are no multiple functions for dealing with different log levels. Set the priority (whether the log is an error or maybe a warning, info, or debug message) and filter the output logs according to the priority levels.
| Priority | Description |
|---|---|
| DLOG_DEBUG | Debug message.
Log message which the developer want to check. |
| DLOG_INFO | Information message.
Normal operational messages. Logs above this priority are always logged. |
| DLOG_WARN | Warning message.
Not an error, but an indication that an error occurs in the future if no action is taken. |
| DLOG_ERROR | Error message.
Indicates an error. |
You can use the dlogutil command to view and follow the content of the log buffers:
dlogutil [<option>] ... [<filter-spec>] ...
Every log message has a tag and a priority associated with it. A filter expression follows the tag:priority format. The tag indicates the tag of interest and the priority indicates the minimum level of priority to report for that tag. Add any number of tag:priority specifications in a single filter expression. The tag of a log message indicates the system component from which the message originates. The priority is one of the following character values, ordered from lowest to highest priority:
- D - Debug
- I - Info
- W - Warning
- E - Error
For example, to see the MY_APP tag with the debug priority:
# dlogutil MY_APP:D
To see all log messages above the info priority:
# dlogutil *:I
| Option | Description |
|---|---|
| -b <buffer> | Alternate log buffer. The main buffer is used by the default buffer. |
| -c | Clears the entire log and exits. |
| -d | Dumps the log and exits. |
| -f <filename> | Writes a log to the filename. The default is stdout. |
| -g | Prints the size of the specified log buffer and exits. |
| -n <count> | Sets the maximum number of rotated logs to count. The default value is 4. Requires the -r option. |
| -r <Kbytes> | Rotates the log file every Kbytes of output. The default value is 16. Requires the -f option. |
| -s | Sets the default filter spec to silent. |
| -v <format> | Sets the output format for log messages. The default is the brief format. |
