From: Jaehyun Kim <jeik01.kim@samsung.com>
Date: Fri, 27 Sep 2024 09:05:44 +0000 (+0900)
Subject: Update API documentation
X-Git-Tag: accepted/tizen/unified/20250116.113526^0
X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=refs%2Fheads%2Faccepted%2Ftizen_unified_x;p=platform%2Fcore%2Fapi%2Fconnection.git

Update API documentation

Change-Id: Ie2e9d1f9d622c142aeff30ad9dd0ad233f50a026
Signed-off-by: Jaehyun Kim <jeik01.kim@samsung.com>
---

diff --git a/include/net_connection.h b/include/net_connection.h
index 5cdc7b0..d4a814a 100755
--- a/include/net_connection.h
+++ b/include/net_connection.h
@@ -317,6 +317,8 @@ int connection_create(connection_h* connection);
 
 /**
  * @brief Destroys the connection handle.
+ * @details This function releases all resources allocated for the given connection handle. \n
+ *          should be called when the connection is no longer needed to prevent memory leaks and other potential issues.
  * @since_tizen 2.3
  * @param[in] connection        The connection handle
  * @return @c 0 on success,
@@ -332,6 +334,8 @@ int connection_destroy(connection_h connection);
 
 /**
  * @brief Called when the type of a connection is changed.
+ * @details This callback function is invoked when the type of the network connection changes. \n
+ *          It provides information about the connection type changes and allows you to handle the change accordingly.
  * @since_tizen 2.3
  * @param[in] type              The type of the current network connection
  * @param[in] user_data         The user data passed from the callback registration function
@@ -343,6 +347,9 @@ typedef void(*connection_type_changed_cb)(connection_type_e type, void* user_dat
 
 /**
  * @brief Called when the address is changed.
+ * @details This callback function is called when the IP address for IPv4 or IPv6 changes. \n
+ *          The addresses provided within this callback are valid only during the execution of the callback. \n
+ *          If you need to use these addresses outside of the callback, you must make a copy of them.
  * @since_tizen 2.3
  * @remarks @a ipv4_address @a ipv6_address should not be freed.
  *          @a ipv4_address @a ipv6_address is available only in the callback.
@@ -361,6 +368,10 @@ typedef void(*connection_address_changed_cb)(const char* ipv4_address,
 
 /**
  * @brief Called when connection_set_default_cellular_service_profile_async() finishes.
+ * @details This callback function is invoked after the asynchronous operation of \n
+ *          setting a default cellular service profile is completed. \n
+ *          It provides the result of the operation and any user data that was passed \n
+ *          during the invocation of connection_set_default_cellular_service_profile_async().
  * @since_tizen 2.3
  * @param[in] result            The result
  * @param[in] user_data         The user data passed from connection_open_profile()
@@ -371,6 +382,8 @@ typedef void(*connection_set_default_cb)(connection_error_e result, void* user_d
 
 /**
  * @brief Called with an IPv6 address.
+ * @details This callback function is invoked when iterating through the list of IPv6 addresses associated with a network interface. \n
+ *          It provides each IPv6 address as a character string and allows the caller to perform custom operations on each address.
  * @since_tizen 4.0
  * @remarks   If @a ipv6_address is needed outside the callback, a copy should be made. \n
  *            @a ipv6_address will be freed automatically after the execution of this callback.
@@ -385,6 +398,9 @@ typedef bool(*connection_ipv6_address_cb)(char *ipv6_address, void *user_data);
 
 /**
  * @brief Called when the DHCP state is changed.
+ * @details This callback function is invoked when the DHCP state changes for a given network interface. \n
+ *          It provides information about DHCP state changes, the network interface associated with the state change, \n
+ *          and the result of the DHCP operation.
  * @since_tizen 8.0
  * @param[in]  state            The DHCP state
  * @param[in]  interface_name   The interface name with DHCP state change
@@ -398,6 +414,8 @@ typedef void(*connection_dhcp_state_changed_cb)(connection_dhcp_state_e state,
 
 /**
  * @brief Gets the type of the current profile for data connection.
+ * @details This function retrieves the type of the network currently being used for data connection. \n
+ *          It returns an integer value representing the type of the network.
  * @since_tizen 2.3
  * @param[in] connection        The connection handle
  * @param[out] type             The type of the network
@@ -414,6 +432,8 @@ int connection_get_type(connection_h connection, connection_type_e* type);
 
 /**
  * @brief Gets the IP address of the current connection.
+ * @details This function retrieves the IP address associated with the network currently being used for data connection and address family. \n
+ *          The retrieved IP address should be released using the free() function.
  * @since_tizen 2.3
  * @remarks You must release @a ip_address using free().
  * @param[in] connection        The connection handle
@@ -434,6 +454,8 @@ int connection_get_ip_address(connection_h connection,
 
 /**
  * @brief Gets the proxy address of the current connection.
+ * @details This function retrieves the proxy address for the specified address family associated with the network currently being used for data connection. \n
+ *          The retrieved proxy address should be released using free() after use.
  * @since_tizen 2.3
  * @remarks You must release @a proxy using free().
  * @param[in] connection        The connection handle
@@ -454,6 +476,8 @@ int connection_get_proxy(connection_h connection,
 
 /**
  * @brief Gets the MAC address of the Wi-Fi or ethernet.
+ * @details This function retrieves the MAC address of the specified network connection type (Wi-Fi or Ethernet). \n
+ *          The caller is responsible for releasing the memory allocated for the MAC address using free().
  * @since_tizen 2.4
  * @remarks @a mac_addr must be released with free() by you.
  * @param[in] connection        The handle of the connection
@@ -475,6 +499,8 @@ int connection_get_mac_address(connection_h connection,
 
 /**
  * @brief Gets if the current connection is metered.
+ * @details This function retrieves information about whether the current network connection is metered or not. \n
+ *          A metered connection is typically one where data usage may be limited or charged for, such as a mobile network.
  * @since_tizen 4.0
  * @privlevel public
  * @privilege %http://tizen.org/privilege/network.get
@@ -494,7 +520,8 @@ int connection_is_metered_network(connection_h connection, bool* is_metered);
 
 /**
  * @brief Gets the state of cellular connection.
- * @details The returned state is for the cellular connection state.
+ * @details This function retrieves the current state of the cellular connection. \n
+ *          The state is returned as an enumeration value of the `connection_cellular_state_e` type.
  * @since_tizen 2.3
  * @param[in] connection        The connection handle
  * @param[out] state            The state of the cellular connection
@@ -511,7 +538,8 @@ int connection_get_cellular_state(connection_h connection, connection_cellular_s
 
 /**
  * @brief Gets the state of the Wi-Fi.
- * @details The returned state is for the Wi-Fi connection state.
+ * @details This function retrieves the current state of the Wi-Fi connection. \n
+ *          This information can be used to determine the status of the Wi-Fi network connection.
  * @since_tizen 2.3
  * @privlevel public
  * @privilege %http://tizen.org/privilege/network.get
@@ -531,7 +559,7 @@ int connection_get_wifi_state(connection_h connection, connection_wifi_state_e*
 
 /**
  * @brief Gets the state of the Ethernet.
- * @details The returned state is for the Ethernet connection state.
+ * @details This function retrieves the current state of the Ethernet connection.
  * @since_tizen 2.4
  * @privlevel public
  * @privilege %http://tizen.org/privilege/network.get
@@ -551,6 +579,8 @@ int connection_get_ethernet_state(connection_h connection, connection_ethernet_s
 
 /**
  * @brief Called when the Internet state of the current connection is changed.
+ * @details This callback function is invoked when the Internet state of the current connection changes. \n
+ *          It provides information about the new state of the connection and allows you to handle any necessary actions based on the updated state.
  * @since_tizen 5.5
  * @param[in] state             The Internet state of current connection
  * @param[in] user_data         The user data passed to callback registration function
@@ -560,6 +590,9 @@ typedef void(*connection_internet_state_changed_cb)(
 
 /**
  * @brief Sets the callback that is called when the Internet availability over the current connection is changed.
+ * @details This function sets a callback function to receive notifications about changes in the Internet availability status of the connection. \n
+ *          When the Internet availability state changes, the provided callback function will be invoked with the new state \n
+ *          and the user data supplied during the registration.
  * @since_tizen 5.5
  * @param[in] connection        The connection handle
  * @param[in] callback          The callback function to be called
@@ -578,6 +611,8 @@ int connection_set_internet_state_changed_cb(connection_h connection,
 
 /**
  * @brief Unsets the callback that is called when the Internet state of the current connection is changed.
+ * @details This function removes the previously set callback for monitoring changes in the Internet state of the connection. \n
+ *          After calling this function, the callback will no longer be invoked when the Internet state changes.
  * @since_tizen 5.5
  * @param[in] connection        The connection handle
  * @return @c 0 on success,
@@ -592,7 +627,8 @@ int connection_unset_internet_state_changed_cb(connection_h connection);
 
 /**
  * @brief Checks for ethernet cable is attached or not.
- * @details The returned state is for the ethernet cable state.
+ * @details This function retrieves the current state of the ethernet cable connected to the device. \n
+ *          The possible states include whether the cable is attached or detached.
  * @since_tizen 2.4
  * @privlevel public
  * @privilege %http://tizen.org/privilege/network.get
@@ -613,6 +649,8 @@ int connection_get_ethernet_cable_state(connection_h connection,
 
 /**
  * @brief Gets the DHCP state of the interface.
+ * @details This function retrieves the DHCP state of the network currently being used for data connection. \n
+ *          The DHCP state indicates whether the interface has started to obtained an IP address via DHCP or not.
  * @since_tizen 8.0
  * @privlevel public
  * @privilege %http://tizen.org/privilege/network.get
@@ -678,6 +716,7 @@ int connection_unset_ethernet_cable_state_chaged_cb(connection_h connection) TIZ
 
 /**
  * @brief Called when ethernet cable is plugged [in/out].
+ * @details This callback function is invoked when an Ethernet cable is either plugged in or unplugged.
  * @since_tizen 4.0
  * @param[in] state             The state of ethernet cable
  * @param[in] user_data         The user data passed to callback registration function
@@ -688,6 +727,8 @@ typedef void(*connection_ethernet_cable_state_changed_cb)(
 
 /**
  * @brief Sets callback for ethernet cable is plugged [in/out] event.
+ * @details This function registers a callback function to be invoked when the state of the ethernet cable changes. \n
+ *          It allows you to monitor whether the ethernet cable is plugged in or out.
  * @since_tizen 4.0
  * @param[in] connection        The connection handle
  * @param[in] callback          The callback function to be called
@@ -706,6 +747,7 @@ int connection_set_ethernet_cable_state_changed_cb(connection_h connection,
 
 /**
  * @brief Unsets callback for ethernet cable is plugged [in/out] event.
+ * @details This function removes the callback that was previously set to receive notifications when the ethernet cable is plugged in or out.
  * @since_tizen 4.0
  * @param[in] connection        The connection handle
  * @return @c 0 on success,
@@ -721,7 +763,8 @@ int connection_unset_ethernet_cable_state_changed_cb(connection_h connection);
 
 /**
  * @brief Gets the state of the Bluetooth.
- * @details The returned state is for the Bluetooth connection state.
+ * @details This function retrieves the current state of the Bluetooth connection. \n
+ *          Possible states include disconnected, connected, and deactivated.
  * @since_tizen 2.3
  * @privlevel public
  * @privilege %http://tizen.org/privilege/network.get
@@ -741,6 +784,8 @@ int connection_get_bt_state(connection_h connection, connection_bt_state_e* stat
 
 /**
  * @brief Sets the callback that is called when the type of the current connection is changed.
+ * @details This function registers a callback function to be invoked when the type of the current network connection changes. \n
+ *          The registered callback will be called with user data provided during registration whenever the connection type changes.
  * @since_tizen 2.3
  * @param[in] connection        The connection handle
  * @param[in] callback          The callback function to be called
@@ -759,6 +804,8 @@ int connection_set_type_changed_cb(connection_h connection,
 
 /**
  * @brief Unsets the callback that is called when the type of current connection is changed.
+ * @details This function removes the callback function that was previously registered using connection_set_type_changed_cb(). \n
+ *          After calling this function, the connection_type_changed_cb callback will no longer be called when the connection type changes.
  * @since_tizen 2.3
  * @param[in] connection        The connection handle
  * @return @c 0 on success,
@@ -774,6 +821,7 @@ int connection_unset_type_changed_cb(connection_h connection);
 
 /**
  * @brief Sets the callback that is called when the IP address is changed.
+ * @details This function registers a callback function to be invoked when the IP address of the connection changes.
  * @since_tizen 2.3
  * @param[in] connection        The connection handle
  * @param[in] callback          The callback function to be called
@@ -792,6 +840,8 @@ int connection_set_ip_address_changed_cb(connection_h connection,
 
 /**
  * @brief Unsets the callback that is called when the IP address is changed.
+ * @details This function removes the callback function that was previously set to be called when the IP address changes for the connection. \n
+ *          After calling this function, no further notifications will be sent about IP address changes.
  * @since_tizen 2.3
  * @param[in] connection        The connection handle
  * @return @c 0 on success,
@@ -807,6 +857,7 @@ int connection_unset_ip_address_changed_cb(connection_h connection);
 
 /**
  * @brief Sets the callback that is called when the proxy address is changed.
+ * @details This function registers a callback function to be invoked when the proxy address changes for the connection.
  * @since_tizen 2.3
  * @param[in] connection        The connection handle
  * @param[in] callback          The callback function to be called
@@ -825,6 +876,8 @@ int connection_set_proxy_address_changed_cb(connection_h connection,
 
 /**
  * @brief Unsets the callback that is called when the proxy address is changed.
+ * @details This function removes the callback function that was previously set using connection_set_proxy_address_changed_cb(). \n
+ *          After calling this function, the proxy address change events will no longer be delivered to the application.
  * @since_tizen 2.3
  * @param[in] connection        The connection handle
  * @return @c 0 on success,
@@ -840,6 +893,8 @@ int connection_unset_proxy_address_changed_cb(connection_h connection);
 
 /**
  * @brief Sets the callback that is called when the DHCP state is changed.
+ * @details This function registers a callback function to receive notifications whenever the DHCP state changes for the connection. \n
+ *          When the DHCP state changes, the registered callback function will be invoked with the new DHCP state and the provided user data.
  * @since_tizen 8.0
  * @param[in] connection        The connection handle
  * @param[in] callback          The callback function to be called
@@ -858,6 +913,7 @@ int connection_set_dhcp_state_changed_cb(connection_h connection,
 
 /**
  * @brief Unsets the callback that is called when the DHCP state is changed.
+ * @details This function removes the callback function that was previously registered to be invoked when the DHCP state changes.
  * @since_tizen 8.0
  * @param[in] connection        The connection handle
  * @return @c 0 on success,
@@ -873,6 +929,9 @@ int connection_unset_dhcp_state_changed_cb(connection_h connection);
 
 /**
  * @brief Adds a new profile which is created by connection_profile_create().
+ * @details This function adds a new cellular profile to the profile list to be used for cellular connection. \n
+ *          The profile must be created using connection_profile_create() and should be of the cellular type. \n
+ *          The caller must have the necessary privileges to perform this operation.
  * @since_tizen 2.3
  * @privlevel public
  * @privilege %http://tizen.org/privilege/network.profile
@@ -893,6 +952,7 @@ int connection_add_profile(connection_h connection, connection_profile_h profile
 
 /**
  * @brief Removes an existing profile.
+ * @details This function removes the specified profile from the profile list.
  * @since_tizen 2.3
  * @privlevel public
  * @privilege %http://tizen.org/privilege/network.profile \n
@@ -941,10 +1001,12 @@ int connection_update_profile(connection_h connection, connection_profile_h prof
 
 /**
  * @brief Gets a profiles iterator.
+ * @details This function retrieves an iterator to enumerate all the profiles of a given type from the profile list. \n
+ *          The caller is responsible for releasing the iterator using the connection_destroy_profile_iterator() function after it is no longer needed.
  * @since_tizen 2.3
  * @privlevel public
  * @privilege %http://tizen.org/privilege/network.get
- * @remarks You must release @a profile_iterator using connection_destroy().
+ * @remarks You must release @a profile_iterator using connection_destroy_profile_iterator().
  * @param[in] connection        The connection handle
  * @param[in] type              The type of the connection iterator
  * @param[out] profile_iterator The iterator of profile
@@ -964,6 +1026,10 @@ int connection_get_profile_iterator(connection_h connection,
 
 /**
  * @brief Moves the profile iterator to the next position and gets a profile handle.
+ * @details This function moves the given profile iterator to the next position and retrieves the profile handle at that position. \n
+ *          If the end of the iteration is reached, the function returns CONNECTION_ERROR_ITERATOR_END. \n
+ *          The retrieved profile handle will be automatically destroyed when the profile iterator is destroyed. \n
+ *          To continue using the profile handle after the iterator is destroyed, make a copy of it.
  * @since_tizen 2.3
  * @remarks The @a profile will be destroyed automatically when the profile iterator is destroyed.
  *          Make a copy if you want to keep using it.
@@ -983,6 +1049,10 @@ int connection_profile_iterator_next(connection_profile_iterator_h profile_itera
 
 /**
  * @brief Checks whether the next element of a profile iterator exists or not.
+ * @details This function checks if there is another profile available to iterate over using the given profile iterator handle. \n
+ *          If the next element exists, it returns true; otherwise, it returns false. \n
+ *          The specific error code can be obtained using the get_last_result() method. \n
+ *          Error codes are described in Exception section.
  * @since_tizen 2.3
  * @remarks The specific error code can be obtained using the get_last_result() method.
  *          Error codes are described in Exception section.
@@ -999,6 +1069,8 @@ bool connection_profile_iterator_has_next(connection_profile_iterator_h profile_
 
 /**
  * @brief Destroys a profiles iterator.
+ * @details This function destroys the given profile iterator handle and releases all its resources. \n
+ *          After calling this function, the profile iterator handle becomes invalid, and you cannot use it to perform any operations.
  * @since_tizen 2.3
  * @param[in] profile_iterator  The iterator of the profile
  * @return @c 0 on success,
@@ -1013,6 +1085,7 @@ int connection_destroy_profile_iterator(connection_profile_iterator_h profile_it
 
 /**
  * @brief Gets the name of the default profile.
+ * @details This function retrieves the default network profile currently in use by the system.
  * @since_tizen 2.3
  * @privlevel public
  * @privilege %http://tizen.org/privilege/network.get
@@ -1035,6 +1108,8 @@ int connection_get_current_profile(connection_h connection, connection_profile_h
 
 /**
  * @brief Gets the default profile which provides the given cellular service.
+ * @details This function retrieves the default profile that provides the specified cellular service type. \n
+ *          The caller must release the returned profile handle using connection_profile_destroy(). \n
  * @since_tizen 2.3
  * @privlevel public
  * @privilege %http://tizen.org/privilege/network.get
@@ -1059,6 +1134,10 @@ int connection_get_default_cellular_service_profile(connection_h connection,
 
 /**
  * @brief Sets the default profile which provides the given cellular service.
+ * @details This function sets the default profile for the specified cellular service type. \n
+ *          It requires both network.profile and network.get privileges. \n
+ *          The function only permits #CONNECTION_CELLULAR_SERVICE_TYPE_INTERNET and #CONNECTION_CELLULAR_SERVICE_TYPE_PREPAID_INTERNET as valid service types. \n
+ *          If successful, it returns #CONNECTION_ERROR_NONE; otherwise, it returns an appropriate error code.
  * @since_tizen 2.3
  * @privlevel public
  * @privilege %http://tizen.org/privilege/network.profile \n
@@ -1084,6 +1163,11 @@ int connection_set_default_cellular_service_profile(connection_h connection,
 
 /**
  * @brief Sets the default profile which provides the given cellular service, asynchronously.
+ * @details This function sets the default profile for a specified cellular service type asynchronously. \n
+ *          It requires both network.profile and network.get privileges. \n
+ *          Only #CONNECTION_CELLULAR_SERVICE_TYPE_INTERNET and #CONNECTION_CELLULAR_SERVICE_TYPE_PREPAID_INTERNET are allowed as the service type. \n
+ *          The function returns an integer value indicating the result of the operation. \n
+ *          If successful, it returns #CONNECTION_ERROR_NONE; otherwise, it returns one of the other error codes.
  * @since_tizen 2.3
  * @privlevel public
  * @privilege %http://tizen.org/privilege/network.profile \n
@@ -1112,6 +1196,9 @@ int connection_set_default_cellular_service_profile_async(connection_h connectio
 
 /**
  * @brief Called after connection_open_profile() is finished.
+ * @details This callback function is invoked when the asynchronous operation of opening a network profile is completed. \n
+ *          It provides the result of the operation and any user data that was passed during the call to connection_open_profile(). \n
+ *          The application can use this callback to handle the result of the profile opening process.
  * @since_tizen 2.3
  * @param[in] result            The result
  * @param[in] user_data         The user data passed from connection_open_profile()
@@ -1123,6 +1210,8 @@ typedef void(*connection_opened_cb)(connection_error_e result, void* user_data);
 
 /**
  * @brief Called after connection_close_profile() is finished.
+ * @details This callback function is invoked when the connection_close_profile() function has completed its execution. \n
+ *          It receives the result of the operation and any user data that was passed to the connection_close_profile() function.
  * @since_tizen 2.3
  * @param[in] result            The result
  * @param[in] user_data         The user data passed from connection_close_profile()
@@ -1134,6 +1223,8 @@ typedef void(*connection_closed_cb)(connection_error_e result, void* user_data);
 
 /**
  * @brief Called after connection_reset_profile() is finished.
+ * @details This callback function is invoked when the connection_reset_profile() function completes its operation. \n
+ *          It receives the result of the operation and the user data that was passed to the connection_reset_profile() function.
  * @since_tizen 2.3
  * @param[in] result            The result
  * @param[in] user_data         The user data passed from connection_reset_profile()
@@ -1145,6 +1236,7 @@ typedef void(*connection_reset_cb)(connection_error_e result, void* user_data);
 
 /**
  * @brief Opens a connection of profile, asynchronously.
+ * @details This function opens a network connection using the specified profile handle in an asynchronous manner.
  * @since_tizen 2.3
  * @privlevel public
  * @privilege %http://tizen.org/privilege/network.set \n
@@ -1175,6 +1267,8 @@ int connection_open_profile(connection_h connection, connection_profile_h profil
 
 /**
  * @brief Closes a connection of profile.
+ * @details This function closes the connection of a specified profile and releases all resources associated with it. \n
+ *          After closing the profile, the corresponding callback function is invoked to notify the completion of the operation.
  * @since_tizen 2.3
  * @privlevel public
  * @privilege %http://tizen.org/privilege/network.set
@@ -1203,6 +1297,11 @@ int connection_close_profile(connection_h connection, connection_profile_h profi
 
 /**
  * @brief Resets the cellular profile.
+ * @details This function resets the cellular profiles. \n
+ *          It requires both network.profile and network.get privileges. \n
+ *          The type of reset can be specified using the 'type' parameter, \n
+ *          and the subscriber identity module ID to reset can be provided using the 'id' parameter. \n
+ *          The callback function and user data are used for asynchronous operation handling.
  * @since_tizen 2.3
  * @privlevel public
  * @privilege %http://tizen.org/privilege/network.profile \n
@@ -1402,6 +1501,7 @@ int connection_remove_route_entry(connection_h connection,
 
 /**
  * @brief Gets all IPv6 addresses assigned to the network interface.
+ * @details This function retrieves all IPv6 addresses associated with a specified network interface and invokes a provided callback function for each address found.
  * @since_tizen 4.0
  * @param[in] connection       The connection handle
  * @param[in] connection_type  The connection type
@@ -1430,6 +1530,8 @@ int connection_foreach_ipv6_address(connection_h connection, connection_type_e c
 
 /**
  * @brief Gets the statistics information.
+ * @details This function retrieves the specified statistics information for the given connection type. \n
+ *          It supports only #CONNECTION_TYPE_WIFI and #CONNECTION_TYPE_CELLULAR types.
  * @since_tizen 2.3
  * @privlevel public
  * @privilege %http://tizen.org/privilege/network.get
@@ -1453,6 +1555,8 @@ int connection_get_statistics(connection_h connection, connection_type_e connect
 
 /**
  * @brief Resets the statistics information.
+ * @details This function resets the specified statistics information for a given connection type. \n
+ *          Supported connection types include #CONNECTION_TYPE_WIFI and #CONNECTION_TYPE_CELLULAR.
  * @since_tizen 2.3
  * @privlevel public
  * @privilege %http://tizen.org/privilege/network.set