From 48cef2a6eb6a912a2cdc123d19398e83bb37dc2f Mon Sep 17 00:00:00 2001
From: Abhishek Sansanwal <abhishek.s94@samsung.com>
Date: Tue, 5 Sep 2017 16:25:31 +0530
Subject: [PATCH] Updated VPN docs to reflect current CAPI status

PS4: Reviewed

Signed-off-by: Abhishek Sansanwal <abhishek.s94@samsung.com>
Change-Id: I040357101cc57d694f00e24066eb40d59f6a60c8
---
 .../html/native/connectivity/vpn_n.htm             | 173 +++++++++++----------
 1 file changed, 95 insertions(+), 78 deletions(-)

diff --git a/org.tizen.guides/html/native/connectivity/vpn_n.htm b/org.tizen.guides/html/native/connectivity/vpn_n.htm
index 1a7b7d4..bfb866d 100644
--- a/org.tizen.guides/html/native/connectivity/vpn_n.htm
+++ b/org.tizen.guides/html/native/connectivity/vpn_n.htm
@@ -30,7 +30,7 @@
             <li><a href="#prerequisites">Prerequisites</a></li>
             <li><a href="#get_param">Getting Interface Parameters</a></li>
             <li><a href="#set_param">Setting Interface Parameters</a></li>
-            <li><a href="#config">Configuring the Interface</a></li>
+            <li><a href="#config">Configuring the Interface and Connecting to the Service</a></li>
             <li><a href="#block">Blocking and Unblocking Networks</a></li>
             <li><a href="#read">Reading and Writing Data</a></li>
 		</ul>
@@ -63,24 +63,12 @@
 	<th>Description</th>
 </tr>
 <tr>
-	<td><code>_MAX_FILE_PATH_LEN</code></td>
-	<td>Maximum file path length</td>
-</tr>
-<tr>
-	<td><code>_USER_SETTING_DEFAULT_MTU</code></td>
-	<td>Default MTU</td>
-</tr>
-<tr>
-	<td><code>_USER_SETTING_DEFAULT_SESSION</code></td>
-	<td>Default session name</td>
-</tr>
-<tr>
 	<td><code>VPNSVC_IP4_STRING_LEN</code></td>
 	<td>IPv4 address string length</td>
 </tr>
 <tr>
-	<td><code>VPNSVC_TUN_IF_NAME_LEN</code></td>
-	<td>Tunnel interface name length</td>
+	<td><code>VPNSVC_VPN_IFACE_NAME_LEN</code></td>
+	<td>VPN interface name length</td>
 </tr>
 <tr>
 	<td><code>VPNSVC_SESSION_STRING_LEN</code></td>
@@ -90,10 +78,11 @@
 </table>
 </li>
 <li>VPN profile
-<p>You can map the VPN profile and get details about the VPN service using the <a href="../../../../org.tizen.native.mobile.apireference/group__CAPI__NETWORK__VPN__SERVICE__MODULE.html#gaef3a3f46336ee7e8c43dd16144b22ac5">vpnsvc_h</a> handle.</p>
+<p>You can map the VPN profile and get details about the VPN service by using the <a href="../../../../org.tizen.native.mobile.apireference/group__CAPI__NETWORK__VPN__SERVICE__MODULE.html#gaef3a3f46336ee7e8c43dd16144b22ac5">vpnsvc_h</a> handle.</p>
 <p>The VPN profile provides different functions for routing management, DNS management, and firewall management:</p>
 <ul>
-	<li>The <code>vpnsvc_up()</code> function is used to <a href="#config">set up the tunnel interface</a> by setting the default route and DNS parameters.</li>
+	<li>The <code>vpnsvc_init()</code> function is used to a initialize the VPN interface and get the handle.</li>
+	<li>The <code>vpnsvc_h</code> handle is used to <a href="#config">configure the tunnel interface</a> before using the <a href="../app_management/common_appcontrol_n.htm#vpnservice">VPN application control</a> to ask the user permission to connect to the VPN service.</li>
 	<li>The <code>vpnsvc_block_networks()</code> function is used to <a href="#block">block network traffic</a> by creating a route parameter for allowed VPN and original interface routes.</li>
 </ul>
 </li>
