From: hyunuk.tak Date: Fri, 20 Sep 2024 01:13:34 +0000 (+0900) Subject: Update API documents X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=refs%2Fheads%2Ftizen;p=platform%2Fcore%2Fapi%2Fuser-awareness.git Update API documents Change-Id: I9bd49b6c863461002df9d2d69ee7cb77075980ff Signed-off-by: hyunuk.tak --- diff --git a/include/user-awareness.h b/include/user-awareness.h index feeeebe..c20f469 100755 --- a/include/user-awareness.h +++ b/include/user-awareness.h @@ -40,6 +40,11 @@ extern "C" { /** * @brief Initializes the user awareness framework. + * @details This function initializes the user awareness + * framework, which is responsible for providing various + * user-related information such as presence, activity, and + * location. Initializing the framework allows applications + * to use its features and services. * @since_tizen 6.5 * * @return 0 on success, otherwise a negative error value @@ -54,6 +59,11 @@ int ua_initialize(void); /** * @brief De-initializes the user awareness framework. + * @details This function de-initializes the user awareness + * framework, releasing all resources allocated during + * initialization. After calling this function, the framework + * will no longer be available for use until it is + * re-initialized with ua_initialize(). * @since_tizen 6.5 * * @return 0 on success, otherwise a negative error value @@ -68,6 +78,11 @@ int ua_deinitialize(void); /** * @brief Retrieves handles of all added services. + * @details This function retrieves handles of all services + * that have been added to the user awareness framework. + * It iterates through the list of services and invokes + * the provided callback function for each service handle, + * passing the handle and user-provided data to the callback. * @since_tizen 6.5 * * @param[in] foreach_cb Callback function to be invoked with each service handle. @@ -87,6 +102,10 @@ int ua_foreach_service( /** * @brief Gets default service handle. + * @details This function retrieves the default service handle, which + * represents the primary service used by the user awareness framework. + * The default service handle can be used to access various features + * and functionalities provided by the framework. * @since_tizen 6.5 * * @remarks The @a service handle is managed by the platform and will be released @@ -108,6 +127,9 @@ int ua_get_default_service( /** * @brief Gets service handle by service name for added service. + * @details This function retrieves the service handle associated with + * the specified service name. If a service with the given name exists, + * its handle is returned; otherwise, an error is returned. * @since_tizen 6.5 * * @remarks The @a service handle should be destroyed by using ua_service_destroy(). @@ -130,6 +152,11 @@ int ua_get_service_by_name( /** * @brief Creates the ua monitor's handle. + * @details This function creates a new handle for a user awareness + * (UA) monitor, which can be used to observe and track user-related + * events and activities. The created monitor handle can be configured + * and used to receive notifications about specific events or changes + * in user behavior. * @since_tizen 6.5 * * @remarks The @a monitor handle should be destroyed by using ua_monitor_destroy(). @@ -150,6 +177,10 @@ int ua_monitor_create( /** * @brief Destroys the ua monitor's handle. + * @details This function destroys the specified user awareness + * (UA) monitor handle, releasing all resources associated with it. + * Once the handle is destroyed, it can no longer be used to monitor + * user-related events or activities. * @since_tizen 6.5 * * @param[in] monitor The monitor handle @@ -168,6 +199,10 @@ int ua_monitor_destroy( /** * @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(). + * @details This function adds the specified sensor to the user awareness + * (UA) monitor, enabling it to track and monitor events related to the sensor. + * Before adding a sensor, its availability can be checked using the + * ua_monitor_is_sensor_available() function. * @since_tizen 6.5 * @remarks If you want to add the BLE sensor, * you should add privilege %http://tizen.org/privilege/bluetooth. @@ -197,6 +232,10 @@ int ua_monitor_add_sensor( /** * @brief Removes sensors from UA monitor. + * @details This function removes the specified sensor from the user awareness + * (UA) monitor, disabling it from tracking and monitoring events related + * to the sensor. Removing a sensor from the monitor stops any ongoing + * monitoring activities for that sensor. * @since_tizen 6.5 * @remarks If you want to remove the BLE sensor, * you should add privilege %http://tizen.org/privilege/bluetooth. @@ -226,6 +265,10 @@ int ua_monitor_remove_sensor( /** * @brief Retrieves all sensors present in UA monitor. + * @details This function retrieves all sensors that are currently present in + * the user awareness (UA) monitor. It iterates through the list of sensors + * and invokes the provided callback function for each sensor, passing the + * sensor type and user-provided data to the callback. * @since_tizen 6.5 * * @param[in] monitor The monitor handle @@ -249,6 +292,9 @@ int ua_monitor_foreach_sensor( /** * @brief Checks if sensor is available or not. + * @details This function checks the availability of the specified sensor in + * the user awareness (UA) monitor. It returns a boolean value indicating + * whether the sensor is available or not. * @since_tizen 6.5 * * @param[in] sensor The sensor for which status to be checked. @@ -269,6 +315,10 @@ int ua_monitor_is_sensor_available( /** * @brief Sets sensor status changed callback. Callback to be invoked * when sensor status changes from 'PRESENCE' to 'ABSENCE' or vice-versa. + * @details This function sets a callback function to be invoked whenever + * the status of an environmental sensor changes. The callback function + * will be called with the updated sensor status and user-provided data + * whenever the sensor transitions between 'PRESENCE' and 'ABSENCE' states. * @since_tizen 6.5 * * @remarks Sensor status change will be reported only for environmental @@ -293,6 +343,10 @@ int ua_monitor_set_sensor_status_changed_cb( /** * @brief Unsets sensor status changed callback. + * @details This function unsets the previously set sensor status changed + * callback function for the user awareness (UA) monitor. After this + * function is called, the callback function will no longer be invoked + * when the status of environmental sensors changes. * @since_tizen 6.5 * * @param[in] monitor The monitor handle @@ -310,6 +364,13 @@ int ua_monitor_unset_sensor_status_changed_cb( /** * @brief Starts scan of registered devices. + * @details This function initiates a scan of registered devices using the + * user awareness (UA) monitor. The scan can include Bluetooth Low Energy + * (BLE) and Wi-Fi devices, depending on the privileges granted and the + * sensors added to the monitor. The scan time can be controlled using + * the scan_time_multiplier parameter, which multiplies the predefined + * scan duration constant (#UA_SCAN_TIME_MULTIPLIER) to determine the + * maximum scan time in seconds. * @since_tizen 6.5 * @privlevel public * @privilege %http://tizen.org/privilege/location @@ -349,6 +410,9 @@ int ua_monitor_start_scan( /** * @brief Stops ua_monitor_start_scan(). + * @details This function stops the ongoing scan initiated by + * ua_monitor_start_scan(). It terminates the scan process early + * and prevents further device discovery until another scan is started. * @since_tizen 6.5 * @privlevel public * @privilege %http://tizen.org/privilege/location @@ -374,6 +438,12 @@ int ua_monitor_stop_scan(ua_monitor_h monitor); /** * @brief Starts user presence detection. + * @details This function initiates user presence detection using the user awareness + * (UA) monitor. The detection can include Bluetooth Low Energy (BLE) and Wi-Fi + * presence detection, depending on the privileges granted and the sensors added + * to the monitor. The detection mode parameter determines whether the presence + * detection callback will be invoked only after a user is detected by all sensors + * or as soon as a user is detected by any one of the sensors. * @since_tizen 6.5 * @privlevel public * @privilege %http://tizen.org/privilege/location @@ -417,6 +487,10 @@ int ua_monitor_start_presence_detection( /** * @brief Stops user presence detection. + * @details This function stops the ongoing user presence detection + * initiated by ua_monitor_start_presence_detection(). It terminates + * the detection process early and prevents further presence detection + * until another detection is started. * @since_tizen 6.5 * @privlevel public * @privilege %http://tizen.org/privilege/location @@ -443,6 +517,13 @@ int ua_monitor_stop_presence_detection( /** * @brief Starts user absence detection. + * @details This function initiates user absence detection using the + * user awareness (UA) monitor. The detection can include Bluetooth + * Low Energy (BLE) and Wi-Fi absence detection, depending on the + * privileges granted and the sensors added to the monitor. The + * detection mode parameter determines whether the absence detection + * callback will be invoked only after no user is detected by all + * sensors or as soon as no user is detected by any one of the sensors. * @since_tizen 6.5 * @privlevel public * @privilege %http://tizen.org/privilege/location @@ -486,6 +567,10 @@ int ua_monitor_start_absence_detection( /** * @brief Stops user absence detection. + * @details This function stops the ongoing user absence detection + * initiated by ua_monitor_start_absence_detection(). It terminates + * the detection process early and prevents further absence detection + * until another detection is started. * @since_tizen 6.5 * @privlevel public * @privilege %http://tizen.org/privilege/location @@ -514,6 +599,12 @@ int ua_monitor_stop_absence_detection( * @brief Sets the location callback period in milli-seconds. * If location period is not set, it will be automatically * set to #UA_LOCATION_PERIOD_DEFAULT. + * @details This function sets the interval at which location + * updates are received from the user awareness (UA) monitor. + * If the location period is not explicitly set, it defaults + * to #UA_LOCATION_PERIOD_DEFAULT. The location period is + * specified in milliseconds and must be within the range + * of 0 to UINT_MAX. * @since_tizen 6.5 * * @param[in] monitor The monitor handle @@ -529,6 +620,13 @@ int ua_monitor_set_location_period( /** * @brief Starts user location detection. + * @details This function initiates user location detection using the + * user awareness (UA) monitor. The detection can include Bluetooth + * Low Energy (BLE) and Wi-Fi location detection, depending on the + * privileges granted and the sensors added to the monitor. The + * location detection callback will be invoked periodically based + * on the location period set by ua_monitor_set_location_period() + * or the default period. * @since_tizen 6.5 * @privlevel public * @privilege %http://tizen.org/privilege/location @@ -564,6 +662,10 @@ int ua_monitor_start_location_detection( /** * @brief Stops user location detection. + * @details This function stops the ongoing user location detection + * initiated by ua_monitor_start_location_detection(). It terminates + * the detection process early and prevents further location detection + * until another detection is started. * @since_tizen 6.5 * @privlevel public * @privilege %http://tizen.org/privilege/location @@ -590,6 +692,12 @@ int ua_monitor_stop_location_detection( /** * @brief Creates the user handle. + * @details This function creates a new user handle with the given + * account information. The account parameter represents the user's + * unique identifier, such as an email address or username. The + * maximum length of the account string is limited to 254 characters. + * The created user handle can be used to interact with the user + * awareness (UA) framework. * @since_tizen 6.5 * * @remarks The @a user handle should be destroyed by using ua_user_destroy(). @@ -612,6 +720,10 @@ int ua_user_create(const char *account, /** * @brief Destroys the user handle. + * @details This function destroys the user handle created by ua_user_create(). + * Destroying the user handle removes the user context and releases any + * allocated memory associated with it. After calling this function, the + * user handle becomes invalid and should not be used again. * @since_tizen 6.5 * * @remarks User context will removed and all allocated memory (if any) will be released. @@ -632,6 +744,11 @@ int ua_user_destroy( /** * @brief Adds the user. Added user is stored in the database * and is also available after the application restarts. + * @details This function adds the user represented by the user + * handle to the user awareness (UA) framework's database. + * Once added, the user remains registered even after the + * application restarts, allowing the application to continue + * monitoring the user's presence and location. * @since_tizen 6.5 * * @param[in] user The user handle @@ -650,6 +767,10 @@ int ua_user_add(ua_user_h user); /** * @brief Removes the user. + * @details This function removes the user represented by the user + * handle from the user awareness (UA) framework's database. + * Removing the user handle effectively unregisters the user, + * making them unavailable for monitoring by the application. * @since_tizen 6.5 * * @param[in] user The user handle @@ -667,6 +788,10 @@ int ua_user_remove(ua_user_h user); /** * @brief Gets account info for user handle. + * @details This function retrieves the account information + * associated with the user handle. The account information + * is returned as a null-terminated string and should be + * freed using g_free() after use. * @since_tizen 6.5 * * @remarks You must release @a account using g_free(). @@ -687,6 +812,11 @@ int ua_user_get_account(ua_user_h user, char **account); /** * @brief Adds device for a user. This information is stored in database * and is also available after the application restarts. + * @details This function adds a device to the user's profile in the user + * awareness (UA) framework's database. The device handle represents + * the device to be added, which can be a Bluetooth Low Energy (BLE) + * device or a Wi-Fi device, depending on the privileges granted and + * the type of device being added. * @since_tizen 6.5 * @remarks If you want to add the BLE device, * you should add privilege %http://tizen.org/privilege/bluetooth. @@ -717,6 +847,11 @@ int ua_user_add_device( /** * @brief Removes the device handle for a user handle. * @since_tizen 6.5 + * @details This function removes the specified device from the user's + * profile in the user awareness (UA) framework's database. The + * device handle represents the device to be removed, which can be + * a Bluetooth Low Energy (BLE) device or a Wi-Fi device, depending + * on the privileges granted and the type of device being removed. * @remarks If you want to remove the BLE device, * you should add privilege %http://tizen.org/privilege/bluetooth. * if you want to remove the Wi-Fi device, @@ -742,6 +877,11 @@ int ua_user_remove_device( /** * @brief Retrieves the device handle of all the registered devices for a specific user. + * @details This function retrieves all the device handles that are registered + * for the specified user in the user awareness (UA) framework's database. + * The foreach_cb callback function is called once for each registered device, + * providing the user and device handles along with the user data provided + * during the call. * @since_tizen 6.5 * * @param[in] user The user handle. @@ -764,6 +904,11 @@ int ua_user_foreach_devices( /** * @brief Creates the service handle. + * @details This function creates a new service handle with the given + * service name information. The service name represents the unique + * identifier for the service, such as a service name or ID. The + * created service handle can be used to interact with the user + * awareness (UA) framework. * @since_tizen 6.5 * * @remarks The @a service handle should be destroyed by using ua_service_destroy(). @@ -786,6 +931,11 @@ int ua_service_create( /** * @brief Destroys the service handle. + * @details This function destroys the service handle created by + * ua_service_create(). Destroying the service handle removes + * the service context and releases any allocated memory + * associated with it. After calling this function, the + * service handle becomes invalid and should not be used again. * @since_tizen 6.5 * * @remarks Service context will be removed and all allocated memory (if any) will be released. @@ -806,6 +956,11 @@ int ua_service_destroy( /** * @brief Adds the service. Added service is stored in database * and is also available after the application restarts. + * @details This function adds the service represented by the service + * handle to the user awareness (UA) framework's database. Once added, + * the service remains registered even after the application restarts, + * allowing the application to continue monitoring the service's + * availability and status. * @since_tizen 6.5 * * @param[in] service The service handle @@ -826,6 +981,11 @@ int ua_service_add( * @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(). + * @details To update a property of a service, its respective setter functions + * should be called to modify the desired property values, and then ua_service_update() + * should be called to commit the changes to the user awareness (UA) framework's database. + * This ensures that the updated service properties are persisted and available after + * the application restarts. * @since_tizen 6.5 * * @param[in] service The service handle @@ -845,6 +1005,10 @@ int ua_service_update( /** * @brief Removes the service. + * @details This function removes the service represented by the service + * handle from the user awareness (UA) framework's database. Removing + * the service handle effectively unregisters the service, making it + * unavailable for monitoring by the application. * @since_tizen 6.5 * * @param[in] service The service handle @@ -863,6 +1027,9 @@ int ua_service_remove( /** * @brief Gets name info for service handle. + * @details This function retrieves the name information associated + * with the service handle. The name information is returned as a + * null-terminated string and should be freed using g_free() after use. * @since_tizen 6.5 * * @remarks You must release @a name using g_free(). @@ -886,6 +1053,13 @@ int ua_service_get_name( * @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. + * @details This function sets the detection thresholds for the service handle. + * The presence threshold specifies the minimum light level (in lux) required + * for the service to be considered present, while the absence threshold + * specifies the maximum light level (in lux) required for the service to be + * considered absent. If the service has already been added, this call should + * be followed by the call of ua_service_update() to reflect the modifications + * in the user awareness (UA) framework's database. * @since_tizen 6.5 * * @param[in] service The service handle @@ -906,6 +1080,11 @@ int ua_service_set_detection_threshold( /** * @brief Gets detection threshold for service handle. + * @details This function retrieves the detection thresholds for the service + * handle. The presence threshold specifies the minimum light level (in lux) + * required for the service to be considered present, while the absence + * threshold specifies the maximum light level (in lux) required for the + * service to be considered absent. * @since_tizen 6.5 * * @param[in] service The service handle @@ -927,6 +1106,9 @@ int ua_service_get_detection_threshold( /** * @brief Sets name info for service handle. + * @details This function sets the name information for the service + * handle. The name information is used to identify the service + * within the user awareness (UA) framework. * @since_tizen 6.5 * * @remarks The @a user should not be released. @@ -950,6 +1132,9 @@ int ua_service_get_user_by_account(ua_service_h service, /** * @brief Adds a user for a specific service. + * @details This function adds a user to a specific service within + * the user awareness (UA) framework. Adding a user allows the + * service to monitor the user's presence and status. * @since_tizen 6.5 * * @param[in] service The service handle. @@ -969,6 +1154,9 @@ int ua_service_add_user( /** * @brief Removes the user for the specific service handle. + * @details This function removes a user from a specific service + * within the user awareness (UA) framework. Removing a user + * stops the service from monitoring the user's presence and status. * @since_tizen 6.5 * * @param[in] service The service handle. @@ -989,6 +1177,11 @@ int ua_service_remove_user( /** * @brief Triggers callback for every user of a specific service. + * @details This function iterates through all users associated with + * a specific service within the user awareness (UA) framework and + * triggers the provided callback function for each user. The + * callback function receives the user handle and any additional + * user data specified by the caller. * @since_tizen 6.5 * * @param[in] service The service handle. @@ -1010,6 +1203,10 @@ int ua_service_foreach_users( /** * @brief Creates the device handle. + * @details This function creates a new device handle for a given MAC address + * type, MAC address, and device ID. The device handle represents a physical + * device within the user awareness (UA) framework and can be used to manage + * the device's properties and interactions. * @since_tizen 6.5 * * @remarks The @a device handle should be destroyed using ua_user_destroy(). @@ -1036,6 +1233,10 @@ int ua_device_create(ua_mac_type_e mac_type, /** * @brief Destroys the device handle. + * @details This function destroys the device handle, removing the device + * context and releasing any allocated memory associated with it. After + * calling this function, the device handle becomes invalid and should + * not be used further. * @since_tizen 6.5 * * @remarks Device context will be removed and all allocated memory (if any) will be released. @@ -1055,6 +1256,9 @@ int ua_device_destroy( /** * @brief Gets device type info from the device. + * @details This function retrieves the MAC address type of the device + * represented by the device handle. The MAC address type indicates + * whether the device uses a 48-bit or 64-bit MAC address. * @since_tizen 6.5 * * @param[in] device The device handle @@ -1073,6 +1277,11 @@ int ua_device_get_mac_type( * @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. + * @details This function sets the operating system information for the + * device represented by the device handle. If the device has already + * been added to the user awareness (UA) framework, this call should + * be followed by the call of ua_device_update() to reflect the + * modifications in the UA framework's database. * @since_tizen 6.5 * * @param[in] device The device handle @@ -1092,6 +1301,10 @@ int ua_device_set_os_info( /** * @brief Gets device's operating system info. + * @details This function retrieves the operating system information + * for the device represented by the device handle. The operating + * system information indicates which operating system the device + * is running. * @since_tizen 6.5 * * @param[in] device The device handle @@ -1109,6 +1322,9 @@ int ua_device_get_os_info( /** * @brief Gets device's MAC address. + * @details This function retrieves the MAC address of the device + * represented by the device handle. The MAC address uniquely + * identifies the device within the network. * @since_tizen 6.5 * * @remarks You must release @a mac_address using g_free(). @@ -1127,6 +1343,9 @@ int ua_device_get_mac_address( /** * @brief Gets device ID of device, which was set while creating the device handle. + * @details This function retrieves the device ID of the device represented by + * the device handle. The device ID is a unique identifier assigned to the + * device during its creation. * @since_tizen 6.5 * * @remarks You must release @a device_id using g_free(). @@ -1146,6 +1365,12 @@ int ua_device_get_device_id( * @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. + * @details This function sets the Wi-Fi Basic Service Set Identifier (BSSID) + * for the device represented by the device handle. The BSSID is a unique + * identifier for the wireless access point that the device is connected + * to. If the device has already been added to the user awareness (UA) + * framework, this call should be followed by the call of ua_device_update() + * to reflect the modifications in the UA framework's database. * @since_tizen 6.5 * * @param[in] device The device handle @@ -1165,6 +1390,10 @@ int ua_device_set_wifi_bssid( /** * @brief Gets device's Wi-Fi BSSID. + * @details This function retrieves the Wi-Fi Basic Service Set Identifier + * (BSSID) for the device represented by the device handle. The BSSID + * is a unique identifier for the wireless access point that the device + * is connected to. * @since_tizen 6.5 * * @remarks You must release @a bssid using g_free(). @@ -1184,6 +1413,12 @@ int ua_device_get_wifi_bssid( * @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. + * @details This function sets the IPv4 address of the device's Wi-Fi interface + * for the device represented by the device handle. The IPv4 address is a + * unique identifier for the device within the network. If the device has + * already been added to the user awareness (UA) framework, this call should + * be followed by the call of ua_device_update() to reflect the modifications + * in the UA framework's database. * @since_tizen 6.5 * * @param[in] device The device handle @@ -1203,6 +1438,10 @@ int ua_device_set_wifi_ipv4_address( /** * @brief Gets device's Wi-Fi IPv4 address. + * @details This function retrieves the IPv4 address of the device's + * Wi-Fi interface for the device represented by the device handle. + * The IPv4 address is a unique identifier for the device within + * the network. * @since_tizen 6.5 * * @remarks You must release @a ipv4_address using g_free(). @@ -1222,6 +1461,10 @@ int ua_device_get_wifi_ipv4_address( /** * @brief Gets last presence time for device handle. + * @details This function retrieves the last presence timestamp for the device + * represented by the device handle. The last presence timestamp indicates + * the most recent time at which the device was detected or interacted with + * within the user awareness (UA) framework. * @since_tizen 6.5 * * @param[in] device The device handle @@ -1238,6 +1481,11 @@ int ua_device_get_last_presence( /** * @brief Gets whether pairing is required for the user device. + * @details This function retrieves the pairing requirement status for the + * device represented by the device handle. Pairing is a process where + * two devices establish a secure connection and exchange authentication + * credentials. If pairing is required, it means that the device needs + * to go through the pairing process before it can be used or accessed. * @since_tizen 6.5 * * @param[in] device The device handle @@ -1260,6 +1508,12 @@ int ua_device_get_pairing_required( * @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(). + * @details This function updates the properties of an existing device in + * the user awareness (UA) framework. To update a property of a device, + * its respective setter functions should be called first, and then + * followed by the call of ua_device_update(). This ensures that the + * changes made to the device's properties are reflected in the UA + * framework's database. * @since_tizen 6.5 * @remarks If you want to update BLE device, * you should add privilege %http://tizen.org/privilege/bluetooth. @@ -1284,6 +1538,11 @@ int ua_device_update( /** * @brief Gets device handle by MAC address. + * @details This function retrieves the device handle for a specific device + * identified by its MAC address. The MAC address is a unique identifier + * for the device within the network. The retrieved device handle can be + * used to access and manipulate the device's properties and functionalities + * within the user awareness (UA) framework. * @since_tizen 6.5 * * @remarks The @a device handle should not be released. @@ -1308,6 +1567,13 @@ int ua_device_get_by_mac_address( /** * @brief Gets device handle by device ID. + * @details This function retrieves the device handle for a specific device + * identified by its device ID and MAC type. The device ID is a unique + * identifier assigned to the device during its creation, while the MAC + * type specifies the type of MAC address (e.g., Wi-Fi, Bluetooth) + * associated with the device. The retrieved device handle can be used + * to access and manipulate the device's properties and functionalities + * within the user awareness (UA) framework. * @since_tizen 6.5 * * @remarks The @a device handle should not be released. @@ -1334,6 +1600,11 @@ int ua_device_get_by_device_id( /** * @brief Gets sensor's status report. + * @details This function retrieves the status report of the sensor + * represented by the sensor handle. The status report provides + * information about the current state and operational status of + * the sensor, such as whether it is active, idle, or experiencing + * any issues. * @since_tizen 6.5 * * @param[in] sensor The sensor handle @@ -1352,6 +1623,10 @@ int ua_sensor_get_status( /** * @brief Gets sensor's timestamp. + * @details This function retrieves the timestamp of the sensor represented + * by the sensor handle. The timestamp indicates the time at which the + * sensor data was captured or generated. It can be useful for determining + * the freshness or recency of the sensor readings. * @since_tizen 6.5 * * @param[in] sensor The sensor handle @@ -1370,6 +1645,11 @@ int ua_sensor_get_timestamp( /** * @brief Gets sensor's type. + * @details This function retrieves the type of the sensor represented by + * the sensor handle. The sensor type indicates the kind of sensor, + * such as temperature, humidity, motion, etc. Knowing the sensor type + * helps in understanding the nature of the sensor and the kind of data + * it provides. * @since_tizen 6.5 * * @param[in] sensor The sensor handle @@ -1388,6 +1668,11 @@ int ua_sensor_get_type( /** * @brief Gets the distance for the location handle. + * @details This function retrieves the distance between the user and the + * detected device, represented by the location handle. The distance is + * measured in a unit specified by the implementation, such as meters + * or feet. This information can be useful for determining the proximity + * of the device to the user. * @since_tizen 6.5 * @privlevel public * @privilege %http://tizen.org/privilege/location @@ -1405,6 +1690,12 @@ int ua_location_get_distance(ua_location_h location, int *distance); /** * @brief Gets the position for the location handle. + * @details This function retrieves the position coordinates (x, y, z) of + * the detected device, represented by the location handle. The position + * coordinates indicate the spatial location of the device within a + * coordinate system defined by the implementation. This information can + * be useful for determining the exact location of the device relative + * to the user or other reference points. * @since_tizen 6.5 * @privlevel public * @privilege %http://tizen.org/privilege/location