From ad7c7a4fbde1a815fddf7c83b774986b4d926d23 Mon Sep 17 00:00:00 2001 From: Unsung Lee Date: Mon, 23 Sep 2024 16:00:49 +0900 Subject: [PATCH] battery_monitor: Update description of battery_monitor Update description of battery_monitor in each tags. Change-Id: Id68cf7fc81eed117a58a5e6f6ddd5db77a479794 Signed-off-by: Unsung Lee --- include/battery_monitor.h | 87 +++++++++++++++++++++++++++++---------- 1 file changed, 65 insertions(+), 22 deletions(-) diff --git a/include/battery_monitor.h b/include/battery_monitor.h index 8b4830b..c0a86e8 100644 --- a/include/battery_monitor.h +++ b/include/battery_monitor.h @@ -70,53 +70,71 @@ typedef struct battery_monitor_total_consumption_s* battery_usage_data_h; /** * @brief Destroys the Battery Consumption handle and releases all its resources. + * @details Releases all resources in battery_monitor_total_consumption_s structure using free(). * @since_tizen 5.5 - * + * @remarks User cannot access resources in @a result after completion of the call. * @param[in] result Battery usage consumption handle for the application - * * @return @c 0 on success, * otherwise a negative error value * @retval #BATTERY_MONITOR_ERROR_NONE Successful * @retval #BATTERY_MONITOR_ERROR_NOT_SUPPORTED Feature Not Supported * @retval #BATTERY_MONITOR_ERROR_INVALID_PARAMETER Invalid Parameter + * @see battery_monitor_get_power_usage_by_app_for_all_resources() + * @code + * battery_usage_data_h data_handle = NULL; + * battery_monitor_get_power_usage_by_app_for_all_resources("org.test.app", + * (time_t)100, (time_t)1000, &data_handle); + * // Using battery info in data_handle + * + * // Release battery info in data_handle + * battery_monitor_battery_usage_data_destroy(data_handle); + * @endcode */ int battery_monitor_battery_usage_data_destroy(battery_usage_data_h result); /** * @brief Gets the battery consumption in mAh (milli-Ampere hour) for specific resource from available data usage handle. + * @details Retrives the battery comsumption for specific resource defined in battery_monitor_resource_id_e + * and change battery consumption in mAh. * @since_tizen 5.5 * @privlevel public * @privilege %http://tizen.org/privilege/systemmonitor - * + * @remarks Must be executed after calling battery_monitor_get_power_usage_by_app_for_all_resources(). * @param[in] result Battery consumption data usage handle for the application * @param[in] resource Identifier of resource type. BLE, WiFi, CPU etc * @param[out] usage Battery consumption in mAh for @a resource - * * @return @c 0 on success, * otherwise a negative error value * @retval #BATTERY_MONITOR_ERROR_NONE Successful * @retval #BATTERY_MONITOR_ERROR_NOT_SUPPORTED Feature Not Supported * @retval #BATTERY_MONITOR_ERROR_PERMISSION_DENIED Permission Denied * @retval #BATTERY_MONITOR_ERROR_INVALID_PARAMETER Invalid Parameter - * * @pre call battery_monitor_get_power_usage_by_app_for_all_resources() to get data handle + * @code + * double usage; + * battery_usage_data_h data_handle = NULL; + * battery_monitor_get_power_usage_by_app_for_all_resources("org.test.app", + * (time_t)100, (time_t)1000, &data_handle); + * + * battery_monitor_usage_data_get_power_usage_per_resource(data_handle, + * BATTERY_MONITOR_RESOURCE_ID_BLE, &usage) + * @endcode */ int battery_monitor_usage_data_get_power_usage_per_resource(battery_usage_data_h result, battery_monitor_resource_id_e resource, double* usage); /** - * @brief Gets the #battery_usage_data_h with battery consumption values in mAh (milli-Ampere hour) by the specified application in custom interval. - * Data within the last 7 days can be retrieved. + * @brief Gets the #battery_usage_data_h with battery consumption values in mAh (milli-Ampere hour). + * @details Retrieves the battery consumption used by a specific application for a certain period of time, + * based on each resource declared in battery_usage_data_h. * @since_tizen 5.5 * @privlevel public * @privilege %http://tizen.org/privilege/systemmonitor - * - * @remarks The @a result handle should be released using battery_monitor_battery_usage_data_destroy(). - * + * @remarks The @a result handle should be released using battery_monitor_battery_usage_data_destroy(). \n + * Data within up to the last seven days can be retrieved. * @param[in] appid Application ID of the application for which battery usage is required * @param[in] from Start Time for data in Epoch Time (in seconds) * @param[in] to End Time for data in Epoch Time (in seconds) * @param[out] result Battery consumption data handle for the application - * * @return @c 0 on success, * otherwise a negative error value * @retval #BATTERY_MONITOR_ERROR_NONE Successful @@ -127,24 +145,25 @@ int battery_monitor_usage_data_get_power_usage_per_resource(battery_usage_data_h * @retval #BATTERY_MONITOR_ERROR_DB_FAILED DB operation failed * @retval #BATTERY_MONITOR_ERROR_RECORD_NOT_FOUND Record Not found * @retval #BATTERY_MONITOR_ERROR_INTERNAL Internal Error - * * @see battery_monitor_usage_data_get_power_usage_per_resource() + * @see battery_monitor_get_power_usage_by_app() + * @see battery_monitor_get_power_usage_by_resource() */ int battery_monitor_get_power_usage_by_app_for_all_resources(const char* appid, time_t from, time_t to, battery_usage_data_h* result); /** - * @brief Gets the battery consumption in mAh (milli-Ampere hour) for the specific resource for the given application in custom interval. - * Data within the last 7 days can be retrieved. + * @brief Gets the battery consumption in mAh (milli-Ampere hour) for the specific resource. + * @details Retrieves the battery consumption used by a specific application for a certain period of time, + * based on a specific resource. * @since_tizen 5.5 * @privlevel public * @privilege %http://tizen.org/privilege/systemmonitor - * + * @remarks Data within up to the last seven days can be retrieved. * @param[in] appid Application ID of the application for which battery usage is required * @param[in] resource Identifier of resource type. BLE, WiFi, CPU etc * @param[in] from Start Time for data in Epoch Time (in seconds) * @param[in] to End Time for data in Epoch Time (in seconds) * @param[out] usage Battery consumption in mAh for the application - * * @return @c 0 on success, * otherwise a negative error value * @retval #BATTERY_MONITOR_ERROR_NONE Successful @@ -155,21 +174,29 @@ int battery_monitor_get_power_usage_by_app_for_all_resources(const char* appid, * @retval #BATTERY_MONITOR_ERROR_DB_FAILED DB operation failed * @retval #BATTERY_MONITOR_ERROR_RECORD_NOT_FOUND Record Not found * @retval #BATTERY_MONITOR_ERROR_INTERNAL Internal Error + * @see battery_monitor_get_power_usage_by_app_for_all_resources() + * @see battery_monitor_get_power_usage_by_app() + * @see battery_monitor_get_power_usage_by_resource() + * @code + * double usage; + * battery_monitor_get_power_usage_by_app_for_per_resource("org.test.app", + * BATTERY_MONITOR_RESOURCE_ID_BLE, + * (time_t)100, (time_t)1000, &usage); + * @endcode */ int battery_monitor_get_power_usage_by_app_per_resource(const char* appid, battery_monitor_resource_id_e resource, time_t from, time_t to, double* usage); /** - * @brief Gets the total battery usage in mAh (milli-Ampere hour) by an application for certain time interval. Data within the last 7 days can be retrieved. + * @brief Gets the total battery usage in mAh (milli-Ampere hour). * @details This will be sum of all battery consumed by resources used by application. * @since_tizen 5.5 * @privlevel public * @privilege %http://tizen.org/privilege/systemmonitor - * + * @remarks Data within up to the last seven days can be retrieved. * @param[in] appid Application ID of the application for which battery usage is required * @param[in] from Start Time for data in Epoch Time (in seconds) * @param[in] to End Time for data in Epoch Time (in seconds) * @param[out] usage Battery consumption in mAh for the application - * * @return @c 0 on success, * otherwise a negative error value * @retval #BATTERY_MONITOR_ERROR_NONE Successful @@ -180,20 +207,28 @@ int battery_monitor_get_power_usage_by_app_per_resource(const char* appid, batte * @retval #BATTERY_MONITOR_ERROR_DB_FAILED DB operation failed * @retval #BATTERY_MONITOR_ERROR_RECORD_NOT_FOUND Record Not found * @retval #BATTERY_MONITOR_ERROR_INTERNAL Internal Error + * @see battery_monitor_get_power_usage_by_app_for_all_resources() + * @see battery_monitor_get_power_usage_by_app_per_resource() + * @see battery_monitor_get_power_usage_by_resource() + * @code + * double usage; + * battery_monitor_get_power_usage_by_app("org.test.app", + * (time_t)100, (time_t)1000, &usage); + * @endcode */ int battery_monitor_get_power_usage_by_app(const char* appid, time_t from, time_t to, double* usage); /** - * @brief Gets the battery usage in mAh (milli-Ampere hour) by a resource for certain time interval. Data within the last 7 days can be retrieved. + * @brief Gets the battery usage in mAh (milli-Ampere hour) by a resource. + * @details Retrieves the battery consumption used by a specific resource for a certain period of time. * @since_tizen 5.5 * @privlevel public * @privilege %http://tizen.org/privilege/systemmonitor - * + * @remarks Data within up to the last seven days can be retrieved. * @param[in] resource Resource identifier for which battery usage is requested * @param[in] from Start Time for data in Epoch Time (in seconds) * @param[in] to End Time for data in Epoch Time (in seconds) * @param[out] usage Battery consumption in mAh (milli-Ampere hour) for resource - * * @return @c 0 on success, * otherwise a negative error value * @retval #BATTERY_MONITOR_ERROR_NONE Successful @@ -204,6 +239,14 @@ int battery_monitor_get_power_usage_by_app(const char* appid, time_t from, time_ * @retval #BATTERY_MONITOR_ERROR_DB_FAILED DB operation failed * @retval #BATTERY_MONITOR_ERROR_RECORD_NOT_FOUND Record Not found * @retval #BATTERY_MONITOR_ERROR_INTERNAL Internal Error + * @see battery_monitor_get_power_usage_by_app_for_all_resources() + * @see battery_monitor_get_power_usage_by_app_per_resource() + * @see battery_monitor_get_power_usage_by_app() + * @code + * double usage; + * battery_monitor_get_power_usage_by_app(BATTERY_MONITOR_RESOURCE_ID_BLE, + * (time_t)100, (time_t)1000, &usage); + * @endcode */ int battery_monitor_get_power_usage_by_resource(battery_monitor_resource_id_e resource, time_t from, time_t to, double* usage); -- 2.34.1