[ACR-472] Modified comments of ACR #1

Change-Id: I5382ed630a717e495b8e35e46b2b3ee241593af5
Signed-off-by: Taesub Kim <taesub.kim@samsung.com>

diff --git a/doc/vpn_doc.h b/doc/vpn_doc.h
index caa82e5..7978be8 100755 (executable)
--- a/doc/vpn_doc.h
+++ b/doc/vpn_doc.h
@@ -24,15 +24,15 @@
 
 /**
  * @defgroup CAPI_NETWORK_VPN_MODULE VPN
- * @brief The VPN API provides functions for managing VPN.
+ * @brief The Virtual Private Network (VPN) API provides functions for managing VPN.
  * @ingroup CAPI_NETWORK_FRAMEWORK
  *
  * @section CAPI_NETWORK_VPN_MODULE_HEADER Required Header
- *   \#include <vpn_service_product.h>
+ *   \#include <vpn_service.h>
  *
  * @section CAPI_NETWORK_VPN_MODULE_OVERVIEW Overview
  * VPN allows your application to manage VPN features.
- * The VPN Service enables your application to init and deinit a VPN device(tun interface),
+ * The VPN Service enables your application to init and deinit a VPN device(TUN(namely netowrk TUNel) interface),
  * Routing management, DNS management and Firewall management.
  */
 
@@ -42,7 +42,7 @@
  * @ingroup CAPI_NETWORK_VPN_MODULE
  *
  * @section CAPI_NETWORK_VPN_SERVICE_MODULE_HEADER Required Header
- *   \#include <vpn_service_product.h>
+ *   \#include <vpn_service.h>
  *
  * @section CAPI_NETWORK_VPN_SERVICE_MODULE_OVERVEW Overview
  * The VPN Service functions for managing VPN.
@@ -53,7 +53,7 @@
  *     - Firewall management
  * @section CAPI_NETWORK_VPN_SERVICE_MODULE_FEATURE Related Features
  * This API is related with the following features:\n
- * - http://developer.samsung.com/tizen/feature/network.vpn\n
+ * - http://tizen.org/feature/network.vpn\n
  *
  * It is recommended to design feature related codes in your application for reliability.\n
  * You can check if a device supports the related features for this API by using @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, thereby controlling the procedure of your application.\n

diff --git a/include/vpn_service.h b/include/vpn_service.h
index 3d6f6c5..0487dcc 100755 (executable)
--- a/include/vpn_service.h
+++ b/include/vpn_service.h
@@ -32,17 +32,18 @@
   * </tr></table>
   **/
 
+/**
+ * @addtogroup CAPI_NETWORK_VPN_MODULE
+ * @{
+ */
+
 #include <tizen.h>
-#include <stdio.h>
-#include <stdlib.h>
-#include <string.h>
 #include <tizen_error.h>
 #include <tizen_vpn_error.h>
 
-#ifdef LOG_TAG
-#undef LOG_TAG
-#endif
-#define LOG_TAG "CAPI_VPNSVC"
+#ifdef __cplusplus
+extern "C" {
+#endif // __cplusplus
 
 #ifndef API
 #define API __attribute__ ((visibility("default")))
@@ -50,16 +51,19 @@
 
 /**
   * @brief IPv4 address string length (includes end null character)
+  * @since_tizen 3.0
   */
 #define VPNSVC_IP4_STRING_LEN 16
 
 /**
-  * @brief TUN interface name length (IFNAMSIZ)
+  * @brief TUN interface name length
+  * @since_tizen 3.0
   */
 #define VPNSVC_TUN_IF_NAME_LEN 16
 
 /**
   * @brief Session name string length (includes end null character)
+  * @since_tizen 3.0
   */
 #define VPNSVC_SESSION_STRING_LEN 32
 
@@ -79,7 +83,6 @@ typedef enum
     VPNSVC_ERROR_IO_ERROR = TIZEN_ERROR_IO_ERROR,                    /**< IO error */
     VPNSVC_ERROR_TIMEOUT = TIZEN_ERROR_TIMED_OUT,                    /**< Time out error or no answer */
     VPNSVC_ERROR_IPC_FAILED = TIZEN_ERROR_VPNSVC | 0x02,             /**< Failed to communicate with server */
-    VPNSVC_ERROR_LICENSE_FAILED = TIZEN_ERROR_VPNSVC | 0x03,         /**< Failed to verify license */
     VPNSVC_ERROR_NOT_SUPPORTED = TIZEN_ERROR_NOT_SUPPORTED           /**< Not Supported */
 } vpnsvc_error_e;
 
