From: Seonah Moon Date: Thu, 9 Apr 2020 04:17:18 +0000 (+0900) Subject: Add description #2 X-Git-Tag: submit/tizen/20200616.063112~5^2~6^2~3 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=f42a8249f63a2cce7045800fc655a94ac1dfe0eb;p=platform%2Fcore%2Fapi%2Fwifi-aware.git Add description #2 --- diff --git a/include/wifi-aware.h b/include/wifi-aware.h index a7cd658..244fc72 100644 --- a/include/wifi-aware.h +++ b/include/wifi-aware.h @@ -197,7 +197,7 @@ int wifi_aware_deinitialize(); /** * @brief Create a Publish request. * @since_tizen 6.0 - * @param[out] publish + * @param[out] publish The Wi-Fi Aware Publish handle. * @return 0 on success, otherwise a negative error value * @retval #WIFI_AWARE_ERROR_NONE * @see wifi_aware_publish_destroy @@ -207,7 +207,7 @@ int wifi_aware_publish_create(wifi_aware_publish_h *publish); /** * @brief Destroy a Publish request. * @since_tizen 6.0 - * @param[in] publish + * @param[in] publish The Wi-Fi Aware Publish handle. * @return 0 on success, otherwise a negative error value * @retval #WIFI_AWARE_ERROR_NONE * @see wifi_aware_publish_create @@ -217,6 +217,7 @@ int wifi_aware_publish_destroy(wifi_aware_publish_h publish); /** * @brief Create a Subscribe request. * @since_tizen 6.0 + * @param[out] subscribe The Wi-Fi Aware Subscribe handle. * @return 0 on success, otherwise a negative error value * @retval #WIFI_AWARE_ERROR_NONE * @see wifi_aware_subscribe_destroy @@ -226,7 +227,7 @@ int wifi_aware_subscribe_create(wifi_aware_subscribe_h *subscribe); /** * @brief Destroy a Subscribe request. * @since_tizen 6.0 - * @param[in] subscribe + * @param[in] subscribe The Wi-Fi Aware Subscribe handle. * @return 0 on success, otherwise a negative error value * @retval #WIFI_AWARE_ERROR_NONE * @see wifi_aware_subscribe_create @@ -234,10 +235,10 @@ int wifi_aware_subscribe_create(wifi_aware_subscribe_h *subscribe); int wifi_aware_subscribe_destroy(wifi_aware_subscribe_h subscribe); /** - * @brief Sets TTL(Time To Live) to Publish configuration. + * @brief Sets TTL(Time To Live) for Publish session. * @since_tizen 6.0 - * @param[in] publish publish configuration handle. - * @param[in] ttl lifetime(seconds) of publish session. 0 means forever until canceled. + * @param[in] publish The Wi-Fi Aware Publish handle. + * @param[in] ttl The lifetime(seconds) of publish session. 0 means forever until canceled. * @return 0 on success, otherwise a negative error value * @retval #WIFI_AWARE_ERROR_NONE */ @@ -246,8 +247,8 @@ int wifi_aware_publish_set_ttl(wifi_aware_publish_h publish, unsigned short ttl) /** * @brief Set the type of the service as solicited or unsolicited. * @since_tizen 6.0 - * @param[in] publish - * @param[in] publish_type + * @param[in] publish The Wi-Fi Aware Publish handle + * @param[in] publish_type The Publish type * @return 0 on success, otherwise a negative error value * @retval #WIFI_AWARE_ERROR_NONE */ @@ -256,8 +257,8 @@ int wifi_aware_publish_set_type(wifi_aware_publish_h publish, wifi_aware_publish /** * @brief Set the name of the service. The length should be less than or equal to 255 * @since_tizen 6.0 - * @param[in] publish - * @param[in] service_name UTF-8 name which identifies the service + * @param[in] publish The Wi-Fi Aware Publish handle + * @param[in] service_name UTF-8 name which identifies the service * @return 0 on success, otherwise a negative error value * @retval #WIFI_AWARE_ERROR_NONE */ @@ -266,20 +267,21 @@ int wifi_aware_publish_set_service_name(wifi_aware_publish_h publish, const char /** * @brief Set the specific information for the service. * @since_tizen 6.0 - * @param[in] publish - * @param[in] service_specific_info - * @param[in] len + * @param[in] publish The Wi-Fi Aware Publish handle + * @param[in] service_specific_info The Sequence of values that are conveyed in the Publish message + * @param[in] len The length of service specific information * @return 0 on success, otherwise a negative error value * @retval #WIFI_AWARE_ERROR_NONE */ int wifi_aware_publish_set_service_specific_info(wifi_aware_publish_h publish, const unsigned char *service_specific_info, size_t len); /** - * @brief Set the match filter of the service. It is used to decide whether accepting a subscribe request or not. + * @brief Set the match filter of the service. * @since_tizen 6.0 - * @param[in] publish - * @param[in] match_filter An ordered sequence of pairs - * @param[in] len + * @param[in] publish The Wi-Fi Aware Publish handle + * @param[in] match_filter An ordered sequence of pairs + * @param[in] len The whole length of match_filter + * @remark The match filter is used to decide whether accepting a subscribe request or not. * @return 0 on success, otherwise a negative error value * @retval #WIFI_AWARE_ERROR_NONE */ @@ -288,8 +290,9 @@ int wifi_aware_publish_set_match_filter(wifi_aware_publish_h publish, const unsi /** * @brief Set whether the ranging function is supported or not. * @since_tizen 6.0 - * @param[in] publish - * @param[in] enable + * @param[in] publish The Wi-Fi Aware Publish handle + * @param[in] enable @c ture if ranging is enabled, + * otherwise @c false if ranging is disabled. * @return 0 on success, otherwise a negative error value * @retval #WIFI_AWARE_ERROR_NONE */ @@ -300,72 +303,75 @@ int wifi_aware_publish_enable_ranging(wifi_aware_publish_h publish, bool enable) // subscribe_config /** - * @brief + * @brief Sets TTL(Time To Live) for Subscribe session. * @since_tizen 6.0 - * @param[in] subscribe - * @param[in] ttl + * @param[in] subscribe The Wi-Fi Aware Subscribe handle + * @param[in] ttl The lifetime(seconds) of subscribe session.\n + * 0 means forever until wifi_aware_service_discovered_cb. * @return 0 on success, otherwise a negative error value * @retval #WIFI_AWARE_ERROR_NONE */ int wifi_aware_subscribe_set_ttl(wifi_aware_subscribe_h subscribe, unsigned short ttl); /** - * @brief + * @brief Sets the type of the service as passive or active. * @since_tizen 6.0 - * @param[in] subscribe - * @param[in] subscribe_type + * @param[in] subscribe The Wi-Fi Aware Subscribe handle + * @param[in] subscribe_type The Subscribe type * @return 0 on success, otherwise a negative error value * @retval #WIFI_AWARE_ERROR_NONE */ int wifi_aware_subscribe_set_type(wifi_aware_subscribe_h subscribe, wifi_aware_subscribe_type_e subscribe_type); /** - * @brief Set the name of the service. The length should be less than or equal to 255 + * @brief Set the name of the service. * @since_tizen 6.0 - * @param[in] subscribe - * @param[in] service_name UTF-8 name which identifies the service + * @param[in] subscribe The Wi-Fi Aware Subscribe handle + * @param[in] service_name UTF-8 name which identifies the service + * @remark The length should be less than or equal to 255 * @return 0 on success, otherwise a negative error value * @retval #WIFI_AWARE_ERROR_NONE */ int wifi_aware_subscribe_set_service_name(wifi_aware_subscribe_h subscribe, const char *service_name); /** - * @brief + * @brief Sets the specific information for the service. * @since_tizen 6.0 - * @param[in] subscribe - * @param[in] service_specific_info - * @param[in] len + * @param[in] subscribe The Wi-Fi Aware Subscribe handle + * @param[in] service_specific_info The Sequence of values that are conveyed in the Subscribe message + * @param[in] len The length of service specific information * @return 0 on success, otherwise a negative error value * @retval #WIFI_AWARE_ERROR_NONE */ int wifi_aware_subscribe_set_service_specific_info(wifi_aware_subscribe_h subscribe, const unsigned char *service_specific_info, size_t len); /** - * @brief + * @brief Sets the match filter of the service. * @since_tizen 6.0 - * @param[in] subscribe - * @param[in] match_filter An ordered sequence of pairs - * @param[in] len + * @param[in] subscribe The Wi-Fi Aware Subscribe handle + * @param[in] match_filter An ordered sequence of pairs + * @param[in] len The whole length of match_filter + * @remark The match filter is used to decide whether accepting a subscribe request or not. * @return 0 on success, otherwise a negative error value * @retval #WIFI_AWARE_ERROR_NONE */ int wifi_aware_subscribe_set_match_filter(wifi_aware_subscribe_h subscribe, const unsigned char *match_filter, size_t len); /** - * @brief + * @brief Sets the maximum distance between the found services * @since_tizen 6.0 - * @param[in] subscribe - * @param[in] distance + * @param[in] subscribe The Wi-Fi Aware Subscribe handle + * @param[in] distance The max distance between found services * @return 0 on success, otherwise a negative error value * @retval #WIFI_AWARE_ERROR_NONE */ int wifi_aware_subscribe_set_max_distance(wifi_aware_subscribe_h subscribe, int distance); /** - * @brief + * @brief Sets the minimum distance between the found services * @since_tizen 6.0 - * @param[in] subscribe - * @param[in] distance + * @param[in] subscribe The Wi-Fi Aware Subscribe handle + * @param[in] distance The min distance between found services * @return 0 on success, otherwise a negative error value * @retval #WIFI_AWARE_ERROR_NONE */ @@ -373,30 +379,30 @@ int wifi_aware_subscribe_set_min_distance(wifi_aware_subscribe_h subscribe, int /** - * @brief + * @brief Called when Wi-Fi Aware is enabled. * @since_tizen 6.0 - * @param[in] error - * @param[in] user_data + * @param[in] error The error code + * @param[in] user_data The user data passed from the request function * @return 0 on success, otherwise a negative error value * @retval #WIFI_AWARE_ERROR_NONE */ typedef void(*wifi_aware_enabled_cb)(wifi_aware_error_e error, void *user_data); /** - * @brief Enable Wi-Fi Aware functions. + * @brief Enables Wi-Fi Aware functions. * If Wi-Fi Aware is already enabled, the callback to return success is immediately invoked. * @remarks If the enable request is sucessfully done, the application can get the MAC address. * TODO: Does an application need to know MAC address (NMI)? * @since_tizen 6.0 - * @param[in] callback The result of enable request is asynchrously delivered - * @param[in] user_data User data + * @param[in] callback The result of enable request is asynchrously delivered + * @param[in] user_data The user data passed to the callback function * @return 0 on success, otherwise a negative error value * @retval #WIFI_AWARE_ERROR_NONE */ int wifi_aware_enable(wifi_aware_enabled_cb callback, void *user_data); /** - * @brief Disable Wi-Fi Aware functions. + * @brief Disables Wi-Fi Aware functions. * @since_tizen 6.0 * @return 0 on success, otherwise a negative error value * @retval #WIFI_AWARE_ERROR_NONE @@ -404,40 +410,40 @@ int wifi_aware_enable(wifi_aware_enabled_cb callback, void *user_data); int wifi_aware_disable(); /** - * @brief + * @brief Creates the Wi-Fi Aware Session. * @since_tizen 6.0 - * @param[in] session_type - * @param[in] session + * @param[in] session_type The type of session + * @param[out] session The Wi-Fi Aware Session handle that is newly created on success * @return 0 on success, otherwise a negative error value * @retval #WIFI_AWARE_ERROR_NONE */ int wifi_aware_session_create(wifi_aware_session_type_e session_type, wifi_aware_session_h *session); /** - * @brief + * @brief Destroies the Wi-Fi Aware Session. * @since_tizen 6.0 - * @param[in] session + * @param[in] session The Wi-Fi Aware Session handle * @return 0 on success, otherwise a negative error value * @retval #WIFI_AWARE_ERROR_NONE */ int wifi_aware_session_destroy(wifi_aware_session_h session); /** - * @brief Callback to notify that the Wi-Fi Aware Session has been lost. + * @brief Called when the Wi-Fi Aware Session has been lost. * @since_tizen 6.0 - * @param[in] session - * @param[in] reason - * @param[in] user_data + * @param[in] session The Wi-Fi Aware Session handle + * @param[in] reason The reason of termination + * @param[in] user_data The user data passed from request function */ typedef void(*wifi_aware_session_terminated_cb)(wifi_aware_session_h session, wifi_aware_termination_reason_e reason, void *user_data); /** - * @brief + * @brief Registers a callback function to notify session is terminated. * @since_tizen 6.0 - * @param[in] session - * @param[in] callback - * @param[in] user_data + * @param[in] session The Wi-Fi Aware Session + * @param[in] callback The callback function to register + * @param[in] user_data The user data to be passed to the callback function * @return 0 on success, otherwise a negative error value * @retval #WIFI_AWARE_ERROR_NONE */ @@ -445,20 +451,20 @@ int wifi_aware_session_set_terminated_cb(wifi_aware_session_h session, wifi_aware_session_terminated_cb callback, void *user_data); /** - * @brief + * @brief Unregisters the terminated callback function. * @since_tizen 6.0 - * @param[in] session + * @param[in] session The Wi-Fi Aware Session * @return 0 on success, otherwise a negative error value * @retval #WIFI_AWARE_ERROR_NONE */ int wifi_aware_session_unset_terminated_cb(wifi_aware_session_h session); /** - * @brief This callback delivers the result of a Publish request. + * @brief Called when publish request is finished. * @since_tizen 6.0 - * @param[in] session - * @param[in] error - * @param[in] user_data + * @param[in] session The Wi-Fi Aware Session handle + * @param[in] error The error code + * @param[in] user_data The user data passed from request function * @return 0 on success, otherwise a negative error value * @retval #WIFI_AWARE_ERROR_NONE * @see wifi_aware_session_publish() @@ -468,7 +474,7 @@ typedef void(*wifi_aware_published_cb)(wifi_aware_session_h session, wifi_aware_error_e error, void *user_data); /** - * @brief Publish a Wi-Fi Aware service so that neighboring devices can find it. + * @brief Publishes a Wi-Fi Aware service so that neighboring devices can find it. * @since_tizen 6.0 * @param[in] sesssion * @param[in] publish