App Control

An application control (app control) is a way of sharing an application's functionality. To use another application's features through application controls reduces your efforts and time to develop your application.

An application can be launched by the user from the Launcher or by another application. The application control can be used to describe either an action to be performed by other applications, or the results of the operation performed by a launched application. The application can receive results from the launched application.

Regardless of how an application is launched, the application framework starts the application by creating a new process and calling the entry point of the application. Like a conventional Linux application, the main function of the application is its entry point. In the Tizen application, the main task is to hand over control to the application framework by calling the ui_app_main() function:

bool app_create(void *user_data)
{
   // Take necessary actions before the main event loop starts
   // Initialize UI resources and application data
   // If this function returns true, the application main loop starts
   // If this function returns false, the application terminates
   return true;
}

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

void app_pause(void *user_data)
{
   // Take necessary actions when application becomes invisible
}

void app_resume(void *user_data)
{
   // Take necessary actions when application becomes visible
}

void app_terminate(void *user_data)
{
   // Release all resources
}

int main(int argc, char *argv[])
{
   struct appdata ad;
 
   ui_app_lifecycle_callback_s event_callback;
     
   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;

   memset(&ad, 0x0, sizeof(struct appdata));

   return ui_app_main(argc, argv, &event_callback, &ad);
}

The ui_app_main() function initializes the application and starts the main loop. It takes 4 parameters and uses them to initialize the application. The argc and argv parameters contain the values from the application framework, and you must never change their values. The third parameter is a state transition handler that is responsible for managing the state transitions the application goes through while it is running. The fourth parameter is application data to be passed to each state handler.

When the ui_app_main() is first invoked, the application moves from the ready state to the created state. The application has to initialize itself. During this transition, the application framework calls the application's app_create_cb() state transition callback just before the application enters the main loop. Within the registered callback, you must initialize the application resources and create the main window.

If the app_create_cb() callback function returns false, the application moves to the terminated state. If it returns true, the application enters the main loop.

Handling the Launch Options

The application framework calls the application's app_control_cb() callback just after the application enters the main loop. This callback is passed to the app_control containing the reason why the application was launched. For example, the application can be launched to open a file to handle the request that has been sent by other application. In all of these cases, the application is responsible for checking the content of the app_control and responding appropriately. The content of the app_control can be empty, if the application is launched by the user from the Launcher.

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;
 
   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);
 
      if (uri && !strcmp(mime_type, "image/jpg"))
      {
         display_image_file(ad, uri); // Display a specific image file
      }
   }
 
   if (ad->win)
      elm_win_activate(ad->win);
}

Managing Application Controls

The App Control API provides functions for launching other applications with a specific operation, URI, and MIME type. The requesting application can get a result back from the launched application.

To launch an application with the App Control API, create an app_control handle and add information to that handle. You can set the following information:

• Operation: Action to be performed by the app control.

  Note
  The operation name format is http://tizen.org/appcontrol/operation/<verb>. You can also use the related macro name, APP_CONTROL_OPERATION_<VERB>. The macro name can only be used in the .c files, not in the application manifest file for the app control export.

• URI: Data itself to be performed.
• MIME type: Specific type of the URI.
• Application ID: ID of the application to be launched.
• Extra data: Key-value pairs to provide additional information for the launch request and the result of the request.

The operation is mandatory information for sending the launch request. The App Control API provides several functions to get and set the above information to the app_control handle.

To launch an application with the App Control API, use one of the following methods:

• Explicit launch: Launch the application with the application ID.
• Implicit launch: Launch the application with an operation, URI, or MIME type.

The application launched by the app control can return the result to the caller application.

You can take advantage of the Tizen base application functionalities through the app control feature. You can also export your application functionality to allow other applications to launch your application.

Note
Since Tizen 2.4, application controls used to launch service applications outside the current package are not supported. Because of this, the service application is only allowed to be launched explicitly by the application in the same package.

Explicit Launch

When you request an explicit launch:

