Update API description

Change-Id: Ifa1a383168b616e1c802734bedd29eb016df9368

diff --git a/doc/softap_doc.h b/doc/softap_doc.h
index c259931da1b4411d2a4058a1ea4323b8e220c3f8..aa527a3fe103f6442dd94648d0b24c10bf7e36f5 100755 (executable)
--- a/doc/softap_doc.h
+++ b/doc/softap_doc.h
@@ -27,6 +27,10 @@
  *   \#include <softap.h>
  *
  * @section CAPI_NETWORK_SOFTAP_MODULE_OVERVIEW Overview
+ * The SoftAP module allows a device to act as a Soft Access Point (SoftAP), enabling other devices to connect to the network it creates.
+ * Applications can use this module to configure and monitor the SoftAP’s status, manage network connectivity, and adjust security settings.
+ * It is primarily used in IoT environments to easily set up and maintain network access points.
+ *
  * SoftAP Service consists of @ref CAPI_NETWORK_SOFTAP_MANAGER_MODULE and @ref CAPI_NETWORK_SOFTAP_CLIENT_MODULE.
  * <table>
  * <tr>
@@ -53,7 +57,9 @@
  *   \#include <softap.h>
  *
  * @section CAPI_NETWORK_SOFTAP_MANAGER_MODULE_OVERVIEW Overview
- * This set of functions is used to manage SoftAP.
+ * The SoftAP Manager module allows Tizen-based devices to set up and manage their own Soft Access Point (SoftAP).
+ * With this functionality, a device can create its own network and enable other client devices to connect to it.
+ * The module provides easy control over network creation, configuration, and security protocols, simplifying SoftAP management.
  * @section CAPI_NETWORK_SOFTAP_MANAGER_MODULE_FEATURE Related Features
  * This API is related with the following features:\n
  * - %http://tizen.org/feature/network.wifi.softap\n
@@ -77,7 +83,7 @@
  *   \#include <softap.h>
  *
  * @section CAPI_NETWORK_SOFTAP_CLIENT_MODULE_OVERVIEW Overview
- * This set of functions is used to get information about a connected client.
+ * This module provides the functionalities that allow application to retrieve information on client devices connected to SoftAP.
  * @section CAPI_NETWORK_SOFTAP_CLIENT_MODULE_FEATURE Related Features
  * This API is related with the following features:\n
  * - %http://tizen.org/feature/network.wifi.softap \n

