Update API description

Change-Id: Ie339a3ff85fe0f984772459beb3f6e71cd3e7466
Signed-off-by: Abhay Agarwal <ay.agarwal@samsung.com>

diff --git a/include/user-awareness.h b/include/user-awareness.h
index f215f4b6d4c5edf24d02ebb8f7c45d3f6c906615..0edeb8fe0e2f73250c721a3599a49718ef75c7ae 100755 (executable)
--- 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 08b99189676159529f5f654e2dde45b486ecbe9e..4535541aa143032bbd5ce62f45ba13f362a14ca9 100755 (executable)
--- 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;