From 32bb0305e069de9e46c635bb400490cf5e217dea Mon Sep 17 00:00:00 2001 From: Junghyun Yeon Date: Mon, 27 Aug 2018 11:50:12 +0900 Subject: [PATCH] Add comments for doxygen Signed-off-by: Junghyun Yeon --- include/capability-manager.h | 427 ++++++++++++++++++++++++++++++++++++++----- 1 file changed, 382 insertions(+), 45 deletions(-) diff --git a/include/capability-manager.h b/include/capability-manager.h index 52e831a..41986c6 100644 --- a/include/capability-manager.h +++ b/include/capability-manager.h @@ -11,236 +11,573 @@ extern "C" { #endif +/** + * @file capability-manager.h + */ + +/** + * @addtogroup CAPI_CAPABILITY_MANAGER_MODULE + * @{ + */ /** - * @brief + * @brief Enumerations for Capability Manager Errors. + * @since_tizen 5.0 */ typedef enum { - CAPMGR_ERROR_NONE = TIZEN_ERROR_NONE, - CAPMGR_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, - CAPMGR_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, - CAPMGR_ERROR_IO_ERROR = TIZEN_ERROR_IO_ERROR, + CAPMGR_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */ + CAPMGR_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */ + CAPMGR_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /**< Out of memory */ + CAPMGR_ERROR_IO_ERROR = TIZEN_ERROR_IO_ERROR, /**< Internal I/O error */ } capmgr_error_e; +/** + * @brief Enumerations for Capability Manager app control result type. + * @since_tizen 5.0 + */ typedef enum { - CAPMGR_APP_CONTROL_RESULT_OK, + CAPMGR_APP_CONTROL_RESULT_OK, /**< Successful */ } capmgr_app_control_result_e; /** - * @brief + * @brief Capability Manager device handle. + * @since_tizen 5.0 */ typedef struct capmgr_device_s* capmgr_device_h; /** - * @brief + * @brief Capability Manager app control handle. + * @since_tizen 5.0 */ typedef struct capmgr_app_control_s* capmgr_app_control_h; /** - * @brief + * @brief Capability Manager package info handle. + * @since_tizen 5.0 */ typedef struct capmgr_package_info_s* capmgr_package_info_h; /** - * @brief + * @brief Called to retrieve information of devices currently discovered. + * @since_tizen 5.0 + * + * @remarks The @a device can be used only in the callback. To use outside, make a copy. + * @param[in] device Device handle + * @param[in] user_data The user data to be passed to the callback function + * @see capmgr_device_foreach_devices() */ typedef int (*capmgr_device_foreach_cb)(const capmgr_device_h device, void* user_data); /** - * @brief + * @brief Called when send app control request has finished. + * @since_tizen 5.0 + * + * @remarks The @a request, @reply can be used only in the callback. To use outside, make a copy. + * @param[in] request Capability Manager app control handle contains data to be sent + * @param[in] reply Capability Manager app control handle which contains + * reply for request + * @param[in] result App control send result + * @param[in] user_data The user data to be passed to the callback function + * @see capmgr_app_control_send() */ typedef int (*capmgr_app_control_reply_cb)(const capmgr_app_control_h request, const capmgr_app_control_h reply, capmgr_app_control_result_e result, void* user_data); /** - * @brief + * @brief Called for each remote package info. + * @since_tizen 5.0 + * + * @remarks The @a remote_package_info can be used only in the callback. To use outside, make a copy. + * @param[in] remote_package_info Capability Manager package info handle + * @param[in] user_data The user data to be passed to the callback function + * @see capmgr_package_info_foreach_packages() */ typedef int (*capmgr_package_info_foreach_package_cb)( const capmgr_package_info_h remote_package_info, void* user_data); /** - * @brief + * @brief Called for each application of remote package. + * @since_tizen 5.0 + * + * @remarks The @a appid can be used only in the callback. To use outside, make a copy. + * @param[in] appid Application ID of remote application + * @param[in] user_data The user data to be passed to the callback function + * @see capmgr_package_info_foreach_applications() */ typedef int (*capmgr_package_info_foreach_app_cb)( const char* appid, void* user_data); /** - * @brief + * @brief Retrieves all remote device info stored on local device. + * @since_tizen 5.0 + * + * @param[in] cb The callback function to invoke + * @param[in] user_data The user data to be passed to the callback function + * @return @c 0 on success, + * otherwise a negative error value + * @retval #CAPMGR_ERROR_NONE Successful + * @retval #CAPMGR_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #CAPMGR_ERROR_IO_ERROR Internal I/O error + * @post This function invokes capmgr_device_foreach_cb() for each remote device information. + * @see capmgr_device_foreach_cb() + * */ int capmgr_device_foreach_devices(capmgr_device_foreach_cb cb, void* user_data); /** - * @brief + * @brief Clones the remote device information handle. + * @since_tizen 5.0 + * @param[in] device The remote device handle + * @param[out] device_clone A newly created remote device information handle, if successfully cloned + * @return @c 0 on success, + * otherwise a negative error value + * @retval #CAPMGR_ERROR_NONE Successful + * @retval #CAPMGR_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #CAPMGR_ERROR_OUT_OF_MEMORY Out of memory */ int capmgr_device_clone(const capmgr_device_h device, capmgr_device_h* device_clone); /** - * @brief + * @brief Destroys the remote device information handle and releases all its resources. + * @since_tizen 5.0 + * @param[in] device The remote device information handle + * @return @c 0 on success, + * otherwise a negative error value + * @retval #CAPMGR_ERROR_NONE Successful + * @retval #CAPMGR_ERROR_INVALID_PARAMETER Invalid parameter + * @see capmgr_device_clone() + * @see capmgr_device_foreach_devices() */ int capmgr_device_destroy(capmgr_device_h device); /** - * @brief + * @brief Gets the device ID with the given remote device context. + * @since_tizen 5.0 + * @remarks You must release @a device_id using free(). + * @param[in] device The remote device information handle + * @param[out] device_id The remote device ID of the given remote device context + * @return @c 0 on success, + * otherwise a negative error value + * @retval #CAPMGR_ERROR_NONE Successful + * @retval #CAPMGR_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #CAPMGR_ERROR_OUT_OF_MEMORY Out of memory + * @see capmgr_device_clone() + * @see capmgr_device_foreach_devices() */ int capmgr_device_get_device_id(capmgr_device_h device, char** device_id); /** - * @brief + * @brief Gets the model name with the given remote device context. + * @since_tizen 5.0 + * @remarks You must release @a model_name using free(). + * @param[in] device The remote device information handle + * @param[out] model_name The model name of the given remote device context + * @return @c 0 on success, + * otherwise a negative error value + * @retval #CAPMGR_ERROR_NONE Successful + * @retval #CAPMGR_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #CAPMGR_ERROR_OUT_OF_MEMORY Out of memory + * @see capmgr_device_clone() + * @see capmgr_device_foreach_devices() */ int capmgr_device_get_model_name(capmgr_device_h device, char** model_name); /** - * @brief + * @brief Gets the device name with the given remote device context. + * @since_tizen 5.0 + * @remarks You must release @a device_name using free(). + * @param[in] device The remote device information handle + * @param[out] device_name The device name of the given remote device context + * @return @c 0 on success, + * otherwise a negative error value + * @retval #CAPMGR_ERROR_NONE Successful + * @retval #CAPMGR_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #CAPMGR_ERROR_OUT_OF_MEMORY Out of memory + * @see capmgr_device_clone() + * @see capmgr_device_foreach_devices() */ int capmgr_device_get_device_name(capmgr_device_h device, char** device_name); /** - * @brief + * @brief Gets the platform verion with the given remote device context. + * @since_tizen 5.0 + * @remarks You must release @a platform_ver using free(). + * @param[in] device The remote device information handle + * @param[out] platform_ver The platform version of the given remote device context + * @return @c 0 on success, + * otherwise a negative error value + * @retval #CAPMGR_ERROR_NONE Successful + * @retval #CAPMGR_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #CAPMGR_ERROR_OUT_OF_MEMORY Out of memory + * @see capmgr_device_clone() + * @see capmgr_device_foreach_devices() */ int capmgr_device_get_platform_ver(capmgr_device_h device, char** platform_ver); /** - * @brief + * @brief Gets the profile with the given remote device context. + * @since_tizen 5.0 + * @remarks You must release @a profile using free(). + * @param[in] device The remote device information handle + * @param[out] profile The profile value of the given remote device context + * @return @c 0 on success, + * otherwise a negative error value + * @retval #CAPMGR_ERROR_NONE Successful + * @retval #CAPMGR_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #CAPMGR_ERROR_OUT_OF_MEMORY Out of memory + * @see capmgr_device_clone() + * @see capmgr_device_foreach_devices() */ int capmgr_device_get_profile(capmgr_device_h device, char** profile); /** - * @brief + * @brief Gets the software verion with the given remote device context. + * @since_tizen 5.0 + * @remarks You must release @a sw_ver using free(). + * @param[in] device The remote device information handle + * @param[out] sw_ver The software version of the given remote device context + * @return @c 0 on success, + * otherwise a negative error value + * @retval #CAPMGR_ERROR_NONE Successful + * @retval #CAPMGR_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #CAPMGR_ERROR_OUT_OF_MEMORY Out of memory + * @see capmgr_device_clone() + * @see capmgr_device_foreach_devices() */ int capmgr_device_get_sw_ver(capmgr_device_h device, char** sw_ver); /** - * @brief + * @brief Creates a remote app control handle. + * @since_tizen 5.0 + * @remarks You must release @a app_control using capmgr_app_control_destroy(). + * + * @param[out] app_control The remote app control handle that is newly created on success + * + * @return @c 0 on success, + * otherwise a negative error value + * + * @retval #CAPMGR_ERROR_NONE Successful + * @retval #CAPMGR_ERROR_OUT_OF_MEMORY Out of memory + * @retval #CAPMGR_ERROR_INVALID_PARAMETER Invalid parameter + * @see capmgr_app_control_destroy() */ int capmgr_app_control_create(capmgr_app_control_h* app_control); /** - * @brief + * @brief Clones the remote app control handle. + * @since_tizen 5.0 + * @param[in] app_control The remote app control handle + * @param[out] app_control_clone A newly created remote app control handle, if successfully cloned + * @return @c 0 on success, + * otherwise a negative error value + * @retval #CAPMGR_ERROR_NONE Successful + * @retval #CAPMGR_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #CAPMGR_ERROR_OUT_OF_MEMORY Out of memory */ int capmgr_app_control_clone(const capmgr_app_control_h app_control, capmgr_app_control_h* app_control_clone); /** - * @brief + * @brief Destroys the remote app control handle and releases all its resources. + * @since_tizen 5.0 + * @param[in] app_control The remote app control handle + * @return @c 0 on success, + * otherwise a negative error value + * @retval #CAPMGR_ERROR_NONE Successful + * @retval #CAPMGR_ERROR_INVALID_PARAMETER Invalid parameter + * @see capmgr_app_control_create() */ int capmgr_app_control_destroy(capmgr_app_control_h app_control); /** - * @brief + * @brief Gets the remote device handle from the given app control context. + * @since_tizen 5.0 + * @remarks You must release @a device using capmgr_device_destroy(). + * @param[in] app_control The remote app control handle + * @param[out] device The remote device handle + * @return @c 0 on success, + * otherwise a negative error value + * @retval #CAPMGR_ERROR_NONE Successful + * @retval #CAPMGR_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #CAPMGR_ERROR_OUT_OF_MEMORY Out of memory + * @see capmgr_app_control_destroy() */ int capmgr_app_control_get_device(capmgr_app_control_h app_control, capmgr_device_h* device); /** - * @brief + * @brief Gets the operation value from the given remote app control context. + * @since_tizen 5.0 + * @remarks You must release @a operation using free(). + * @param[in] app_control The remote app control handle + * @param[out] operation The operation value + * @return @c 0 on success, + * otherwise a negative error value + * @retval #CAPMGR_ERROR_NONE Successful + * @retval #CAPMGR_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #CAPMGR_ERROR_OUT_OF_MEMORY Out of memory + * @see capmgr_app_control_destroy() */ int capmgr_app_control_get_operation(capmgr_app_control_h app_control, char** operation); /** - * @brief + * @brief Gets the URI value from the given remote app control context. + * @since_tizen 5.0 + * @remarks You must release @a uri using free(). + * @param[in] app_control The remote app control handle + * @param[out] uri The URI value + * @return @c 0 on success, + * otherwise a negative error value + * @retval #CAPMGR_ERROR_NONE Successful + * @retval #CAPMGR_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #CAPMGR_ERROR_OUT_OF_MEMORY Out of memory + * @see capmgr_app_control_destroy() */ int capmgr_app_control_get_uri(capmgr_app_control_h app_control, char** uri); /** - * @brief + * @brief Gets the MIME value from the given remote app control context. + * @since_tizen 5.0 + * @remarks You must release @a mime using free(). + * @param[in] app_control The remote app control handle + * @param[out] mime The MIME value + * @return @c 0 on success, + * otherwise a negative error value + * @retval #CAPMGR_ERROR_NONE Successful + * @retval #CAPMGR_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #CAPMGR_ERROR_OUT_OF_MEMORY Out of memory + * @see capmgr_app_control_destroy() */ int capmgr_app_control_get_mime(capmgr_app_control_h app_control, char** mime); /** - * @brief + * @brief Gets the application ID from the given remote app control context. + * @since_tizen 5.0 + * @remarks You must release @a appid using free(). + * @param[in] app_control The remote app control handle + * @param[out] appid The application ID + * @return @c 0 on success, + * otherwise a negative error value + * @retval #CAPMGR_ERROR_NONE Successful + * @retval #CAPMGR_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #CAPMGR_ERROR_OUT_OF_MEMORY Out of memory + * @see capmgr_app_control_destroy() */ int capmgr_app_control_get_appid(capmgr_app_control_h app_control, char** appid); /** - * @brief + * @brief Gets the extra data corresponding to given key from remote app control context. + * @since_tizen 5.0 + * @remarks You must release @a value using free(). + * @param[in] app_control The remote app control handle + * @param[in] key The key value + * @param[out] value The value related with given key + * @return @c 0 on success, + * otherwise a negative error value + * @retval #CAPMGR_ERROR_NONE Successful + * @retval #CAPMGR_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #CAPMGR_ERROR_OUT_OF_MEMORY Out of memory + * @see capmgr_app_control_destroy() */ int capmgr_app_control_get_extra_data(capmgr_app_control_h app_control, const char* key, char** value); /** - * @brief + * @brief Sets the target remote device to given remote app control context. + * @since_tizen 5.0 + * @param[in] app_control The remote app control handle + * @param[in] device The remote device handle to set + * @return @c 0 on success, + * otherwise a negative error value + * @retval #CAPMGR_ERROR_NONE Successful + * @retval #CAPMGR_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #CAPMGR_ERROR_OUT_OF_MEMORY Out of memory */ int capmgr_app_control_set_device(capmgr_app_control_h app_control, const capmgr_device_h device); /** - * @brief + * @brief Sets the operation value to given remote app control context. + * @since_tizen 5.0 + * @param[in] app_control The remote app control handle + * @param[in] operation The operation value to set + * @return @c 0 on success, + * otherwise a negative error value + * @retval #CAPMGR_ERROR_NONE Successful + * @retval #CAPMGR_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #CAPMGR_ERROR_OUT_OF_MEMORY Out of memory */ int capmgr_app_control_set_operation(capmgr_app_control_h app_control, const char* operation); /** - * @brief + * @brief Sets the URI value to given remote app control context. + * @since_tizen 5.0 + * @param[in] app_control The remote app control handle + * @param[in] uri The URI value to set + * @return @c 0 on success, + * otherwise a negative error value + * @retval #CAPMGR_ERROR_NONE Successful + * @retval #CAPMGR_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #CAPMGR_ERROR_OUT_OF_MEMORY Out of memory */ int capmgr_app_control_set_uri(capmgr_app_control_h app_control, const char* uri); /** - * @brief + * @brief Sets the MIME value to given remote app control context. + * @since_tizen 5.0 + * @param[in] app_control The remote app control handle + * @param[in] mime The MIME value to set + * @return @c 0 on success, + * otherwise a negative error value + * @retval #CAPMGR_ERROR_NONE Successful + * @retval #CAPMGR_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #CAPMGR_ERROR_OUT_OF_MEMORY Out of memory */ int capmgr_app_control_set_mime(capmgr_app_control_h app_control, const char* mime); /** - * @brief + * @brief Sets the application ID to given remote app control context. + * @since_tizen 5.0 + * @param[in] app_control The remote app control handle + * @param[in] appid The application ID to set + * @return @c 0 on success, + * otherwise a negative error value + * @retval #CAPMGR_ERROR_NONE Successful + * @retval #CAPMGR_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #CAPMGR_ERROR_OUT_OF_MEMORY Out of memory */ int capmgr_app_control_set_appid(capmgr_app_control_h app_control, const char* appid); /** - * @brief + * @brief Sets the extra data to given remote app control context. + * @since_tizen 5.0 + * @param[in] app_control The remote app control handle + * @param[in] key The key of extra data to set + * @param[in] value The value corresponding to key. + * @return @c 0 on success, + * otherwise a negative error value + * @retval #CAPMGR_ERROR_NONE Successful + * @retval #CAPMGR_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #CAPMGR_ERROR_OUT_OF_MEMORY Out of memory */ int capmgr_app_control_add_extra_data(capmgr_app_control_h app_control, const char* key, const char* value); /** - * @brief + * @brief Removes the extra data corresponding to given key at remote app control context. + * @since_tizen 5.0 + * @param[in] app_control The remote app control handle + * @param[in] key The key of extra data to remove + * @return @c 0 on success, + * otherwise a negative error value + * @retval #CAPMGR_ERROR_NONE Successful + * @retval #CAPMGR_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #CAPMGR_ERROR_OUT_OF_MEMORY Out of memory */ int capmgr_app_control_remove_extra_data(capmgr_app_control_h app_control, const char* key); /** - * @brief + * @brief Sends the app control to remote device specified at handle. + * @since_tizen 5.0 + * @param[in] app_control The remote app control handle + * @param[in] cb Callback to be invoked when send has done + * @param[in] user_data The user data to be passed to the callback function + * @return @c 0 on success, + * otherwise a negative error value + * @retval #CAPMGR_ERROR_NONE Successful + * @retval #CAPMGR_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #CAPMGR_ERROR_OUT_OF_MEMORY Out of memory */ int capmgr_app_control_send(capmgr_app_control_h app_control, capmgr_app_control_reply_cb cb, void* user_data); /** - * @brief + * @brief Retrieves all packages installed at specified remote device and invoke callback each of it. + * @since_tizen 5.0 + * @param[in] device The remote device handle + * @param[in] cb Callback to be invoked for each package + * @param[in] user_data The user data to be passed to the callback function + * @return @c 0 on success, + * otherwise a negative error value + * @retval #CAPMGR_ERROR_NONE Successful + * @retval #CAPMGR_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #CAPMGR_ERROR_IO_ERROR I/O error + * @retval #CAPMGR_ERROR_OUT_OF_MEMORY Out of memory */ int capmgr_package_info_foreach_packages(const capmgr_device_h device, capmgr_package_info_foreach_package_cb cb, void* user_data); /** - * @brief + * @brief Retrieves all applications belongs to given package and invoke callback each of it. + * @since_tizen 5.0 + * @param[in] remote_package_info The package information installed at specific remote device + * @param[in] cb Callback to be invoked for each application + * @param[in] user_data The user data to be passed to the callback function + * @return @c 0 on success, + * otherwise a negative error value + * @retval #CAPMGR_ERROR_NONE Successful + * @retval #CAPMGR_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #CAPMGR_ERROR_IO_ERROR I/O error + * @retval #CAPMGR_ERROR_OUT_OF_MEMORY Out of memory */ int capmgr_package_info_foreach_applications( const capmgr_package_info_h remote_package_info, capmgr_package_info_foreach_app_cb cb, void* user_data); /** - * @brief + * @brief Gets the package ID from given remote package information. + * @since_tizen 5.0 + * @remarks You must release @a pkgid using free(). + * @param[in] remote_package_info The package information installed at specific remote device + * @param[in] pkgid The package ID + * @return @c 0 on success, + * otherwise a negative error value + * @retval #CAPMGR_ERROR_NONE Successful + * @retval #CAPMGR_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #CAPMGR_ERROR_OUT_OF_MEMORY Out of memory */ int capmgr_package_info_get_pkgid(capmgr_package_info_h remote_package_info, char** pkgid); /** - * @brief + * @brief Gets the label from given remote package information. + * @since_tizen 5.0 + * @remarks You must release @a label using free(). + * @param[in] remote_package_info The package information installed at specific remote device + * @param[in] label The label of package + * @return @c 0 on success, + * otherwise a negative error value + * @retval #CAPMGR_ERROR_NONE Successful + * @retval #CAPMGR_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #CAPMGR_ERROR_OUT_OF_MEMORY Out of memory */ int capmgr_package_info_get_label(capmgr_package_info_h remote_package_info, char** label); - /** - * @brief + * @brief Gets the version from given remote package information. + * @since_tizen 5.0 + * @remarks You must release @a version using free(). + * @param[in] remote_package_info The package information installed at specific remote device + * @param[in] version The version of package + * @return @c 0 on success, + * otherwise a negative error value + * @retval #CAPMGR_ERROR_NONE Successful + * @retval #CAPMGR_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #CAPMGR_ERROR_OUT_OF_MEMORY Out of memory */ int capmgr_package_info_get_version(capmgr_package_info_h remote_package_info, char** version); -- 2.7.4