From: saerome.kim Date: Fri, 23 Mar 2018 11:29:16 +0000 (+0900) Subject: d2d-manager: initial documentation X-Git-Tag: submit/tizen/20190131.065036~85 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=f52736219578e67d461e3d4b30c87ead92329ce6;p=platform%2Fcore%2Fapi%2Fmulti-device-group.git d2d-manager: initial documentation Signed-off-by: saerome.kim --- diff --git a/capi/include/companion.h b/capi/include/companion.h index 545bc8e..c946c72 100644 --- a/capi/include/companion.h +++ b/capi/include/companion.h @@ -16,8 +16,8 @@ * limitations under the License. * */ -#ifndef __COMPANION_H__ -#define __COMPANION_H__ +#ifndef __TIZEN_NETWORK_COMMON_COMPANION_H__ +#define __TIZEN_NETWORK_COMMON_COMPANION_H__ #include @@ -25,9 +25,23 @@ extern "C" { #endif -#define TIZEN_ERROR_COMP 0 +/** + * @file companion.h + */ + +/** + * @addtogroup CAPI_NETWORK_COMMON_COMPANION_MODULE + * @{ + */ +#ifndef TIZEN_ERROR_COMP +#define TIZEN_ERROR_COMP -0x02F50000 /**< Base error code */ +#endif -/* error enum */ +/** + * @brief Error codes for companion-manager. + * + * @since_tizen 5.0 + */ typedef enum { COMP_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */ COMP_ERROR_IO_ERROR = TIZEN_ERROR_IO_ERROR, /**< I/O error */ @@ -38,124 +52,1068 @@ typedef enum { COMP_ERROR_COMM_ERROR = TIZEN_ERROR_COMP | 0x01, /**< communication error */ COMP_ERROR_RX = TIZEN_ERROR_COMP | 0x02, /**< RX error */ COMP_ERROR_TX = TIZEN_ERROR_COMP | 0x03, /**< TX error */ - COMP_ERROR_PLUGIN_FAIL = TIZEN_ERROR_COMP | 0x04, /**< Plugin failed */ - COMP_ERROR_OPERATION_FAILED = TIZEN_ERROR_COMP | 0x05, /**< Operation Failed */ - COMP_ERROR_ALREADY_IN_PROGRESS = TIZEN_ERROR_COMP | 0x06, /**< Already initilized */ + 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_UNKNOWN = -999, } comp_error_e; +/** + * @brief Group type. + * + * @since_tizen 5.0 + */ typedef enum { COMPANION_GROUP_TYPE_ERROR = 0, /**< Error */ COMPANION_GROUP_TYPE_MINE = 1, /**< Local type */ COMPANION_GROUP_TYPE_REMOTE = 2, /**< Remote type */ } companion_group_type_e; -typedef void *companion_group_h; -typedef void *companion_device_h; +/** + * @brief Device hande which represents a companion device. + * + * @since_tizen 5.0 + */ +typedef void *companion_group_h; /**< Group handle */ + +/** + * @brief Group handle which represents a companion group. + * + * @since_tizen 5.0 + */ +typedef void *companion_device_h; /**< Device handle */ + -typedef bool (*companion_group_found_cb)(companion_group_type_e type, companion_group_h group, - void *user_data); +/** + * @brief Called after companion_group_find(). + * @details This function can receive a group resource found. + * + * @since_tizen 5.0 + * + * @remarks The @group should not be released. + * @remarks The @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 + * + * @remarks The @device should not be released. + * @remarks The @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() + */ 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. + * + * @since_tizen 5.0 + * + * @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); + +/** + * @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 + * + * @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. + * + * @since_tizen 5.0 + * + * @param[out] result Result of operation + * @param[out] user_data User data pointer + * + * @pre The callback must be registered with companion_device_invite() + * + * @see companion_device_invite() + */ typedef void (*companion_device_invite_result_cb)(int result, void *user_data); + +/** + * @brief Called after companion_device_eject(). + * @details Called when the maximum wait time elapsed or after the companion_device_eject() + * finished successfully. + * + * @since_tizen 5.0 + * + * @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_device_eject() + */ typedef void (*companion_device_eject_result_cb)(int result, void *user_data); -typedef void (*companion_send_data_finish_cb)(int result, char *resp_data, void *user_data); -typedef void (*companion_request_result_cb)(char *cmd, char *arg, int ret, void *user_data); + +/** + * @brief Called after companion_send_data(). + * @details Called when the maximum wait time elapsed or after the companion_send_data() + * finished successfully. + * + * @since_tizen 5.0 + * + * @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_send_data() + * + * @see companion_send_data() + */ +typedef void (*companion_send_data_finish_cb)(int result, char *resp_data, + void *user_data); + +/** + * @brief Callback function potiner to be regsitered by calling + * companion_request_result_callback(). + * + * @since_tizen 5.0 + * + * @remarks The @cmd, @arg should not be released. + * @remarks The @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*/ -int companion_initialize(); /* initialize gdbus connection with manager daemon */ -int companion_deinitialize(); /* deinitialize gdbus connection with manager daemon */ + +/** + * @brief Initializes companion-manager. + * @since_tizen 5.0 + * + * @remarks You must release @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_INVALID_OPERATION Invalid operation + * @retval #COMP_ERROR_OPERATION_FAILED Operation failed + * @retval #COMP_ERROR_PERMISSION_DENIED Permission Denied + * @retval #COMP_ERROR_OUT_OF_MEMORY Out of memory + */ +int companion_initialize(); + +/** + * @brief Deinitializes the companion-manager. + * @since_tizen 5.0 + * + * @param[in] handle The companion manager handle + * + * @return 0 on success, otherwise negative error value + * @retval #COMP_ERROR_NONE Successful + * @retval #COMP_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #COMP_ERROR_INVALID_OPERATION Invalid operation + * @retval #COMP_ERROR_OPERATION_FAILED Operation failed + */ +int companion_deinitialize(); /* Group Module APIs*/ + /* companion_group_create : craete group in my daemon */ -int companion_group_create(char *group_name); /* O */ -/* companion_group_find : find groups in my daemon + remote groups in network */ -int companion_group_find(int timeout, companion_group_found_cb found_cb, - companion_group_find_finish_cb finish_cb, void *user_data); /* O */ -/* companion_group_find : find groups in my daemon + remote groups in network */ -int companion_group_get_found_groups(companion_group_h **groups, - int *count); /* O */ -/* companion_group_join : join to remote group. if group handle is my daemon's, then the api return fail error */ -int companion_group_join(companion_group_h group, companion_group_find_finish_cb callback, - void *user_data); -/* companion_group_join : leave from remote group. if group handle is my daemon's, then the api return fail error */ -int companion_group_leave(companion_group_h group, companion_group_find_finish_cb callback, + +/** + * @brief Create group + * @details This API is to allocate new group in local companion-manager + * + * @since_tizen 5.0 + * + * @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_find() + * @see companion_group_get_found_groups() + * + */ +int companion_group_create(char *group_name); + +/** + * @brief Finds group resources in local and the network + * @details This API is find group resources in the network plus my local network. + * + * @since_tizen 5.0 + * + * @param[in] timeout Time to find + * @param[in] found_cb Callback handler to retrieve the found group resource + * @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 + * + * @see companion_group_create() + * @see companion_group_get_found_groups() + * + */ +int companion_group_find( + int timeout, + companion_group_found_cb found_cb, + companion_group_find_finish_cb finish_cb, void *user_data); -/* companion_group_delete : remove group. if group handle is remote group, then the api return fail error */ + +/** + * @brief Gets a list of group resources + * @details This API retrieves a list of group resources found. + * + * @since_tizen 5.0 + * + * @param[in] groups Group resource list + * @param[out] count Number of groups + * + * + * @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_find() + * + */ +int companion_group_get_found_groups(companion_group_h **groups, + int *count); + +/** + * @brief Joins the remote group. + * @details This API 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 + * + * @param[in] groups 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() + * + */ +int companion_group_join(companion_group_h group, + companion_group_find_finish_cb callback, void *user_data); + +/** + * @brief Leaves my own devices from the remote group. + * @details This API allows my own device to be removed from the remote group. + * + * @since_tizen 5.0 + * + * @param[in] group Group handle + * @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_join() + * @see companion_group_delete() + * @see companion_group_merge() + * @see companion_group_get_member_devices() + * + */ +int companion_group_leave(companion_group_h group, + companion_group_find_finish_cb callback, void *user_data); + +/** + * @brief Deletes the group. + * @details This API deletes a specific group and expels all devices in that group. + * + * @since_tizen 5.0 + * + * @param[in] group Group handle + * + * + * @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_leave() + * @see companion_group_merge() + * @see companion_group_get_member_devices() + * + */ int companion_group_delete(companion_group_h group); -int companion_group_merge(companion_group_h dest_group, companion_group_h src_group); + +/** + * @brief Combines both groups to one. + * @details This API combines two groups into one. + * + * @since_tizen 5.0 + * + * @param[in] dest_group Group handle to be united + * @param[in] src_group Group handle to be merged + * + * + * @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_leave() + * @see companion_group_delete() + * @see companion_group_get_member_devices() + * + */ +int companion_group_merge(companion_group_h dest_group, + companion_group_h src_group); + +/** + * @brief Gets devices list in a group resource + * @details This API retrieves a devices list of group resources. + * + * @since_tizen 5.0 + * + * @param[in] groups Group resource list + * @param[out] groups Group resource list + * @param[out] count Number of devices in a group + * + * + * @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_leave() + * @see companion_group_delete() + * @see companion_group_merge() + * + */ int companion_group_get_member_devices(companion_group_h group, companion_device_h **devices, int *count); /* Device Module */ -/* The "Device" is only one group device per target. - If you have any good terms, I would appreciate your suggestions.*/ - -/* companion_group_device_find : Find the group devices on the network. (exclude myself) */ -int companion_device_find(int timeout, companion_device_found_cb found_cb, - companion_device_find_finish_cb finish_cb, void *user_data); -int companion_device_get_found_devices(companion_device_h **devices, int *count); -int companion_device_find_mowned_device(int timeout, - companion_device_found_cb found_cb, companion_device_find_finish_cb finish_cb, void *user_data); + +/** + * @brief Finds candidate devices to include my groups in the network. + * @details This API will search for candidate devices that can be included in local group. + * + * @since_tizen 5.0 + * + * @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 + * + * @see companion_device_get_found_devices() + * + */ +int companion_device_find( + int timeout, + companion_device_found_cb found_cb, + companion_device_find_finish_cb finish_cb, + void *user_data); + +/** + * @brief Gets a list of candidate devices to can be included my group + * @details This API retrieves a list of multiple owner enabled devices found. + * + * @since_tizen 5.0 + * + * @param[in] devices Device list + * @param[in] count Number of devices + * + * + * @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() + * + */ +int companion_device_get_found_devices( + companion_device_h **devices, + int *count); + +/** + * @brief Finds my owned devices in the network. + * @details This API looks up devices on your network that are registered as multiple + * owners. + * + * @since_tizen 5.0 + * + * @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 + * + * @see companion_device_get_found_mowned_devices() + * + */ +int companion_device_find_mowned_device( + int timeout, + companion_device_found_cb found_cb, + companion_device_find_finish_cb finish_cb, + void *user_data); + +/** + * @brief Gets a list of discovered owned devices + * @details This API retrieves a list of my owned devices found. + * + * @since_tizen 5.0 + * + * @param[in] devices Device list + * @param[in] count Number of devices + * + * + * @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() + * + */ int companion_device_get_found_mowned_devices( companion_device_h **devices, int *count); -/* companion_group_device_invite : Invite a remote group device to my group. */ -int companion_device_invite(companion_group_h group, - companion_device_h device, char *PIN, companion_device_invite_result_cb callback, void *user_data); +/* companion_group_device_invite : Invite a remote group device to my local group. */ + +/** + * @brief Requests to invite a device to the group which local device owns. + * @details This API 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 + * + * @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_request_create_group() + * @see companion_request_eject() + * @see companion_request_delete_group() + * @see companion_request_result_callback() + * @see companion_send_data() + * + */ +int companion_device_invite( + companion_group_h group, + companion_device_h device, + char *PIN, + companion_device_invite_result_cb callback, + void *user_data); /* companion_group_device_eject : Eject a remote group device from my group. */ -int companion_device_eject(companion_group_h group, - companion_device_h device, companion_device_eject_result_cb callback, void *user_data); +/** + * @brief Requests to expel the device from the group which local device owns. + * @details This API is used to kick away a remote devices in my local group. + * + * @since_tizen 5.0 + * + * @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 + * + * + * @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() + * + */ +int companion_device_eject( + companion_group_h group, + companion_device_h device, + companion_device_eject_result_cb callback, + void *user_data); + +/** + * @brief Get my local device handle. + * @details This API returns the local device information handle. + * + * @since_tizen 5.0 + * + * @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 + * + * @see companion_device_get_my_uuid() + * + */ int companion_device_get_my_device(companion_device_h *device); + +/** + * @brief Get my local device ID. + * @details This API returns current UUID of local device. + * + * @since_tizen 5.0 + * + * @param[in] 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 + * + * @see companion_device_get_my_device() + * + */ int companion_device_get_my_uuid(char **uuid); /* Group Information Module */ + +/** + * @brief Creates a group handle. + * + * @since_tizen 5.0 + * + * @param[in] group Group handle + * + * @return 0 on success, otherwise a negative error value. + * @retval #COMP_ERROR_NONE Successful + * @retval #COMP_ERROR_INVALID_PARAMETER Invalid parameter + * + * @see companion_group_information_clone() + * @see companion_group_information_destroy() + * @see companion_group_information_get_type() + * @see companion_group_information_get_resource_type() + * @see companion_group_information_get_uri_path() + * @see companion_group_information_get_name() + * @see companion_group_information_get_host_addr() + * + */ int companion_group_information_create(companion_group_h* group); + +/** + * @brief Clones the group handle. + * + * @since_tizen 5.0 + * + * @param[out] dst Destination group handle + * @param[in] src Source group handle + * + * @return 0 on success, otherwise a negative error value. + * @retval #COMP_ERROR_NONE Successful + * @retval #COMP_ERROR_INVALID_PARAMETER Invalid parameter + * + * @see companion_group_information_create() + * @see companion_group_information_destroy() + * @see companion_group_information_get_type() + * @see companion_group_information_get_resource_type() + * @see companion_group_information_get_uri_path() + * @see companion_group_information_get_name() + * @see companion_group_information_get_host_addr() + * + */ int companion_group_information_clone(companion_group_h dst, companion_group_h src); + +/** + * @brief Destroys the group handle. + * + * @since_tizen 5.0 + * + * @param[in] group Group handle + * + * @return 0 on success, otherwise a negative error value. + * @retval #COMP_ERROR_NONE Successful + * @retval #COMP_ERROR_INVALID_PARAMETER Invalid parameter + * + * @see companion_group_information_create() + * @see companion_group_information_clone() + * @see companion_group_information_get_type() + * @see companion_group_information_get_resource_type() + * @see companion_group_information_get_uri_path() + * @see companion_group_information_get_name() + * @see companion_group_information_get_host_addr() + * + */ int companion_group_information_destroy(companion_group_h group); +/** + * @brief Gets group type of the group handle. + * + * @since_tizen 5.0 + * + * @param[in] group Group handle + * @param[out] type Group type + * + * @return 0 on success, otherwise a negative error value. + * @retval #COMP_ERROR_NONE Successful + * @retval #COMP_ERROR_INVALID_PARAMETER Invalid parameter + * + * @see companion_group_information_create() + * @see companion_group_information_clone() + * @see companion_group_information_destroy() + * @see companion_group_information_get_resource_type() + * @see companion_group_information_get_uri_path() + * @see companion_group_information_get_name() + * @see companion_group_information_get_host_addr() + * + */ int companion_group_information_get_type(companion_group_h group, companion_group_type_e *type); + +/** + * @brief Gets resource type of the group handle. + * + * @since_tizen 5.0 + * + * @param[in] group Group handle + * @param[out] resource_type Resource type + * + * @return 0 on success, otherwise a negative error value. + * @retval #COMP_ERROR_NONE Successful + * @retval #COMP_ERROR_INVALID_PARAMETER Invalid parameter + * + * @see companion_group_information_create() + * @see companion_group_information_clone() + * @see companion_group_information_destroy() + * @see companion_group_information_get_type() + * @see companion_group_information_get_uri_path() + * @see companion_group_information_get_name() + * @see companion_group_information_get_host_addr() + * + */ int companion_group_information_get_resource_type( - companion_group_h group, char **resource_type); + companion_group_h group, char **resource_type); + +/** + * @brief Gets URI path of the group handle. + * + * @since_tizen 5.0 + * + * @param[in] group Group handle + * @param[out] uri_path URI path + * + * @return 0 on success, otherwise a negative error value. + * @retval #COMP_ERROR_NONE Successful + * @retval #COMP_ERROR_INVALID_PARAMETER Invalid parameter + * + * @see companion_group_information_create() + * @see companion_group_information_clone() + * @see companion_group_information_destroy() + * @see companion_group_information_get_type() + * @see companion_group_information_get_resource_type() + * @see companion_group_information_get_name() + * @see companion_group_information_get_host_addr() + * + */ int companion_group_information_get_uri_path(companion_group_h group, - char **uri_path); + char **uri_path); + +/** + * @brief Gets name of the group handle. + * + * @since_tizen 5.0 + * + * @param[in] group Group handle + * @param[out] name Name of the group + * + * @return 0 on success, otherwise a negative error value. + * @retval #COMP_ERROR_NONE Successful + * @retval #COMP_ERROR_INVALID_PARAMETER Invalid parameter + * + * @see companion_group_information_create() + * @see companion_group_information_clone() + * @see companion_group_information_destroy() + * @see companion_group_information_get_type() + * @see companion_group_information_get_resource_type() + * @see companion_group_information_get_uri_path() + * @see companion_group_information_get_host_addr() + * + */ int companion_group_information_get_name(companion_group_h group, - char **name); + char **name); + +/** + * @brief Gets host address of the group handle. + * + * @since_tizen 5.0 + * + * @param[in] group Group handle + * @param[out] host_addr Host address of the group + * + * @return 0 on success, otherwise a negative error value. + * @retval #COMP_ERROR_NONE Successful + * @retval #COMP_ERROR_INVALID_PARAMETER Invalid parameter + * + * @see companion_group_information_create() + * @see companion_group_information_clone() + * @see companion_group_information_destroy() + * @see companion_group_information_get_type() + * @see companion_group_information_get_resource_type() + * @see companion_group_information_get_name() + * @see companion_group_information_get_uri_path() + * + */ int companion_group_information_get_host_addr(companion_group_h group, - char **host_addr); + char **host_addr); /* Group Device Information Module */ -/* I think the information in the group device is the same as the "device informations" */ + +/** + * @brief Create a device handle. + * + * @since_tizen 5.0 + * + * @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_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_device_information_create(companion_device_h* device); + +/** + * @brief Clones the device handle. + * + * @since_tizen 5.0 + * + * @param[out] target Target device handle + * @param[int] 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_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_device_information_clone(companion_device_h target, companion_device_h source); -int companion_device_information_destroy(companion_device_h data); + +/** + * @brief Destroys the device handle. + * + * @since_tizen 5.0 + * + * @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 Get device ID of the device handle. + * + * @since_tizen 5.0 + * + * @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() + * + */ int companion_device_information_get_device_id(companion_device_h device, char **device_id); + +/** + * @brief Get IP of the device handle. + * + * @since_tizen 5.0 + * + * @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() + * + */ int companion_device_information_get_ip(companion_device_h device, char **ip); -int companion_device_information_get_device_type( - companion_device_h device, char **device_type); +/** + * @brief Get device type of the device handle. + * + * @since_tizen 5.0 + * + * @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() + * + */ +int companion_device_information_get_device_type(companion_device_h device, + char **device_type); + +/* Group Management Module */ + +/** + * @brief Sends data to the remote device. + * @details We can send data to devices included in group. + * + * @since_tizen 5.0 + * + * @param[in] device Device handle + * @param[in] data Data to send + * @param[in] len What length to send + * + * + * @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_request_result_callback() + * + */ int companion_send_data(companion_device_h device, char *data, int len, companion_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. + * + * @since_tizen 5.0 + * + * @param[in] device Device handle + * @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_request_invite() + * @see companion_request_eject() + * @see companion_request_delete_group() + * @see companion_request_result_callback() + * @see companion_send_data() + * + */ int companion_request_create_group(companion_device_h device, char *group_name); + +/** + * @brief Requests to invite a device to the group. + * @details This API 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 + * + * @param[in] group Group handle + * @param[in] device Device handle + * @param[in] PIN PIN number + * + * + * @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() + * + */ int companion_request_invite(companion_group_h group, companion_device_h device, char *PIN); + +/** + * @brief Requests to eject a device. + * @details This API is used to kick away a remote devices in a specific group. + * + * @since_tizen 5.0 + * + * @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_request_create_group() + * @see companion_request_eject() + * @see companion_request_delete_group() + * @see companion_request_result_callback() + * @see companion_send_data() + * + */ int companion_request_eject(companion_group_h group, companion_device_h device); + +/** + * @brief Requests to delete the group. + * @details This API deletes a specific group and expels all devices in that group. + * + * @since_tizen 5.0 + * + * @param[in] group Group 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_invite() + * @see companion_request_eject() + * @see companion_request_result_callback() + * @see companion_send_data() + * + */ int companion_request_delete_group(companion_group_h group); + +/** + * @brief Registers request result callback funtion. + * @details This API registers the callback function for requested group management + * functions and receive processing results after the request complete. + * + * @since_tizen 5.0 + * + * @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_request_create_group() + * @see companion_request_invite() + * @see companion_request_eject() + * @see companion_request_delete_group() + * @see companion_send_data() + * + */ int companion_request_result_callback(companion_request_result_cb callback, void *user_data); +/** + * @} + */ #ifdef __cplusplus } #endif -#endif +#endif /* __TIZEN_NETWORK_COMMON_COMPANION_H__ */ \ No newline at end of file diff --git a/capi/include/companion_debug.h b/capi/include/companion_debug.h index bfd6dfe..4e438c0 100644 --- a/capi/include/companion_debug.h +++ b/capi/include/companion_debug.h @@ -15,8 +15,8 @@ * */ -#ifndef __COMPANION_DEBUG_H__ -#define __COMPANION_DEBUG_H__ +#ifndef __TIZEN_NETWORK_COMMON_COMPANION_DEBUG_H__ +#define __TIZEN_NETWORK_COMMON_COMPANION_DEBUG_H__ #include @@ -106,4 +106,4 @@ #define PRT(format, args...) printf("%s:%d() "format, __FUNCTION__, __LINE__, ##args) #define TC_PRT(format, args...) PRT(format"\n", ##args) -#endif +#endif /* __TIZEN_NETWORK_COMMON_COMPANION_DEBUG_H__ */ \ No newline at end of file diff --git a/capi/src/companion.c b/capi/src/companion.c index 16afa15..55002d6 100644 --- a/capi/src/companion.c +++ b/capi/src/companion.c @@ -26,17 +26,11 @@ #include #include -static pthread_mutex_t mutex = PTHREAD_MUTEX_INITIALIZER; - -#define COMP_DBUS_SERVICE "org.tizen.companion" -#define COMP_DBUS_GROUP_PATH "/org/tizen/companion/group" -#define COMP_DBUS_ENABLER_PATH "/org/tizen/companion/enabler" - -Group *group_proxy = NULL; -Enabler *enabler_proxy = NULL; +/** + * Companion Manager CAPI + */ -int ref_count = 0; -bool __is_initialized = false; +static pthread_mutex_t mutex = PTHREAD_MUTEX_INITIALIZER; /**< Mutex for dbus */ #define COMPANION_LOCK \ do { \ @@ -48,6 +42,16 @@ do { \ pthread_mutex_unlock(&mutex); \ } while (0); +#define COMP_DBUS_SERVICE "org.tizen.companion" /**< For companion dbus */ +#define COMP_DBUS_GROUP_PATH "/org/tizen/companion/group" /**< For group dbus */ +#define COMP_DBUS_ENABLER_PATH "/org/tizen/companion/enabler" /**< dbus auto-activation */ + +Group *group_proxy = NULL; /**< To receive signal from companion-manager */ +Enabler *enabler_proxy = NULL; /**< Enbler proxy */ + +int ref_count = 0; +bool __is_initialized = false; + typedef struct _companion_group_t { char *uri_path; @@ -187,7 +191,8 @@ static void __group_found_cb(Group *object, g_variant_iter_free(iter); - group = _create_group_handle(uri_path, device_id, group_name, host_addr, resource_type, type); + group = _create_group_handle(uri_path, device_id, group_name, host_addr, + resource_type, type); if (group_found_cb.found_cb) group_found_cb.found_cb(type, group, group_found_cb.user_data); } @@ -327,16 +332,26 @@ static void _group_proxy_init(void) NULL, &error); - g_signal_connect(group_proxy, "group-found", G_CALLBACK(__group_found_cb), NULL); - g_signal_connect(group_proxy, "group-find-finish", G_CALLBACK(_group_find_finish_cb), NULL); - g_signal_connect(group_proxy, "device-found", G_CALLBACK(__device_found_cb), NULL); - g_signal_connect(group_proxy, "device-find-finish", G_CALLBACK(_device_find_finish_cb), NULL); - g_signal_connect(group_proxy, "mowned-device-found", G_CALLBACK(__mowned_device_found_cb), NULL); - g_signal_connect(group_proxy, "mowned-device-find-finish", G_CALLBACK(_mowned_device_find_finish_cb), NULL); - g_signal_connect(group_proxy, "device-invite-result", G_CALLBACK(__device_invite_result_cb), NULL); - g_signal_connect(group_proxy, "device-eject-result", G_CALLBACK(__device_eject_result_cb), NULL); - g_signal_connect(group_proxy, "send-data-finish", G_CALLBACK(__send_data_finish_cb), NULL); - g_signal_connect(group_proxy, "request-result", G_CALLBACK(__request_result_cb), NULL); + g_signal_connect(group_proxy, + "group-found", G_CALLBACK(__group_found_cb), NULL); + g_signal_connect(group_proxy, + "group-find-finish", G_CALLBACK(_group_find_finish_cb), NULL); + g_signal_connect(group_proxy, + "device-found", G_CALLBACK(__device_found_cb), NULL); + g_signal_connect(group_proxy, + "device-find-finish", G_CALLBACK(_device_find_finish_cb), NULL); + g_signal_connect(group_proxy, + "mowned-device-found", G_CALLBACK(__mowned_device_found_cb), NULL); + g_signal_connect(group_proxy, + "mowned-device-find-finish", G_CALLBACK(_mowned_device_find_finish_cb), NULL); + g_signal_connect(group_proxy, + "device-invite-result", G_CALLBACK(__device_invite_result_cb), NULL); + g_signal_connect(group_proxy, + "device-eject-result", G_CALLBACK(__device_eject_result_cb), NULL); + g_signal_connect(group_proxy, + "send-data-finish", G_CALLBACK(__send_data_finish_cb), NULL); + g_signal_connect(group_proxy, + "request-result", G_CALLBACK(__request_result_cb), NULL); } static void _enabler_proxy_init(void) @@ -387,7 +402,7 @@ static int _gdbus_deinitialize(void) return ret; } -int companion_initialize() +EXPORT_API int companion_initialize() { int ret = 0; @@ -396,8 +411,8 @@ int companion_initialize() COMPANION_LOCK; if (__is_initialized == false) { - ret = _gdbus_initialize(); - __is_initialized = true; + ret = _gdbus_initialize(); + __is_initialized = true; } ref_count++; @@ -408,7 +423,7 @@ int companion_initialize() return ret; } -int companion_deinitialize() +EXPORT_API int companion_deinitialize() { int ret = 0; @@ -417,11 +432,11 @@ int companion_deinitialize() COMPANION_LOCK; if (ref_count > 0) - ref_count--; + ref_count--; if (__is_initialized == true && ref_count == 0) { - ret = _gdbus_deinitialize(); - __is_initialized = false; + ret = _gdbus_deinitialize(); + __is_initialized = false; } COMPANION_UNLOCK; @@ -432,7 +447,7 @@ int companion_deinitialize() } -int companion_group_create(char *group_name) +EXPORT_API int companion_group_create(char *group_name) { int ret = 0; GError *error = NULL; @@ -443,7 +458,7 @@ int companion_group_create(char *group_name) return ret; } -void companion_group_destroy(companion_group_t *group) +EXPORT_API void companion_group_destroy(companion_group_t *group) { companion_check_null_ret("group", group); @@ -471,7 +486,7 @@ void companion_group_destroy(companion_group_t *group) group = NULL; } -int companion_group_find(int timeout, companion_group_found_cb found_cb, +EXPORT_API int companion_group_find(int timeout, companion_group_found_cb found_cb, companion_group_find_finish_cb finish_cb, void *user_data) { int ret = 0; @@ -488,7 +503,8 @@ int companion_group_find(int timeout, companion_group_found_cb found_cb, return ret; } -int companion_group_get_found_groups(companion_group_h **groups, int *count) +EXPORT_API int companion_group_get_found_groups(companion_group_h **groups, + int *count) { int ret = 0; GVariant *va = NULL; @@ -552,7 +568,8 @@ int companion_group_get_found_groups(companion_group_h **groups, int *count) return ret; } -int companion_group_join(companion_group_h group, companion_group_find_finish_cb callback, void *user_data) +EXPORT_API int companion_group_join(companion_group_h group, + companion_group_find_finish_cb callback, void *user_data) { int ret = COMP_ERROR_NONE; NOTUSED(group); @@ -561,7 +578,8 @@ int companion_group_join(companion_group_h group, companion_group_find_finish_cb return ret; } -int companion_group_leave(companion_group_h group, companion_group_find_finish_cb callback, void *user_data) +EXPORT_API int companion_group_leave(companion_group_h group, + companion_group_find_finish_cb callback, void *user_data) { int ret = COMP_ERROR_NONE; NOTUSED(group); @@ -570,7 +588,7 @@ int companion_group_leave(companion_group_h group, companion_group_find_finish_c return ret; } -int companion_device_find(int timeout, companion_device_found_cb found_cb, +EXPORT_API int companion_device_find(int timeout, companion_device_found_cb found_cb, companion_device_find_finish_cb finish_cb, void *user_data) { int ret = 0; @@ -587,8 +605,9 @@ int companion_device_find(int timeout, companion_device_found_cb found_cb, return ret; } -int companion_device_find_mowned_device(int timeout, - companion_device_found_cb found_cb, companion_device_find_finish_cb finish_cb, void *user_data) +EXPORT_API int companion_device_find_mowned_device(int timeout, + companion_device_found_cb found_cb, companion_device_find_finish_cb finish_cb, + void *user_data) { int ret = 0; GError *error = NULL; @@ -604,7 +623,7 @@ int companion_device_find_mowned_device(int timeout, return ret; } -int companion_send_data(companion_device_h device, char *data, int len, +EXPORT_API int companion_send_data(companion_device_h device, char *data, int len, companion_send_data_finish_cb finish_cb, void *user_data) { int ret = COMP_ERROR_NONE; @@ -632,8 +651,10 @@ int companion_send_data(companion_device_h device, char *data, int len, return ret; } -/* companion_group_join : join to remote group. if group handle is my daemon's, then the api return fail error */ -int companion_device_get_found_devices(companion_device_h **devices, int *count) +/* companion_group_join : 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_device_h **devices, + int *count) { int ret = 0; int num = 0; @@ -687,7 +708,7 @@ int companion_device_get_found_devices(companion_device_h **devices, int *count) return ret; } -int companion_device_get_found_mowned_devices( +EXPORT_API int companion_device_get_found_mowned_devices( companion_device_h **devices, int *count) { int ret = 0; @@ -742,7 +763,7 @@ int companion_device_get_found_mowned_devices( return ret; } -int companion_device_get_my_device(companion_device_h *device) +EXPORT_API int companion_device_get_my_device(companion_device_h *device) { int ret = 0; GError *error = NULL; @@ -800,7 +821,7 @@ static void companion_device_destroy(companion_device_t *device) device = NULL; } -int companion_device_get_my_uuid(char **uuid) +EXPORT_API int companion_device_get_my_uuid(char **uuid) { int ret = 0; GError *error = NULL; @@ -811,24 +832,26 @@ int companion_device_get_my_uuid(char **uuid) } /* group merge */ -int companion_group_merge(companion_group_h dest_group, companion_group_h src_group) +EXPORT_API int companion_group_merge(companion_group_h dest_group, + companion_group_h src_group) { return 0; } -int companion_group_delete(companion_group_h group) +EXPORT_API int companion_group_delete(companion_group_h group) { return 0; } -int companion_group_get_member_devices(companion_group_h group, +EXPORT_API int companion_group_get_member_devices(companion_group_h group, companion_device_h **devices, int *count) { return 0; } -int companion_device_invite(companion_group_h group, - companion_device_h device, char *PIN, companion_device_invite_result_cb result_cb, void *user_data) +EXPORT_API int companion_device_invite(companion_group_h group, + companion_device_h device, char *PIN, companion_device_invite_result_cb result_cb, + void *user_data) { int ret = 0; GError *error = NULL; @@ -838,17 +861,19 @@ int companion_device_invite(companion_group_h group, device_invite_result_cb.result_cb = result_cb; device_invite_result_cb.user_data = user_data; - /* Now, for the sake of convenience, we change 'companion_device_invite' to 'group_call_invite_sync'. */ + /* Now, for the sake of convenience, we change 'companion_device_invite' 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(group_proxy, grp->group_name, dev->device_id, PIN, &ret, NULL, &error); + group_call_invite_sync(group_proxy, grp->group_name, dev->device_id, PIN, &ret, + NULL, &error); #endif return ret; } -int companion_device_eject(companion_group_h group, +EXPORT_API int companion_device_eject(companion_group_h group, companion_device_h device, companion_device_eject_result_cb result_cb, void *user_data) { int ret = 0; @@ -858,7 +883,8 @@ int companion_device_eject(companion_group_h group, device_eject_result_cb.result_cb = result_cb; device_eject_result_cb.user_data = user_data; - /* Now, for the sake of convenience, we change 'companion_device_eject' to 'group_call_eject_sync'. */ + /* Now, for the sake of convenience, we change 'companion_device_eject' to + 'group_call_eject_sync'. */ #if 0 group_call_device_eject_sync(group_proxy, dev->device_id, &ret, NULL, &error); #else @@ -868,7 +894,7 @@ int companion_device_eject(companion_group_h group, return ret; } -int companion_group_information_create(companion_group_h* group) +EXPORT_API int companion_group_information_create(companion_group_h* group) { companion_group_h _group = g_malloc0(sizeof(companion_group_t)); *group = _group; @@ -876,7 +902,7 @@ int companion_group_information_create(companion_group_h* group) return 0; } -int companion_group_information_clone(companion_group_h target, +EXPORT_API int companion_group_information_clone(companion_group_h target, companion_group_h source) { companion_group_t * dst = (companion_group_t *)target; @@ -907,7 +933,7 @@ int companion_group_information_clone(companion_group_h target, return 0; } -int companion_group_information_destroy(companion_group_h data) +EXPORT_API int companion_group_information_destroy(companion_group_h data) { companion_group_t * group = (companion_group_t *)data; @@ -940,43 +966,47 @@ int companion_group_information_destroy(companion_group_h data) return 0; } -int companion_group_information_get_type(companion_group_h group, companion_group_type_e *type) +EXPORT_API int companion_group_information_get_type(companion_group_h group, + companion_group_type_e *type) { *type = ((companion_group_t *)group)->type; return 0; } -int companion_group_information_get_resource_type(companion_group_h group, char **resource_type) +EXPORT_API int companion_group_information_get_resource_type( + companion_group_h group, char **resource_type) { *resource_type = g_strdup(((companion_group_t *)group)->resource_type); return 0; } -int companion_group_information_get_uri_path(companion_group_h group, char **uri_path) +EXPORT_API int companion_group_information_get_uri_path( + companion_group_h group, char **uri_path) { *uri_path = g_strdup(((companion_group_t *)group)->uri_path); return 0; } -int companion_group_information_get_name(companion_group_h group, char **name) +EXPORT_API int companion_group_information_get_name( + companion_group_h group, char **name) { *name = g_strdup(((companion_group_t *)group)->group_name); return 0; } -int companion_group_information_get_host_addr(companion_group_h group, - char **host_addr) +EXPORT_API int companion_group_information_get_host_addr + (companion_group_h group, char **host_addr) { *host_addr = g_strdup(((companion_group_t *)group)->host_addr); return 0; } -int companion_device_information_create(companion_device_h* device) +EXPORT_API int companion_device_information_create(companion_device_h* device) { companion_device_h _device = g_malloc0(sizeof(companion_device_t)); *device = _device; @@ -984,7 +1014,7 @@ int companion_device_information_create(companion_device_h* device) return 0; } -int companion_device_information_clone(companion_device_h target, +EXPORT_API int companion_device_information_clone(companion_device_h target, companion_device_h source) { companion_device_t * dst = (companion_device_t *)target; @@ -1008,7 +1038,7 @@ int companion_device_information_clone(companion_device_h target, return 0; } -int companion_device_information_destroy(companion_device_h data) +EXPORT_API int companion_device_information_destroy(companion_device_h data) { companion_device_t * device = (companion_device_t *)data; @@ -1036,28 +1066,32 @@ int companion_device_information_destroy(companion_device_h data) return 0; } -int companion_device_information_get_device_id(companion_device_h device, char **device_id) +EXPORT_API int companion_device_information_get_device_id( + companion_device_h device, char **device_id) { *device_id = g_strdup(((companion_device_t *)device)->device_id); return 0; } -int companion_device_information_get_ip(companion_device_h device, char **ip) +EXPORT_API int companion_device_information_get_ip( + companion_device_h device, char **ip) { *ip = g_strdup(((companion_device_t *)device)->ip); return 0; } -int companion_device_information_get_device_type(companion_device_h device, char **device_type) +EXPORT_API int companion_device_information_get_device_type( + companion_device_h device, char **device_type) { *device_type = g_strdup(((companion_device_t *)device)->device_type); return 0; } -int companion_request_create_group(companion_device_h device, char *group_name) +EXPORT_API int companion_request_create_group(companion_device_h device, + char *group_name) { int ret; GError *error = NULL; @@ -1065,12 +1099,14 @@ int companion_request_create_group(companion_device_h device, char *group_name) _DBG("Device id : %s", dev->device_id); - group_call_request_create_group_sync(group_proxy, dev->device_id, group_name, &ret, NULL, &error); + group_call_request_create_group_sync(group_proxy, dev->device_id, + group_name, &ret, NULL, &error); return ret; } -int companion_request_invite(companion_group_h group, companion_device_h device, char *PIN) +EXPORT_API int companion_request_invite(companion_group_h group, + companion_device_h device, char *PIN) { int ret = 0; @@ -1081,13 +1117,15 @@ int companion_request_invite(companion_group_h group, companion_device_h device, _DBG("%s", grp->group_name); _DBG("%s", dev->device_id); - group_call_request_invite(group_proxy, grp->device_id, grp->group_name, dev->device_id, PIN, + group_call_request_invite(group_proxy, grp->device_id, grp->group_name, + dev->device_id, PIN, NULL, NULL, NULL); return ret; } -int companion_request_eject(companion_group_h group, companion_device_h device) +EXPORT_API int companion_request_eject(companion_group_h group, + companion_device_h device) { int ret = 0; @@ -1104,13 +1142,14 @@ int companion_request_eject(companion_group_h group, companion_device_h device) return ret; } -int companion_request_delete_group(companion_group_h group) +EXPORT_API int companion_request_delete_group(companion_group_h group) { int ret = 0; return ret; } -int companion_request_result_callback(companion_request_result_cb result_cb, void *user_data) +EXPORT_API int companion_request_result_callback( + companion_request_result_cb result_cb, void *user_data) { int ret = 0; @@ -1119,4 +1158,3 @@ int companion_request_result_callback(companion_request_result_cb result_cb, voi return ret; } - diff --git a/src/companion-manager/include/comp_context.h b/src/companion-manager/include/comp_context.h index 2071fd0..6772ce4 100644 --- a/src/companion-manager/include/comp_context.h +++ b/src/companion-manager/include/comp_context.h @@ -53,4 +53,4 @@ comp_context_t *comp_context_get_context(); #ifdef __cplusplus } #endif -#endif +#endif /* __COMP_CONTEXT_H__ */ \ No newline at end of file diff --git a/src/companion-manager/include/comp_enum.h b/src/companion-manager/include/comp_enum.h index cbbe801..8416050 100644 --- a/src/companion-manager/include/comp_enum.h +++ b/src/companion-manager/include/comp_enum.h @@ -20,11 +20,15 @@ #include -#define NOTUSED(var) (var = var) +#define NOTUSED(var) (var = var) /**< It is used to avoid generating build warning */ -#define TIZEN_ERROR_COMP 0 +#define TIZEN_ERROR_COMP 0 /**< Same one */ -/* error enum */ +/** + * @brief Error codes for companion-manager. + * + * @since_tizen 5.0 + */ typedef enum { COMP_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */ COMP_ERROR_IO_ERROR = TIZEN_ERROR_IO_ERROR, /**< I/O error */ @@ -41,7 +45,11 @@ typedef enum { COMP_ERROR_UNKNOWN = -999, } comp_error_e; -/* resource type enum */ +/** + * @brief Resource type. + * + * @since_tizen 5.0 + */ typedef enum { COMP_RESOURCE_TYPE_GROUP = 0, /**< Group resource type */ COMP_RESOURCE_TYPE_DEVICE, /**< Device resource type */ @@ -50,7 +58,11 @@ typedef enum { COMP_RESOURCE_TYPE_MAX } comp_resource_type_e; -/* group type enum */ +/** + * @brief Group type. + * + * @since_tizen 5.0 + */ typedef enum { COMP_GROUP_GROUP_ERROR = 0, /**< Group type error */ COMP_GROUP_GROUP_LOCAL = 1, /**< Local group type */ @@ -72,4 +84,4 @@ typedef enum { COMP_REQ_SEND_DATA_ALL, /**< Send data in subnet */ } comp_request_type_e; -#endif +#endif /* __COMP_ENUM_H__ */ \ No newline at end of file diff --git a/src/companion-manager/include/comp_gdbus.h b/src/companion-manager/include/comp_gdbus.h index db5fb54..029a859 100644 --- a/src/companion-manager/include/comp_gdbus.h +++ b/src/companion-manager/include/comp_gdbus.h @@ -20,10 +20,10 @@ #include -#define COMP_DBUS_SERVICE "org.tizen.companion" -#define COMP_DBUS_GROUP_PATH "/org/tizen/companion/group" -#define COMP_DBUS_ENABLER_PATH "/org/tizen/companion/enabler" +#define COMP_DBUS_SERVICE "org.tizen.companion" /**< For companion dbus */ +#define COMP_DBUS_GROUP_PATH "/org/tizen/companion/group" /**< For group commands */ +#define COMP_DBUS_ENABLER_PATH "/org/tizen/companion/enabler" /**< For d-bus activation */ int comp_gdbus_init(); -#endif +#endif /* __COMP_GDBUS_H__ */ \ No newline at end of file diff --git a/src/companion-manager/include/comp_gdbus_group.h b/src/companion-manager/include/comp_gdbus_group.h index cdb8f8e..0bb5757 100644 --- a/src/companion-manager/include/comp_gdbus_group.h +++ b/src/companion-manager/include/comp_gdbus_group.h @@ -116,4 +116,4 @@ void notify_request_result(const char *cmd, char *arg, int ret); #ifdef __cplusplus } #endif -#endif +#endif /* __COMP_GDBUS_GROUP_H__ */ \ No newline at end of file diff --git a/src/companion-manager/include/comp_group.h b/src/companion-manager/include/comp_group.h index 3b71e91..c1133f0 100644 --- a/src/companion-manager/include/comp_group.h +++ b/src/companion-manager/include/comp_group.h @@ -26,42 +26,42 @@ extern "C" #endif typedef struct { - char *uri_path; - char *device_id; - char *host_addr; - char *group_name; - char *resource_type; - comp_group_type_e type; + char *uri_path; /**< URI path */ + char *device_id; /**< Device ID */ + char *host_addr; /**< Host address */ + char *group_name; /**< Group name */ + char *resource_type; /**< Resource type */ + comp_group_type_e type; /**< Group yype */ } comp_group_t; typedef struct { - char *device_id; - int adapter; - int flags; - int port; - char *addr; - int ifindex; - char *route_data; - char *remote_id; - int conn_type; - int secure_port; - int tcp_port; - char *sec_ver; - int dev_status; + char *device_id; /**< Device Id */ + int adapter; /**< Adapter type */ + int flags; /**< Flags */ + int port; /**< Remtoe device is listening this port */ + char *addr; /**< IP Address of remote device */ + int ifindex; /**< Network interfce index of Remote device */ + char *route_data; /**< Route data */ + char *remote_id; /**< Remote Id */ + int conn_type; /**< Connection type */ + int secure_port; /**< Secured port once TLS handhaking complete */ + int tcp_port; /**< TCP port when using CoAP over TCP */ + char *sec_ver; /**< OCF Security specification version */ + int dev_status; /**< Device status */ } comp_mot_device_t; typedef struct { - char *uuid_dev1; - char *uuid_dev2; - char *pin; - char *uri_1; - char *rt_1; - char *interface_1; - int permission_1; - char *uri_2; - char *rt_2; - char *interface_2; - int permission_2; + char *uuid_dev1; /**< Source device Id */ + char *uuid_dev2; /**< Target device Id */ + char *pin; /**< Random or pre-configured PIN */ + char *uri_1; /**< URI at source resource */ + char *rt_1; /**< Resource type at source resource */ + char *interface_1; /**< Interface at source resource */ + int permission_1; /**< CRUDN for target device */ + char *uri_2; /**< URI at target resource */ + char *rt_2; /**< Resource type at target resource */ + char *interface_2; /**< Interface at target resource */ + int permission_2; /**< CRUDN for source device */ } comp_group_invite_info_t; /* Called when daemon is start. */ @@ -87,14 +87,15 @@ int comp_group_find_mot_enabled_devices(int timeout); char *comp_group_invite_get_uuid(); char *comp_group_invite_get_pin(); -//Join to device in group (async) + +/* Join to device in group (async) */ int comp_group_invite(const char *group_name, const char *uuid, const char *pin); comp_group_invite_info_t *comp_group_get_invite_info(); void comp_group_free_invite_info(); void comp_group_notify_group_invite(int result); -//dismiss from group (async) +/* dismiss from group (async) */ int comp_group_dismiss(gchar *uuid_dev1, const char *uuid_dev2); void comp_group_notify_group_dismiss(int result); @@ -123,6 +124,7 @@ int comp_group_leave_from(/* callback */); //leave from certain remote group (As /* Called when daemon is end. */ int comp_group_deinitialize(); +/* Getter for a group */ int comp_group_get_group_name(comp_group_t *handle, char **name); int comp_group_get_group_type(comp_group_t *handle, int *type); int comp_group_get_group_device_type(comp_group_t *handle); @@ -132,6 +134,7 @@ int comp_group_get_group_device_id(comp_group_t *handle); int comp_group_event_handler(/*callback*/); // event hadnler int comp_group_add_device_in_group(const char *group_name, const char *uuid); +/* Group management */ int comp_group_request_create_group(char *uuid, char *group_name); int comp_group_request_invite(char *uuid, char *group_name, char *target_uuid, char *PIN); int comp_group_request_eject(char *uuid, char *group_name, char *target_uuid); @@ -140,4 +143,4 @@ int comp_group_request_delete_group(char *uuid, char *group_name); #ifdef __cplusplus } #endif -#endif +#endif /* __COMP_GROUP_H__ */ \ No newline at end of file diff --git a/src/companion-manager/include/comp_manager.h b/src/companion-manager/include/comp_manager.h index 670d421..d22276c 100644 --- a/src/companion-manager/include/comp_manager.h +++ b/src/companion-manager/include/comp_manager.h @@ -23,4 +23,4 @@ #include #include -#endif +#endif /* __COMP_MANAGER_H__ */ \ No newline at end of file diff --git a/src/companion-manager/include/comp_resource.h b/src/companion-manager/include/comp_resource.h index 2480aa0..3a20e23 100644 --- a/src/companion-manager/include/comp_resource.h +++ b/src/companion-manager/include/comp_resource.h @@ -46,4 +46,4 @@ void comp_resource_print_list(); #ifdef __cplusplus } #endif -#endif +#endif /* __COMP_RESOURCE_H__ */ \ No newline at end of file diff --git a/src/companion-manager/src/comp_context.c b/src/companion-manager/src/comp_context.c index c858e13..6a5b3ec 100644 --- a/src/companion-manager/src/comp_context.c +++ b/src/companion-manager/src/comp_context.c @@ -24,7 +24,7 @@ int comp_context_create() { _comp_ctx = g_new0(comp_context_t, 1); if (!_comp_ctx) { - LOG_DEBUG("create mtp_context is failed"); + LOG_DEBUG("create comp_context is failed"); return COMP_ERROR_UNKNOWN; } _comp_ctx->mot_me = FALSE; diff --git a/src/companion-manager/src/comp_gdbus.c b/src/companion-manager/src/comp_gdbus.c index 27e1da4..1ba79df 100644 --- a/src/companion-manager/src/comp_gdbus.c +++ b/src/companion-manager/src/comp_gdbus.c @@ -156,7 +156,7 @@ static bool __group_init(GDBusConnection *connection) // Set connection to 'manager' g_dbus_object_manager_server_set_connection(group, connection); - // Export 'group' interface on FN DBUS + // Export 'group' interface on companion-manager DBUS ret = g_dbus_interface_skeleton_export(G_DBUS_INTERFACE_SKELETON(group_skeleton), connection, COMP_DBUS_GROUP_PATH, &error); @@ -205,7 +205,7 @@ static bool __enabler_init(GDBusConnection *connection) // Set connection to 'enabler' g_dbus_object_manager_server_set_connection(enabler, connection); - // Export 'enabler' interface on FN DBUS + // Export 'enabler' interface on companion DBUS ret = g_dbus_interface_skeleton_export( G_DBUS_INTERFACE_SKELETON(enabler_skeleton), connection, COMP_DBUS_ENABLER_PATH, &error); diff --git a/src/companion-manager/src/comp_gdbus_group.c b/src/companion-manager/src/comp_gdbus_group.c index 30da137..ff3b209 100644 --- a/src/companion-manager/src/comp_gdbus_group.c +++ b/src/companion-manager/src/comp_gdbus_group.c @@ -20,8 +20,8 @@ /* GDBUS Group Layer */ /* In this gdbus group layer, Please call the "fn_group" service layer function.*/ -gboolean group_create(Group *group, GDBusMethodInvocation *invocation, gchar *group_name, - gpointer user_data) +gboolean group_create(Group *group, GDBusMethodInvocation *invocation, + gchar *group_name, gpointer user_data) { gint result = 0; @@ -91,8 +91,8 @@ gboolean group_delete(Group *group, GDBusMethodInvocation *invocation, return TRUE; } -gboolean group_device_find(Group *group, GDBusMethodInvocation *invocation, gint timeout, - gpointer user_data) +gboolean group_device_find(Group *group, GDBusMethodInvocation *invocation, + gint timeout, gpointer user_data) { int result = 0; diff --git a/src/companion-manager/src/comp_manager.c b/src/companion-manager/src/comp_manager.c index 435bb4c..e9eff6c 100644 --- a/src/companion-manager/src/comp_manager.c +++ b/src/companion-manager/src/comp_manager.c @@ -58,7 +58,8 @@ int main(int argc, char *argv[]) //7. operation mgr initialize ret = agent_dbus_start(); if (ret != COMP_ERROR_NONE) { - LOG_ERR("MOT agent interface initialize failed : %s", comp_log_get_error_string(ret)); + LOG_ERR("MOT agent interface initialize failed : %s", + comp_log_get_error_string(ret)); goto EXIT; } agent_enable(); @@ -75,7 +76,8 @@ EXIT: agent_disable(); ret = agent_dbus_stop(); if (ret != COMP_ERROR_NONE) - LOG_ERR("MOT agent interface deinitialize failed : %s", comp_log_get_error_string(ret)); + LOG_ERR("MOT agent interface deinitialize failed : %s", + comp_log_get_error_string(ret)); ret = comp_group_deinitialize(); if (ret != COMP_ERROR_NONE) diff --git a/src/companion-manager/src/comp_mot_agent.c b/src/companion-manager/src/comp_mot_agent.c index 5fae8a9..ed3a888 100644 --- a/src/companion-manager/src/comp_mot_agent.c +++ b/src/companion-manager/src/comp_mot_agent.c @@ -34,8 +34,6 @@ #define AGENT_ENABLER_OBJ_PATH "/net/ma/enabler" #define AGENT_ENABLER_INTERFACE "net.ma.enabler" -#define NOTUSED(var) (var = var) - #define AGENT_DBUS_PROXY_TIMEOUT ((9.5 + 2) * 1000) /**< default timeout for GDBus */ struct agent_s { @@ -44,7 +42,7 @@ struct agent_s { GCancellable *ca; /**< Cancellable for MOT agent */ GList *dbus_sub_ids; /**< DBus ID for MOT agent */ }; -struct agent_s agent; +struct agent_s agent; /**< MOT agent context */ #ifdef INVITE_EJECT_DEVICE_BY_MULTI_RUN static bool mot_dev2 = false;