modified: app_controls_n.htm

PS2: [LB] Reviewed

Change-Id: I158bb428b78ebb5b966d451bd1ff8b068c796e22

diff --git a/org.tizen.guides/html/native/app_management/app_controls_n.htm b/org.tizen.guides/html/native/app_management/app_controls_n.htm
index a3ad23c..85e13a8 100644 (file)
--- a/org.tizen.guides/html/native/app_management/app_controls_n.htm
+++ b/org.tizen.guides/html/native/app_management/app_controls_n.htm
@@ -165,7 +165,7 @@ app_control_destroy(app_control);
 
 <h3 id="implicit" name="implicit">Implicit Launch Request</h3>
 
-<p>The following examples shows how to create an implicit launch request:</p>
+<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:
 
@@ -590,10 +590,10 @@ main(int argc, char *argv[])
 &nbsp;&nbsp;&nbsp;&nbsp;ui_app_lifecycle_callback_s event_callback;
 
 &nbsp;&nbsp;&nbsp;&nbsp;event_callback.create = app_create;
-&nbsp;&nbsp;&nbsp;&nbsp;event_callback.terminate = app_terminate;
+&nbsp;&nbsp;&nbsp;&nbsp;event_callback.app_control = app_control;
 &nbsp;&nbsp;&nbsp;&nbsp;event_callback.pause = app_pause;
 &nbsp;&nbsp;&nbsp;&nbsp;event_callback.resume = app_resume;
-&nbsp;&nbsp;&nbsp;&nbsp;event_callback.app_control = app_control;
+&nbsp;&nbsp;&nbsp;&nbsp;event_callback.terminate = app_terminate;
 
 &nbsp;&nbsp;&nbsp;&nbsp;memset(&amp;ad, 0x0, sizeof(struct appdata));
 
@@ -608,7 +608,9 @@ main(int argc, char *argv[])
 <p>If the <span style="font-family: Courier New,Courier,monospace">app_create_cb()</span> callback function returns <span style="font-family: Courier New,Courier,monospace">false</span>, the application moves to the terminated state. If it returns <span style="font-family: Courier New,Courier,monospace">true</span>, the application enters the main loop.</p>
 </li>
 <li>Just after the application enters the main loop, the application framework calls the application&#39;s <span style="font-family: Courier New,Courier,monospace">app_control_cb()</span> callback.
+
 <p>The callback is passed to the <span style="font-family: Courier New,Courier,monospace">app_control</span> handle 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. The application is always responsible for checking the content of the <span style="font-family: Courier New,Courier,monospace">app_control</span> handle and responding appropriately. The content of the <span style="font-family: Courier New,Courier,monospace">app_control</span> handle 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 <span style="font-family: Courier New,Courier,monospace">app_control_reply_to_launch_request()</span> function.</p>
 
 <pre class="prettyprint">
@@ -622,7 +624,7 @@ app_control(app_control_h app_control, void *user_data)
 &nbsp;&nbsp;&nbsp;&nbsp;app_control_h reply;
 &nbsp;&nbsp;&nbsp;&nbsp;char *app_id;
 
-&nbsp;&nbsp;&nbsp;&nbsp;app_control_get_operation(app_control, operation);
+&nbsp;&nbsp;&nbsp;&nbsp;app_control_get_operation(app_control, &amp;operation);
 
 &nbsp;&nbsp;&nbsp;&nbsp;if (!strcmp(operation, APP_CONTROL_OPERATION_VIEW)) {
 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;app_control_get_uri(app_control, &amp;uri);
@@ -633,21 +635,21 @@ app_control(app_control_h app_control, void *user_data)
 &nbsp;&nbsp;&nbsp;&nbsp;}
 
 &nbsp;&nbsp;&nbsp;&nbsp;if (!strcmp(operation, APP_CONTROL_OPERATION_CREATE_CONTENT)) {
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;app_control_get_mime(app_control, &amp;mime);
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;app_control_get_mime(app_control, &amp;mime_type);
 
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;if (!strcmp(mime, &quot;text/plain&quot;)) {
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;if (!strcmp(mime_type, &quot;text/plain&quot;)) {
 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;app_control_create(&amp;reply);
 
 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;app_get_app_id(&amp;app_id);
+
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* Set the value of APP_CONTROL_DATA_SELECTED to give to caller */
 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;app_control_add_extra_data(reply, APP_CONTROL_DATA_SELECTED, app_id);
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* Reply to caller */
 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;app_control_reply_to_launch_request(reply, app_control, APP_CONTROL_RESULT_SUCCEEDED);
 
 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;app_control_destroy(reply);
 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;}
 &nbsp;&nbsp;&nbsp;&nbsp;}
-
-&nbsp;&nbsp;&nbsp;&nbsp;if (ad-&gt;win)
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;elm_win_activate(ad-&gt;win);
 }
 </pre>
 
