Add error description to doxygen

[platform/core/api/connection.git] / include / net_connection.h

diff --git a/include/net_connection.h b/include/net_connection.h
index f506edf..2e0c5a3 100755 (executable)
--- a/include/net_connection.h
+++ b/include/net_connection.h
@@ -129,8 +129,16 @@ typedef enum {
  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 */
 typedef enum {
-       CONNECTION_RESET_DEFAULT_PROFILE = 0,  /**< Initialized with the default profile defined by csc */
-       CONNECTION_RESET_CLEAR_PROFILE = 1,    /**< Remove all profiles */
+       /**
+        * Initialized with the default profile defined by csc
+        */
+       CONNECTION_RESET_DEFAULT_PROFILE = 0,
+
+       /**
+        * Remove all profiles
+        */
+       CONNECTION_RESET_CLEAR_PROFILE = 1,
+
 } connection_reset_option_e;
 
 
@@ -155,12 +163,12 @@ typedef enum {
        CONNECTION_ERROR_NONE = TIZEN_ERROR_NONE,
 
        /**
-        *Invalid parameter
+        * Invalid parameter
         */
        CONNECTION_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER,
 
        /**
-        *   Out of memory error
+        * Out of memory error
         */
        CONNECTION_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY,
 
@@ -170,12 +178,12 @@ typedef enum {
        CONNECTION_ERROR_INVALID_OPERATION = TIZEN_ERROR_INVALID_OPERATION,
 
        /**
-        * Address family         Not supported
+        * Address family not supported
         */
        CONNECTION_ERROR_ADDRESS_FAMILY_NOT_SUPPORTED = TIZEN_ERROR_ADDRESS_FAMILY_NOT_SUPPORTED,
 
        /**
-        *      Operation failed
+        * Operation failed
         */
        CONNECTION_ERROR_OPERATION_FAILED = TIZEN_ERROR_CONNECTION|0x0401,
 
@@ -220,12 +228,12 @@ typedef enum {
        CONNECTION_ERROR_NO_REPLY = TIZEN_ERROR_CONNECTION|0x0408,
 
        /**
-        *     Permission denied
+        * Permission denied
         */
        CONNECTION_ERROR_PERMISSION_DENIED = TIZEN_ERROR_PERMISSION_DENIED,
 
        /**
-        *         Not supported
+        * Not supported
         */
        CONNECTION_ERROR_NOT_SUPPORTED = TIZEN_ERROR_NOT_SUPPORTED
 
@@ -277,6 +285,7 @@ typedef enum {
  * @retval #CONNECTION_ERROR_NONE                  Successful
  * @retval #CONNECTION_ERROR_INVALID_PARAMETER     Invalid parameter
  * @retval #CONNECTION_ERROR_OUT_OF_MEMORY         Out of memory
+ * @retval #CONNECTION_ERROR_PERMISSION_DENIED     Permission denied
  * @see connection_destroy()
  */
 int connection_create(connection_h* connection);
@@ -299,7 +308,7 @@ int connection_destroy(connection_h connection);
  * @brief Called when the type of a connection is changed.
  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  * @param[in] type              The type of the current network connection
- * @param[in] user_data The user data passed from the callback registration function
+ * @param[in] user_data         The user data passed from the callback registration function
  * @see connection_set_type_changed_cb()
  * @see connection_unset_type_changed_cb()
  */
@@ -311,7 +320,7 @@ typedef void(*connection_type_changed_cb)(connection_type_e type, void* user_dat
  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  * @param[in] ipv4_address      The IP address for IPv4
  * @param[in] ipv6_address      The IP address for IPv6
- * @param[in] user_data The user data passed from the callback registration function
+ * @param[in] user_data         The user data passed from the callback registration function
  * @see connection_set_ip_address_changed_cb()
  * @see connection_unset_ip_address_changed_cb()
  * @see connection_set_proxy_address_changed_cb()
@@ -337,7 +346,8 @@ typedef void(*connection_set_default_cb)(connection_error_e result, void* user_d
  *            @a ipv6_address will be freed automatically after the execution of this callback.
  * @param[in]  ipv6_address     The IPv6 address
  * @param[in]  user_data        The user data passed from the foreach function
- * @return  @c true to continue with the next iteration of the loop, \n @c false to break out of the loop
+ * @return  @c true to continue with the next iteration of the loop, \n
+ *          @c false to break out of the loop
  * @pre  connection_foreach_ipv6_addresses() will invoke this callback.
  * @see  connection_foreach_ipv6_addresses()
  */
@@ -363,7 +373,7 @@ int connection_get_type(connection_h connection, connection_type_e* type);
  * @remarks You must release @a ip_address using free().
  * @param[in] connection        The connection handle
  * @param[in] address_family    The address family
- * @param[out] ip_address The pointer to the IP address string
+ * @param[out] ip_address       The pointer to the IP address string
  * @return @c 0 on success,
  *         otherwise a negative error value
  * @retval #CONNECTION_ERROR_NONE                           Successful
@@ -381,7 +391,7 @@ int connection_get_ip_address(connection_h connection,
  * @remarks You must release @a proxy using free().
  * @param[in] connection        The connection handle
  * @param[in] address_family    The address family
- * @param[out] proxy The proxy address
+ * @param[out] proxy            The proxy address
  * @return @c 0 on success,
  *         otherwise a negative error value
  * @retval #CONNECTION_ERROR_NONE                           Successful
@@ -443,7 +453,7 @@ int connection_get_cellular_state(connection_h connection, connection_cellular_s
  * @retval #CONNECTION_ERROR_INVALID_PARAMETER     Invalid parameter
  * @retval #CONNECTION_ERROR_OPERATION_FAILED      Operation failed
  * @retval #CONNECTION_ERROR_PERMISSION_DENIED     Permission denied
- * @retval #CONNECTION_ERROR_NOT_SUPPORTED            Not supported
+ * @retval #CONNECTION_ERROR_NOT_SUPPORTED             Not supported
  */
 int connection_get_wifi_state(connection_h connection, connection_wifi_state_e* state);
 
@@ -488,7 +498,7 @@ int connection_get_ethernet_cable_state(connection_h connection,
 
 
 /**
- * @deprecated Deprecated since 4.0. Use connection_ethernet_cable_state_changed_cb() instead.
+ * @deprecated Deprecated since 4.0. Use connection_ethernet_cable_state_changed_cb instead.
  * @brief Called when ethernet cable is plugged [in/out].
  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
  * @param[in] state             The state of ethernet cable
@@ -652,8 +662,8 @@ int connection_unset_ip_address_changed_cb(connection_h connection);
  * @brief Registers the callback that is called when the proxy address is changed.
  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  * @param[in] connection        The connection handle
- * @param[in] callback The callback function to be called
- * @param[in] user_data The user data passed to the callback function
+ * @param[in] callback          The callback function to be called
+ * @param[in] user_data         The user data passed to the callback function
  * @return @c 0 on success,
  *         otherwise a negative error value
  * @retval #CONNECTION_ERROR_NONE                  Successful
@@ -718,8 +728,10 @@ int connection_remove_profile(connection_h connection, connection_profile_h prof
 
 /**
  * @brief Updates an existing profile.
- * @details When a profile is changed, these changes will be not applied to the Connection Manager immediately.
- *          When you call this function, your changes affect the Connection Manager and the existing profile is updated.
+ * @details When a profile is changed, these changes will be not applied to the
+ *          Connection Manager immediately.
+ *          When you call this function, your changes affect the Connection Manager
+ *          and the existing profile is updated.
  *          In addition, the existing profile will be updated if you call connection_open_profile().
  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  * @privlevel public
@@ -779,7 +791,8 @@ int connection_profile_iterator_next(connection_profile_iterator_h profile_itera
 /**
  * @brief Checks whether the next element of a profile iterator exists or not.
  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
- * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
+ * @remarks The specific error code can be obtained using the get_last_result() method.
+ *          Error codes are described in Exception section.
  * @param[in] profile_iterator  The iterator of profile
  * @return @c true if next element exists,
  *         otherwise @c false if next element doesn't exist
@@ -827,7 +840,7 @@ int connection_get_current_profile(connection_h connection, connection_profile_h
  * @remarks You must release @a profile using connection_profile_destroy().
  * @param[in] connection        The connection handle
  * @param[in] type              The type of cellular service \n
- *                           #CONNECTION_CELLULAR_SERVICE_TYPE_APPLICATION is not permitted
+ *            #CONNECTION_CELLULAR_SERVICE_TYPE_APPLICATION is not permitted
  * @param[out] profile          The profile handle
  * @return @c 0 on success,
  *         otherwise a negative error value
@@ -847,12 +860,12 @@ int connection_get_default_cellular_service_profile(connection_h connection,
  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  * @privlevel public
  * @privilege %http://tizen.org/privilege/network.profile \n
- *               %http://tizen.org/privilege/network.get
+ *            %http://tizen.org/privilege/network.get
  * @remarks This API needs both privileges.
  * @param[in] connection        The connection handle
  * @param[in] type              The type of cellular service \n
- *                        only #CONNECTION_CELLULAR_SERVICE_TYPE_INTERNET and \n
- *                 #CONNECTION_CELLULAR_SERVICE_TYPE_PREPAID_INTERNET are permitted
+ *            Only #CONNECTION_CELLULAR_SERVICE_TYPE_INTERNET and
+ *            #CONNECTION_CELLULAR_SERVICE_TYPE_PREPAID_INTERNET are permitted
  * @param[in] profile           The profile handle
  * @return @c 0 on success,
  *         otherwise a negative error value
@@ -860,7 +873,7 @@ int connection_get_default_cellular_service_profile(connection_h connection,
  * @retval #CONNECTION_ERROR_INVALID_PARAMETER     Invalid parameter
  * @retval #CONNECTION_ERROR_OPERATION_FAILED      Operation failed
  * @retval #CONNECTION_ERROR_PERMISSION_DENIED     Permission denied
- * @retval #CONNECTION_ERROR_NOT_SUPPORTED            Not supported
+ * @retval #CONNECTION_ERROR_NOT_SUPPORTED         Not supported
  */
 int connection_set_default_cellular_service_profile(connection_h connection,
                connection_cellular_service_type_e type, connection_profile_h profile);
@@ -874,8 +887,9 @@ int connection_set_default_cellular_service_profile(connection_h connection,
  *               %http://tizen.org/privilege/network.get
  * @remarks This API needs both privileges.
  * @param[in] connection        The connection handle
- * @param[in] type              The type of cellular service (only #CONNECTION_CELLULAR_SERVICE_TYPE_INTERNET \n
- *            and #CONNECTION_CELLULAR_SERVICE_TYPE_PREPAID_INTERNET are permitted)
+ * @param[in] type              The type of cellular service \n
+ *            Only #CONNECTION_CELLULAR_SERVICE_TYPE_INTERNET and
+ *            #CONNECTION_CELLULAR_SERVICE_TYPE_PREPAID_INTERNET are permitted
  * @param[in] profile The profile handle
  * @param[in] callback The callback function to be called
  * @param[in] user_data The user data passed to the callback function
@@ -930,7 +944,7 @@ typedef void(*connection_reset_cb)(connection_error_e result, void* user_data);
  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  * @privlevel public
  * @privilege %http://tizen.org/privilege/network.set \n
- *               %http://tizen.org/privilege/network.get
+ *            %http://tizen.org/privilege/network.get
  * @remarks This API needs both privileges.
  * @param[in] connection        The connection handle
  * @param[in] profile           The profile handle
@@ -988,7 +1002,8 @@ int connection_close_profile(connection_h connection, connection_profile_h profi
  * @remarks This API needs both privileges.
  * @param[in] connection        The connection handle
  * @param[in] type              The type of reset
- * @param[in] id                The subscriber identity module ID to reset (The sim index starts from 0.)
+ * @param[in] id                The subscriber identity module ID to reset
+ *                              (The sim index starts from 0.)
  * @param[in] callback          The callback function to be called
  * @param[in] user_data         The user data passed to the callback function
  * @return @c 0 on success,
@@ -997,7 +1012,7 @@ int connection_close_profile(connection_h connection, connection_profile_h profi
  * @retval #CONNECTION_ERROR_INVALID_PARAMETER     Invalid parameter
  * @retval #CONNECTION_ERROR_OPERATION_FAILED      Operation failed
  * @retval #CONNECTION_ERROR_PERMISSION_DENIED     Permission denied
- * @retval #CONNECTION_ERROR_NOT_SUPPORTED            Not supported
+ * @retval #CONNECTION_ERROR_NOT_SUPPORTED         Not supported
  * @post connection_reset_cb() will be invoked.
 */
 int connection_reset_profile(connection_h connection, connection_reset_option_e type,
@@ -1005,9 +1020,9 @@ int connection_reset_profile(connection_h connection, connection_reset_option_e
 
 
 /**
- * @deprecated Deprecated since 4.0. Use connection_add_route_entry() instead.
  * @brief Adds a IPv4 route to the routing table.
- * @details You can get the @a interface_name from connection_profile_get_network_interface_name() of opened profile.
+ * @details You can get the @a interface_name from
+ *          connection_profile_get_network_interface_name() of opened profile.
  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  * @privlevel public
  * @privilege %http://tizen.org/privilege/network.set
@@ -1030,7 +1045,8 @@ int connection_add_route(connection_h connection, const char* interface_name,
 /**
  * @deprecated Deprecated since 4.0. Use connection_remove_route_entry() instead.
  * @brief Removes a IPv4 route from the routing table.
- * @details You can get the @a interface_name from connection_profile_get_network_interface_name() of opened profile.
+ * @details You can get the @a interface_name from
+ *          connection_profile_get_network_interface_name() of opened profile.
  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  * @privlevel public
  * @privilege %http://tizen.org/privilege/network.set
@@ -1045,14 +1061,14 @@ int connection_add_route(connection_h connection, const char* interface_name,
  * @retval #CONNECTION_ERROR_PERMISSION_DENIED     Permission denied
  * @see connection_profile_get_network_interface_name()
  */
-int connection_remove_route(connection_h connection, const char* interface_name,
-               const char* host_address) TIZEN_DEPRECATED_API;
+int connection_remove_route(connection_h connection, const char* interface_name, const char* host_address);
 
 
 /**
  * @deprecated Deprecated since 4.0. Use connection_add_route_entry() instead.
  * @brief Adds a IPv6 route to the routing table.
- * @details You can get the @a interface_name from connection_profile_get_network_interface_name() of opened profile.
+ * @details You can get the @a interface_name from
+ *          connection_profile_get_network_interface_name() of opened profile.
  * @since_tizen 2.3.1
  * @privlevel public
  * @privilege %http://tizen.org/privilege/network.set
@@ -1076,7 +1092,8 @@ int connection_add_route_ipv6(connection_h connection, const char *interface_nam
 /**
  * @deprecated Deprecated since 4.0. Use connection_remove_route_entry() instead.
  * @brief Removes a IPV6 route from the routing table.
- * @details You can get the @a interface_name from connection_profile_get_network_interface_name() of opened profile.
+ * @details You can get the @a interface_name from
+ *          connection_profile_get_network_interface_name() of opened profile.
  * @since_tizen 2.3.1
  * @privlevel public
  * @privilege %http://tizen.org/privilege/network.set
@@ -1151,15 +1168,15 @@ int connection_remove_route_entry(connection_h connection,
 /*
  * @brief Gets all IPv6 addresses assigned to the network interface.
  * @since_tizen 4.0
- * @param[in] connection        The connection handle
- * @param[in] connection_type   The connection type
- * @param[in] callback          The callback to be called for each IPv6 address
- * @param[in] user_data         The user data passed to the callback function
+ * @param[in] connection       The connection handle
+ * @param[in] connection_type  The connection type
+ * @param[in] callback         The callback to be called for each IPv6 address
+ * @param[in] user_data        The user data passed to the callback function
  * @return 0 on success, otherwise negative error value.
- * @retval #CONNECTION_ERROR_NONE                  Successful
- * @retval #CONNECTION_ERROR_INVALID_PARAMETER     Invalid parameter
- * @retval #CONNECTION_ERROR_OPERATION_FAILED      Operation failed
- * @retval #CONNECTION_ERROR_NOT_SUPPORTED         Not supported
+ * @retval #CONNECTION_ERROR_NONE               Successful
+ * @retval #CONNECTION_ERROR_INVALID_PARAMETER  Invalid parameter
+ * @retval #CONNECTION_ERROR_OPERATION_FAILED   Operation failed
+ * @retval #CONNECTION_ERROR_NOT_SUPPORTED      Not supported
  */
 int connection_foreach_ipv6_address(connection_h connection, connection_type_e connection_type,
                connection_ipv6_address_cb callback, void *user_data);
@@ -1181,7 +1198,8 @@ int connection_foreach_ipv6_address(connection_h connection, connection_type_e c
  * @privlevel public
  * @privilege %http://tizen.org/privilege/network.get
  * @param[in] connection The connection handle
- * @param[in] connection_type   The type of connection (only CONNECTION_TYPE_WIFI and CONNECTION_TYPE_CELLULAR are supported)
+ * @param[in] connection_type   The type of connection \n
+ *            Only CONNECTION_TYPE_WIFI and CONNECTION_TYPE_CELLULAR are supported
  * @param[in] statistics_type   The type of statistics
  * @param[out] size             The received data size of the last cellular packet data connection (bytes)
  * @return @c 0 on success,
@@ -1203,7 +1221,8 @@ int connection_get_statistics(connection_h connection, connection_type_e connect
  * @privilege %http://tizen.org/privilege/network.set
  * @remarks This API needs both privileges.
  * @param[in] connection        The connection handle
- * @param[in] connection_type   The type of connection (only CONNECTION_TYPE_WIFI and CONNECTION_TYPE_CELLULAR are supported)
+ * @param[in] connection_type   The type of connection \n
+ *            Only CONNECTION_TYPE_WIFI and CONNECTION_TYPE_CELLULAR are supported
  * @param[in] statistics_type   The type of statistics
  * @return @c 0 on success,
  *         otherwise a negative error value