@@ -110,8 +99,8 @@
 <li>Privilege:
 <p>The application needs the partner level privilege for accessing the VPN service daemon.</p>
 </li>
-<li>VPN license:
-<p>The VPN configurations, such as DNS, routing, and firewall (iptables), need an admin capability. The VPN service daemon checks the application's VPN license to verify that the client application has the admin capability.</p>
+<li>Application control:
+<p>Connecting or disconnecting from a VPN network requires user permission, which is requested by invoking the VPN application control.</p>
 </li>
 </ul>
 
@@ -191,33 +180,33 @@ handle = NULL;
 
 <p>To get the interface parameters after successfully initializing the VPN service:</p>
 <ul>
-<li>Get the tunnel file descriptor using the <code>vpnsvc_get_tun_fd()</code> function:
+<li>Get the interface file descriptor using the <code>vpnsvc_get_iface_fd()</code> function:
 <pre class="prettyprint">
 int int_value;
 
-if (vpnsvc_get_tun_fd(handle, &amp;int_value) == VPNSVC_ERROR_NONE)
-    printf("tun_fd: %d\n", int_value);
+if (vpnsvc_get_iface_fd(handle, &amp;int_value) == VPNSVC_ERROR_NONE)
+    printf("iface_fd: %d\n", int_value);
 </pre>
 </li>
-<li>Get the tunnel index using the <code>vpnsvc_get_tun_index()</code> function:
+<li>Get the interface index using the <code>vpnsvc_get_iface_index()</code> function:
 <pre class="prettyprint">
 int int_value;
 
-if (vpnsvc_get_tun_index(handle, &amp;int_value) == VPNSVC_ERROR_NONE)
-    printf("tun_index: %d\n", int_value);
+if (vpnsvc_get_iface_index(handle, &amp;int_value) == VPNSVC_ERROR_NONE)
+    printf("iface_index: %d\n", int_value);
 </pre>
 </li>
-<li>Get the tunnel name using the <code>vpnsvc_get_tun_name()</code> function:
+<li>Get the interface name using the <code>vpnsvc_get_iface_name()</code> function:
 <pre class="prettyprint">
-char* result_name = NULL;
+char *result_name = NULL;
 int ret = VPNSVC_ERROR_NONE;
 
-ret = vpnsvc_get_tun_name(handle, &amp;result_name);
+ret = vpnsvc_get_iface_name(handle, &amp;result_name);
 if (ret == VPNSVC_ERROR_NONE)
-    printf("tun_name: %s\n", result_name);
+    printf("iface_name: %s\n", result_name);
 </pre>
 </li>
-<li>Get the session for the tunnel interface using the <code>vpnsvc_get_session()</code> function:
+<li>Get the session for the interface using the <code>vpnsvc_get_session()</code> function:
 <pre class="prettyprint">
 int ret = VPNSVC_ERROR_NONE;
 char *get_session = NULL;
@@ -233,7 +222,7 @@ printf("vpnsvc_set_session succeeded!\n");
 
 <p>To set the interface parameters:</p>
 <ul>
-<li>Set the MTU configuration for the tunnel interface using the <code>vpnsvc_set_mtu()</code> function. The MTU value is used when the user brings up the VPN interface using the VPN UP API.
+<li>Set the MTU configuration for the tunnel interface using the <code>vpnsvc_set_mtu()</code> function, then update the value using the <code>vpnsvc_update_settings()</code> function:
 <pre class="prettyprint">
 int ret;
 
@@ -242,6 +231,13 @@ if (ret != VPNSVC_ERROR_NONE)
     printf("vpnsvc_set_mtu failed!\n");
 else
     printf("vpnsvc_set_mtu succeeded!\n");
