/**
* @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
/**
* @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
/**
* @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.
/**
* @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
/**
* @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().
/**
* @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().
/**
* @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
/**
* @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.
/**
* @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.
/**
* @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
/**
* @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.
/**
* @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
/**
* @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
/**
* @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
/**
* @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
/**
* @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
/**
* @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
/**
* @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
/**
* @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
* @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
/**
* @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
/**
* @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
/**
* @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().
/**
* @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.
/**
* @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
/**
* @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
/**
* @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().
/**
* @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.
/**
* @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,
/**
* @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.
/**
* @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().
/**
* @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.
/**
* @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
* @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
/**
* @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
/**
* @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().
* @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
/**
* @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
/**
* @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.
/**
* @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.
/**
* @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.
/**
* @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.
/**
* @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().
/**
* @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.
/**
* @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
* @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
/**
* @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
/**
* @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().
/**
* @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().
* @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
/**
* @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().
* @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
/**
* @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().
/**
* @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
/**
* @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
* @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.
/**
* @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.
/**
* @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.
/**
* @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
/**
* @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
/**
* @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
/**
* @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
/**
* @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
projects / platform / core / api / user-awareness.git / commitdiff