--- /dev/null
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+ <meta http-equiv="content-type" content="text/html; charset=utf-8"/>
+ <meta http-equiv="X-UA-Compatible" content="IE=9" />
+ <link rel="stylesheet" type="text/css" href="../../css/styles.css" />
+ <link rel="stylesheet" type="text/css" href="../../css/snippet.css" />
+ <script type="text/javascript" src="../../scripts/snippet.js"></script>
+ <script type="text/javascript" src="../../scripts/jquery.util.js" charset="utf-8"></script>
+ <script type="text/javascript" src="../../scripts/common.js" charset="utf-8"></script>
+ <script type="text/javascript" src="../../scripts/core.js" charset="utf-8"></script>
+ <script type="text/javascript" src="../../scripts/search.js" charset="utf-8"></script>
+ <title>Application Controls</title>
+ </head>
+ <body onload="prettyPrint()" style="overflow: auto;">
+
+ <div id="toc-navigation">
+ <div id="toc_border"><div id="toc">
+ <p class="toc-title">Dependencies</p>
+ <ul class="toc">
+ <li>Tizen 4.0 and Higher</li>
+ </ul>
+ <p class="toc-title">Content</p>
+ <ul class="toc">
+ <li><a href="#launch">Launch Types</a></li>
+ <li><a href="#request">Launch Requests</a></li>
+ <li><a href="#process">Launch Process</a></li>
+ <li><a href="#results">Launch Results</a></li>
+ <li><a href="#export_appcontrol">Application Control Export</a></li>
+ <li><a href="#group">Application Group Management</a></li>
+ <li><a href="#prerequisites">Prerequisites</a></li>
+ <li><a href="#use">Launching Applications Using Extra Data</a></li>
+ <li><a href="#mode">Controlling the Launch Mode</a></li>
+ </ul>
+ <p class="toc-title">Related Info</p>
+ <ul class="toc">
+ <li><a href="https://developer.tizen.org/dev-guide/csapi/api/Tizen.Applications.html">Tizen.Applications Namespace</a></li>
+ </ul>
+ </div></div>
+</div>
+
+<div id="container"><div id="contents"><div class="content">
+<h1>Application Controls</h1>
+
+<p>An application control (app control) is a way of sharing an application's functionality with other applications. Using another application's features through application controls reduces the time and effort needed to develop your own application.</p>
+
+<p>An application can be launched by the user from the launcher or by another application through the application control. The application control launch request describes either an action to be performed by other applications, or the results of that action. The application can also receive results from the launched application through an application control reply.</p>
+
+<p>The main application control features are:</p>
+<ul>
+ <li>Requesting application launches
+ <p>You can <a href="#request">create application control launch requests</a> to ask the platform to launch an application to perform a specific task for you.</p>
+ <p>You can use different <a href="#launch">launch types</a> (implicit or explicit), depending on whether you know the exact application you want to launch. When you make an implicit launch request, the platform uses the conditions in the launch request to determine which application can be launched to handle the requested task.</p></li>
+ <li>Launching an application due to a launch request
+ <p>After the platform has found the correct application to launch, the application is activated through the <a href="#process">launch process</a>, and can perform the task the original application has requested. After the task is completed, the launched application can send the results back to the original application.</p></li>
+ <li>Handling application control launch results
+ <p>When the launched application is finished with its task and has sent back the results, you can <a href="#results">receive those results</a> in your application and handle them accordingly.</p></li>
+ <li>Exporting application controls
+ <p>You can <a href="#export_appcontrol">allow other applications to launch your application and use your functionalities</a> by exporting your application features as application controls.</p></li>
+ <li>Controlling application groups through the launch mode
+ <p>You can <a href="#group">set the launch mode</a> when launching an application through an application control. The launch mode determines whether the application is launched in its own group, or as a sub application within an existing group.</p></li>
+</ul>
+
+<h2 id="launch">Launch Types</h2>
+
+<p>You can launch an application with an application control using 2 different launch types:</p>
+<ul>
+ <li>Explicit launch:
+ <p>Explicit launch means that you launch a specific application with the application ID. When you <a href="#explicit">request an explicit launch</a>:</p>
+ <ul>
+ <li>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 <code>AppNotFoundException</code> occurs. Additional information (such as operation, URI, or MIME type) is not used to select an application for an explicit launch.
+ </li>
+ <li>If the <code>Operation</code> property of a <a href="https://developer.tizen.org/dev-guide/csapi/api/Tizen.Applications.AppControl.html">Tizen.Applications.AppControl</a> instance is set to <code>AppControlOperations.Default</code>, the application ID must be set. Otherwise the <code>ArgumentException</code> occurs.</li>
+ </ul>
+
+<div class="note">
+ <strong>Note</strong>
+ Be careful when using the explicit launch, because if the target application does not exist on the device, you need to handle the <code>AppNotFoundException</code>. If you want to launch any application that supports a certain operation, use the implicit launch.
+</div>
+ </li>
+ <li>Implicit launch
+ <p>Implicit launch means that you launch any application which matches the operation, URI (or scheme), or MIME type you need. When you <a href="#implicit">request an implicit launch</a>:</p>
+ <ol>
+ <li>To determine which application can be launched, the application launcher framework compares the operation, URI, and MIME type conditions.</li>
+ <li>The application launcher framework iterates the application controls of all applications on the device to <a href="#resolution">find the applications that match</a> the given conditions.</li>
+ <li>If only 1 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.</li>
+ </ol>
+ </li>
+</ul>
+
+<h2 id="request">Launch Requests</h2>
+
+<p>To launch an application with the application control, you must create a launch request. You must create an instance of the <a href="https://developer.tizen.org/dev-guide/csapi/api/Tizen.Applications.AppControl.html">Tizen.Applications.AppControl</a> class, and add the conditions for selecting the application to be launched. You can add the following information to the instance:</p>
+<ul>
+ <li><code>Operation</code>: Action to be performed by the launched application.
+<div class="note">
+ <strong>Note</strong>
+ The operation name format is <code>http://tizen.org/appcontrol/operation/<verb></code>. You can also use an instance of the <a href="https://developer.tizen.org/dev-guide/csapi/api/Tizen.Applications.AppControlOperations.html">Tizen.Applications.AppControlOperations</a> class.
+</div>
+
+ <p>The operation is mandatory information for sending the launch request.</p>
+ </li>
+ <li><code>Uri</code>: Data itself to be performed.</li>
+ <li><code>Mime</code>: Specific type of the URI.</li>
+ <li><code>ApplicationId</code>: ID of the application to be launched.</li>
+ <li><code>ExtraData</code>: Key-value pairs to <a href="#use">provide additional information for the launch request and launch result</a>.</li>
+</ul>
+
+
+<h3 id="explicit">Explicit Launch Request</h3>
+
+<p>The following example shows how to create an explicit launch request which launches an application explicitly by setting the <code>ApplicationId</code> property of the <a href="https://developer.tizen.org/dev-guide/csapi/api/Tizen.Applications.AppControl.html">Tizen.Applications.AppControl</a> class instance:</p>
+
+<pre class="prettyprint">
+AppControl appcontrol = new AppControl();
+
+appcontrol.Operation = AppControlOperations.Default;
+appcontrol.ApplicationId = "org.tizen.TestApp";
+
+AppControl.SendLauncherRequest(appcontrol);
+</pre>
+
+
+<h3 id="implicit">Implicit Launch Request</h3>
+
+<p>The following examples show how to create an implicit launch request:</p>
+
+<ul>
+ <li>To launch a camera application with a specific operation and MIME type:
+<pre class="prettyprint">
+AppControl appcontrol = new AppControl();
+
+appcontrol.Operation = AppControlOperations.CreateContent;
+appcontrol.Mime = "image/jpg";
+
+AppControl.SendLauncherRequest(appcontrol);
+</pre>
+ </li>
+ <li>To launch a viewer application with a specific operation, URI, and MIME type:
+<pre class="prettyprint">
+AppControl appcontrol = new AppControl();
+
+appcontrol.Operation = AppControlOperations.View;
+appcontrol.Mime = "image/*";
+appcontrol.Uri = "file:///home/myhome/Photos/1_photo.jpg";
+
+AppControl.SendLauncherRequest(appcontrol);
+</pre>
+ </li>
+</ul>
+
+<h3 id="resolution">Determining the Application for an Implicit Launch Request</h3>
+
+<p>In the case of an implicit launch, the platform determines which application to launch by "resolving the application control". This means that the platform considers the given conditions (operation, URI, and MIME type) in the launch request, searches the filters (installed applications with available application controls) on the device, and attempts to find a match.</p>
+
+<p>The launch request conditions are matched to the available filters using the following logic:</p>
+
+<ol>
+<li>The operation value is matched first. An exact match is required for the value in both the launch request and the filters.
+<p>If multiple matching filters with identical operations are available, the URI and MIME types in the matching filters are compared.</p></li>
+
+<li>If the launch 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 launch 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 launch request has MIME types, it is not compared to the filters that have no MIME types.
+
+<p>An exception is applied to the URIs with a "file" scheme for the value. If the launch request URI 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.</p>
+
+<div class="note">
+ <strong>Note</strong>
+ A filter (application) that expects to match with any form of URI and any type of MIME must use <code>'*'</code> and <code>*/*</code> in their application control information in the <code>tizen-manifest.xml</code> file, instead of leaving the value to <code>NULL</code>. Otherwise, the application is discarded by the platform when the application control is resolved.
+</div>
+</li>
+
+<li>Unlike the operation, the URI and MIME types support wildcards on the filters. Detailed conditions for matches are:
+<ul>
+ <li>The URI match can be an exact, partial (scheme), or pattern match according to the value in the filters. URI filters are matched with the launch request if:
+ <ul>
+ <li>Both URIs are exactly the same.</li>
+ <li>Launch request URI passes the test with a <code>glob()</code>-like function with the filter URI.</li>
+ <li>Scheme and host part of the URI in the launch request and filters are the same.</li>
+ <li>Scheme part of the URI in the launch request and filters is the same.</li>
+ </ul>
+ </li>
+ <li>The MIME type match can be an exact or pattern match according to the value in the filters. MIME type filters are matched with the launch request if:
+ <ul>
+ <li>Both MIME types are exactly the same.</li>
+ <li>MIME type in the launch request and filters has the same type and '*' for the subtype.</li>
+ <li>The filters have <code>*/*</code> for the MIME type.</li>
+ </ul>
+ </li>
+</ul>
+</li>
+</ol>
+
+
+
+<p>The following examples show different scenarios for the results of resolving the application control:</p>
+<ul>
+<li>
+<p>Operation provided:</p>
+<ul>
+<li>Request:
+<ul>
+<li>Operation: <code>http://tizen.org/appcontrol/operation/view</code></li>
+<li>URI: <code>NULL</code></li>
+<li>MIME: <code>NULL</code></li>
+</ul>
+</li>
+<li>Result (the reason for the failure is marked in <strong>bold</strong>):</li>
+</ul>
+
+<p align="center" class="Table"><strong>Table: Scenario when only the operation is provided</strong></p>
+<table>
+<tbody>
+ <tr>
+ <th>Filter ID</th>
+ <th>Operation</th>
+ <th>URI</th>
+ <th>MIME</th>
+ <th>Result</th>
+ </tr>
+ <tr>
+ <td>1</td>
+ <td><code>http://tizen.org/appcontrol/operation/view</code></td>
+ <td><code>NULL</code></td>
+ <td><code>NULL</code></td>
+ <td>Pass</td>
+ </tr>
+ <tr>
+ <td>2</td>
+ <td><code><strong>http://tizen.org/appcontrol/operation/default</strong></code></td>
+ <td><code>NULL</code></td>
+ <td><code>NULL</code></td>
+ <td>Fail</td>
+ </tr>
+ <tr>
+ <td>3</td>
+ <td><code>http://tizen.org/appcontrol/operation/view</code></td>
+ <td><code><strong>file</strong></code></td>
+ <td><code>NULL</code></td>
+ <td>Fail</td>
+ </tr>
+ </tbody>
+</table>
+</li>
+<li>
+<p>Operation and URI provided:</p>
+<ul>
+<li>Request:
+<ul>
+<li>Operation: <code>http://tizen.org/appcontrol/operation/view</code></li>
+<li>URI: <code>file:///usr/share/icons/calendar.png</code></li>
+<li>MIME: <code>NULL</code></li>
+</ul>
+</li>
+<li>Result (the reason for the failure is marked in <strong>bold</strong>):</li>
+</ul>
+<p align="center" class="Table"><strong>Table: Scenario when the operation and URI are provided</strong></p>
+<table>
+<tbody>
+ <tr>
+ <th>Filter ID</th>
+ <th>Operation</th>
+ <th>URI</th>
+ <th>MIME</th>
+ <th>Result</th>
+ </tr>
+ <tr>
+ <td>1</td>
+ <td><code>http://tizen.org/appcontrol/operation/view</code></td>
+ <td><code><strong>NULL</strong></code></td>
+ <td><code>NULL</code></td>
+ <td>Fail</td>
+ </tr>
+ <tr>
+ <td>2</td>
+ <td><code>http://tizen.org/appcontrol/operation/view</code></td>
+ <td><code>file:///usr/share/icons/calendar.png</code></td>
+ <td><code>*/*</code></td>
+ <td>Pass</td>
+ </tr>
+ <tr>
+ <td>3</td>
+ <td><code>http://tizen.org/appcontrol/operation/view</code></td>
+ <td><code>file:///*</code></td>
+ <td><code>*/*</code></td>
+ <td>Pass</td>
+ </tr>
+ <tr>
+ <td>4</td>
+ <td><code>http://tizen.org/appcontrol/operation/view</code></td>
+ <td><code>file</code></td>
+ <td><code>*/*</code></td>
+ <td>Pass</td>
+ </tr>
+ <tr>
+ <td>5</td>
+ <td><code>http://tizen.org/appcontrol/operation/view</code></td>
+ <td><code><strong>http</strong></code></td>
+ <td><code>*/*</code></td>
+ <td>Fail</td>
+ </tr>
+ <tr>
+ <td>6</td>
+ <td><code>http://tizen.org/appcontrol/operation/view</code></td>
+ <td><code>NULL</code></td>
+ <td><code>image/png</code></td>
+ <td>Pass</td>
+ </tr>
+ <tr>
+ <td>7</td>
+ <td><code>http://tizen.org/appcontrol/operation/view</code></td>
+ <td><code>NULL</code></td>
+ <td><code><strong>image/jpg</strong></code></td>
+ <td>Fail</td>
+ </tr>
+ </tbody>
+</table>
+</li>
+<li>
+<p>Operation and MIME type provided:</p>
+<ul>
+<li>Request:
+ <ul>
+ <li>Operation: <code>http://tizen.org/appcontrol/operation/view</code></li>
+ <li>URI: <code>NULL</code></li>
+ <li>MIME: <code>image/png</code></li>
+ </ul>
+</li>
+<li>Result (the reason for the failure is marked in <strong>bold</strong>):</li>
+</ul>
+<p align="center" class="Table"><strong>Table: Scenario when the operation and MIME type are provided</strong></p>
+<table>
+<tbody>
+ <tr>
+ <th>Filter ID</th>
+ <th>Operation</th>
+ <th>URI</th>
+ <th>MIME</th>
+ <th>Result</th>
+ </tr>
+ <tr>
+ <td>1</td>
+ <td><code>http://tizen.org/appcontrol/operation/view</code></td>
+ <td><code>NULL</code></td>
+ <td><code>image/png</code></td>
+ <td>Pass</td>
+ </tr>
+ <tr>
+ <td>2</td>
+ <td><code>http://tizen.org/appcontrol/operation/view</code></td>
+ <td><code>NULL</code></td>
+ <td><code>image/*</code></td>
+ <td>Pass</td>
+ </tr>
+ <tr>
+ <td>3</td>
+ <td><code>http://tizen.org/appcontrol/operation/view</code></td>
+ <td><code>NULL</code></td>
+ <td><code>*/*</code></td>
+ <td>Pass</td>
+ </tr>
+ <tr>
+ <td>4</td>
+ <td><code>http://tizen.org/appcontrol/operation/view</code></td>
+ <td><code>file:///usr/share/icons/calendar.png</code></td>
+ <td><code><strong>NULL</strong></code></td>
+ <td>Fail</td>
+ </tr>
+ <tr>
+ <td>5</td>
+ <td><code>http://tizen.org/appcontrol/operation/view</code></td>
+ <td><code>NULL</code></td>
+ <td><code><strong>image/jpg</strong></code></td>
+ <td>Fail</td>
+ </tr>
+ <tr>
+ <td>6</td>
+ <td><code>http://tizen.org/appcontrol/operation/view</code></td>
+ <td><code>NULL</code></td>
+ <td><code><strong>video/*</strong></code></td>
+ <td>Fail</td>
+ </tr>
+ <tr>
+ <td>7</td>
+ <td><code>http://tizen.org/appcontrol/operation/view</code></td>
+ <td><code><strong>http://tizen.org/favorites.png</strong></code></td>
+ <td><code>image/png</code></td>
+ <td>Fail</td>
+ </tr>
+ </tbody>
+</table>
+</li>
+<li>
+<p>Operation, URI, and MIME type provided:</p>
+<ul>
+<li>Request:
+ <ul>
+ <li>Operation: <code>http://tizen.org/appcontrol/operation/view</code></li>
+ <li>URI: <code>http://www.tizen.org/favorites.png</code></li>
+ <li>MIME: <code>image/png</code></li>
+ </ul>
+</li>
+<li>Result (the reason for the failure is marked in <strong>bold</strong>):</li>
+</ul>
+<p align="center" class="Table"><strong>Table: Scenario when the operation, URI, and MIME type are provided</strong></p>
+<table>
+<tbody>
+ <tr>
+ <th>Filter ID</th>
+ <th>Operation</th>
+ <th>URI</th>
+ <th>MIME</th>
+ <th>Result</th>
+ </tr>
+ <tr>
+ <td>1</td>
+ <td><code>http://tizen.org/appcontrol/operation/view</code></td>
+ <td><code>http://www.tizen.org/favorites.png</code></td>
+ <td><code>image/png</code></td>
+ <td>Pass</td>
+ </tr>
+ <tr>
+ <td>2</td>
+ <td><code>http://tizen.org/appcontrol/operation/view</code></td>
+ <td><code>http://www.tizen.org/favorites.png</code></td>
+ <td><code><strong>NULL</strong></code></td>
+ <td>Fail</td>
+ </tr>
+ <tr>
+ <td>3</td>
+ <td><code>http://tizen.org/appcontrol/operation/view</code></td>
+ <td><code>http://www.tizen.org/*</code></td>
+ <td><code>image/png</code></td>
+ <td>Pass</td>
+ </tr>
+ <tr>
+ <td>4</td>
+ <td><code>http://tizen.org/appcontrol/operation/view</code></td>
+ <td><code>http</code></td>
+ <td><code>image/png</code></td>
+ <td>Pass</td>
+ </tr>
+ <tr>
+ <td>5</td>
+ <td><code>http://tizen.org/appcontrol/operation/view</code></td>
+ <td><code><strong>NULL</strong></code></td>
+ <td><code>image/png</code></td>
+ <td>Fail</td>
+ </tr>
+ <tr>
+ <td>6</td>
+ <td><code>http://tizen.org/appcontrol/operation/view</code></td>
+ <td><code>*</code></td>
+ <td><code>*/*</code></td>
+ <td>Pass</td>
+ </tr>
+ </tbody>
+</table>
+</li>
+</ul>
+
+
+<h2 id="process">Launch Process</h2>
+
+<p>Regardless of the launch request type, when the application launcher framework has received and resolved a launch request, it starts the application by creating a new process and calling the entry point of the application:</p>
+
+<ol>
+ <li>Like a conventional C# application, the main method of the application is its entry point. In a Tizen .NET application, the main task is to hand over control to the application framework by calling the <code>Run()</code> method:
+<pre class="prettyprint">
+class App : CoreUIApplication
+{
+ protected override void OnCreate()
+ {
+ /// Hook to take necessary actions before main event loop starts; this
+ /// usually means initializing the UI
+
+ base.OnCreate();
+ }
+
+ protected override void OnAppControlReceived(AppControlReceivedEventArgs e)
+ {
+ /// Handle the launch request, show the user the task requested through the
+ /// "AppControlReceivedEventArgs" parameter
+
+ base.OnAppControlReceived(e);
+ }
+
+ protected override void OnPause()
+ {
+ /// Take necessary actions when application becomes invisible
+
+ base.OnPause();
+ }
+
+ protected override void OnResume()
+ {
+ /// Take necessary actions when application becomes visible
+
+ base.OnResume();
+ }
+
+ protected override void OnTerminate()
+ {
+ /// Release all resources
+
+ base.OnTerminate();
+ }
+
+ static void Main(string[] args)
+ {
+ App app = new App();
+ app.Run(args);
+ }
+}
+</pre>
+ </li>
+ <li>The <code>Run()</code> method initializes the application and starts the main loop.
+ <p>It takes a parameter and uses it to initialize the application. The <code>args</code> parameter contains the values from the application framework, and you must never change their values.</p>
+ </li>
+ <li>When the <code>Run()</code> method is first invoked, the application moves from the ready state to the created state, and must initialize itself. During this transition, the application framework calls the application's <code>OnCreate()</code> state transition method just before the application enters the main loop. Within the method, you must initialize the application resources and create the main window.
+ </li>
+ <li>Just after the application enters the main loop, the application framework calls the application's <code>OnAppControlReceived()</code> method.
+ <p>The reason the application was launched is contained in an instance of the <a href="https://developer.tizen.org/dev-guide/csapi/api/Tizen.Applications.ReceivedAppControl.html">Tizen.Applications.ReceivedAppControl</a> class, which is derived from the <a href="https://developer.tizen.org/dev-guide/csapi/api/Tizen.Applications.AppControl.html">Tizen.Applications.AppControl</a> class. The application is always responsible for checking the content of the <code>Tizen.Applications.ReceivedAppControl</code> instance and responding appropriately. The content of the <code>Tizen.Applications.ReceivedAppControl</code> instance can be empty, if the application is launched by the user from the launcher.</p>
+ <p>If the application wants to return the result of the application control operation to the application that originally sent the launch request, the result can be sent with the <code>ReplyToLaunchRequest()</code> method of the <code>Tizen.Applications.ReceivedAppControl</code> class.</p>
+
+<pre class="prettyprint">
+protected override void OnAppControlReceived(AppControlReceivedEventArgs e)
+{
+ ReceivedAppControl receivedAppControl = e.ReceivedAppControl;
+
+ if (receivedAppControl.IsReplyRequest)
+ {
+ AppControl replyRequest = new AppControl();
+
+ /// Send reply to the caller app
+ receivedAppControl.ReplyToLaunchRequest(replyRequest, AppControlReplyResult.Succeeded);
+ }
+
+ base.OnAppControlReceived(e);
+}
+</pre>
+
+</li>
+</ol>
+
+<h2 id="results">Launch Results</h2>
+
+<p>After the requested application (callee) has been launched and the launched application has performed the requested operation, the results of the operation are delivered back to the application that sent the original launch request (caller).</p>
+
+<p>The following code example requests the launch of another application and sets the <code>AppControlReplyCallback()</code> method to get the launch result:</p>
+
+<pre class="prettyprint">
+public void LaunchRequestResultTest()
+{
+ string MyAppId = "org.tizen.MyApp";
+
+ AppControl appCtrl = new AppControl();
+ appCtrl.Operation = AppControlOperations.Default;
+ appCtrl.ApplicationId = MyAppId;
+
+ /// Set method to get the launch result
+ AppControl.SendLaunchRequest(appCtrl, AppControlReplyCallback);
+}
+</pre>
+
+<p>The results are delivered in an instance of the <a href="https://developer.tizen.org/dev-guide/csapi/api/Tizen.Applications.AppControl.html">Tizen.Applications.AppControl</a> instance with extra data. For some cases, the <a href="https://developer.tizen.org/dev-guide/csapi/api/Tizen.Applications.AppControlData.html">Tizen.Applications.AppControlData</a> provides predefined extra data keys. If the key you need is not predefined, you can create your own key. However, the customized key must be shared between the caller and callee applications.</p>
+
+<p>The following example shows how you can retrieve the results of the launch request and requested operation by implementing the <code>AppControlReplyCallback()</code> method:</p>
+<pre class="prettyprint">
+/// Method for getting the result
+static void AppControlReplyCallback(Tizen.Applications.AppControl launchRequest, Tizen.Applications.AppControl replyRequest, AppControlReplyResult result)
+{
+ string callerAppId;
+ string selected;
+
+ if (result >= AppControlReplyResult.Succeeded)
+ {
+ /// Get the value of ExtraData sent by callee
+ callerAppId = replyRequest.ExtraData.Get<string>("CallerApplicationId");
+ selected = replyRequest.ExtraData.Get<string>(AppControlData.Selected);
+ }
+}
+</pre>
+
+<h2 id="export_appcontrol">Application Control Export</h2>
+
+<p>You can allow other applications to launch your application and use your application features through application controls by exporting your application control functionalities. To allow other applications to launch your application implicitly without the application ID, declare your application control information in the <code>tizen-manifest.xml</code> file:</p>
+<pre class="prettyprint">
+<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>
+</pre>
+
+
+<p>The operation, URI, and MIME type information is used when <a href="#resolution">resolving the application control</a>. The operation information is mandatory, while the URI or MIME type information is optional. Any application requesting a launch of your application must either specify your application ID (for an explicit launch) or have the same operation value and applicable URI and MIME type information (for an implicit launch).</p>
+
+<div class="note">
+ <strong>Note</strong>
+ The URI or MIME type can contain wildcards, such as '*', to match against given conditions in the application control:
+ <ul>
+ <li>In the MIME type, you can use 2 types of wildcards: <code>image/*</code> and <code>*/*</code>.</li>
+ <li>In the URI, a more complex pattern of wildcards with similar semantics as the standard <code>glob()</code> function is available: '*' matches an arbitrary, possibly empty, string, and '?' matches an arbitrary character. Unlike in the <code>glob()</code> 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.</li>
+ </ul>
+</div>
+
+<h2 id="group">Application Group Management</h2>
+<p>You can <a href="#mode">define the application launch mode</a> and group your applications into entities that can be managed together.</p>
+
+ <p>The main application group features include:</p>
+ <ul>
+ <li>Defining the application launch mode
+ <p>When an application is launched through an application control, its launch mode defines its behavior:</p>
+ <ul><li>The single launch mode means that the application is launched as a main application (in a new group).</li>
+ <li>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.</li></ul>
+ <p>You can set the application launch mode <a href="../../../../vstools/tools/manifest_editor.htm#launch_mode">in the manifest file</a> using the <code>launch_mode</code> attribute of the <code><ui-application></code> element. If the launch mode is set to <code>caller</code>, the application that calls the application control can define the launch mode for the called application using the <code>LaunchMode</code> property. However, if the called application has set its launch mode in its manifest file to <code>single</code>, that setting overrides the caller application's launch mode request.</p>
+ </li>
+ <li>Managing the application group
+ <p>Applications in a same group act as if they are in 1 stack. For example, if application A wants to send an email using 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.</p>
+ <p>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).</p>
+
+<p align="center"><strong>Figure: Group behavior</strong></p>
+<p align="center"><img alt="Group behavior" src="../../images/app_group_behavior.png" /></p>
+
+ </li>
+</ul>
+
+<h2 id="prerequisites">Prerequisites</h2>
+<p>To enable your application to use the application control functionality:</p>
+<ol>
+ <li>To use application controls, the application has to request permission by adding the following privilege to the <code>tizen-manifest.xml</code> file:
+<pre class="prettyprint">
+<privileges>
+ <privilege>http://tizen.org/privilege/appmanager.launch</privilege>
+</privileges>
+</pre>
+ </li>
+ <li>To use the methods and data types of the <a href="https://developer.tizen.org/dev-guide/csapi/api/Tizen.Applications.html">Tizen.Applications</a> namespace, include it in your application:
+<pre class="prettyprint">
+using Tizen.Applications;
+</pre>
+ </li>
+</ol>
+
+<h2 id="use">Launching Applications Using Extra Data</h2>
+
+<p>To run a specific application control with some preconfigured parameters:</p>
+
+<ol>
+ <li>Prepare the application control:
+<pre class="prettyprint">
+AppControl appControl = new AppControl();
+</pre>
+ </li>
+ <li>When the instance of the <a href="https://developer.tizen.org/dev-guide/csapi/api/Tizen.Applications.AppControl.html">Tizen.Applications.AppControl</a> class is created, set the operation and MIME type. In this example, the application control launches an application which has the <code>AppControlOperations.View</code> operation and the <code>image/jpeg</code> MIME type.
+ <p>The <code>Operation</code> property is mandatory information for the launch request. If the operation is not specified, <code>AppControlOperations.Default</code> is used for the launch request.</p>
+<pre class="prettyprint">
+appControl.Operation = AppControlOperations.View;
+appControl.Mime = "image/jpeg";
+</pre>
+ </li>
+ <li>Add extra data to the <code>Tizen.Applications.AppControl</code> instance by using the <code>ExtraData</code> property and the <code>Add()</code> method of the <a href="https://developer.tizen.org/dev-guide/csapi/api/Tizen.Applications.AppControl.ExtraDataCollection.html">Tizen.Applications.AppControl.ExtraDataCollection</a> class. In the following example, a message is added as extra data:
+<pre class="prettyprint">
+appControl.ExtraData.Add("MyKey", "My Message");
+</pre>
+ </li>
+ <li>Launch the <code>Tizen.Applications.AppControl</code> instance with the <code>SendLaunchRequest()</code> method:
+<pre class="prettyprint">
+AppControl.SendLaunchRequest(appControl, AppControlReplyCallback);
+</pre>
+ </li>
+ <li>In the launched application, read the extra data added to the application control by using the <code>ExtraData</code> property of the <a href="https://developer.tizen.org/dev-guide/csapi/api/Tizen.Applications.ReceivedAppControl.html">Tizen.Applications.ReceivedAppControl</a> class instance and the <code>Get()</code> method of the <code>Tizen.Applications.ExtraDataCollection</code> class. The same property and method can be used in the original application to read the reply message, when the application control reply is returned.
+
+<pre class="prettyprint">
+/// Callee application
+protected override void OnAppControlReceived(AppControlReceivedEventArgs e)
+{
+ string message;
+ ReceivedAppControl receivedAppControl = e.ReceivedAppControl;
+
+ /// Get ExtraData coming from caller application
+ message = receivedAppControl.ExtraData.Get<string>("MyKey");
+
+ if (receivedAppControl.IsReplyRequest)
+ {
+ AppControl replyRequest = new AppControl();
+ replyRequest.ExtraData.Add("ReplyKey", "Reply message");
+
+ /// Send reply to the caller application
+ receivedAppControl.ReplyToLaunchRequest(replyRequest, AppControlReplyResult.Succeeded);
+ }
+
+ base.OnAppControlReceived(e);
+}
+</pre>
+<pre class="prettyprint">
+/// Caller application
+static void AppControlReplyCallback(Tizen.Applications.AppControl launchRequest, Tizen.Applications.AppControl replyRequest, AppControlReplyResult result)
+{
+ string receivedMessage;
+ if(result >= AppControlReplyResult.Succeeded)
+ {
+ receivedMessage = replyRequest.ExtraData.Get<string>("ReplyKey");
+ }
+}
+</pre>
+ </li>
+</ol>
+
+<h2 id="mode">Controlling the Launch Mode</h2>
+
+<p>To set the application control in the caller application to launch a sub application within the same group:</p>
+
+<pre class="prettyprint">
+AppControl appControl = new AppControl();
+appControl.ApplicationId = "org.tizen.TestApp";
+appControl.LaunchMode = AppControlLaunchMode.Group;
+
+AppControl.SendLaunchRequest(appControl);
+</pre>
+
+<script type="text/javascript" src="../../scripts/jquery.zclip.min.js"></script>
+<script type="text/javascript" src="../../scripts/showhide.js"></script>
+</div></div></div>
+
+<a class="top sms" href="#"><img src="../../images/btn_top.gif" alt="Go to top" /></a>
+
+<div id="footer">
+<p class="footer">Except as noted, this content - excluding the Code Examples - is licensed under <a href="http://creativecommons.org/licenses/by/3.0/legalcode" target="_blank">Creative Commons Attribution 3.0</a> and all of the Code Examples contained herein are licensed under <a href="https://www.tizen.org/bsd-3-clause-license" target="_blank">BSD-3-Clause</a>.<br/>For details, see the <a href="https://www.tizen.org/content-license" target="_blank">Content License</a>.</p>
+</div>
+
+<script type="text/javascript">
+var _gaq = _gaq || [];
+_gaq.push(['_setAccount', 'UA-25976949-1']);
+_gaq.push(['_trackPageview']);
+(function() {
+var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
+ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
+var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
+})();
+</script>
+
+</body>
+</html>
projects / sdk / online-doc.git / commitdiff