@@ -87,7 +90,6 @@ typedef enum
 /**
   * @brief   The structure containing the route information
   * @details This structure can be used for both vpnsvc_up() and vpnsvc_block_networks() functions.
-  *
   * @since_tizen 3.0
   * @see vpnsvc_up()
   * @see vpnsvc_block_networks()
@@ -99,7 +101,7 @@ struct vpnsvc_route {
 
 /**
   * @brief   The VPN tun interface handle
-  * @details This handle can be obtained by calling vpnsvc_init() and destroyed(NULL) by calling vpnsvc_deinit().
+  * @details This handle can be obtained by calling vpnsvc_init() and destroyed() by calling vpnsvc_deinit().
   * @since_tizen 3.0
   * @see vpnsvc_init()
   * @see vpnsvc_deinit()
@@ -108,24 +110,20 @@ typedef void* vpnsvc_tun_h;
 
 
 /**
- * @brief  Initializes TUN interface (/dev/net/tun)
+ * @brief  Initializes TUN interface
  * @detail You should call vpnsvc_get_tun_name() for checking the actual initialized TUN interface name. (In case of duplicated interface name)
- *
  * @since_tizen 3.0
  * @privlevel public
- * @privilege %http://tizen.org/privilege/vpnservicea
- * @remarks  The license needed if you want to use this VPN API
- *
+ * @privilege %http://tizen.org/privilege/vpnservice
+ * @remarks The @a  handle should be released using vpnsvc_deinit().
  * @param[in] tun_name The interface name
  * @param[out] handle  The VPN tun interface handle
- *
  * @return 0 on success. otherwise, a negative error value.
  * @retval #VPNSVC_ERROR_NONE                  Success
  * @retval #VPNSVC_ERROR_INVALID_PARAMETER     Invalid parameter
  * @retval #VPNSVC_ERROR_IO_ERROR              I/O Error (e.g. socket I/O error)
  * @retval #VPNSVC_ERROR_IPC_FAILED            Cannot connect to service daemon
  * @retval #VPNSVC_ERROR_PERMISSION_DENIED     Permission Denied
- * @retval #VPNSVC_ERROR_LICENSE_FAILED        Failed to verify license
  * @retval #VPNSVC_ERROR_NOT_SUPPORTED         Not Supported
  * @post Please call vpnsvc_deinit() if you want to de-initialize VPN tun interface.
  * @post Please call vpnsvc_get_tun_fd() if you want to know the fd of tun interface.
@@ -140,19 +138,13 @@ API int vpnsvc_init(const char* tun_name, vpnsvc_tun_h *handle);
 
 /**
  * @brief De-Initializes TUN interface
- *
  * @since_tizen 3.0
- * @remarks The license needed if you want to use this VPN API
- *
  * @param[in] handle The VPN tun interface handle
- *
  * @return 0 on success. otherwise, a negative error value.
  * @retval #VPNSVC_ERROR_NONE                  Success
  * @retval #VPNSVC_ERROR_INVALID_PARAMETER     Invalid parameter
  * @retval #VPNSVC_ERROR_IPC_FAILED            Cannot connect to service daemon
- * @retval #VPNSVC_ERROR_LICENSE_FAILED        Failed to verify license
  * @retval #VPNSVC_ERROR_NOT_SUPPORTED         Not Supported
- *
  * @pre Before calling this function, VPN tun interface should be initialized already.
  * @see vpnsvc_init()
  */
