App Control: Launching Applications and Managing Groups

This tutorial demonstrates how you can launch other applications and manage application groups.

Warm-up

Become familiar with the App Control API basics by learning about:

Running Applications Using Extra Data
Run a specific application control with preconfigured parameters.
Controlling the Launch Mode
Set the launch mode when calling for an application through an application control to manage application groups.

Running Applications Using Extra Data

To run a specific application control with some preconfigured parameters:

To use the functions and data types of the App Control API (in mobile and wearable applications), include the <app.h> header file in your application:
```
#include <app.h>
```

Prepare the application control:

error_code = app_control_create(&app_control);

ret = app_control_create(&app);
if (ret != APP_CONTROL_ERROR_NONE)
   dlog_print(DLOG_ERROR, LOG_TAG, "app_control_create() is failed. err = %d", ret);

When the app_control instance is created, set the operation and MIME type. In this example, the app_control launches an application which has the APP_CONTROL_OPERATION_VIEW operation and the image/jpeg MIME type.

The operation is mandatory information for the launch request. If the operation is not specified, APP_CONTROL_OPERATION_DEFAULT is used for the launch request.
```
ret = app_control_set_operation(app, APP_CONTROL_OPERATION_VIEW);
if (ret != APP_CONTROL_ERROR_NONE)
   dlog_print(DLOG_ERROR, LOG_TAG, "app_control_set_operation() is failed. err = %d", ret);

ret = app_control_set_mime(app, "image/jpeg");
if (ret != APP_CONTROL_ERROR_NONE)
   dlog_print(DLOG_ERROR, LOG_TAG, "app_control_set_mime() is failed. err = %d", ret);
```
For more information on the common application services and the extra data related to them, see Common Application Controls.

Add extra data to the app_control instance using the app_control_add_extra_data() or app_control_add_extra_data_array() function. In this example, a message is added as extra data:

ret = app_control_add_extra_data(app, Your Message Key, message);
if (ret != APP_CONTROL_ERROR_NONE)
   dlog_print(DLOG_ERROR, LOG_TAG, "app_control_add_extra_data() is failed. err = %d", ret);

Launch the app_control instance using the app_control_send_launch_request() function:

ret = app_control_send_launch_request(app, NULL, NULL);
if (ret != APP_CONTROL_ERROR_NONE)
   dlog_print(DLOG_ERROR, LOG_TAG, "app_control_send_launch_request() is failed. err = %d", ret);

Note
Since Tizen 2.4, service applications are only allowed to be launched explicitly and the caller must be an application in the same package. Otherwise, the app_control instance returns an error.

Read the extra data set to the app_control instance using the app_control_foreach_extra_data() function. The same function used on the app_control_h instance returned by the app_control reply allows you to read the reply message.

bool
_app_control_extra_data_cb(app_control_h app_control, const char *key, void *user_data)
{
   int ret;
   char *value;
   
   ret = app_control_get_extra_data(app, key, &value);
   if (ret != APP_CONTROL_ERROR_NONE) 
   {
      dlog_print(DLOG_ERROR, LOG_TAG, "app_control_get_extra_data() is failed. err = %d", ret);
   }
   dlog_print(DLOG_DEBUG, LOG_TAG, "[value] %s", value);

   return true;
}

ret = app_control_foreach_extra_data(app, _app_control_extra_data_cb, 0);
if (ret != APP_CONTROL_ERROR_NONE)
   dlog_print(DLOG_ERROR, LOG_TAG, "app_control_foreach_extra_data() is failed. err = %d", ret);

When your work with the application control is finished, clean up. To do this, pass the app_control handle to the app_control_destroy() function.

ret = app_control_destroy(app);
if (ret != APP_CONTROL_ERROR_NONE)
   dlog_print(DLOG_ERROR, LOG_TAG, "app_control_destroy() is failed. err = %d", ret);

Controlling the Launch Mode

In this use case, the caller application has a Launch button. When it is clicked, an application control is used to launch a sub application within the same group.

To control the launch mode:

Create the UI with the Launch button:

static void 
create_base_gui(appdata_s *ad)
{
   Evas_Object *bigbox, *bx, *bt;

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

   evas_object_smart_callback_add(ad->win, "delete,request", win_delete_request_cb, NULL);
   eext_object_event_callback_add(ad->win, EEXT_CALLBACK_BACK, win_back_cb, ad);

   bigbox = elm_box_add(ad->win);
   evas_object_size_hint_weight_set(bigbox, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
   elm_win_resize_object_add(ad->win, bigbox);
   evas_object_show(bigbox);

   bx = elm_box_add(ad->win);
   elm_box_pack_end(bigbox, bx);
   evas_object_show(bx);

   bt = elm_label_add(ad->win);
   elm_object_text_set(bt, "AGT3");
   elm_box_pack_end(bx, bt);
   evas_object_show(bt);

   bt = elm_button_add(ad->win);
   elm_object_text_set(bt, "Launch");
   elm_box_pack_end(bx, bt);
   evas_object_show(bt);
   evas_object_smart_callback_add(bt, "clicked", button_click_cb, NULL);

   evas_object_show(ad->win);
}

When the button is clicked, use an application control to launch the sub application.

Define the launch mode for the application to be called using the app_control_set_launch_mode() function. The second parameter defines the launch mode with the app_control_launch_mode_e enumerator (in mobile and wearable applications).

static void 
button_click_cb(void *data, Evas_Object *obj, void *event_info)
{
   app_control_h h;

   app_control_create(&h);
   app_control_set_operation(h, "http://tizen.org/appcontrol/operation/view");
   app_control_set_mime(h, "application/pdf");
   app_control_set_launch_mode(h, APP_CONTROL_LAUNCH_MODE_GROUP);
   app_control_send_launch_request(h, NULL, NULL);

   app_control_destroy(h);
}

static void 
app_control(app_control_h app_control, void *data)
{
   // Handle the launch request
}