• If the underlying application launcher framework finds an application matched with the given application ID in the installed application list, it launches the application in a new process. If the matched application is not found, the framework returns the APP_CONTROL_ERROR_APP_NOT_FOUND result. Additional information (such as operation, URI, or MIME type) is not used to select an application for an explicit launch.
• If the operation setting in the app_control handle is set to APP_CONTROL_OPERATION_DEFAULT, the application ID must be set. Otherwise the APP_CONTROL_ERROR_INVALID_PARAMETER result is returned.

The following code example launches a calculator application explicitly with the application ID:

#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);

Implicit Launch

When you request an implicit launch:

• To determine which application can be launched, the application launcher framework compares the following conditions: operation, URI (or scheme), and MIME type.
• The application launcher framework iterates the app controls of all applications on the device to find the applications that match the given conditions.
• If only one application is matched for the given conditions, that application is launched. If multiple matching applications are found, the application selector is shown and the user can select the proper application.

To allow the application launcher framework to find and select matching applications, each application must describe its operation, URI, or MIME type correctly.

The following code example launches a camera application with the operation and MIME type:

#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_CREATE_CONTENT);
app_control_set_mime(app_control, "image/jpg");
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);

The following code example launches a gallery application with the operation, URI, and MIME type:

#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/*");
 
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);

Note
Since Tizen 2.4, service applications are only allowed to be launched explicitly. All service applications are excluded from matches of implicit launch requests.

Getting the App Control Results

The app control result from the requested application is delivered to the caller application in the app_control handle with extra data. For some cases, the App Control API provides pre-defined extra data keys.

If you cannot find a proper key, you can define your own key. However, the customized key must be shared between the caller and callee applications.

The following code example gets the result of an app control request by implementing an app_control result callback:

#include <app.h>
#include <dlog.h>
 
#define TAG "MY_TAG"
 
// Callback function to get result
static void app_control_result(app_control_h request, app_control_h reply, app_control_result_e result, void *user_data) 
{
   char *value;
 
   if (result == APP_CONTROL_RESULT_SUCCEEDED) 
   {
      if (app_control_get_extra_data(reply, APP_CONTROL_DATA_SELECTED, &value) == APP_CONTROL_ERROR_NONE)
      {
         dlog_print(DLOG_INFO, TAG, "[app_control_result_cb] Succeeded: value(%s)", value);
      } 
      else 
      {
         dlog_print(DLOG_ERROR, TAG, "[app_control_result_cb] Failed");
      }
 
   } 
   else 
   {
      dlog_print(DLOG_ERROR, TAG, "[app_control_result_cb] APP_CONTROL_RESULT_FAILED.");
   }
}

The following code example requests the launch of another application:

#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_CREATE_CONTENT);
app_control_set_mime(app_control, "text/plain");
 
if (app_control_send_launch_request(app_control, app_control_result, NULL) == APP_CONTROL_ERROR_NONE) 
{
   dlog_print(DLOG_INFO, TAG, "Succeeded: the application is launched.");
} 
else 
{
   dlog_print(DLOG_ERROR, TAG, "Failed to launch an application.");
}
 
app_control_destroy(app_control);

The following code example implements an app_control callback in the callee application:

static void app_control(app_control_h app_control, void *user_data) 
{
   struct appdata *ad = (struct appdata *)user_data;
   char *operation;
   char *mime;
   app_control_h reply;
   char *app_id;
 
   app_control_get_operation(app_control, &operation);
 
   if (!strcmp(operation, APP_CONTROL_OPERATION_CREATE_CONTENT)) 
   {
      app_control_get_mime(app_control, &mime);
 
      if (!strcmp(mime, "text/plain")) 
      {
         app_control_create(&reply);
 
         app_get_app_id(&app_id);
         app_control_add_extra_data(reply, APP_CONTROL_DATA_SELECTED, app_id);
         app_control_reply_to_launch_request(reply, app_control, APP_CONTROL_RESULT_SUCCEEDED);
 
         app_control_destroy(reply);
      }
   }
}

Common Application Controls

