From: Abhay Agarwal Date: Mon, 22 Feb 2021 07:19:44 +0000 (+0530) Subject: Update API description X-Git-Tag: submit/tizen/20210303.222245~2 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=2a70846d4ca16aba73945cdde6f83a28c38c1d24;p=platform%2Fcore%2Fapi%2Fuser-awareness.git Update API description Change-Id: Ie339a3ff85fe0f984772459beb3f6e71cd3e7466 Signed-off-by: Abhay Agarwal --- diff --git a/include/user-awareness.h b/include/user-awareness.h index f215f4b..0edeb8f 100755 --- a/include/user-awareness.h +++ b/include/user-awareness.h @@ -92,7 +92,6 @@ int ua_foreach_service( * * @remarks The @a service handle is managed by the platform and will be released * when #ua_deinitialize() is called. - * * @param[out] service The service handle * * @return 0 on success, otherwise a negative error value @@ -109,7 +108,7 @@ int ua_get_default_service( /** * @ingroup CAPI_NETWORK_UA_MODULE - * @brief Gets service handle by service name. + * @brief Gets service handle by service name for added service. * @since_tizen 6.5 * * @remarks The @a service handle should be destroyed by using #ua_service_destroy(). @@ -119,7 +118,7 @@ int ua_get_default_service( * * @return 0 on success, otherwise a negative error value * @retval #UA_ERROR_NONE Successful - * @retval #UA_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #UA_ERROR_INVALID_PARAMETER Invalid parameter or if service with such name does not exist. * @retval #UA_ERROR_OPERATION_FAILED Operation failed * @retval #UA_ERROR_NOT_INITIALIZED Not initialized yet * @@ -175,6 +174,7 @@ int ua_monitor_destroy( /** * @ingroup CAPI_NETWORK_UA_MODULE * @brief Adds sensors to UA monitor for which monitoring is to be done. + * Availability of sensors to be added can be checked using #ua_monitor_is_sensor_available() * @since_tizen 6.5 * @privlevel public * @privilege %http://tizen.org/privilege/userawareness @@ -185,7 +185,7 @@ int ua_monitor_destroy( * @return 0 on success, otherwise a negative error value * @retval #UA_ERROR_NONE Successful * @retval #UA_ERROR_PERMISSION_DENIED Permission Denied - * @retval #UA_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #UA_ERROR_INVALID_PARAMETER Invalid parameter or sensor not available to add * @retval #UA_ERROR_NOT_PERMITTED Operation not permitted * @retval #UA_ERROR_ALREADY_DONE Already done * @retval #UA_ERROR_NOT_READY Resource not ready @@ -275,7 +275,8 @@ int ua_monitor_is_sensor_available( * @since_tizen 6.5 * * @remarks Sensor status change will be reported only for environmental - * sensors (ie. the sensors for which user/device information is not available) + * sensors (ie. the sensors for which user/device information is not available, + * For example. Light and Motion Sensors) * * @param[in] monitor The monitor handle * @param[in] callback Sensor status changed callback @@ -496,7 +497,8 @@ int ua_monitor_stop_absence_detection( * * @remarks The @a user handle should be destroyed by using #ua_user_destroy(). * - * @param[in] account Account information + * @param[in] account Account information. Maximum Account string + * length allowed is 254. * @param[out] user The user handle * * @return 0 on success, otherwise a negative error value @@ -535,7 +537,8 @@ int ua_user_destroy( /** * @ingroup CAPI_NETWORK_UA_MODULE - * @brief Adds the user. + * @brief Adds the user. Added user is stored in the database + * and is also available after the application restarts. * @since_tizen 6.5 * @privlevel public * @privilege %http://tizen.org/privilege/userawareness @@ -548,6 +551,7 @@ int ua_user_destroy( * @retval #UA_ERROR_INVALID_PARAMETER Invalid parameter * @retval #UA_ERROR_OPERATION_FAILED Operation failed * @retval #UA_ERROR_NOT_INITIALIZED Not initialized yet + * @retval #UA_ERROR_ALREADY_REGISTERED Already Registered * * @see ua_user_remove() */ @@ -594,7 +598,8 @@ int ua_user_get_account(ua_user_h user, char **account); /** * @ingroup CAPI_NETWORK_UA_MODULE - * @brief Adds device for a user. + * @brief Adds device for a user. This information is stored in database + * and is also available after the application restarts. * @since_tizen 6.5 * @privlevel public * @privilege %http://tizen.org/privilege/userawareness @@ -697,7 +702,7 @@ int ua_service_create( * @privlevel public * @privilege %http://tizen.org/privilege/userawareness * - * @remarks Service context will removed and all allocated memory (if any) will be released. + * @remarks Service context will be removed and all allocated memory (if any) will be released. * * @param[in] service The service handle * @@ -714,7 +719,8 @@ int ua_service_destroy( /** * @ingroup CAPI_NETWORK_UA_MODULE - * @brief Adds the service. + * @brief Adds the service. Added service is stored in database + * and is also available after the application restarts. * @since_tizen 6.5 * @privlevel public * @privilege %http://tizen.org/privilege/userawareness @@ -735,7 +741,9 @@ int ua_service_add( /** * @ingroup CAPI_NETWORK_UA_MODULE - * @brief Updates the service. + * @brief Updates the properties for the added service. + * To update a property of a service its respective setter functions + * should be called and then followed by the call of ua_service_update(). * @since_tizen 6.5 * @privlevel public * @privilege %http://tizen.org/privilege/userawareness @@ -800,11 +808,13 @@ int ua_service_get_name( /** * @ingroup CAPI_NETWORK_UA_MODULE * @brief Sets detection threshold for service handle. + * If the service has already been added, this call should be followed by + * the call of ua_service_update() to reflect the modifications. * @since_tizen 6.5 * * @param[in] service The service handle - * @param[in] presence_threshold The service presence threshold information - * @param[in] absence_threshold The service absence threshold information + * @param[in] presence_threshold The service presence threshold information (in lux) + * @param[in] absence_threshold The service absence threshold information (in lux) * * @return 0 on success, otherwise a negative error value * @retval #UA_ERROR_NONE Successful @@ -825,8 +835,8 @@ int ua_service_set_detection_threshold( * @privilege %http://tizen.org/privilege/userawareness * * @param[in] service The service handle - * @param[out] presence_threshold The service presence threshold information - * @param[out] absence_threshold The service absence threshold information + * @param[out] presence_threshold The service presence threshold information (in lux) + * @param[out] absence_threshold The service absence threshold information (in lux) * * @return 0 on success, otherwise a negative error value * @retval #UA_ERROR_NONE Successful @@ -958,7 +968,7 @@ int ua_service_get_device_discriminant( /** * @ingroup CAPI_NETWORK_UA_MODULE - * @brief Retrieves the user handle of all the added users for a specific service. + * @brief Triggers callback for every user of a specific service. * @since_tizen 6.5 * * @param[in] service The service handle. @@ -984,7 +994,7 @@ int ua_service_foreach_users( * @privlevel public * @privilege %http://tizen.org/privilege/userawareness * - * @remarks The @a device handle should be destroyed by using #ua_user_destroy(). + * @remarks The @a device handle should be destroyed using #ua_user_destroy(). * * @param[in] mac_type The MAC address type of the device * @param[in] mac_address The device's MAC address. @@ -1013,7 +1023,7 @@ int ua_device_create(ua_mac_type_e mac_type, * @privlevel public * @privilege %http://tizen.org/privilege/userawareness * - * @remarks Device context will removed and all allocated memory (if any) will be released. + * @remarks Device context will be removed and all allocated memory (if any) will be released. * * @param[in] device The device handle * @@ -1049,6 +1059,8 @@ int ua_device_get_mac_type( /** * @ingroup CAPI_NETWORK_UA_MODULE * @brief Sets device's operating system info. + * If the device has already been added, this call should be followed by + * the call of ua_device_update() to reflect the modifications. * @since_tizen 6.5 * @privlevel public * @privilege %http://tizen.org/privilege/userawareness @@ -1108,7 +1120,7 @@ int ua_device_get_mac_address( /** * @ingroup CAPI_NETWORK_UA_MODULE - * @brief Gets device ID. + * @brief Gets device ID of device, which was set while creating the device handle. * @since_tizen 6.5 * * @remarks You must release @a device_id using g_free(). @@ -1128,6 +1140,8 @@ int ua_device_get_device_id( /** * @ingroup CAPI_NETWORK_UA_MODULE * @brief Sets device's Wi-Fi BSSID. + * If the device has already been added, this call should be followed by + * the call of ua_device_update() to reflect the modifications. * @since_tizen 6.5 * @privlevel public * @privilege %http://tizen.org/privilege/userawareness @@ -1168,6 +1182,8 @@ int ua_device_get_wifi_bssid( /** * @ingroup CAPI_NETWORK_UA_MODULE * @brief Sets device's Wi-Fi IPv4 address. + * If the device has already been added, this call should be followed by + * the call of ua_device_update() to reflect the modifications. * @since_tizen 6.5 * @privlevel public * @privilege %http://tizen.org/privilege/userawareness @@ -1213,7 +1229,7 @@ int ua_device_get_wifi_ipv4_address( * @since_tizen 6.5 * * @param[in] device The device handle - * @param[out] last_seen The last presence time for UA device + * @param[out] last_seen The last presence monotonic timestamp for UA device (in msec) * * @return 0 on success, otherwise a negative error value * @retval #UA_ERROR_NONE Successful @@ -1246,7 +1262,9 @@ int ua_device_get_pairing_required( /** * @ingroup CAPI_NETWORK_UA_MODULE - * @brief Updates the device. + * @brief Updates the properties for the added device. + * To update a property of a device its respective setter functions + * should be called and then followed by the call of ua_device_update(). * @since_tizen 6.5 * @privlevel public * @privilege %http://tizen.org/privilege/userawareness @@ -1272,7 +1290,9 @@ int ua_device_update( * @since_tizen 6.5 * * @remarks The @a device handle should not be released. - * @remarks The @a device handle can be used only in the function. + * @remarks The @a device handle is available until device is + * removed and released by application using #ua_user_remove_device() + * and #ua_device_destroy() * * @param[in] mac The device's MAC address * @param[out] device The device handle @@ -1294,7 +1314,9 @@ int ua_device_get_by_mac_address( * @since_tizen 6.5 * * @remarks The @a device handle should not be released. - * @remarks The @a device handle can be used only in the function. + * @remarks The @a device handle is available until device is + * removed and released by application using #ua_user_remove_device() + * and #ua_device_destroy() * * @param[in] device_id The device ID * @param[in] mac_type The device's MAC type diff --git a/src/user-awareness-monitors.c b/src/user-awareness-monitors.c index 08b9918..4535541 100755 --- a/src/user-awareness-monitors.c +++ b/src/user-awareness-monitors.c @@ -1307,7 +1307,7 @@ int ua_monitor_add_sensor( _uam_get_available_sensors(&available_sensors))) UA_WARN("_uam_get_available_sensors failed"); // LCOV_EXCL_LINE - retv_if(0 == (available_sensors & bitmask), UA_ERROR_NOT_READY); + retv_if(0 == (available_sensors & bitmask), UA_ERROR_INVALID_PARAMETER); monitor->sensor_bitmask |= bitmask;