diff --git a/include/softap.h b/include/softap.h
index aef043c83d0312c1b16e049ccc5623e5c1ade1ea..eb5b05dcc1b446e8c19a586c64d4f3ca883b8dfb 100644 (file)
--- a/include/softap.h
+++ b/include/softap.h
@@ -278,6 +278,10 @@ int softap_destroy(softap_h softap);
 /**
  * @platform
  * @brief Enables the SoftAP, asynchronously.
+ * @details This function allows you to activate the SoftAP functionality on the device.
+ * It's important to ensure that the required privileges have been obtained before invoking this function, as mentioned in the precondition.
+ * Upon successful execution, the SoftAP will be enabled, allowing nearby devices to establish wireless connections.
+ * Depending on the device, the user might need to manually turn off the current Wi-Fi connection before enabling the SoftAP.
  * @since_tizen 5.0
  * @privlevel platform
  * @privilege %http://tizen.org/privilege/softap.admin
@@ -298,6 +302,8 @@ int softap_enable(softap_h softap);
 /**
  * @platform
  * @brief Disables the SoftAP, asynchronously.
+ * @details This function enables you to deactivate the SoftAP functionality on the device.
+ * Upon successful execution, the SoftAP will be disabled, preventing further wireless connections from being established.
  * @since_tizen 5.0
  * @privlevel platform
  * @privilege %http://tizen.org/privilege/softap.admin
@@ -331,7 +337,12 @@ int softap_disable(softap_h softap);
 int softap_is_enabled(softap_h softap, bool *enable);
 
 /**
- * @brief Gets the MAC address of local device as "FC:A1:3E:D6:B1:B1".
+ * @brief Gets the Media Access Control (MAC) address of the local device in the format "FC:A1:3E:D6:B1:B1".
+ * @details This function allows you to obtain the MAC address of the local device.
+ * Remember that the SoftAP must be enabled in order to use this function.
+ * You can verify the SoftAP's activation state using the 'softap_is_enabled' function.
+ * Upon successful execution, the MAC address will be returned in the form of a string,
+ * which should be freed using the 'free' function once it's no longer needed.
  * @since_tizen 5.0
  * @privlevel public
  * @privilege %http://tizen.org/privilege/softap
@@ -354,6 +365,11 @@ int softap_get_mac_address(softap_h softap, char **mac_address);
 
 /**
  * @brief Gets the name of network interface (e.g. wlan0).
+ * @details This function enables you to retrieve the name of the network interface associated with the SoftAP functionality.
+ * Remember that the SoftAP must be enabled in order to use this function.
+ * You can verify the SoftAP's activation state using the 'softap_is_enabled' function.
+ * Upon successful execution, the name of the network interface will be returned as a string,
+ * which should be freed using the 'free' function once it's no longer needed.
  * @since_tizen 5.0
  * @privlevel public
  * @privilege %http://tizen.org/privilege/softap
@@ -394,6 +410,11 @@ int softap_set_ip_address(softap_h softap, softap_address_family_e address_famil
 
 /**
  * @brief Gets the local IP address.
+ * @details This function retrieves the IP address of the SoftAP.
+ * Remember that the SoftAP must be enabled in order to use this function.
+ * You can verify the SoftAP's activation state using the 'softap_is_enabled' function.
+ * Upon successful execution, the IP address will be returned as a string,
+ * which should be freed using the 'free' function once it's no longer needed.
  * @since_tizen 5.0
  * @privlevel public
  * @privilege %http://tizen.org/privilege/softap
@@ -417,6 +438,11 @@ int softap_get_ip_address(softap_h softap, softap_address_family_e address_famil
 
 /**
  * @brief Gets the Gateway address.
+ * @details This function retrieves the gateway address of the SoftAP.
+ * Remember that the SoftAP must be enabled in order to use this function.
+ * You can verify the SoftAP's activation state using the 'softap_is_enabled' function.
+ * Upon successful execution, the gateway address will be returned as a string,
+ * which should be freed using the 'free' function once it's no longer needed.
  * @since_tizen 5.0
  * @privlevel public
  * @privilege %http://tizen.org/privilege/softap
@@ -440,6 +466,11 @@ int softap_get_gateway_address(softap_h softap, softap_address_family_e address_
 
 /**
  * @brief Gets the Subnet Mask.
+ * @details This function retrieves the subnet mask of the SoftAP.
+ * Remember that the SoftAP must be enabled in order to use this function.
+ * You can verify the SoftAP's activation state using the 'softap_is_enabled' function.
+ * Upon successful execution, the subnet mask will be returned as a string,
+ * which should be freed using the 'free' function once it's no longer needed.
  * @since_tizen 5.0
  * @privlevel public
  * @privilege %http://tizen.org/privilege/softap
@@ -463,6 +494,9 @@ int softap_get_subnet_mask(softap_h softap, softap_address_family_e address_fami
 
 /**
  * @brief Gets the clients which are connected.
+ * @details This function allows you to enumerate the clients that are currently connected to the SoftAP.
+ * By providing the appropriate SoftAP handle as the 'softap' argument and specifying the callback function and user data, you can receive information about each connected client.
+ * Upon successful execution, the callback function will be called for each connected client, giving you the opportunity to perform actions based on the received client information.
  * @since_tizen 5.0
  * @privlevel public
  * @privilege %http://tizen.org/privilege/softap
@@ -483,7 +517,10 @@ int softap_get_subnet_mask(softap_h softap, softap_address_family_e address_fami
 int softap_foreach_connected_clients(softap_h softap, softap_connected_client_cb callback, void *user_data);
 
 /**
- * @brief Sets the callback function, which is called when SoftAP is enabled.
+ * @brief Sets a callback function to be called when the SoftAP is enabled.
+ * @details This function allows you to associate a callback function with the SoftAP handle, which will be invoked when the SoftAP is successfully enabled or when an error occurs during the enabling process. 
+ * By providing the appropriate SoftAP handle as the 'softap' argument and specifying the callback function and user data, you can receive notification regarding the SoftAP's activation status.
+ * Upon successful execution, the callback function will be registered, ensuring that your application receives timely updates regarding the SoftAP's enabling process.
  * @since_tizen 5.0
  * @privlevel public
  * @privilege %http://tizen.org/privilege/softap
@@ -496,11 +533,14 @@ int softap_foreach_connected_clients(softap_h softap, softap_connected_client_cb
  * @retval  #SOFTAP_ERROR_NOT_SUPPORTED     API is not supported
  * @retval  #SOFTAP_ERROR_PERMISSION_DENIED Permission denied
  * @see  softap_unset_enabled_cb()
+ * @see  softap_enable()
  */
 int softap_set_enabled_cb(softap_h softap, softap_enabled_cb callback, void *user_data);
 
 /**
  * @brief Unsets the callback function, which is called when SoftAP is enabled.
+ * @details This function enables you to unregister the callback function from the SoftAP handle, preventing it from receiving notifications regarding the SoftAP's activation status.
+ * By providing the appropriate SoftAP handle as the'softap' argument, you can initiate the unregistration process.
  * @since_tizen 5.0
  * @privlevel public
  * @privilege %http://tizen.org/privilege/softap
@@ -516,6 +556,9 @@ int softap_unset_enabled_cb(softap_h softap);
 
 /**
  * @brief Sets the callback function called when SoftAP is disabled.
+ * @details This function allows you to associate a callback function with the SoftAP handle, which will be invoked when the SoftAP is successfully disabled.
+ * By providing the appropriate SoftAP handle as the'softap' argument and specifying the callback function and user data, you can receive notification regarding the SoftAP's deactivation status.
+ * Upon successful execution, the callback function will be registered, ensuring that your application receives timely updates regarding the SoftAP's disabling process.
  * @since_tizen 5.0
  * @privlevel public
  * @privilege %http://tizen.org/privilege/softap
@@ -533,6 +576,10 @@ int softap_set_disabled_cb(softap_h softap, softap_disabled_cb callback, void *u
 
 /**
  * @brief Unsets the callback function, which is called when SoftAP is disabled.
+ * @details This function enables you to dissociate the callback function from the SoftAP handle,
+ * preventing it from receiving notifications regarding the SoftAP's deactivation status.
+ * By providing the appropriate SoftAP handle as the'softap' argument, you can initiate the unregistration process.
+ * Upon successful execution, the callback function will be unregistered, allowing your application to focus solely on other aspects of the SoftAP functionality.
  * @since_tizen 5.0
  * @privlevel public
  * @privilege %http://tizen.org/privilege/softap