The Tizen common application controls specify a standard protocol for sharing application functionalities. You can use the common application controls to perform some basic tasks, such as selecting a file or taking a picture.

The following common application controls are available:

• Browser
• Calendar
• Call
• Camera
• Contact
• Email
• File Storage
• Map
• Message
• Multimedia
• System Settings
• Settings for Bluetooth
• Settings for Location
• Settings for NFC
• Settings for Wi-Fi
• Voice Recorder

Exporting AppControl Functionality

You can advertise your application features to other applications by exporting your application control functionalities. To allow other applications to find and use your application features implicitly without the application ID, declare your application control information in the tizen-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>
<app-control>
   <operation name="http://tizen.org/appcontrol/operation/call"/>
</app-control>

Note
In the application manifest file, the valid operation name format is http://tizen.org/appcontrol/operation/<verb>. You cannot use the related macro name, APP_CONTROL_OPERATION_<VERB>.

The resolution filter is used when resolving the application control. Each entry of the resolution filter has the <app-control> element and forms an application resolution unit. The additional URI or MIME type information must contain the associated operation ID, and the retrieved application control must have the specified application ID and operation ID when resolving the application control.

Note

The additional URI or MIME type can contain wildcards, such as '*', to match against given conditions in the app control: In the MIME type, you can use 2 types of wildcards: image/* and */*. In the additional URI, a more complex pattern of wildcards with similar semantics as the standard glob() function is available: '*' matches an arbitrary, possibly empty, string, and '?' matches an arbitrary character. Unlike in the glob() function, the '/' character can be matched by the wildcards. There are no [...] character ranges, and the wildcards '*' and '?' cannot be escaped to include them literally in a pattern.

You can specify the application control information of your application in the application project settings in the IDE; an operation ID must be specified for the application control.

Resolving Application Controls

In case of an implicit launch, the platform resolves the application control with given conditions in the request by searching the filters (available application controls) in the device. The application control references the following conditions in its description:

• Operation: exact match required for the value in both the request and the filters.
• URI: exact, partial (scheme), and pattern matches are allowed according to the value in the filters.
• MIME type: exact and pattern matches are allowed according to the value in the filters.

Each application control request has an operation value by default. In an application that is selected by the application control, the value in the request and the filters are always the same. Among the filters with identical operations, the URI and MIME types in the filters are compared with the following rules:

• If the request has URI or MIME types as a condition, the comparison is done only among the filters that have URI or MIME types. For example, if the request has a URI, but a filter does not, that filter is not added to the result even if the operations are the same. Similarly, if the request has MIME types, it is not compared to the filters that have no MIME types.

  An exception is applied to the URIs with a "file" scheme for the value. If the URI of the request contains an existing file path and no MIME types are supplied, the filters that have the MIME type of the given file path are also added to the results.

• Unlike the operation, the URI and MIME types support wildcards on the filters. Detailed conditions for matches are:
  • URI filters are matched if:
    • Both URIs are exactly the same.
    • URI in the request passes the test with a glob()-like function with the URI in the filters.
    • Scheme and host part of the URI in the request and the URI in the filters are the same.
    • Scheme part of the URI in the request and the URI in the filters are the same.
  • MIME type filters are matched if:
    • Both MIME types are exactly the same.
    • MIME type in the request and the filters have the same type and '*' for the subtype.
    • The filters have */* for the MIME type.

Note
An application that expects to match with any form of URI and any type of MIME must use '*' and */* in the resolution filter instead of leaving the value to NULL. Otherwise, the application is discarded by the application control.

The following examples show different scenarios for the results of resolving the application control:

• Operation only provided:

  • Request:
    • Operation: http://tizen.org/appcontrol/operation/view
    • URI: NULL
    • MIME: NULL
  • Result (the reason for the failure is marked in bold):

  Filter ID	Operation	URI	MIME	Result
  1	http://tizen.org/appcontrol/operation/view	NULL	NULL	Pass
  2	http://tizen.org/appcontrol/operation/default	NULL	NULL	Fail
  3	http://tizen.org/appcontrol/operation/view	file	NULL	Fail

