From: Seonah Moon Date: Fri, 27 Sep 2024 13:01:55 +0000 (+0900) Subject: Update API description X-Git-Tag: accepted/tizen/unified/20241007.161048^0 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=refs%2Fheads%2Faccepted%2Ftizen_9.0_unified;p=platform%2Fcore%2Fapi%2Fsoftap.git Update API description Change-Id: Ifa1a383168b616e1c802734bedd29eb016df9368 --- diff --git a/doc/softap_doc.h b/doc/softap_doc.h index c259931..aa527a3 100755 --- a/doc/softap_doc.h +++ b/doc/softap_doc.h @@ -27,6 +27,10 @@ * \#include * * @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. * * @@ -53,7 +57,9 @@ * \#include * * @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 * * @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 aef043c..eb5b05d 100644 --- 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