@@ -161,30 +153,22 @@ API int vpnsvc_deinit(vpnsvc_tun_h handle);
 /**
  * @brief    Prevents the underlying VPN traffic to be routed to the VPN itself
  * @details  The specific socket will be bound to the network interface using by this function.
- *
  * @since_tizen 3.0
- * @remarks The license needed if you want to use this VPN API
- *
  * @param[in] handle    The VPN tun interface handle
  * @param[in] socket_fd The opened socket file descriptor
  * @param[in] dev_name  The network interface name (i.e. eth0 or ppp0, not to confuse with tunXXX) through which the VPN is working
- *
  * @return 0 on success. otherwise, a negative error value.
  * @retval #VPNSVC_ERROR_NONE                  Success
  * @retval #VPNSVC_ERROR_INVALID_PARAMETER     Invalid parameter
  * @retval #VPNSVC_ERROR_IO_ERROR              I/O Error (e.g. socket I/O error)
  * @retval #VPNSVC_ERROR_IPC_FAILED            Cannot connect to service daemon
- * @retval #VPNSVC_ERROR_LICENSE_FAILED        Failed to verify license
  * @retval #VPNSVC_ERROR_NOT_SUPPORTED         Not Supported
  */
 API int vpnsvc_protect(vpnsvc_tun_h handle, int socket_fd, const char* dev_name);
 
 /**
  * @brief Sets-up TUN interface and brings it up. Installs specified routes/DNS servers/DNS suffix
- *
  * @since_tizen 3.0
- * @remarks The license needed if you want to use this VPN API
- *
  * @param[in] handle         The VPN tun interface handle
  * @param[in] local_ip       The local IP address
  * @param[in] remote_ip      The remote IP address
@@ -193,14 +177,11 @@ API int vpnsvc_protect(vpnsvc_tun_h handle, int socket_fd, const char* dev_name)
  * @param[in] dns_servers    The list of DNS server names - Optional
  * @param[in] nr_dns_servers The number of DNS server names - Optional
  * @param[in] dns_suffix     The DNS suffix - Optional
- *
  * @return 0 on success. otherwise, a negative error value.
  * @retval #VPNSVC_ERROR_NONE                  Success
  * @retval #VPNSVC_ERROR_INVALID_PARAMETER     Invalid parameter
  * @retval #VPNSVC_ERROR_IPC_FAILED            Cannot connect to service daemon
- * @retval #VPNSVC_ERROR_LICENSE_FAILED        Failed to verify license
  * @retval #VPNSVC_ERROR_NOT_SUPPORTED         Not Supported
- *
  * @pre The VPN tun interface should be initialized already.
  * @post If you want to set interface down, please call vpnsvc_down().
  * @see #vpnsvc_route
@@ -214,19 +195,13 @@ API int vpnsvc_up(vpnsvc_tun_h handle, const char* local_ip, const char* remote_
 
 /**
  * @brief Brings the TUN interface down and restores original DNS servers/domains
- *
  * @since_tizen 3.0
- * @remarks The license needed if you want to use this VPN API.
- *
  * @param[in] handle The VPN tun interface handle
- *
  * @return 0 on success. otherwise, a negative error value.
  * @retval #VPNSVC_ERROR_NONE                  Success
  * @retval #VPNSVC_ERROR_INVALID_PARAMETER     Invalid parameter
  * @retval #VPNSVC_ERROR_IPC_FAILED            Cannot connect to service daemon
- * @retval #VPNSVC_ERROR_LICENSE_FAILED        Failed to verify license
  * @retval #VPNSVC_ERROR_NOT_SUPPORTED         Not Supported
- *
  * @pre The VPN tun interface should be initialized already.
  * @post Please call vpnsvc_deinit() if you want to de-initialize VPN tun interface.
  * @see vpnsvc_up()
@@ -236,19 +211,15 @@ API int vpnsvc_down(vpnsvc_tun_h handle);
 
 /**
  * @brief Waits for the read event on TUN descriptor, but no more than the indicated timeout in milliseconds
- *
  * @since_tizen 3.0
- *
  * @param[in] handle      The VPN tun interface handle
  * @param[in] timeout_ms  The value of timeout (milliseconds)
- *
  * @return 0 on success. otherwise, a negative error value.
  * @retval #VPNSVC_ERROR_NONE                  Success
  * @retval #VPNSVC_ERROR_INVALID_PARAMETER     Invalid parameter
  * @retval #VPNSVC_ERROR_IO_ERROR              I/O Error (e.g. socket I/O error)
  * @retval #VPNSVC_ERROR_TIMEOUT               Timeout (no answer in timeout_ms)
  * @retval #VPNSVC_ERROR_NOT_SUPPORTED         Not Supported
- *
  * @pre The VPN interface should be initialized already.
  * @see vpnsvc_init()
  * @see vpnsvc_up()
@@ -257,18 +228,15 @@ API int vpnsvc_read(vpnsvc_tun_h handle, int timeout_ms);
 
 /**
  * @brief Writes the data supplied into the TUN interface
- *
  * @since_tizen 3.0
- *
  * @param[in] handle The VPN tun interface handle
  * @param[in] data   Data writing to tun interface
  * @param[in] size   The size of data
- *
  * @return On success, the number of bytes written is returned (zero indicates nothing was written). Otherwise, a negative error value.
+ * @retval #VPNSVC_ERROR_NONE                  Success
  * @retval #VPNSVC_ERROR_INVALID_PARAMETER     Invalid parameter
  * @retval #VPNSVC_ERROR_NOT_SUPPORTED         Not Supported
  * @retval In case of negative error, please refer to standard posix write API's error code.
- *
  * @pre The VPN interface should be initialized already.
  * @see vpnsvc_init()
  * @see vpnsvc_up()
@@ -277,22 +245,16 @@ API int vpnsvc_write(vpnsvc_tun_h handle, const char* data, size_t size);
 
 /**
  * @brief Blocks all traffics except specified allowing networks
- *
  * @since_tizen 3.0
- * @remarks The license needed if you want to use this VPN API
- *
  * @param[in] handle                  The VPN tun interface handle
  * @param[in] allow_routes_vpn        The list of allowing networks over VPN interface (Please see vpnsvc_route structure).
  * @param[in] nr_allow_routes_vpn     The number of allowing networks over VPN interface
  * @param[in] allow_routes_orig       The list of allowing networks over the original interface (Please see vpnsvc_route structure).
  * @param[in] nr_allow_routes_orig    The number of allowing networks over the original interface
- *
  * @return 0 on success. otherwise, a negative error value.
  * @retval #VPNSVC_ERROR_NONE                  Success
  * @retval #VPNSVC_ERROR_IPC_FAILED            Cannot connect to service daemon
- * @retval #VPNSVC_ERROR_LICENSE_FAILED        Failed to verify license
  * @retval #VPNSVC_ERROR_NOT_SUPPORTED         Not Supported
- *
  * @post Please call vpnsvc_unblock_networks() if you want to allow all traffics.
  * @see vpnsvc_unblock_networks()
  */
