Samsung Wearable Native API
The Basics of Tizen Native API Programming

Tizen Native API is carefully selected and tightly managed APIs from the Tizen native subsystems. The Tizen Native API Specification available in the Tizen SDK shows full list of the selected native subsystem APIs. The Native API is divided into dozens of API modules; each module represents a logically similar set of submodule APIs, which can be grouped into the same category. The Tizen Native API follows basic principles listed below:

Ownership of returned strings

All strings returned as pointers should be freed by the caller unless stated otherwise. Not freeing memory may lead to memory leaks. Insufficient system memory will trigger a system 'low memory' notification and some application(s) may be killed. As a heuristic algorithm selects the process to be killed, it may destabilize the system.

 char *app_id_string = NULL;
 if(!app_get_id(&app_id_string))
 {
     // use app_id_string;
     if(app_id_string != NULL)
         free(app_id_string);
 }


Handles

A handle provides means to manage an instance associated with it. Handles are widely used in Tizen Native API for ABI compatibility reasons.
Creation and destruction functions (create/destroy) are provided for each handle type. They do not create and destroy the handle itself, but they operate on the instance associated with a given handle. It means that a handle is not valid until a corresponding create function has been called and the handle is not valid after a corresponding destroy function has been called. Also accessor functions (getters/setters) are provided to access members of the hidden structure identified by a given handle. For example, a text message is represented by a handle:

 messages_message_h sms_msg;

A message is created and associated with this handle by calling

 messages_create_message(MESSAGES_TYPE_SMS, &sms_msg);

and destroyed by calling

 messages_destroy_message(sms_msg);

To change the properties of the text message appropriate setters have to be used

 messages_set_text(sms_msg,"Hello, how are you?"); 
 messages_add_address (sms_msg,"01020157919", MESSAGE_RECIPIENT_TO);


Error handling

Every error code in Tizen Native API is represented as an integer value. Almost all API functions, which return error code, have the following 'Returns' section in their description.

 Returns:
      0 on success, otherwise a negative error value

To see all returned values, please refer to the Return values section in each API function description.
For example:

 Return values:
       MESSAGES_ERROR_NONE Successful
       MESSAGES_ERROR_INVALID_PARAMETER    Invalid parameter
       MESSAGES_ERROR_SERVER_NOT_READY  Server is not read
       MESSAGES_ERROR_COMMUNICATION_WITH_SERVER_FAILED Communication with server failed

Typical error handling example is showed below

 location_manager_h location_handle;
 int result = location_manager_create(LOCATION_METHOD_GPS, location_handle);
 if(result != LOCATIONS_ERROR_NONE)
 {
     dlog_print(DLOG_INFO, "USR_TAG", "Creation of the location manager failed.");
     return false;
 }

To find a detailed description of an error one should check LOG messages starting with "CAPI_". While working with the simulator this information is available in the 'Log' SDK tab. While working with the target device, one should use the dlog utility.

 int result = app_control_send_launch_request(appcontrol_handle, my_app_control_callback, NULL);
 switch(result)
 {
     case APP_CONTROL_ERROR_APP_NOT_FOUND:
     dlog_print(DLOG_ERROR, "USR_TAG", "Application not found.");
     break;
     ...
 }

A sample log output shows how the error is propagated

error_log.png

For a process with ID=12387 (here, the test application) an internal error code is converted to a CAPI error code and details are reported. Finally, the test application handles the error code.


Asynchronous function calls

Some of Tizen Native API functions are asynchronous. An asynchronous function starts some processing and returns before this processing is finished. However, sometimes one should know, when this processing is finished. In such cases waiting for the processing completion notification should be properly implemented.


API Privilege

Some of Tizen Native API functions require adding appropriate privileges (defined in each API's Privilege section in the specification) to the application's manifest xml file. The privilege is essential part to get access grant for privacy related data or sensitive system resources. If required privileges are not included in the manifest xml file, then the function will return TIZEN_ERROR_PERMISSION_DENIED error.

For example, see the "Privilege:" section in the following picture:

core_privilege.png


To add privilege, click tizen-manifest.xml and go to Privileges tab to add proper privileges:

select_core_privilege.png

Except as noted, this content - excluding the Code Examples - is licensed under Creative Commons Attribution 3.0 and all of the Code Examples contained herein are licensed under BSD-3-Clause.
For details, see the Content License