Modified header files by tizen policy

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

diff --git a/include/net_connection.h b/include/net_connection.h
index 7db93d7..5a5dc51 100755 (executable)
--- a/include/net_connection.h
+++ b/include/net_connection.h
@@ -15,8 +15,8 @@
  */
 
 
-#ifndef __NET_CONNECTION_INTF_H__
-#define __NET_CONNECTION_INTF_H__
+#ifndef __TIZEN_NETWORK_NET_CONNECTION_H__
+#define __TIZEN_NETWORK_NET_CONNECTION_H__
 
 
 #include <connection_profile.h>
@@ -278,7 +278,7 @@ typedef enum {
  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  * @privlevel public
  * @privilege %http://tizen.org/privilege/network.get
- * @remarks You must release @a handle using connection_destroy().
+ * @remarks You must release @a connection using connection_destroy().
  * @param[out] connection       The connection handle
  * @return @c 0 on success,
  *         otherwise a negative error value
@@ -318,6 +318,9 @@ typedef void(*connection_type_changed_cb)(connection_type_e type, void* user_dat
 /**
  * @brief Called when the address is changed.
  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
+ * @remarks @a ipv4_address @a ipv6_address should not be freed.
+ *          @a ipv4_address @a ipv6_address is available only in the callback.
+ *          To use outside the callback, make a copy.
  * @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
@@ -517,7 +520,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
@@ -529,7 +532,7 @@ typedef void(*connection_ethernet_cable_state_chaged_cb)
 
 /**
  * @deprecated Deprecated since 4.0. Use connection_set_ethernet_cable_state_changed_cb() instead.
- * @brief Registers callback for ethernet cable is plugged [in/out] event.
+ * @brief Sets callback for ethernet cable is plugged [in/out] event.
  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
  * @param[in] connection        The handle of connection
  * @param[in] callback          The callback function to be called
@@ -547,7 +550,7 @@ int connection_set_ethernet_cable_state_chaged_cb(connection_h connection,
 
 /**
  * @deprecated Deprecated since 4.0. Use connection_unset_ethernet_cable_state_changed_cb() instead.
- * @brief Unregisters callback for ethernet cable is plugged [in/out] event.
+ * @brief Unsets callback for ethernet cable is plugged [in/out] event.
  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
  * @param[in] connection        The handle of connection
  * @return @c 0 on success,
@@ -570,7 +573,7 @@ typedef void(*connection_ethernet_cable_state_changed_cb)(
 
 
 /**
- * @brief Registers callback for ethernet cable is plugged [in/out] event.
+ * @brief Sets callback for ethernet cable is plugged [in/out] event.
  * @since_tizen 4.0
  * @param[in] connection        The handle of connection
  * @param[in] callback          The callback function to be called
@@ -587,7 +590,7 @@ int connection_set_ethernet_cable_state_changed_cb(connection_h connection,
 
 
 /**
- * @brief Unregisters callback for ethernet cable is plugged [in/out] event.
+ * @brief Unsets callback for ethernet cable is plugged [in/out] event.
  * @since_tizen 4.0
  * @param[in] connection        The handle of connection
  * @return @c 0 on success,
@@ -620,7 +623,7 @@ int connection_get_bt_state(connection_h connection, connection_bt_state_e* stat
 
 
 /**
- * @brief Registers the callback that is called when the type of the current connection is changed.
+ * @brief Sets the callback that is called when the type of the current connection 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
@@ -636,7 +639,7 @@ int connection_set_type_changed_cb(connection_h connection,
 
 
 /**
- * @brief Unregisters the callback that is called when the type of current connection is changed.
+ * @brief Unsets the callback that is called when the type of current connection is changed.
  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  * @param[in] connection        The connection handle
  * @return @c 0 on success,
@@ -649,7 +652,7 @@ int connection_unset_type_changed_cb(connection_h connection);
 
 
 /**
- * @brief Registers the callback that is called when the IP address is changed.
+ * @brief Sets the callback that is called when the IP 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
@@ -665,7 +668,7 @@ int connection_set_ip_address_changed_cb(connection_h connection,
 
 
 /**
- * @brief Unregisters the callback that is called when the IP address is changed.
+ * @brief Unsets the callback that is called when the IP address is changed.
  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  * @param[in] connection        The connection handle
  * @return @c 0 on success,
@@ -678,7 +681,7 @@ int connection_unset_ip_address_changed_cb(connection_h connection);
 
 
 /**
- * @brief Registers the callback that is called when the proxy address is changed.
+ * @brief Sets 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
@@ -694,7 +697,7 @@ int connection_set_proxy_address_changed_cb(connection_h connection,
 
 
 /**
- * @brief Unregisters the callback that is called when the proxy address is changed.
+ * @brief Unsets 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
  * @return @c 0 on success,
@@ -731,7 +734,7 @@ int connection_add_profile(connection_h connection, connection_profile_h profile
  * @privlevel public
  * @privilege %http://tizen.org/privilege/network.profile \n
  *            %http://tizen.org/privilege/network.get
- * @remarks This API needs both privileges.
+ * @remarks This function needs both privileges.
  * @param[in] connection        The connection handle
  * @param[in] profile           The profile handle
  * @return @c 0 on success,
@@ -756,7 +759,7 @@ int connection_remove_profile(connection_h connection, connection_profile_h prof
  * @privlevel public
  * @privilege %http://tizen.org/privilege/network.profile \n
  *            %http://tizen.org/privilege/network.get
- * @remarks This API needs both privileges.
+ * @remarks This function needs both privileges.
  * @param[in] connection        The connection handle
  * @param[in] profile           The profile handle
  * @return @c 0 on success,
@@ -883,7 +886,7 @@ int connection_get_default_cellular_service_profile(connection_h connection,
  * @privlevel public
  * @privilege %http://tizen.org/privilege/network.profile \n
  *            %http://tizen.org/privilege/network.get
- * @remarks This API needs both privileges.
+ * @remarks This function 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
@@ -907,7 +910,7 @@ int connection_set_default_cellular_service_profile(connection_h connection,
  * @privlevel public
  * @privilege %http://tizen.org/privilege/network.profile \n
  *               %http://tizen.org/privilege/network.get
- * @remarks This API needs both privileges.
+ * @remarks This function 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
@@ -967,7 +970,7 @@ typedef void(*connection_reset_cb)(connection_error_e result, void* user_data);
  * @privlevel public
  * @privilege %http://tizen.org/privilege/network.set \n
  *            %http://tizen.org/privilege/network.get
- * @remarks This API needs both privileges.
+ * @remarks This function needs both privileges.
  * @param[in] connection        The connection handle
  * @param[in] profile           The profile handle
  * @param[in] callback          The callback function to be called
@@ -1021,7 +1024,7 @@ int connection_close_profile(connection_h connection, connection_profile_h profi
  * @privlevel public
  * @privilege %http://tizen.org/privilege/network.profile \n
  *               %http://tizen.org/privilege/network.get
- * @remarks This API needs both privileges.
+ * @remarks This function 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
@@ -1042,6 +1045,7 @@ 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.
@@ -1083,7 +1087,8 @@ 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);
+int connection_remove_route(connection_h connection, const char* interface_name,
+               const char* host_address) TIZEN_DEPRECATED_API;
 
 
 /**
@@ -1221,7 +1226,7 @@ int connection_foreach_ipv6_address(connection_h connection, connection_type_e c
  * @privilege %http://tizen.org/privilege/network.get
  * @param[in] connection The connection handle
  * @param[in] connection_type   The type of connection \n
- *            Only CONNECTION_TYPE_WIFI and CONNECTION_TYPE_CELLULAR are supported
+ *            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,
@@ -1243,7 +1248,7 @@ int connection_get_statistics(connection_h connection, connection_type_e connect
  * @privilege %http://tizen.org/privilege/network.set
  * @param[in] connection        The connection handle
  * @param[in] connection_type   The type of connection \n
- *            Only CONNECTION_TYPE_WIFI and CONNECTION_TYPE_CELLULAR are supported
+ *            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
@@ -1265,4 +1270,4 @@ int connection_reset_statistics(connection_h connection, connection_type_e conne
 #endif /* __cplusplus */
 
 
-#endif
+#endif /* __TIZEN_NETWORK_NET_CONNECTION_H__ */