+
+ret = vpnsvc_update_settings(handle);
+
+if (ret != VPNSVC_ERROR_NONE)
+    printf("vpnsvc_update_settings failed!\n");
+else
+    printf("vpnsvc_update_settings succeeded!\n");
 </pre>
 </li>
 <li>Set the session name for the tunnel interface using the <code>vpnsvc_set_session()</code> function:
@@ -256,10 +252,52 @@ if (ret != VPNSVC_ERROR_NONE)
 </li>
 </ul>
 
-<h2 id="config" name="config">Configuring the Interface</h2>
+<h2 id="config" name="config">Configuring the Interface and Connecting to the Service</h2>
 
-<p>To configure the interface:</p>
+<p>To configure the interface and connect to the VPN service through an application control:</p>
 <ol>
+<li>Define a function to launch the <a href="../app_management/common_appcontrol_n.htm#vpnservice">VPN application control</a> and a callback to handle the results:
+<pre class="prettyprint">
+#include &lt;app_control.h&gt;
+
+void
+launch_vpn_service_appcontrol(void)
+{
+    app_control_h service;
+    app_control_create(&amp;service);
+
+    app_control_set_operation(service, APP_CONTROL_OPERATION_SETTING_VPN);
+    app_control_add_extra_data(service, APP_CONTROL_DATA_TYPE, "up");
+    app_control_add_extra_data(service, APP_CONTROL_DATA_NAME, "tizen");
+    app_control_set_launch_mode(service, APP_CONTROL_LAUNCH_MODE_GROUP);
+
+    app_control_send_launch_request(service, vpn_appcontrol_result_cb, NULL);
+    app_control_destroy(service);
+}
+
+static void
+vpn_appcontrol_result_cb(app_control_h request, app_control_h reply, app_control_result_e result, void *user_data)
+{
+    char *result_txt;
+
+    switch (result) {
+    case APP_CONTROL_RESULT_APP_STARTED:
+    case APP_CONTROL_RESULT_SUCCEEDED:
+      dlog_print(DLOG_INFO, LOG_TAG, "Success!");
+      break;
+    case APP_CONTROL_RESULT_FAILED:
+      dlog_print(DLOG_INFO, LOG_TAG, "Failed!");
+      break;
+    case APP_CONTROL_RESULT_CANCELED:
+      dlog_print(DLOG_INFO, LOG_TAG, "Canceled!");
+      break;
+    }
+
+    app_control_get_extra_data(reply, APP_CONTROL_DATA_TEXT, &amp;result_txt);
+    dlog_print(DLOG_INFO, LOG_TAG, "Result: %s", result_txt);
+}
+</pre>
+</li>
 <li>Protect the underlying VPN traffic to be routed to the VPN itself by binding the socket to the underlying network interface, such as <code>wlan0</code>:
 <pre class="prettyprint">
 int sock;
@@ -272,19 +310,11 @@ else
     printf("vpnsvc_protect succeeded!\n");
 </pre>
 </li>
-<li>Set up the tunnel interface.
-<p>The <code>vpnsvc_up()</code> function configures the VPN tunnel interface based on the configured parameters passed by the client application.</p>
-<p>To change the MTU parameter of the configured interface, the client application must invoke the <code>vpnsvc_set_mtu()</code> function that is used to set the MTU value. The client application must invoke the function before the <code>vpnsvc_up()</code> function call.</p>
+<li>Set up the connection information, which includes the local IP address and the remote IP address:
 <pre class="prettyprint">
 int ret;
 char local[VPNSVC_IP4_STRING_LEN] = {'\0',};
 char remote[VPNSVC_IP4_STRING_LEN] = {'\0',};
