From af8c69014bf77427733fc7549303dbc0fb22f383 Mon Sep 17 00:00:00 2001 From: DoHyun Pyun Date: Wed, 8 Mar 2017 15:43:31 +0900 Subject: [PATCH] Add the documentation for IPSP internal APIs Change-Id: I09d9302cff0449c477e8d1ba01d84c139ca6a082 Signed-off-by: DoHyun Pyun --- include/bluetooth_internal.h | 97 ++++++++++++++++++++++++++++++++++----- include/bluetooth_type_internal.h | 22 ++++++--- 2 files changed, 100 insertions(+), 19 deletions(-) diff --git a/include/bluetooth_internal.h b/include/bluetooth_internal.h index fae8d2c..1be5da5 100644 --- a/include/bluetooth_internal.h +++ b/include/bluetooth_internal.h @@ -3660,39 +3660,112 @@ int bt_dpm_set_data_transfer_state(bt_dpm_status_e value); int bt_dpm_get_data_transfer_state(bt_dpm_status_e *value); /** - * @internal - * @brief Initialize Bluetooth IPSP service and set the callback + * @ingroup CAPI_NETWORK_BLUETOOTH_ADAPTER_LE_MODULE + * @brief Initializes the Bluetooth IPSP(Internet Protocol Support Profile) service and set the callback. + * @since_tizen 4.0 + * @param[in] bt_ipsp_init_state_changed_cb The callback called when the initialization is finished + * @param[in] user_data The user data to be passed to the callback function + * @return 0 on success, otherwise a negative error value. + * @retval #BT_ERROR_NONE Successful + * @retval #BT_ERROR_NOT_INITIALIZED Not initialized + * @retval #BT_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #BT_ERROR_OPERATION_FAILED Operation failed + * @retval #BT_ERROR_NOT_SUPPORTED Not supported + * + * @pre The Bluetooth service must be initialized with bt_initialize(). + * @see bt_initialize() */ int bt_ipsp_initialize(bt_ipsp_init_state_changed_cb callback, void *user_data); /** - * @internal - * @brief De-Initialize Bluetooth IPSP service and unset the callback + * @ingroup CAPI_NETWORK_BLUETOOTH_ADAPTER_LE_MODULE + * @brief Deinitializes the Bluetooth IPSP(Internet Protocol Support Profile) service. + * @since_tizen 4.0 + * @return 0 on success, otherwise a negative error value. + * @retval #BT_ERROR_NONE Successful + * @retval #BT_ERROR_NOT_INITIALIZED Not initialized + * @retval #BT_ERROR_OPERATION_FAILED Operation failed + * @retval #BT_ERROR_NOT_SUPPORTED Not supported + * + * @pre The Bluetooth service must be initialized with bt_initialize(). + * @see bt_initialize() */ int bt_ipsp_deinitialize(void); /** - * @internal - * @brief Connect to a IPSP service over LE to remote device. + * @ingroup CAPI_NETWORK_BLUETOOTH_ADAPTER_LE_MODULE + * @brief Connects to a IPSP service over LE to remote device, asynchronously. + * @since_tizen 4.0 + * @privlevel public + * @privilege %http://tizen.org/privilege/bluetooth + * @param[in] remote_address The remote address + * @return 0 on success, otherwise a negative error value. + * @retval #BT_ERROR_NONE Successful + * @retval #BT_ERROR_NOT_INITIALIZED Not initialized + * @retval #BT_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #BT_ERROR_NOT_ENABLED Not enabled + * @retval #BT_ERROR_OPERATION_FAILED Operation failed + * @retval #BT_ERROR_PERMISSION_DENIED Permission denied + * @retval #BT_ERROR_NOT_SUPPORTED Not supported + * + * @post bt_ipsp_set_connection_state_changed_cb() will be invoked. + * @see bt_ipsp_set_connection_state_changed_cb() */ int bt_ipsp_connect(const char *address); /** - * @internal - * @brief Disconnect to a IPSP service over LE to remote device. + * @ingroup CAPI_NETWORK_BLUETOOTH_ADAPTER_LE_MODULE + * @brief Disonnects to a IPSP service over LE to remote device, asynchronously. + * @since_tizen 4.0 + * @privlevel public + * @privilege %http://tizen.org/privilege/bluetooth + * @param[in] remote_address The remote address + * @return 0 on success, otherwise a negative error value. + * @retval #BT_ERROR_NONE Successful + * @retval #BT_ERROR_NOT_INITIALIZED Not initialized + * @retval #BT_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #BT_ERROR_NOT_ENABLED Not enabled + * @retval #BT_ERROR_REMOTE_DEVICE_NOT_CONNECTED Remote device is not connected + * @retval #BT_ERROR_OPERATION_FAILED Operation failed + * @retval #BT_ERROR_PERMISSION_DENIED Permission denied + * @retval #BT_ERROR_NOT_SUPPORTED Not supported + * + * @pre The remote device must be connected by bt_ipsp_connect(). + * @post bt_ipsp_set_connection_state_changed_cb() will be invoked. + * @see bt_ipsp_connect() + * @see bt_ipsp_set_connection_state_changed_cb() */ int bt_ipsp_disconnect(const char *address); /** - * @internal - * @brief Set IPSP connection state event change callback. + * @ingroup CAPI_NETWORK_BLUETOOTH_ADAPTER_LE_MODULE + * @brief Registers a callback function that will be invoked when the connection state changes. + * @since_tizen 4.0 + * @param[in] bt_ipsp_connection_state_changed_cb The callback function to register + * @param[in] user_data The user data to be passed to the callback function + * @return 0 on success, otherwise a negative error value. + * @retval #BT_ERROR_NONE Successful + * @retval #BT_ERROR_NOT_INITIALIZED Not initialized + * @retval #BT_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #BT_ERROR_NOT_SUPPORTED Not supported + * + * @pre The Bluetooth service must be initialized with bt_initialize(). + * @see bt_initialize() */ int bt_ipsp_set_connection_state_changed_cb(bt_ipsp_connection_state_changed_cb callback, void *user_data); /** - * @internal - * @brief Unset IPSP connection state event change callback. + * @ingroup CAPI_NETWORK_BLUETOOTH_ADAPTER_LE_MODULE + * @brief Unregisters the callback function. + * @since_tizen 4.0 + * @return 0 on success, otherwise a negative error value. + * @retval #BT_ERROR_NONE Successful + * @retval #BT_ERROR_NOT_INITIALIZED Not initialized + * @retval #BT_ERROR_NOT_SUPPORTED Not supported + * + * @pre The Bluetooth service must be initialized with bt_initialize(). + * @see bt_initialize() */ int bt_ipsp_unset_connection_state_changed_cb(void); diff --git a/include/bluetooth_type_internal.h b/include/bluetooth_type_internal.h index 6880694..a8744d0 100644 --- a/include/bluetooth_type_internal.h +++ b/include/bluetooth_type_internal.h @@ -667,20 +667,28 @@ typedef struct { typedef void (*bt_device_att_mtu_changed_cb)(int result, bt_device_att_mtu_info_s *mtu_info, void *user_data); /** - * @internal - * @ingroup + * @ingroup CAPI_NETWORK_BLUETOOTH_ADAPTER_LE_MODULE * @brief IPSP Init state changed callback - * @since_tizen 3.0 + * @since_tizen 4.0 + * @param[in] result The result of the initializing or deinitializing request + * @param[in] ipsp_initialized The initialized state: (@c true = initialized, @c false = deinitialized) + * @param[in] user_data The user data passed from the callback registration function + * @see bt_ipsp_initialize() */ typedef void (*bt_ipsp_init_state_changed_cb) (int result, bool ipsp_initialized, void *user_data); /** - * @internal - * @ingroup - * @since_tizen 3.0 - + * @ingroup CAPI_NETWORK_BLUETOOTH_ADAPTER_LE_MODULE * @brief IPSP Connection state changed callback + * @since_tizen 4.0 + * @param[in] result The result of the connecting or disconnecting request + * @param[in] connected The connection status: (@c true = connected, @c false = disconnected) + * @param[in] remote_address Address of remote device + * @param[in] iface_name The network interface name for IPv6 network interface + * @param[in] user_data The user data passed from the callback registration function + * @see bt_ipsp_connect() + * @see bt_ipsp_disconnect() */ typedef void (*bt_ipsp_connection_state_changed_cb) (int result, bool connected, const char *remote_address, const char *iface_name, void *user_data); -- 2.7.4