• Operation and URI provided:

  • Request:
    • Operation: http://tizen.org/appcontrol/operation/view
    • URI: file:///usr/share/icons/calendar.png
    • MIME: NULL
  • Result (the reason for the failure is marked in bold):

  Filter ID	Operation	URI	MIME	Result
  1	http://tizen.org/appcontrol/operation/view	NULL	NULL	Fail
  2	http://tizen.org/appcontrol/operation/view	file:///usr/share/icons/calendar.png	NULL	Pass
  3	http://tizen.org/appcontrol/operation/view	file:///*	NULL	Pass
  4	http://tizen.org/appcontrol/operation/view	file	NULL	Pass
  5	http://tizen.org/appcontrol/operation/view	http	NULL	Fail
  6	http://tizen.org/appcontrol/operation/view	NULL	image/png	Pass
  7	http://tizen.org/appcontrol/operation/view	NULL	image/jpg	Fail

• Operation and MIME type provided:

  • Request:
    • Operation: http://tizen.org/appcontrol/operation/view
    • URI: NULL
    • MIME: image/png
  • Result (the reason for the failure is marked in bold):

  Filter ID	Operation	URI	MIME	Result
  1	http://tizen.org/appcontrol/operation/view	NULL	image/png	Pass
  2	http://tizen.org/appcontrol/operation/view	NULL	image/*	Pass
  3	http://tizen.org/appcontrol/operation/view	NULL	*/*	Pass
  4	http://tizen.org/appcontrol/operation/view	file:///usr/share/icons/calendar.png	NULL	Pass
  5	http://tizen.org/appcontrol/operation/view	NULL	image/jpg	Fail
  6	http://tizen.org/appcontrol/operation/view	NULL	video/*	Fail
  7	http://tizen.org/appcontrol/operation/view	http://tizen.org/favorites.png	image/png	Fail

• Operation, URI, and MIME type provided:

  • Request:
    • Operation: http://tizen.org/appcontrol/operation/view
    • URI: http://www.tizen.org/favorites.png
    • MIME: image/png
  • Result (the reason for the failure is marked in bold):

  Filter ID	Operation	URI	MIME	Result
  1	http://tizen.org/appcontrol/operation/view	http://www.tizen.org/favorites.png	image/png	Pass
  2	http://tizen.org/appcontrol/operation/view	http://www.tizen.org/favorites.png	NULL	Fail
  3	http://tizen.org/appcontrol/operation/view	http://www.tizen.org/*	image/png	Pass
  4	http://tizen.org/appcontrol/operation/view	http	image/png	Pass
  5	http://tizen.org/appcontrol/operation/view	NULL	image/png	Fail
  6	http://tizen.org/appcontrol/operation/view	*	*/*	Pass

Managing Application Groups

You can define the application launch mode and group your applications into entities that can be managed together.

The main application group features include:

• Defining the application launch mode

  When an application is launched through an app control, its launch mode defines its behavior:

  • The single launch mode means that the application is launched as a main application (in a new group).
  • The caller launch mode means that the application is launched as a sub application belonging to the same group as the caller application who is causing the application to be launched.

  You can set the application launch mode in the manifest file using the launch_mode attribute of the <ui-application> element. If the launch mode is set to caller, the application that calls the app control can define the launch mode for the called application using the app_control_set_launch_mode() function. However, if the called application has set its launch mode in its manifest file to single, that setting overrides the caller application's launch mode request.

• Managing the application group

  Applications in a same group act as if they are in 1 stack. For example, if an application A wants to send an email using an email application B, the application A can launch the email application B, making the email application B a sub application in the same group as the application A. When both applications are running, and the user presses the home button, both applications are hidden. When the user later resumes the caller application (application A), the email application B is shown on top of the caller application.

  If an application is launched in a group, it can be terminated by the main (first) application in the group. If the main application is terminated or killed, the sub applications in the group are terminated automatically (they can be terminated by the framework even if they are hidden).

  Figure: Group behavior