From: saerome.kim Date: Mon, 2 Apr 2018 13:03:10 +0000 (+0900) Subject: capi: change API names to make doxygen doc. X-Git-Tag: submit/tizen/20190131.065036~65 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=99daba5ef0d9daace6111072f5c560a63f92239d;p=platform%2Fcore%2Fapi%2Fmulti-device-group.git capi: change API names to make doxygen doc. Signed-off-by: saerome.kim --- diff --git a/capi/demo/comp-manager.c b/capi/demo/comp-manager.c index 4263878..cbb9e50 100644 --- a/capi/demo/comp-manager.c +++ b/capi/demo/comp-manager.c @@ -143,12 +143,12 @@ static int run_device_eject(MManager *mm, struct menu_data *menu) return RET_FAILURE; } - ret = companion_device_eject(handle, group, device, _device_eject_result_cb, NULL); + ret = companion_group_eject_device(handle, group, device, _device_eject_result_cb, NULL); if (COMP_ERROR_NONE != ret) { msgr("Failed to Delete Group: [%s(0x%X)]", comp_error_to_string(ret), ret); return RET_FAILURE; } - msg(" - companion_device_invite() ret: [0x%X] [%s]", ret, comp_error_to_string(ret)); + msg(" - companion_group_eject_device() ret: [0x%X] [%s]", ret, comp_error_to_string(ret)); return RET_SUCCESS; } @@ -202,12 +202,12 @@ static int run_device_invite(MManager *mm, struct menu_data *menu) return RET_FAILURE; } - ret = companion_device_invite(handle, group, device, pin, _device_invite_result_cb, NULL); + ret = companion_group_invite_device(handle, group, device, pin, _device_invite_result_cb, NULL); if (COMP_ERROR_NONE != ret) { msgr("Failed to device invite: [%s(0x%X)]", comp_error_to_string(ret), ret); return RET_FAILURE; } - msg(" - companion_device_invite() ret: [0x%X] [%s]", ret, comp_error_to_string(ret)); + msg(" - companion_group_invite_device() ret: [0x%X] [%s]", ret, comp_error_to_string(ret)); return RET_SUCCESS; } @@ -597,12 +597,12 @@ static int run_group_leave(MManager *mm, struct menu_data *menu) } } - ret = companion_group_leave(handle, group, _group_leave_finish_cb, NULL); + ret = companion_request_leave_group (handle, group, _group_leave_finish_cb, NULL); if (COMP_ERROR_NONE != ret) { msgr("Failed to Leave Group: [%s(0x%X)]", comp_error_to_string(ret), ret); return RET_FAILURE; } - msg(" - companion_group_leave() ret: [0x%X] [%s]", ret, comp_error_to_string(ret)); + msg(" - companion_request_leave_group () ret: [0x%X] [%s]", ret, comp_error_to_string(ret)); return RET_SUCCESS; } @@ -675,12 +675,12 @@ static int run_group_join(MManager *mm, struct menu_data *menu) } } - ret = companion_group_join(handle, group, _group_join_finish_cb, NULL); + ret = companion_request_join_group(handle, group, _group_join_finish_cb, NULL); if (COMP_ERROR_NONE != ret) { msgr("Failed to Join Group: [%s(0x%X)]", comp_error_to_string(ret), ret); return RET_FAILURE; } - msg(" - companion_group_join() ret: [0x%X] [%s]", ret, comp_error_to_string(ret)); + msg(" - companion_request_join_group() ret: [0x%X] [%s]", ret, comp_error_to_string(ret)); return RET_SUCCESS; } @@ -828,7 +828,8 @@ static int __send_data(int idx) address = NULL; } - ret = companion_send_data(handle, device, message, strlen(message), _send_data_finish_cb, NULL); + ret = companion_device_send_data(handle, device, message, strlen(message), + _send_data_finish_cb, NULL); if (COMP_ERROR_NONE != ret) msgr("Failed to Send Data: [ID] %s [IP] %s", deviceid, address); @@ -874,7 +875,8 @@ static int run_send_data_all(MManager *mm, struct menu_data *menu) void _mowned_device_finish_cb(int result, void *user_data) { - msgb("\rFind My Owned Devices Finished ret: [0x%X] [%s]", result, comp_error_to_string(result)); + msgb("\rFind My Owned Devices Finished ret: [0x%X] [%s]", result, + comp_error_to_string(result)); } bool _mowned_device_found_cb(companion_device_h device, void *user_data) @@ -913,10 +915,12 @@ static int run_devices_find_mowned_device(MManager *mm, struct menu_data *menu) ret = companion_device_find_mowned_device(handle, duration, _mowned_device_found_cb, _mowned_device_finish_cb, NULL); if (COMP_ERROR_NONE != ret) { - msgr("Failed to Find My Owned Devices: [%s(0x%X)]", comp_error_to_string(ret), ret); + msgr("Failed to Find My Owned Devices: [%s(0x%X)]", + comp_error_to_string(ret), ret); return RET_FAILURE; } - msg(" - companion_device_find_mowned_device() ret: [0x%X] [%s]", ret, comp_error_to_string(ret)); + msg(" - companion_device_find_mowned_device() ret: [0x%X] [%s]", + ret, comp_error_to_string(ret)); if (my_devices_list) { g_list_free_full(my_devices_list, _destroy_comp_device_info); @@ -934,10 +938,12 @@ int run_device_show_mowned_device(MManager *mm, struct menu_data *menu) ret = companion_device_get_found_mowned_devices(handle, &devices, &count); if (COMP_ERROR_NONE != ret) { - msgr("Failed to Get Found Mowned Devices: [%s(0x%X)]", comp_error_to_string(ret), ret); + msgr("Failed to Get Found Mowned Devices: [%s(0x%X)]", + comp_error_to_string(ret), ret); return RET_FAILURE; } - msg(" - companion_device_get_found_mowned_devices() ret: [0x%X] [%s]", ret, comp_error_to_string(ret)); + msg(" - companion_device_get_found_mowned_devices() ret: [0x%X] [%s]", ret, + comp_error_to_string(ret)); for (int i = 0; i < count; i++) { char *device_id = NULL; @@ -960,6 +966,12 @@ int run_device_show_mowned_device(MManager *mm, struct menu_data *menu) return RET_SUCCESS; } + +static void _group_create_finish_cb(int result, void *user_data) +{ + msgb("\rCreate operation finished"); +} + static int run_request_create_group(MManager *mm, struct menu_data *menu) { int ret = 0; @@ -992,17 +1004,25 @@ static int run_request_create_group(MManager *mm, struct menu_data *menu) } } - ret = companion_request_create_group(handle, device, request_groupid); + ret = companion_request_create_group(handle, device, request_groupid, + _group_create_finish_cb, NULL); if (COMP_ERROR_NONE != ret) { - msgr("Failed to Request Create Group: [%s(0x%X)]", comp_error_to_string(ret), ret); + msgr("Failed to Request Create Group: [%s(0x%X)]", + comp_error_to_string(ret), ret); return RET_FAILURE; } - msg(" - companion_request_create_group() ret: [0x%X] [%s]", ret, comp_error_to_string(ret)); + msg(" - companion_request_create_group() ret: [0x%X] [%s]", + ret, comp_error_to_string(ret)); return RET_SUCCESS; } +static void _group_invite_finish_cb(int result, void *user_data) +{ + msgb("\rInvite operation finished"); +} + static int run_request_invite(MManager *mm, struct menu_data *menu) { int ret = 0; @@ -1053,17 +1073,24 @@ static int run_request_invite(MManager *mm, struct menu_data *menu) } } - ret = companion_request_invite(handle, group, device, pin); + ret = companion_request_invite_device(handle, group, device, pin, + _group_invite_finish_cb, NULL); if (COMP_ERROR_NONE != ret) { msgr("Failed to Request Invite: [%s(0x%X)]", comp_error_to_string(ret), ret); return RET_FAILURE; } - msg(" - companion_request_invite() ret: [0x%X] [%s]", ret, comp_error_to_string(ret)); + msg(" - companion_request_invite_device() ret: [0x%X] [%s]", + ret, comp_error_to_string(ret)); return RET_SUCCESS; } +static void _group_eject_finish_cb(int result, void *user_data) +{ + msgb("\rEject operation finished"); +} + static int run_request_eject(MManager *mm, struct menu_data *menu) { int ret = 0; @@ -1114,17 +1141,23 @@ static int run_request_eject(MManager *mm, struct menu_data *menu) } } - ret = companion_request_eject(handle, group, device); + ret = companion_request_eject_device(handle, group, device, _group_eject_finish_cb, + NULL); if (COMP_ERROR_NONE != ret) { msgr("Failed to Request Eject: [%s(0x%X)]", comp_error_to_string(ret), ret); return RET_FAILURE; } - msg(" - companion_request_eject() ret: [0x%X] [%s]", ret, comp_error_to_string(ret)); + msg(" - companion_request_eject_device() ret: [0x%X] [%s]", ret, comp_error_to_string(ret)); return RET_SUCCESS; } +static void _group_delete_finish_cb(int result, void *user_data) +{ + msgb("\rDelete operation finished"); +} + static int run_request_delete_group(MManager *mm, struct menu_data *menu) { int ret = 0; @@ -1155,13 +1188,15 @@ static int run_request_delete_group(MManager *mm, struct menu_data *menu) } } - ret = companion_request_delete_group(handle, group); + ret = companion_request_delete_group(handle, group, _group_delete_finish_cb, NULL); if (COMP_ERROR_NONE != ret) { - msgr("Failed to Request Delete Group: [%s(0x%X)]", comp_error_to_string(ret), ret); + msgr("Failed to Request Delete Group: [%s(0x%X)]", + comp_error_to_string(ret), ret); return RET_FAILURE; } - msg(" - companion_request_delete_group() ret: [0x%X] [%s]", ret, comp_error_to_string(ret)); + msg(" - companion_request_delete_group() ret: [0x%X] [%s]", + ret, comp_error_to_string(ret)); return RET_SUCCESS; } @@ -1301,6 +1336,7 @@ struct menu_data menu_comp_manager[] = { { "15", "Request Create Group", menu_request_create_group, NULL, NULL }, { "16", "Request Invite", menu_request_invite, NULL, NULL }, { "17", "Request Eject", menu_request_eject, NULL, NULL }, - { "18", "Request Delete Group (Not yet developed)", menu_request_delete_group, NULL, NULL }, + { "18", "Request Delete Group (Not yet developed)", menu_request_delete_group, + NULL, NULL }, { NULL, NULL, }, }; diff --git a/capi/demo/companion_demo.c b/capi/demo/companion_demo.c index a0c878d..ab76c16 100644 --- a/capi/demo/companion_demo.c +++ b/capi/demo/companion_demo.c @@ -294,7 +294,7 @@ int companion_device_invite_test(void) companion_group_h group = (companion_group_h)(found_group_list[0].data); companion_device_h device = (companion_device_h)(found_device_list[0].data); - companion_device_invite(handle, group, device, "12341234", _device_invite_result_cb, NULL); + companion_group_invite_device(handle, group, device, "12341234", _device_invite_result_cb, NULL); } else { TC_PRT("not exist found group or device list"); @@ -321,7 +321,7 @@ int companion_device_eject_test(void) companion_device_h device = (companion_device_h)(found_device_list[0].data); /* using stored group list and device list */ - companion_device_eject(handle, group, device, _device_eject_result_cb, NULL); + companion_group_eject_device(handle, group, device, _device_eject_result_cb, NULL); } else { TC_PRT("not exist found group or device list"); } @@ -341,7 +341,7 @@ int companion_send_data_to_remote_device_test(void) if (g_list_length(found_device_list) > 0) { companion_device_h device = (companion_device_h)(found_device_list[0].data); - ret = companion_send_data(handle, device, "123", NULL, NULL); + ret = companion_device_send_data(handle, device, "123", NULL, NULL); } else { TC_PRT("not exist found device list"); } diff --git a/capi/doc/companion_doc.h b/capi/doc/companion_doc.h index 5a8d097..e4829b0 100644 --- a/capi/doc/companion_doc.h +++ b/capi/doc/companion_doc.h @@ -45,4 +45,130 @@ * */ +/** + * @defgroup CAPI_NETWORK_COMPANION_GROUP_MODULE Local Group Management + * @brief The Companion API provides functions for device management. + * @ingroup CAPI_NETWORK_COMPANION_MODULE + * + * @section CAPI_NETWORK_COMPANION_GROUP_MODULE_HEADER Required Header + * \#include + * + * @section CAPI_NETWORK_COMPANION_GROUP_MODULE_OVERVIEW Overview + * These functions are used to manipulate the groups. + * + * It is recommended to design applications with regard to features, for reliability.\n + * + * You can check if a device supports the related features for this API by using @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, and control your application's actions accordingly.\n + * + * To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK.\n + * + * More details on featuring your application can be found from Feature Element. + * + */ + +/** + * @defgroup CAPI_NETWORK_COMPANION_LOCAL_GROUP_MODULE Local Group Management + * @brief The Companion API provides functions for device management. + * @ingroup CAPI_NETWORK_COMPANION_GROUP_MODULE + * + * @section CAPI_NETWORK_COMPANION_LOCAL_GROUP_MODULE_HEADER Required Header + * \#include + * + * @section CAPI_NETWORK_COMPANION_LOCAL_GROUP_MODULE_OVERVIEW Overview + * These functions are used to manipulate the local groups. + * + * It is recommended to design applications with regard to features, for reliability.\n + * + * You can check if a device supports the related features for this API by using @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, and control your application's actions accordingly.\n + * + * To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK.\n + * + * More details on featuring your application can be found from Feature Element. + * + */ + +/** + * @defgroup CAPI_NETWORK_COMPANION_REMOTE_GROUP_MODULE Remote Group Management + * @brief The Companion API provides functions for device management. + * @ingroup CAPI_NETWORK_COMPANION_GROUP_MODULE + * + * @section CAPI_NETWORK_COMPANION_REMOTE_GROUP_MODULE_HEADER Required Header + * \#include + * + * @section CAPI_NETWORK_COMPANION_REMOTE_GROUP_MODULE_OVERVIEW Overview + * These functions are used to manipulate the remote groups. + * + * It is recommended to design applications with regard to features, for reliability.\n + * + * You can check if a device supports the related features for this API by using @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, and control your application's actions accordingly.\n + * + * To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK.\n + * + * More details on featuring your application can be found from Feature Element. + * + */ + +/** + * @defgroup CAPI_NETWORK_COMPANION_GROUP_INFORMATION_MODULE Group Information + * @brief The Companion API provides functions for device management. + * @ingroup CAPI_NETWORK_COMPANION_GROUP_MODULE + * + * @section CAPI_NETWORK_COMPANION_GROUP_INFORMATION_MODULE_HEADER Required Header + * \#include + * + * @section CAPI_NETWORK_COMPANION_GROUP_INFORMATION_MODULE_OVERVIEW Overview + * These functions are used to get group information using the group handle. + * + * It is recommended to design applications with regard to features, for reliability.\n + * + * You can check if a device supports the related features for this API by using @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, and control your application's actions accordingly.\n + * + * To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK.\n + * + * More details on featuring your application can be found from Feature Element. + * + */ + +/** + * @defgroup CAPI_NETWORK_COMPANION_DEVICE_MODULE Device Management + * @brief The Companion API provides functions for device management. + * @ingroup CAPI_NETWORK_COMPANION_MODULE + * + * @section CAPI_NETWORK_COMPANION_DEVICE_MODULE_HEADER Required Header + * \#include + * + * @section CAPI_NETWORK_COMPANION_DEVICE_MODULE_OVERVIEW Overview + * These functions are used to get information from the device handle. + * + * It is recommended to design applications with regard to features, for reliability.\n + * + * You can check if a device supports the related features for this API by using @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, and control your application's actions accordingly.\n + * + * To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK.\n + * + * More details on featuring your application can be found from Feature Element. + * + */ + +/** + * @defgroup CAPI_NETWORK_COMPANION_DEVICE_INFORMATION_MODULE Device Information + * @brief The Companion API provides functions for device management. + * @ingroup CAPI_NETWORK_COMPANION_DEVICE_MODULE + * + * @section CAPI_NETWORK_COMPANION_DEVICE_INFORMATION_MODULE_HEADER Required Header + * \#include + * + * @section CAPI_NETWORK_COMPANION_DEVICE_INFORMATION_MODULE_OVERVIEW Overview + * These functions are used to get device information using the device handle. + * + * It is recommended to design applications with regard to features, for reliability.\n + * + * You can check if a device supports the related features for this API by using @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, and control your application's actions accordingly.\n + * + * To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK.\n + * + * More details on featuring your application can be found from Feature Element. + * + */ + #endif /* __TIZEN_NETWORK_COMPANION_DOC_H__ */ diff --git a/capi/include/companion.h b/capi/include/companion.h index 679515a..890bdad 100644 --- a/capi/include/companion.h +++ b/capi/include/companion.h @@ -67,6 +67,7 @@ typedef enum { COMP_ERROR_OPERATION_FAILED = TIZEN_ERROR_COMP | 0x04, /**< Operation Failed */ COMP_ERROR_ALREADY_IN_PROGRESS = TIZEN_ERROR_COMP | 0x05, /**< Operation now in progress */ COMP_ERROR_ALREADY_INITIALIZED = TIZEN_ERROR_COMP | 0x06, /**< Already initilized */ + COMP_ERROR_NO_DATA = TIZEN_ERROR_COMP | 0x07, /**< No Data */ COMP_ERROR_UNKNOWN = -999, } comp_error_e; @@ -82,11 +83,9 @@ typedef enum { } companion_group_type_e; /** - * @brief Device hande which represents a companion device. - * - * @since_tizen 5.0 + * @addtogroup CAPI_NETWORK_COMPANION_DEVICE_MODULE + * @{ */ -typedef void *companion_group_h; /**< Group handle */ /** * @brief Group handle which represents a companion group. @@ -94,226 +93,130 @@ typedef void *companion_group_h; /**< Group handle */ * @since_tizen 5.0 */ typedef void *companion_device_h; /**< Device handle */ - - /** - * @brief Called after companion_group_find(). - * @details This function can receive a group resource found. - * - * @since_tizen 5.0 - * @privlevel public - * @privilege %http://tizen.org/privilege/internet - * - * @remarks The @a group should not be released. - * @remarks The @a group can be used only in the callback. To use outside, make a copy. - * - * @param[out] type Companion group type - * @param[out] group Group resource found - * @param[out] user_data User data pointer - * - * @pre The callback must be registered with companion_group_find() - * - * @see companion_group_find() + * @} */ -typedef bool (*companion_group_found_cb)(companion_group_type_e type, - companion_group_h group, void *user_data); /** - * @brief Called after companion_device_find(). - * @details This function can receive a device found. - * - * @since_tizen 5.0 - * @privlevel public - * @privilege %http://tizen.org/privilege/internet - * - * @remarks The @a device should not be released. - * @remarks The @a device can be used only in the callback. To use outside, make a copy. - * - * @param[out] device Device found - * @param[out] user_data User data pointer - * - * @pre The callback must be registered with companion_device_find() - * - * @see companion_device_find() + * @addtogroup CAPI_NETWORK_COMPANION_GROUP_MODULE + * @{ */ -typedef bool (*companion_device_found_cb)(companion_device_h device, void *user_data); /** - * @brief Called after companion_group_find() finished. - * @details Called when the maximum wait time elapsed after the companion_group_find() done. + * @brief Device hande which represents a companion device. * * @since_tizen 5.0 - * @privlevel public - * @privilege %http://tizen.org/privilege/internet - * - * @param[out] result Result of operation - * @param[out] user_data User data pointer - * - * @pre The callback must be registered with companion_group_find() - * - * @see companion_group_find() */ -typedef void (*companion_group_find_finish_cb)(int result, void *user_data); - +typedef void *companion_group_h; /**< Group handle */ /** - * @brief Called after companion_device_find() finished. - * @details Called when the maximum wait time elapsed after the companion_device_find() done. - * - * @since_tizen 5.0 - * @privlevel public - * @privilege %http://tizen.org/privilege/internet - * - * @param[out] result Result of operation - * @param[out] user_data User data pointer - * - * @pre The callback must be registered with companion_device_find() - * - * @see companion_device_find() + * @} */ -typedef void (*companion_device_find_finish_cb)(int result, void *user_data); /** - * @brief Called after companion_device_invite(). - * @details Called when the maximum wait time elapsed or after the companion_device_invite() - * finished successfully. - * + * @brief Initializes companion-manager. * @since_tizen 5.0 * @privlevel public * @privilege %http://tizen.org/privilege/internet * - * @param[out] result Result of operation - * @param[out] user_data User data pointer + * @remarks You must release @a handle using companion_deinitialize(). * - * @pre The callback must be registered with companion_device_invite() + * @param[out] handle The companion manager handle * - * @see companion_device_invite() + * @return @c 0 on success, otherwise negative error value + * @retval #COMP_ERROR_NONE Successful + * @retval #COMP_ERROR_ALREADY_INITIALIZED Already initialized + * @retval #COMP_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #COMP_ERROR_OPERATION_FAILED Operation failed + * @retval #COMP_ERROR_OUT_OF_MEMORY Out of memory */ -typedef void (*companion_device_invite_result_cb)(int result, void *user_data); +int companion_initialize(companion_h *handle); /** - * @brief Called after companion_device_eject(). - * @details Called when the maximum wait time elapsed or after the companion_device_eject() - * finished successfully. - * + * @brief Deinitializes the companion-manager. * @since_tizen 5.0 * @privlevel public * @privilege %http://tizen.org/privilege/internet * - * @param[out] result Result of operation - * @param[out] user_data User data pointer - * - * @pre The callback must be registered with companion_device_eject() + * @param[in] handle The companion manager handle * - * @see companion_device_eject() + * @return 0 on success, otherwise negative error value + * @retval #COMP_ERROR_NONE Successful + * @retval #COMP_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #COMP_ERROR_OPERATION_FAILED Operation failed */ -typedef void (*companion_device_eject_result_cb)(int result, void *user_data); +int companion_deinitialize(companion_h handle); /** - * @brief Called after companion_send_data(). - * @details Called when the maximum wait time elapsed or after the companion_send_data() - * finished successfully. + * @brief Gets my local device ID. + * @details This function returns current UUID of local device. * * @since_tizen 5.0 * @privlevel public * @privilege %http://tizen.org/privilege/internet * - * @remarks The @a resp_data should not be released. - * @remarks The @a resp_data can be used only in the callback. To use outside, make a copy. + * @remarks The @a uuid should not be released. + * @remarks The @a uuid can be used only in the callback. To use outside, make a copy. * - * @param[out] result Result of operation - * @param[out] resp_data Retrieved data - * @param[out] user_data User data pointer + * @param[in] handle The companion manager handle + * @param[out] uuid Local device UUID + * + * @return 0 on success, otherwise a negative error value. + * @retval #COMP_ERROR_NONE Successful + * @retval #COMP_ERROR_INVALID_PARAMETER Invalid parameter * - * @pre The callback must be registered with companion_send_data() + * @see companion_device_get_my_device() * - * @see companion_send_data() */ -typedef void (*companion_send_data_finish_cb)(int result, char *resp_data, - void *user_data); +int companion_device_get_my_uuid(companion_h handle, char **uuid); /** - * @brief Callback function potiner to be regsitered by calling - * companion_request_result_callback(). - * - * @since_tizen 5.0 - * @privlevel public - * @privilege %http://tizen.org/privilege/internet - * - * @remarks The @a cmd, @arg should not be released. - * @remarks The @a cmd, @arg can be used only in the callback. To use outside, make a copy. - * - * @param[out] cmd Command - * @param[out] arg Argument - * @param[out] ret Return code - * @param[out] user_data User data pointer - * - * @pre The callback must be registered with companion_request_result_callback() - * - * @see companion_send_data() + * @} */ -typedef void (*companion_request_result_cb)(char *cmd, char *arg, int ret, - void *user_data); -/* Management Module APIs*/ /** - * @brief Initializes companion-manager. - * @since_tizen 5.0 - * @privlevel public - * @privilege %http://tizen.org/privilege/internet - * - * @remarks You must release @a handle using companion_deinitialize(). - * - * @param[out] handle The companion manager handle - * - * @return @c 0 on success, otherwise negative error value - * @retval #COMP_ERROR_NONE Successful - * @retval #COMP_ERROR_ALREADY_INITIALIZED Already initialized - * @retval #COMP_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #COMP_ERROR_OPERATION_FAILED Operation failed - * @retval #COMP_ERROR_OUT_OF_MEMORY Out of memory + * @addtogroup CAPI_NETWORK_COMPANION_GROUP_MODULE + * @{ */ -int companion_initialize(companion_h *handle); /** - * @brief Deinitializes the companion-manager. + * @brief Called after companion_group_find(). + * @details This function can receive a group resource found. + * * @since_tizen 5.0 * @privlevel public * @privilege %http://tizen.org/privilege/internet * - * @param[in] handle The companion manager handle + * @remarks The @a group should not be released. + * @remarks The @a group can be used only in the callback. To use outside, make a copy. * - * @return 0 on success, otherwise negative error value - * @retval #COMP_ERROR_NONE Successful - * @retval #COMP_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #COMP_ERROR_OPERATION_FAILED Operation failed + * @param[out] type Companion group type + * @param[out] group Group resource found + * @param[out] user_data User data pointer + * + * @pre The callback must be registered with companion_group_find() + * + * @see companion_group_find() */ -int companion_deinitialize(companion_h handle); - -/* Group Module APIs*/ - -/* companion_group_create : craete group in my daemon */ +typedef bool (*companion_group_found_cb)(companion_group_type_e type, + companion_group_h group, void *user_data); /** - * @brief Creates a group. - * @details This function is to allocate new group in local companion-manager. + * @brief Called after companion_group_find() finished. + * @details Called when the maximum wait time elapsed after the companion_group_find() done. * * @since_tizen 5.0 * @privlevel public * @privilege %http://tizen.org/privilege/internet * - * @param[in] handle The companion manager handle - * @param[in] group_name Group name + * @param[out] result Result of operation + * @param[out] user_data User data pointer * - * @return 0 on success, otherwise a negative error value. - * @retval #COMP_ERROR_NONE Successful - * @retval #COMP_ERROR_INVALID_PARAMETER Invalid parameter + * @pre The callback must be registered with companion_group_find() * * @see companion_group_find() - * @see companion_group_get_found_groups() - * */ -int companion_group_create(companion_h handle, char *group_name); +typedef void (*companion_group_find_finish_cb)(int result, void *user_data); /** * @brief Finds group resources in local and the network. @@ -366,61 +269,35 @@ int companion_group_get_found_groups(companion_h handle, companion_group_h **groups, int *count); /** - * @brief Joins the remote group. - * @details This function allows users to join a device to a remote group. - * if group handle is my owns, then the API returns failure. - * - * @since_tizen 5.0 - * @privlevel public - * @privilege %http://tizen.org/privilege/internet - * - * @param[in] handle The companion manager handle - * @param[in] group Group resource list - * @param[in] callback Callback handler to retrieve the found group resource - * @param[in] user_data User data poiter - * - * - * @return 0 on success, otherwise a negative error value. - * @retval #COMP_ERROR_NONE Successful - * @retval #COMP_ERROR_INVALID_PARAMETER Invalid parameter - * - * @see companion_group_create() - * @see companion_group_leave() - * @see companion_group_delete() - * @see companion_group_merge() - * @see companion_group_get_member_devices() - * + * @} + */ + +/** + * @addtogroup CAPI_NETWORK_COMPANION_LOCAL_GROUP_MODULE + * @{ */ -int companion_group_join(companion_h handle, companion_group_h group, - companion_group_find_finish_cb callback, void *user_data); + /** - * @brief Leaves my own devices from the remote group. - * @details This function allows my own device to be removed from the remote group. + * @brief Creates a group. + * @details This function is to allocate new group in local companion-manager. * * @since_tizen 5.0 * @privlevel public * @privilege %http://tizen.org/privilege/internet * * @param[in] handle The companion manager handle - * @param[in] group Group handle - * @param[in] callback Callback handler to retrieve the found group resource - * @param[in] user_data User data poiter - * + * @param[in] group_name Group name * * @return 0 on success, otherwise a negative error value. * @retval #COMP_ERROR_NONE Successful * @retval #COMP_ERROR_INVALID_PARAMETER Invalid parameter * - * @see companion_group_create() - * @see companion_group_join() - * @see companion_group_delete() - * @see companion_group_merge() - * @see companion_group_get_member_devices() + * @see companion_group_find() + * @see companion_group_get_found_groups() * */ -int companion_group_leave(companion_h handle, companion_group_h group, - companion_group_find_finish_cb callback, void *user_data); +int companion_group_create(companion_h handle, char *group_name); /** * @brief Deletes the group. @@ -439,8 +316,8 @@ int companion_group_leave(companion_h handle, companion_group_h group, * @retval #COMP_ERROR_INVALID_PARAMETER Invalid parameter * * @see companion_group_create() - * @see companion_group_join() - * @see companion_group_leave() + * @see companion_request_join_group() + * @see companion_request_leave_group () * @see companion_group_merge() * @see companion_group_get_member_devices() * @@ -465,8 +342,8 @@ int companion_group_delete(companion_h handle, companion_group_h group); * @retval #COMP_ERROR_INVALID_PARAMETER Invalid parameter * * @see companion_group_create() - * @see companion_group_join() - * @see companion_group_leave() + * @see companion_request_join_group() + * @see companion_request_leave_group () * @see companion_group_delete() * @see companion_group_get_member_devices() * @@ -495,8 +372,8 @@ int companion_group_merge(companion_h handle, companion_group_h dest_group, * @retval #COMP_ERROR_INVALID_PARAMETER Invalid parameter * * @see companion_group_create() - * @see companion_group_join() - * @see companion_group_leave() + * @see companion_request_join_group() + * @see companion_request_leave_group () * @see companion_group_delete() * @see companion_group_merge() * @@ -504,71 +381,86 @@ int companion_group_merge(companion_h handle, companion_group_h dest_group, int companion_group_get_member_devices(companion_h handle, companion_group_h group, companion_device_h **devices, int *count); - -/* Device Module */ - /** - * @brief Finds candidate devices to include my groups in the network. - * @details This function will search for candidate devices that can be included in local group. + * @brief Called after companion_group_invite_device(). + * @details Called when the maximum wait time elapsed or after the companion_group_invite_device() + * finished successfully. * * @since_tizen 5.0 * @privlevel public * @privilege %http://tizen.org/privilege/internet * - * @param[in] handle The companion manager handle - * @param[in] timeout Time to find - * @param[in] found_cb Callback handler to retrieve the found device - * @param[in] finish_cb Callback handler to know finding process finished - * @param[in] user_data User data poiter - * - * - * @return 0 on success, otherwise a negative error value. - * @retval #COMP_ERROR_NONE Successful - * @retval #COMP_ERROR_INVALID_PARAMETER Invalid parameter + * @param[out] result Result of operation + * @param[out] user_data User data pointer * - * @see companion_device_get_found_devices() + * @pre The callback must be registered with companion_group_invite_device() * + * @see companion_group_invite_device() */ -int companion_device_find(companion_h handle, int timeout, - companion_device_found_cb found_cb, companion_device_find_finish_cb finish_cb, - void *user_data); +typedef void (*companion_group_invite_device_result_cb)(int result, void *user_data); /** - * @brief Gets a list of candidate devices to can be included my group. - * @details This function retrieves a list of multiple owner enabled devices found. + * @brief Called after companion_group_eject_device(). + * @details Called when the maximum wait time elapsed or after the companion_device_eject() + * finished successfully. + * + * @since_tizen 5.0 + * @privlevel public + * @privilege %http://tizen.org/privilege/internet + * + * @param[out] result Result of operation + * @param[out] user_data User data pointer + * + * @pre The callback must be registered with companion_device_eject() + * + * @see companion_group_ejecct_device() + */ +typedef void (*companion_group_eject_device_result_cb)(int result, void *user_data); + +/** + * @brief Requests to invite a device to the group which local device owns. + * @details This function invites a remote device to a specific group. At the time of invitation, + * user can enter the authentication information (i.e., PIN) or use the certificate. * * @since_tizen 5.0 * @privlevel public * @privilege %http://tizen.org/privilege/internet * * @param[in] handle The companion manager handle - * @param[in] devices Device list - * @param[in] count Number of devices + * @param[in] group Group handle + * @param[in] device Device handle + * @param[in] PIN PIN number + * @param[in] callback Callback handler to receive the result + * @param[in] user_data User data poiter * * * @return 0 on success, otherwise a negative error value. * @retval #COMP_ERROR_NONE Successful * @retval #COMP_ERROR_INVALID_PARAMETER Invalid parameter * - * @see companion_device_find_mowned_device() + * @see companion_request_create_group() + * @see companion_request_eject_device() + * @see companion_request_delete_group() + * @see companion_request_result_callback() + * @see companion_device_send_data() * */ -int companion_device_get_found_devices(companion_h handle, - companion_device_h **devices, int *count); +int companion_group_invite_device(companion_h handle, companion_group_h group, + companion_device_h device, char *PIN, + companion_group_invite_device_result_cb callback, void *user_data); /** - * @brief Finds my owned devices in the network. - * @details This function looks up devices on your network that are registered as multiple - * owners. + * @brief Requests to expel the device from the group which local device owns. + * @details This function is used to kick away a remote devices in my local group. * * @since_tizen 5.0 * @privlevel public * @privilege %http://tizen.org/privilege/internet * * @param[in] handle The companion manager handle - * @param[in] timeout Time to find - * @param[in] found_cb Callback handler to retrieve the found device - * @param[in] finish_cb Callback handler to know finding process finished + * @param[in] group Group handle + * @param[in] device Device handle + * @param[in] callback Callback handler to receive the result * @param[in] user_data User data poiter * * @@ -576,42 +468,139 @@ int companion_device_get_found_devices(companion_h handle, * @retval #COMP_ERROR_NONE Successful * @retval #COMP_ERROR_INVALID_PARAMETER Invalid parameter * - * @see companion_device_get_found_mowned_devices() + * @see companion_request_create_group() + * @see companion_request_eject_device() + * @see companion_request_delete_group() + * @see companion_request_result_callback() + * @see companion_device_send_data() * */ -int companion_device_find_mowned_device(companion_h handle, int timeout, - companion_device_found_cb found_cb, companion_device_find_finish_cb finish_cb, +int companion_group_eject_device(companion_h handle, companion_group_h group, + companion_device_h device, companion_group_eject_device_result_cb callback, void *user_data); + /** - * @brief Gets a list of discovered owned devices. - * @details This function retrieves a list of my owned devices found. + * @} + */ + +/** + * @addtogroup CAPI_NETWORK_COMPANION_REMOTE_GROUP_MODULE + * @{ + */ + +/** + * @brief Callback function potiner to be regsitered by calling request to remote groups. + * + * @since_tizen 5.0 + * @privlevel public + * @privilege %http://tizen.org/privilege/internet + * + * + * @param[out] result Return code + * @param[out] user_data User data pointer + * + * @see companion_request_join_group() + * @see companion_request_leave_group() + * @see companion_device_send_data() + * @see companion_device_send_data() + */ +typedef void (*companion_request_done_cb)(int result, void *user_data); + +/** + * @brief Requests my device to be joined to remote group. + * @details This function requests a remote groups to join my device in the remote groups. * * @since_tizen 5.0 * @privlevel public * @privilege %http://tizen.org/privilege/internet * * @param[in] handle The companion manager handle - * @param[in] devices Device list - * @param[in] count Number of devices + * @param[in] group Group resource list + * @param[in] cb Callback handler to receive the result + * @param[in] user_data User data pointer * * * @return 0 on success, otherwise a negative error value. * @retval #COMP_ERROR_NONE Successful * @retval #COMP_ERROR_INVALID_PARAMETER Invalid parameter * - * @see companion_device_find_mowned_device() + * @see companion_group_create() + * @see companion_request_leave_group () + * @see companion_request_create_group() + * @see companion_request_invite_device() + * @see companion_request_eject_device() + * @see companion_request_delete_group() * */ -int companion_device_get_found_mowned_devices(companion_h handle, - companion_device_h **devices, int *count); +int companion_request_join_group(companion_h handle, companion_group_h group, + companion_request_done_cb cb, void *user_data); -/* companion_group_device_invite : Invite a remote group device to my local group. */ +/** + * @brief Requests my device to be exit from remote group. + * @details This function requests remote groups to exit my devices that belonged to the + * remote group. + * + * @since_tizen 5.0 + * @privlevel public + * @privilege %http://tizen.org/privilege/internet + * + * @param[in] handle The companion manager handle + * @param[in] group Group handle + * @param[in] cb Callback handler to receive the result + * @param[in] user_data User data pointer + * + * + * @return 0 on success, otherwise a negative error value. + * @retval #COMP_ERROR_NONE Successful + * @retval #COMP_ERROR_INVALID_PARAMETER Invalid parameter + * + * @see companion_group_create() + * @see companion_request_join_group() + * @see companion_group_delete() + * @see companion_group_merge() + * @see companion_group_get_member_devices() + * + */ +int companion_request_leave_group (companion_h handle, companion_group_h group, + companion_request_done_cb cb, void *user_data); /** - * @brief Requests to invite a device to the group which local device owns. - * @details This function invites a remote device to a specific group. At the time of invitation, - * user can enter the authentication information (i.e., PIN) or use the certificate. + * @brief Requests to create a group. + * @details We can create a group. This generated group can include device, and remote + * devices can inquire remotely group information and device information included in group. + * + * @since_tizen 5.0 + * @privlevel public + * @privilege %http://tizen.org/privilege/internet + * + * @param[in] handle The companion manager handle + * @param[in] device Device handle + * @param[in] group_name Group name + * @param[in] cb Callback handler to receive the result + * @param[in] user_data User data pointer + * + * + * @return 0 on success, otherwise a negative error value. + * @retval #COMP_ERROR_NONE Successful + * @retval #COMP_ERROR_INVALID_PARAMETER Invalid parameter + * + * @see companion_request_invite_device() + * @see companion_request_eject_device() + * @see companion_request_delete_group() + * @see companion_request_result_callback() + * @see companion_device_send_data() + * + */ +int companion_request_create_group(companion_h handle, + companion_device_h device, char *group_name, companion_request_done_cb cb, + void *user_data); + +/** + * @brief Requests to invite a device to the group. + * @details This function invites a remote device to a specific group. At the time of + * invitation, user can enter the authentication information (i.e., PIN) or use the + * certificate. * * @since_tizen 5.0 * @privlevel public @@ -621,8 +610,8 @@ int companion_device_get_found_mowned_devices(companion_h handle, * @param[in] group Group handle * @param[in] device Device handle * @param[in] PIN PIN number - * @param[in] callback Callback handler to receive the result - * @param[in] user_data User data poiter + * @param[in] cb Callback handler to receive the result + * @param[in] user_data User data pointer * * * @return 0 on success, otherwise a negative error value. @@ -630,21 +619,19 @@ int companion_device_get_found_mowned_devices(companion_h handle, * @retval #COMP_ERROR_INVALID_PARAMETER Invalid parameter * * @see companion_request_create_group() - * @see companion_request_eject() + * @see companion_request_eject_device() * @see companion_request_delete_group() * @see companion_request_result_callback() - * @see companion_send_data() + * @see companion_device_send_data() * */ -int companion_device_invite(companion_h handle, companion_group_h group, - companion_device_h device, char *PIN, companion_device_invite_result_cb callback, +int companion_request_invite_device(companion_h handle, companion_group_h group, + companion_device_h device, char *PIN, companion_request_done_cb cb, void *user_data); -/* companion_group_device_eject : Eject a remote group device from my group. */ - /** - * @brief Requests to expel the device from the group which local device owns. - * @details This function is used to kick away a remote devices in my local group. + * @brief Requests to eject a device. + * @details This function is used to kick away a remote devices in a specific group. * * @since_tizen 5.0 * @privlevel public @@ -653,8 +640,8 @@ int companion_device_invite(companion_h handle, companion_group_h group, * @param[in] handle The companion manager handle * @param[in] group Group handle * @param[in] device Device handle - * @param[in] callback Callback handler to receive the result - * @param[in] user_data User data poiter + * @param[in] cb Callback handler to receive the result + * @param[in] user_data User data pointer * * * @return 0 on success, otherwise a negative error value. @@ -662,61 +649,100 @@ int companion_device_invite(companion_h handle, companion_group_h group, * @retval #COMP_ERROR_INVALID_PARAMETER Invalid parameter * * @see companion_request_create_group() - * @see companion_request_eject() + * @see companion_request_eject_device() * @see companion_request_delete_group() * @see companion_request_result_callback() - * @see companion_send_data() + * @see companion_device_send_data() * */ -int companion_device_eject(companion_h handle, companion_group_h group, - companion_device_h device, companion_device_eject_result_cb callback, - void *user_data); +int companion_request_eject_device(companion_h handle, companion_group_h group, + companion_device_h device, companion_request_done_cb cb, void *user_data); /** - * @brief Gets my local device handle. - * @details This function returns the local device information handle. + * @brief Requests to delete the group. + * @details This function deletes a specific group and expels all devices in that group. * * @since_tizen 5.0 * @privlevel public * @privilege %http://tizen.org/privilege/internet * * @param[in] handle The companion manager handle - * @param[in] device Local device handle + * @param[in] group Group handle + * @param[in] cb Callback handler to receive the result + * @param[in] user_data User data pointer + * * * @return 0 on success, otherwise a negative error value. * @retval #COMP_ERROR_NONE Successful * @retval #COMP_ERROR_INVALID_PARAMETER Invalid parameter * - * @see companion_device_get_my_uuid() + * @see companion_request_create_group() + * @see companion_request_invite_device() + * @see companion_request_eject_device() + * @see companion_request_result_callback() + * @see companion_device_send_data() * */ -int companion_device_get_my_device(companion_h handle, - companion_device_h *device); +int companion_request_delete_group(companion_h handle, companion_group_h group, + companion_request_done_cb cb, void *user_data); /** - * @brief Gets my local device ID. - * @details This function returns current UUID of local device. + * @brief Callback function potiner to be regsitered by calling + * companion_request_result_callback(). * * @since_tizen 5.0 * @privlevel public * @privilege %http://tizen.org/privilege/internet * - * @remarks The @a uuid should not be released. - * @remarks The @a uuid can be used only in the callback. To use outside, make a copy. + * @remarks The @a cmd, @arg should not be released. + * @remarks The @a cmd, @arg can be used only in the callback. To use outside, make a copy. + * + * @param[out] cmd Command + * @param[out] arg Argument + * @param[out] ret Return code + * @param[out] user_data User data pointer + * + * @pre The callback must be registered with companion_request_result_callback() + * + * @see companion_request_result_callback() + */ +typedef void (*companion_request_result_cb)(char *cmd, char *arg, int ret, + void *user_data); + +/** + * @brief Registers request result callback funtion. + * @details This function registers the callback function for requested group management + * functions and receive processing results after the request complete. + * + * @since_tizen 5.0 * * @param[in] handle The companion manager handle - * @param[out] uuid Local device UUID + * @param[in] callback Callback function pointer + * @param[in] user_data User data pointer + * * * @return 0 on success, otherwise a negative error value. * @retval #COMP_ERROR_NONE Successful * @retval #COMP_ERROR_INVALID_PARAMETER Invalid parameter * - * @see companion_device_get_my_device() + * @see companion_request_create_group() + * @see companion_request_invite_device() + * @see companion_request_eject_device() + * @see companion_request_delete_group() + * @see companion_device_send_data() * */ -int companion_device_get_my_uuid(companion_h handle, char **uuid); +int companion_request_result_callback(companion_h handle, + companion_request_result_cb callback, void *user_data); + +/** + * @} + */ -/* Group Information Module */ +/** + * @addtogroup CAPI_NETWORK_COMPANION_GROUP_INFORMATION_MODULE + * @{ + */ /** * @brief Creates a group handle. @@ -918,146 +944,200 @@ int companion_group_information_get_name(companion_group_h group, int companion_group_information_get_host_addr(companion_group_h group, char **host_addr); -/* Group Device Information Module */ +/** + * @} + */ + /** - * @brief Creates a device handle. + * @addtogroup CAPI_NETWORK_COMPANION_DEVICE_MODULE + * @{ + */ + + +/** + * @brief Called after companion_device_find(). + * @details This function can receive a device found. * * @since_tizen 5.0 + * @privlevel public + * @privilege %http://tizen.org/privilege/internet * - * @remarks The @a device should be released using companion_device_information_destroy(). - * - * @param[out] device Device handle + * @remarks The @a device should not be released. + * @remarks The @a device can be used only in the callback. To use outside, make a copy. * - * @return 0 on success, otherwise a negative error value. - * @retval #COMP_ERROR_NONE Successful - * @retval #COMP_ERROR_INVALID_PARAMETER Invalid parameter + * @param[out] device Device found + * @param[out] user_data User data pointer * - * @see companion_device_information_clone() - * @see companion_device_information_destroy() - * @see companion_device_information_get_device_id() - * @see companion_device_information_get_ip() - * @see companion_device_information_get_device_type() + * @pre The callback must be registered with companion_device_find() * + * @see companion_device_find() */ -int companion_device_information_create(companion_device_h* device); +typedef bool (*companion_device_found_cb)(companion_device_h device, void *user_data); /** - * @brief Clones the device handle. + * @brief Called after companion_device_find() finished. + * @details Called when the maximum wait time elapsed after the companion_device_find() done. * * @since_tizen 5.0 + * @privlevel public + * @privilege %http://tizen.org/privilege/internet * - * @remarks The @a target should be released using companion_device_information_destroy(). - * - * @param[in] target Target device handle - * @param[in] source Source device handle + * @param[out] result Result of operation + * @param[out] user_data User data pointer * - * @return 0 on success, otherwise a negative error value. - * @retval #COMP_ERROR_NONE Successful - * @retval #COMP_ERROR_INVALID_PARAMETER Invalid parameter + * @pre The callback must be registered with companion_device_find() * - * @see companion_device_information_create() - * @see companion_device_information_destroy() - * @see companion_device_information_get_device_id() - * @see companion_device_information_get_ip() - * @see companion_device_information_get_device_type() + * @see companion_device_find() + */ +typedef void (*companion_device_find_finish_cb)(int result, void *user_data); + + +/** + * @brief Called after companion_device_send_data(). + * @details Called when the maximum wait time elapsed or after the companion_device_send_data() + * finished successfully. + * + * @since_tizen 5.0 + * @privlevel public + * @privilege %http://tizen.org/privilege/internet + * + * @remarks The @a resp_data should not be released. + * @remarks The @a resp_data can be used only in the callback. To use outside, make a copy. + * + * @param[out] result Result of operation + * @param[out] resp_data Retrieved data + * @param[out] user_data User data pointer * + * @pre The callback must be registered with companion_device_send_data() + * + * @see companion_device_send_data() */ -int companion_device_information_clone(companion_device_h target, - companion_device_h source); +typedef void (*companion_device_send_data_finish_cb)(int result, char *resp_data, + void *user_data); + /** - * @brief Destroys the device handle. + * @brief Finds candidate devices to include my groups in the network. + * @details This function will search for candidate devices that can be included in local group. * * @since_tizen 5.0 + * @privlevel public + * @privilege %http://tizen.org/privilege/internet + * + * @param[in] handle The companion manager handle + * @param[in] timeout Time to find + * @param[in] found_cb Callback handler to retrieve the found device + * @param[in] finish_cb Callback handler to know finding process finished + * @param[in] user_data User data poiter * - * @param[in] device Device handle * * @return 0 on success, otherwise a negative error value. * @retval #COMP_ERROR_NONE Successful * @retval #COMP_ERROR_INVALID_PARAMETER Invalid parameter * - * @see companion_device_information_create() - * @see companion_device_information_clone() - * @see companion_device_information_get_device_id() - * @see companion_device_information_get_ip() - * @see companion_device_information_get_device_type() + * @see companion_device_get_found_devices() * */ -int companion_device_information_destroy(companion_device_h device); +int companion_device_find(companion_h handle, int timeout, + companion_device_found_cb found_cb, companion_device_find_finish_cb finish_cb, + void *user_data); /** - * @brief Gets device ID of the device handle. + * @brief Gets a list of candidate devices to can be included my group. + * @details This function retrieves a list of multiple owner enabled devices found. * * @since_tizen 5.0 + * @privlevel public + * @privilege %http://tizen.org/privilege/internet * - * @remarks The @a device_id should be released using free(). + * @param[in] handle The companion manager handle + * @param[in] devices Device list + * @param[in] count Number of devices * - * @param[in] device Device handle - * @param[out] device_id Device ID * * @return 0 on success, otherwise a negative error value. * @retval #COMP_ERROR_NONE Successful * @retval #COMP_ERROR_INVALID_PARAMETER Invalid parameter * - * @see companion_device_information_create() - * @see companion_device_information_clone() - * @see companion_device_information_destroy() - * @see companion_device_information_get_ip() - * @see companion_device_information_get_device_type() + * @see companion_device_find_mowned_device() * */ -int companion_device_information_get_device_id(companion_device_h device, - char **device_id); +int companion_device_get_found_devices(companion_h handle, + companion_device_h **devices, int *count); /** - * @brief Gets IP of the device handle. + * @brief Finds my owned devices in the network. + * @details This function looks up devices on your network that are registered as multiple + * owners. * * @since_tizen 5.0 + * @privlevel public + * @privilege %http://tizen.org/privilege/internet * - * @remarks The @a ip should be released using free(). + * @param[in] handle The companion manager handle + * @param[in] timeout Time to find + * @param[in] found_cb Callback handler to retrieve the found device + * @param[in] finish_cb Callback handler to know finding process finished + * @param[in] user_data User data poiter * - * @param[in] device Device handle - * @param[out] ip IP address * * @return 0 on success, otherwise a negative error value. * @retval #COMP_ERROR_NONE Successful * @retval #COMP_ERROR_INVALID_PARAMETER Invalid parameter * - * @see companion_device_information_create() - * @see companion_device_information_clone() - * @see companion_device_information_destroy() - * @see companion_device_information_get_device_id() - * @see companion_device_information_get_device_type() + * @see companion_device_get_found_mowned_devices() * */ -int companion_device_information_get_ip(companion_device_h device, char **ip); +int companion_device_find_mowned_device(companion_h handle, int timeout, + companion_device_found_cb found_cb, companion_device_find_finish_cb finish_cb, + void *user_data); /** - * @brief Gets device type of the device handle. + * @brief Gets a list of discovered owned devices. + * @details This function retrieves a list of my owned devices found. * * @since_tizen 5.0 + * @privlevel public + * @privilege %http://tizen.org/privilege/internet * - * @remarks The @a device_type should be released using free(). + * @param[in] handle The companion manager handle + * @param[in] devices Device list + * @param[in] count Number of devices * - * @param[in] device Device handle - * @param[out] device_type Device type * * @return 0 on success, otherwise a negative error value. * @retval #COMP_ERROR_NONE Successful * @retval #COMP_ERROR_INVALID_PARAMETER Invalid parameter * - * @see companion_device_information_create() - * @see companion_device_information_clone() - * @see companion_device_information_destroy() - * @see companion_device_information_get_device_id() - * @see companion_device_information_get_ip() + * @see companion_device_find_mowned_device() * */ -int companion_device_information_get_device_type(companion_device_h device, - char **device_type); +int companion_device_get_found_mowned_devices(companion_h handle, + companion_device_h **devices, int *count); -/* Group Management Module */ + +/** + * @brief Gets my local device handle. + * @details This function returns the local device information handle. + * + * @since_tizen 5.0 + * @privlevel public + * @privilege %http://tizen.org/privilege/internet + * + * @param[in] handle The companion manager handle + * @param[in] device Local device handle + * + * @return 0 on success, otherwise a negative error value. + * @retval #COMP_ERROR_NONE Successful + * @retval #COMP_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #COMP_ERROR_NO_DATA No data + * + * @see companion_device_get_my_uuid() + * + */ +int companion_device_get_my_device(companion_h handle, + companion_device_h *device); /** * @brief Sends data to the remote device. @@ -1071,7 +1151,7 @@ int companion_device_information_get_device_type(companion_device_h device, * @param[in] device Device handle * @param[in] data Data to send * @param[in] len What length to send - * @param[in] finish_cb Callback to be called after companion_send_data() complete + * @param[in] finish_cb Callback to be called after companion_device_send_data() complete * @param[in] user_data User data pointer * * @@ -1080,157 +1160,168 @@ int companion_device_information_get_device_type(companion_device_h device, * @retval #COMP_ERROR_INVALID_PARAMETER Invalid parameter * * @see companion_request_create_group() - * @see companion_request_invite() - * @see companion_request_eject() + * @see companion_request_invite_device() + * @see companion_request_eject_device() * @see companion_request_delete_group() * @see companion_request_result_callback() * */ -int companion_send_data(companion_h handle, companion_device_h device, char *data, - int len, companion_send_data_finish_cb finish_cb, void *user_data); +int companion_device_send_data(companion_h handle, companion_device_h device, char *data, + int len, companion_device_send_data_finish_cb finish_cb, void *user_data); /** - * @brief Requests to create a group. - * @details We can create a group. This generated group can include device, and remote - * devices can inquire remotely group information and device information included in group. + * @} + */ + +/** + * @addtogroup CAPI_NETWORK_COMPANION_DEVICE_INFORMATION_MODULE + * @{ + */ + +/** + * @brief Creates a device handle. * * @since_tizen 5.0 - * @privlevel public - * @privilege %http://tizen.org/privilege/internet * - * @param[in] handle The companion manager handle - * @param[in] device Device handle - * @param[in] group_name Group name + * @remarks The @a device should be released using companion_device_information_destroy(). * + * @param[out] device Device handle * * @return 0 on success, otherwise a negative error value. * @retval #COMP_ERROR_NONE Successful * @retval #COMP_ERROR_INVALID_PARAMETER Invalid parameter * - * @see companion_request_invite() - * @see companion_request_eject() - * @see companion_request_delete_group() - * @see companion_request_result_callback() - * @see companion_send_data() + * @see companion_device_information_clone() + * @see companion_device_information_destroy() + * @see companion_device_information_get_device_id() + * @see companion_device_information_get_ip() + * @see companion_device_information_get_device_type() * */ -int companion_request_create_group(companion_h handle, - companion_device_h device, char *group_name); +int companion_device_information_create(companion_device_h* device); /** - * @brief Requests to invite a device to the group. - * @details This function invites a remote device to a specific group. At the time of - * invitation, user can enter the authentication information (i.e., PIN) or use the - * certificate. + * @brief Clones the device handle. * * @since_tizen 5.0 - * @privlevel public - * @privilege %http://tizen.org/privilege/internet * - * @param[in] handle The companion manager handle - * @param[in] group Group handle - * @param[in] device Device handle - * @param[in] PIN PIN number + * @remarks The @a target should be released using companion_device_information_destroy(). * + * @param[in] target Target device handle + * @param[in] source Source device handle * * @return 0 on success, otherwise a negative error value. * @retval #COMP_ERROR_NONE Successful * @retval #COMP_ERROR_INVALID_PARAMETER Invalid parameter * - * @see companion_request_create_group() - * @see companion_request_eject() - * @see companion_request_delete_group() - * @see companion_request_result_callback() - * @see companion_send_data() + * @see companion_device_information_create() + * @see companion_device_information_destroy() + * @see companion_device_information_get_device_id() + * @see companion_device_information_get_ip() + * @see companion_device_information_get_device_type() * */ -int companion_request_invite(companion_h handle, companion_group_h group, - companion_device_h device, char *PIN); +int companion_device_information_clone(companion_device_h target, + companion_device_h source); /** - * @brief Requests to eject a device. - * @details This function is used to kick away a remote devices in a specific group. + * @brief Destroys the device handle. * * @since_tizen 5.0 - * @privlevel public - * @privilege %http://tizen.org/privilege/internet * - * @param[in] handle The companion manager handle - * @param[in] group Group handle * @param[in] device Device handle * + * @return 0 on success, otherwise a negative error value. + * @retval #COMP_ERROR_NONE Successful + * @retval #COMP_ERROR_INVALID_PARAMETER Invalid parameter + * + * @see companion_device_information_create() + * @see companion_device_information_clone() + * @see companion_device_information_get_device_id() + * @see companion_device_information_get_ip() + * @see companion_device_information_get_device_type() + * + */ +int companion_device_information_destroy(companion_device_h device); + +/** + * @brief Gets device ID of the device handle. + * + * @since_tizen 5.0 + * + * @remarks The @a device_id should be released using free(). + * + * @param[in] device Device handle + * @param[out] device_id Device ID * * @return 0 on success, otherwise a negative error value. * @retval #COMP_ERROR_NONE Successful * @retval #COMP_ERROR_INVALID_PARAMETER Invalid parameter * - * @see companion_request_create_group() - * @see companion_request_eject() - * @see companion_request_delete_group() - * @see companion_request_result_callback() - * @see companion_send_data() + * @see companion_device_information_create() + * @see companion_device_information_clone() + * @see companion_device_information_destroy() + * @see companion_device_information_get_ip() + * @see companion_device_information_get_device_type() * */ -int companion_request_eject(companion_h handle, companion_group_h group, - companion_device_h device); +int companion_device_information_get_device_id(companion_device_h device, + char **device_id); /** - * @brief Requests to delete the group. - * @details This function deletes a specific group and expels all devices in that group. + * @brief Gets IP of the device handle. * * @since_tizen 5.0 - * @privlevel public - * @privilege %http://tizen.org/privilege/internet * - * @param[in] handle The companion manager handle - * @param[in] group Group handle + * @remarks The @a ip should be released using free(). * + * @param[in] device Device handle + * @param[out] ip IP address * * @return 0 on success, otherwise a negative error value. * @retval #COMP_ERROR_NONE Successful * @retval #COMP_ERROR_INVALID_PARAMETER Invalid parameter * - * @see companion_request_create_group() - * @see companion_request_invite() - * @see companion_request_eject() - * @see companion_request_result_callback() - * @see companion_send_data() + * @see companion_device_information_create() + * @see companion_device_information_clone() + * @see companion_device_information_destroy() + * @see companion_device_information_get_device_id() + * @see companion_device_information_get_device_type() * */ -int companion_request_delete_group(companion_h handle, companion_group_h group); +int companion_device_information_get_ip(companion_device_h device, char **ip); /** - * @brief Registers request result callback funtion. - * @details This function registers the callback function for requested group management - * functions and receive processing results after the request complete. + * @brief Gets device type of the device handle. * * @since_tizen 5.0 * - * @param[in] handle The companion manager handle - * @param[in] callback Callback function pointer - * @param[in] user_data User data pointer + * @remarks The @a device_type should be released using free(). * + * @param[in] device Device handle + * @param[out] device_type Device type * * @return 0 on success, otherwise a negative error value. * @retval #COMP_ERROR_NONE Successful * @retval #COMP_ERROR_INVALID_PARAMETER Invalid parameter * - * @see companion_request_create_group() - * @see companion_request_invite() - * @see companion_request_eject() - * @see companion_request_delete_group() - * @see companion_send_data() + * @see companion_device_information_create() + * @see companion_device_information_clone() + * @see companion_device_information_destroy() + * @see companion_device_information_get_device_id() + * @see companion_device_information_get_ip() * */ -int companion_request_result_callback(companion_h handle, - companion_request_result_cb callback, void *user_data); +int companion_device_information_get_device_type(companion_device_h device, + char **device_type); /** * @} */ + #ifdef __cplusplus } #endif -#endif /* __TIZEN_NETWORK_COMPANION_H__ */ \ No newline at end of file +#endif /* __TIZEN_NETWORK_COMPANION_H__ */ diff --git a/capi/src/companion.c b/capi/src/companion.c old mode 100755 new mode 100644 index 91dd6ab..74c10ca --- a/capi/src/companion.c +++ b/capi/src/companion.c @@ -202,6 +202,7 @@ EXPORT_API int companion_group_get_found_groups(companion_h handle, _DBG("get found groups : %d", *count); + /* LCOV_EXCL_START */ if (*count > 0) { GVariantIter *iter = NULL, *iter_row = NULL; GVariant *key_value; @@ -248,12 +249,13 @@ EXPORT_API int companion_group_get_found_groups(companion_h handle, } g_variant_iter_free(iter); } + /* LCOV_EXCL_STOP */ g_variant_unref(va); return ret; } -EXPORT_API int companion_group_join(companion_h handle, companion_group_h group, +EXPORT_API int companion_request_join_group(companion_h handle, companion_group_h group, companion_group_find_finish_cb callback, void *user_data) { int ret = COMP_ERROR_NONE; @@ -268,8 +270,8 @@ EXPORT_API int companion_group_join(companion_h handle, companion_group_h group, return ret; } -EXPORT_API int companion_group_leave(companion_h handle, companion_group_h group, - companion_group_find_finish_cb callback, void *user_data) +EXPORT_API int companion_request_leave_group (companion_h handle, + companion_group_h group, companion_group_find_finish_cb callback, void *user_data) { int ret = COMP_ERROR_NONE; @@ -329,8 +331,9 @@ EXPORT_API int companion_device_find_mowned_device(companion_h handle, return ret; } -EXPORT_API int companion_send_data(companion_h handle, companion_device_h device, - char *data, int len, companion_send_data_finish_cb finish_cb, void *user_data) +EXPORT_API int companion_device_send_data(companion_h handle, + companion_device_h device, char *data, int len, + companion_device_send_data_finish_cb finish_cb, void *user_data) { int ret = COMP_ERROR_NONE; char *buf = NULL; @@ -346,8 +349,10 @@ EXPORT_API int companion_send_data(companion_h handle, companion_device_h device buf = g_malloc0(len + 1); if (NULL == buf) { + /* LCOV_EXCL_START */ _ERR("g_malloc0 is failed"); return COMP_ERROR_OUT_OF_MEMORY; + /* LCOV_EXCL_STOP */ } memcpy(buf, data, len); @@ -363,7 +368,7 @@ EXPORT_API int companion_send_data(companion_h handle, companion_device_h device return ret; } -/* companion_group_join : join to remote group. if group handle is my daemon's, +/* companion_request_join_group : join to remote group. if group handle is my daemon's, then the api return fail error */ EXPORT_API int companion_device_get_found_devices(companion_h handle, companion_device_h **devices, int *count) @@ -384,7 +389,7 @@ EXPORT_API int companion_device_get_found_devices(companion_h handle, *count = num; _DBG("get found devices : %d", *count); - + /* LCOV_EXCL_START */ if (*count > 0) { GVariantIter *iter = NULL, *iter_row = NULL; GVariant *key_value; @@ -422,6 +427,7 @@ EXPORT_API int companion_device_get_found_devices(companion_h handle, } g_variant_iter_free(iter); } + /* LCOV_EXCL_STOP */ g_variant_unref(va); return ret; @@ -447,6 +453,7 @@ EXPORT_API int companion_device_get_found_mowned_devices( _INFO("get found mowned devices : %d", *count); + /* LCOV_EXCL_START */ if (*count > 0) { GVariantIter *iter = NULL, *iter_row = NULL; GVariant *key_value; @@ -484,6 +491,7 @@ EXPORT_API int companion_device_get_found_mowned_devices( } g_variant_iter_free(iter); } + /* LCOV_EXCL_STOP */ g_variant_unref(va); return ret; @@ -512,6 +520,7 @@ EXPORT_API int companion_device_get_my_device(companion_h handle, group_call_get_my_mowned_device_sync(_handle->group_proxy, &va, NULL, &error); g_variant_get(va, "a{sv}", &iter); + /* LCOV_EXCL_START */ while (g_variant_iter_loop(iter, "{sv}", &key, &key_value)) { if (g_strcmp0(key, "DeviceID") == 0) deviceid = (char *)g_variant_get_string(key_value, NULL); @@ -526,7 +535,8 @@ EXPORT_API int companion_device_get_my_device(companion_h handle, } if (deviceid == NULL || addr == NULL || ver == NULL) - return -1; + return COMP_ERROR_NO_DATA; + /* LCOV_EXCL_STOP */ *device = (companion_device_h)create_device_handle(deviceid, addr, ver, port, sec_port); @@ -615,9 +625,9 @@ EXPORT_API int companion_group_get_member_devices(companion_h handle, return ret; } -EXPORT_API int companion_device_invite(companion_h handle, +EXPORT_API int companion_group_invite_device(companion_h handle, companion_group_h group, companion_device_h device, char *PIN, - companion_device_invite_result_cb result_cb, void *user_data) + companion_group_invite_device_result_cb result_cb, void *user_data) { int ret = COMP_ERROR_NONE; GError *error = NULL; @@ -636,21 +646,21 @@ EXPORT_API int companion_device_invite(companion_h handle, _handle->device_invite_result_cb.result_cb = result_cb; _handle->device_invite_result_cb.user_data = user_data; - /* Now, for the sake of convenience, we change 'companion_device_invite' to + /* Now, for the sake of convenience, we change 'companion_group_invite_device' to 'group_call_invite_sync'. */ #if 0 group_call_device_invite_sync(group_proxy, dev->device_id, PIN, &ret, NULL, &error); #else - group_call_invite_sync(_handle->group_proxy, grp->group_name, dev->device_id, PIN, &ret, - NULL, &error); + group_call_invite_sync(_handle->group_proxy, grp->group_name, dev->device_id, PIN, + &ret, NULL, &error); #endif return ret; } -EXPORT_API int companion_device_eject(companion_h handle, +EXPORT_API int companion_group_eject_device(companion_h handle, companion_group_h group, companion_device_h device, - companion_device_eject_result_cb result_cb, void *user_data) + companion_group_eject_device_result_cb result_cb, void *user_data) { int ret = COMP_ERROR_NONE; GError *error = NULL; @@ -674,7 +684,8 @@ EXPORT_API int companion_device_eject(companion_h handle, #if 0 group_call_device_eject_sync(group_proxy, dev->device_id, &ret, NULL, &error); #else - group_call_eject_sync(_handle->group_proxy, grp->group_name, dev->device_id, &ret, NULL, &error); + group_call_eject_sync(_handle->group_proxy, grp->group_name, dev->device_id, &ret, + NULL, &error); #endif return ret; @@ -688,8 +699,10 @@ EXPORT_API int companion_group_information_create(companion_group_h* group) companion_group_h _group = g_malloc0(sizeof(companion_group_s)); if (NULL == _group) { + /* LCOV_EXCL_START */ _ERR("Memory allocation Failed(%d)", errno); return COMP_ERROR_OUT_OF_MEMORY; + /* LCOV_EXCL_STOP */ } *group = _group; @@ -832,8 +845,10 @@ EXPORT_API int companion_device_information_create(companion_device_h* device) companion_device_h _device = g_malloc0(sizeof(companion_device_s)); if (NULL == device) { + /* LCOV_EXCL_START */ _ERR("Memory allocation Failed(%d)", errno); return COMP_ERROR_OUT_OF_MEMORY; + /* LCOV_EXCL_STOP */ } *device = _device; @@ -928,11 +943,15 @@ EXPORT_API int companion_device_information_get_device_type( } EXPORT_API int companion_request_create_group(companion_h handle, - companion_device_h device, char *group_name) + companion_device_h device, char *group_name, companion_request_done_cb cb, + void *user_data) { int ret = COMP_ERROR_NONE; GError *error = NULL; + NOTUSED(cb); + NOTUSED(user_data); + CHECK_FEATURE_SUPPORTED(COMPANION_FEATURE); comp_manager_s *_handle = handle; @@ -940,7 +959,8 @@ EXPORT_API int companion_request_create_group(companion_h handle, companion_device_s *dev = (companion_device_s *)device; companion_check_null_ret_error("device", device, COMP_ERROR_INVALID_PARAMETER); - companion_check_null_ret_error("group_name", group_name, COMP_ERROR_INVALID_PARAMETER); + companion_check_null_ret_error("group_name", group_name, + COMP_ERROR_INVALID_PARAMETER); _DBG("Device id : %s", dev->device_id); @@ -950,11 +970,15 @@ EXPORT_API int companion_request_create_group(companion_h handle, return ret; } -EXPORT_API int companion_request_invite(companion_h handle, - companion_group_h group, companion_device_h device, char *PIN) +EXPORT_API int companion_request_invite_device(companion_h handle, + companion_group_h group, companion_device_h device, char *PIN, + companion_request_done_cb cb, void *user_data) { int ret = COMP_ERROR_NONE; + NOTUSED(cb); + NOTUSED(user_data); + CHECK_FEATURE_SUPPORTED(COMPANION_FEATURE); comp_manager_s *_handle = handle; @@ -976,11 +1000,15 @@ EXPORT_API int companion_request_invite(companion_h handle, return ret; } -EXPORT_API int companion_request_eject(companion_h handle, - companion_group_h group, companion_device_h device) +EXPORT_API int companion_request_eject_device(companion_h handle, + companion_group_h group, companion_device_h device, companion_request_done_cb cb, + void *user_data) { int ret = COMP_ERROR_NONE; + NOTUSED(cb); + NOTUSED(user_data); + CHECK_FEATURE_SUPPORTED(COMPANION_FEATURE); comp_manager_s *_handle = handle; @@ -1003,7 +1031,7 @@ EXPORT_API int companion_request_eject(companion_h handle, } EXPORT_API int companion_request_delete_group(companion_h handle, - companion_group_h group) + companion_group_h group, companion_request_done_cb cb, void *user_data) { int ret = COMP_ERROR_NONE; @@ -1011,6 +1039,8 @@ EXPORT_API int companion_request_delete_group(companion_h handle, NOTUSED(handle); NOTUSED(group); + NOTUSED(cb); + NOTUSED(user_data); return ret; } diff --git a/capi/src/companion_private.h b/capi/src/companion_private.h index 9cdd606..350a98c 100644 --- a/capi/src/companion_private.h +++ b/capi/src/companion_private.h @@ -112,7 +112,7 @@ typedef struct _mowned_device_find_finish_cb_t { * @since_tizen 5.0 */ typedef struct _device_invite_result_cb_t { - companion_device_invite_result_cb result_cb; /**< User callback to be called */ + companion_group_invite_device_result_cb result_cb; /**< User callback to be called */ void *user_data; /**< User data pointer */ } device_invite_result_cb_t; @@ -121,7 +121,7 @@ typedef struct _device_invite_result_cb_t { * @since_tizen 5.0 */ typedef struct _device_eject_result_cb_t { - companion_device_eject_result_cb result_cb; /**< User callback to be called */ + companion_group_eject_device_result_cb result_cb; /**< User callback to be called */ void *user_data; /**< User data pointer */ } device_eject_result_cb_t; @@ -130,7 +130,7 @@ typedef struct _device_eject_result_cb_t { * @since_tizen 5.0 */ typedef struct _send_data_finish_cb_t { - companion_send_data_finish_cb finish_cb; /**< User callback to be called */ + companion_device_send_data_finish_cb finish_cb; /**< User callback to be called */ void *user_data; /**< User data pointer */ } send_data_finish_cb_t;