@@ -656,12 +658,35 @@ app_control(app_control_h app_control, void *user_data)
 
 <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). The results are delivered in the <span style="font-family: Courier New,Courier,monospace">app_control</span> handle with extra data. For some cases, the App Control API provides predefined extra data keys.</p>
+<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 by setting the <span style="font-family: Courier New,Courier,monospace">app_control_result</span> callback to get the launch result:</p>
+
+<pre class="prettyprint">
+#include &lt;app.h&gt;
+#include &lt;dlog.h&gt;
+
+#define TAG &quot;MY_TAG&quot;
+
+app_control_h app_control;
+
+app_control_create(&amp;app_control);
 
-<p>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>
+app_control_set_operation(app_control, APP_CONTROL_OPERATION_CREATE_CONTENT);
+app_control_set_mime(app_control, &quot;text/plain&quot;);
+
+/* Set callback function, app_control_result, to get the launch result */
+if (app_control_send_launch_request(app_control, app_control_result, NULL) == APP_CONTROL_ERROR_NONE)
+&nbsp;&nbsp;&nbsp;&nbsp;dlog_print(DLOG_INFO, TAG, &quot;Succeeded: the application is launched.&quot;);
+else
+&nbsp;&nbsp;&nbsp;&nbsp;dlog_print(DLOG_ERROR, TAG, &quot;Failed to launch an application.&quot;);
+
+app_control_destroy(app_control);
+</pre>
 
-<p>The following example shows how you can retrieve the results of the launch request and requested operation by implementing an application control result callback:</p>
+<p>The results are delivered in the <span style="font-family: Courier New,Courier,monospace">app_control</span> handle with extra data. For some cases, the App Control API 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 <span style="font-family: Courier New,Courier,monospace">app_control_result</span> callback:</p>
 <pre class="prettyprint">
 #include &lt;app.h&gt;
 #include &lt;dlog.h&gt;
@@ -675,6 +700,7 @@ app_control_result(app_control_h request, app_control_h reply, app_control_resul
 &nbsp;&nbsp;&nbsp;&nbsp;char *value;
 
 &nbsp;&nbsp;&nbsp;&nbsp;if (result == APP_CONTROL_RESULT_SUCCEEDED) {
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* Get the value of APP_CONTROL_DATA_SELECTED sent by callee */
 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;if (app_control_get_extra_data(reply, APP_CONTROL_DATA_SELECTED, &amp;value) == APP_CONTROL_ERROR_NONE)
 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;dlog_print(DLOG_INFO, TAG, &quot;[app_control_result_cb] Succeeded: value(%s)&quot;, value);
 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;else
@@ -739,7 +765,7 @@ app_control_result(app_control_h request, app_control_h reply, app_control_resul
        <p>You can set the application launch mode <a href="../../../../org.tizen.studio/html/native_tools/manifest_text_editor_n.htm#launch_mode">in the manifest file</a> using the <span style="font-family: Courier New,Courier,monospace">launch_mode</span> attribute of the <span style="font-family: Courier New,Courier,monospace">&lt;ui-application&gt;</span> element. If the launch mode is set to <span style="font-family: Courier New,Courier,monospace">caller</span>, the application that calls the app control can define the launch mode for the called application using the <span style="font-family: Courier New,Courier,monospace">app_control_set_launch_mode()</span> function. However, if the called application has set its launch mode in its manifest file to <span style="font-family: Courier New,Courier,monospace">single</span>, that setting overrides the caller application&#39;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 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.</p>
+       <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 class="figure">Figure: Group behavior</p>