-char *routes[2];
-int prefix[2];
-int nr_routes = 2;
-const char *dns_server[2];
-int nr_dns = 2;
-char dns_suffix[100] = "tizen.org";
 
 if (!handle) {
     printf("invalid handle\n");
@@ -295,49 +325,36 @@ if (!handle) {
 strncpy(local, "192.168.0.82", VPNSVC_IP4_STRING_LEN);
 strncpy(remote, "192.168.0.1", VPNSVC_IP4_STRING_LEN);
 
-routes[0] = malloc(sizeof(char) * VPNSVC_IP4_STRING_LEN);
-routes[1] = malloc(sizeof(char) * VPNSVC_IP4_STRING_LEN);
+/* Local IP address */
+ret = vpnsvc_set_local_ip_address(handle, local);
 
-memset(routes[0], 0, sizeof(char) * VPNSVC_IP4_STRING_LEN);
-memset(routes[1], 0, sizeof(char) * VPNSVC_IP4_STRING_LEN);
-
-strncpy(routes[0], "192.168.0.10", VPNSVC_IP4_STRING_LEN);
-prefix[0] = 32;
-
-strncpy(routes[1], "192.168.0.11", VPNSVC_IP4_STRING_LEN);
-prefix[1] = 32;
-
-char *dns1 = "1.1.1.1";
-char *dns2 = "2.2.2.2";
-
-dns_server[0] = dns1;
-dns_server[1] = dns2;
+if (ret != VPNSVC_ERROR_NONE)
+    printf("vpnsvc_set_local_ip_address failed!\n");
+else
+    printf("vpnsvc_set_local_ip_address succeeded!\n");
 
-ret = vpnsvc_up(handle, local, remote, routes, prefix, nr_routes,
-                dns_server, nr_dns, dns_suffix);
+/* Remote IP address */
+ret = vpnsvc_set_remote_ip_address(handle, remote);
 
 if (ret != VPNSVC_ERROR_NONE)
-    printf("vpnsvc_up failed!\n");
+    printf("vpnsvc_set_remote_ip_address failed!\n");
 else
-    printf("vpnsvc_up succeeded!\n");
+    printf("vpnsvc_set_remote_ip_address succeeded!\n");
 </pre>
-</li>
-<li>Set down the tunnel interface, and remove it using the <code>vpnsvc_down()</code> function:
+	</li>
+	<li>Update the <a href="../../../../org.tizen.native.mobile.apireference/group__CAPI__NETWORK__VPN__SERVICE__MODULE.html#gaef3a3f46336ee7e8c43dd16144b22ac5">vpnsvc_h</a> handle with the connection information by calling the <code>vpnsvc_update_settings()</code> function:
 <pre class="prettyprint">
-int ret;
-
-if (!handle) {
-    printf("invalid handle\n");
-
-    return -1;
-}
-
-ret = vpnsvc_down(handle);
+ret = vpnsvc_update_settings(handle);
 
 if (ret != VPNSVC_ERROR_NONE)
-    printf("vpnsvc_down failed!\n");
+    printf("vpnsvc_update_settings failed!\n");
 else
-    printf("vpnsvc_down succeeded!\n");
+    printf("vpnsvc_update_settings succeeded!\n");
+</pre>
+</li>
+<li>Launch the application control to allow the user to connect to the VPN service:
+<pre class="prettyprint">
+launch_vpn_service_appcontrol();
 </pre>
 </li>
 </ol>
@@ -348,10 +365,10 @@ else
 <ul>
 <li>Block all traffic, except specified allowed networks, and send the specified UP addresses to a specified interface:
 <pre class="prettyprint">
-char* block_nets[2];
+char *block_nets[2];
 int block_prefix[2];
 int block_nr_nets = 2;
-char* allow_nets[2];
+char *allow_nets[2];
 int allow_prefix[2];
 int allow_nr_nets = 2;
 int ret;
@@ -463,4 +480,4 @@ var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga
 </script>
 
 </body>
-</html>
\ No newline at end of file
+</html>
-- 
2.7.4