From: taesub.kim Date: Mon, 21 Dec 2015 02:45:31 +0000 (+0900) Subject: [ACR-472] Modified comments of ACR #1 X-Git-Tag: submit/tizen/20160211.020959~3 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=29bc3d69e7d7d74602e3a24f71b3b537bc92f31c;p=platform%2Fcore%2Fapi%2Fvpn-service.git [ACR-472] Modified comments of ACR #1 Change-Id: I5382ed630a717e495b8e35e46b2b3ee241593af5 Signed-off-by: Taesub Kim --- diff --git a/doc/vpn_doc.h b/doc/vpn_doc.h index caa82e5..7978be8 100755 --- 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 + * \#include * * @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 + * \#include * * @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 --- a/include/vpn_service.h +++ b/include/vpn_service.h @@ -32,17 +32,18 @@ * **/ +/** + * @addtogroup CAPI_NETWORK_VPN_MODULE + * @{ + */ + #include -#include -#include -#include #include #include -#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__ */