@@ -304,81 +266,63 @@ API int vpnsvc_block_networks(vpnsvc_tun_h handle,
 
 /**
  * @brief Removes any restrictions imposed by vpnsvc_block_networks()
- *
  * @since_tizen 3.0
- * @remarks The license needed if you want to use this VPN API
- *
  * @param[in] handle The VPN tun interface handle
- *
  * @return 0 on success. otherwise, a negative error value.
  * @retval #VPNSVC_ERROR_NONE                  Success
  * @retval #VPNSVC_ERROR_IPC_FAILED            Cannot connect to service daemon
- * @retval #VPNSVC_ERROR_LICENSE_FAILED        Failed to verify license
  * @retval #VPNSVC_ERROR_NOT_SUPPORTED         Not Supported
- *
  */
 API int vpnsvc_unblock_networks(vpnsvc_tun_h handle);
 
 /**
  * @brief Gets the fd of the VPN tun interface
- *
  * @since_tizen 3.0
- *
  * @param[in] handle The VPN tun interface handle
- *
  * @return The fd value of VPN tun interface. Otherwise, a negative error value.
+ * @retval #VPNSVC_ERROR_NONE                  Success
  * @retval #VPNSVC_ERROR_INVALID_PARAMETER     Invalid parameter
  * @retval #VPNSVC_ERROR_NOT_SUPPORTED         Not Supported
  */
 API int vpnsvc_get_tun_fd(vpnsvc_tun_h handle);
 
 /**
- * @brief Gets the index of VPN tun interface (if.if_index)
- *
+ * @brief Gets the index of VPN tun interface
  * @since_tizen 3.0
- *
  * @param[in] handle The VPN tun interface handle
- *
  * @return The index of the VPN tun interface. otherwise, a negative error value.
+ * @retval #VPNSVC_ERROR_NONE                  Success
  * @retval #VPNSVC_ERROR_INVALID_PARAMETER     Invalid parameter
  * @retval #VPNSVC_ERROR_NOT_SUPPORTED         Not Supported
- *
  * @pre Before calling this function, VPN tun interface should be initialized already.
  * @see vpnsvc_init()
  */
 API int vpnsvc_get_tun_index(vpnsvc_tun_h handle);
 
 /**
- * @brief Gets the name of VPN tun interface (if.if_name)
- *
+ * @brief Gets the name of VPN tun interface
  * @since_tizen 3.0
- *
+ * @remarks The @a tun_name should be released using free()
  * @param[in] handle    The VPN tun interface handle
  * @param[out] tun_name The name of VPN tun interface name
- *
  * @return 0 on success. Otherwise, a negative error value.
  * @retval #VPNSVC_ERROR_NONE                  Success
  * @retval #VPNSVC_ERROR_INVALID_PARAMETER     Invalid parameter
  * @retval #VPNSVC_ERROR_NOT_SUPPORTED         Not Supported
- *
  * @pre Before calling this function, VPN tun interface should be initialized already.
  * @see vpnsvc_init()
  */
 API int vpnsvc_get_tun_name(vpnsvc_tun_h handle, char* tun_name);
 
 /**
- * @brief Sets the MTU of the VPN tun interface (if.if_name)
- *
+ * @brief Sets the MTU of the VPN tun interface
  * @since_tizen 3.0
- *
  * @param[in] handle The VPN tun interface handle
  * @param[in] mtu    The MTU (Maximum Transmission Unit) value to be set for VPN tun interface. Default MTU size is 1500.
- *
  * @return 0 on success. Otherwise, a negative error value.
  * @retval #VPNSVC_ERROR_NONE                  Success
  * @retval #VPNSVC_ERROR_INVALID_PARAMETER     Invalid parameter
  * @retval #VPNSVC_ERROR_NOT_SUPPORTED         Not Supported
- *
  * @pre Before calling this function, VPN tun interface should be initialized already.
  * @see vpnsvc_init()
  */
@@ -386,18 +330,14 @@ API int vpnsvc_set_mtu(vpnsvc_tun_h handle, int mtu);
 
 /**
  * @brief Sets blocking mode of the file descriptor of VPN tun interface
- *
  * @since_tizen 3.0
- *
  * @param[in] handle    The VPN tun interface handle
  * @param[in] blocking  The blocking mode flag; True = BLOCKING, False = NON_BLOCKING
- *
  * @return 0 on success. Otherwise, a negative error value.
  * @retval #VPNSVC_ERROR_NONE                  Success
  * @retval #VPNSVC_ERROR_INVALID_PARAMETER     Invalid parameter
  * @retval #VPNSVC_ERROR_IO_ERROR              Failed to set the blocking flags
  * @retval #VPNSVC_ERROR_NOT_SUPPORTED         Not Supported
- *
  * @pre Before calling this function, VPN tun interface should be initialized already.
  * @see vpnsvc_init()
  */
@@ -405,38 +345,39 @@ API int vpnsvc_set_blocking(vpnsvc_tun_h handle, bool blocking);
 
 /**
  * @brief Sets the session name for the VPN
- *
  * @since_tizen 3.0
- *
+ * @remarks a tun_name should be released using free()
  * @param[in] handle       The VPN tun interface handle
  * @param[in] session      The Session Name
- *
  * @return 0 on success. Otherwise, a negative error value.
  * @retval #VPNSVC_ERROR_NONE                  Success
  * @retval #VPNSVC_ERROR_INVALID_PARAMETER     Invalid parameter
  * @retval #VPNSVC_ERROR_NOT_SUPPORTED         Not Supported
- *
  * @pre Before calling this function, VPN tun interface should be initialized already.
  * @see vpnsvc_init()
  */
-API int vpnsvc_set_session(vpnsvc_tun_h handle, const char* session);
+API int vpnsvc_set_session(vpnsvc_tun_h handle, const char* session_name);
 
 /**
  * @brief Gets the session name for the VPN
- *
  * @since_tizen 3.0
- *
  * @param[in] handle   The VPN tun interface handle
  * @param[out] session The Session Name returned
- *
  * @return 0 on success. Otherwise, a negative error value.
  * @retval #VPNSVC_ERROR_NONE                  Success
  * @retval #VPNSVC_ERROR_INVALID_PARAMETER     Invalid parameter
  * @retval #VPNSVC_ERROR_NOT_SUPPORTED         Not Supported
- *
  * @pre Before calling this function, VPN tun interface should be initialized already.
  * @see vpnsvc_init()
  */
-API int vpnsvc_get_session(vpnsvc_tun_h handle, char* session);
+API int vpnsvc_get_session(vpnsvc_tun_h handle, char* session_name);
+
+#ifdef __cplusplus
+}
+#endif // __cplusplus
+
+/**
+* @}
+*/
 
 #endif /* __TIZEN_CAPI_VPN_SERVICE_H__ */