From: Wootak Jung Date: Thu, 19 Sep 2024 01:41:07 +0000 (+0900) Subject: Reinforce API documents X-Git-Tag: accepted/tizen/unified/20241224.130041~2 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=refs%2Fchanges%2F03%2F317803%2F2;p=platform%2Fcore%2Fapi%2Fbluetooth.git Reinforce API documents Change-Id: I39f9166986b5d148e8488fd85e8b68fc78217ab0 Signed-off-by: Wootak Jung --- diff --git a/doc/bluetooth_doc.h b/doc/bluetooth_doc.h index 59db437..21c00af 100644 --- a/doc/bluetooth_doc.h +++ b/doc/bluetooth_doc.h @@ -59,12 +59,10 @@ * \#include * * @section CAPI_NETWORK_BLUETOOTH_ADAPTER_MODULE_OVERVIEW Overview - * This set of function is used to control a bluetooth adapter. - * You can also control visibility of the device, its appearance for others (adapter name). - * In addition, this api is used to discover neighboring bluetooth devices. - * This process is asynchronous, so it is up to you to build and hold list of devices in the neighborhood - * - the api does not provide this list. - * Before starting a device discovery, you can find a device from the connected devices. + * The Bluetooth Adapter APIs allow you to retrieve and set the current state, address, and name of your local Bluetooth adapter. + * Additionally, it enables checking the visibility mode of the adapter, starting/stopping device discovery, + * retrieving information about connected devices, determining whether specific services are being utilized, + * registering callbacks for various types of updates, and unregistering those callbacks when no longer needed. * This functionality is implemented by foreach loop. * * @section CAPI_NETWORK_BLUETOOTH_ADAPTER_MODULE_FEATURE Related Features @@ -165,7 +163,10 @@ * \#include * * @section CAPI_NETWORK_BLUETOOTH_ADAPTER_LE_MODULE_OVERVIEW Overview - * Bluetooth stack architecture has been changed. Thus, GATT APIs defined in Tizen 2.3 are deprecated and new GATT client APIs are defined. + * The Bluetooth Adapter LE APIs facilitate operations involving Low Energy (LE) communication. + * They offer functions to check for active LE scans, initiate and stop LE scans, extract meaningful information from scan results, + * create and manage advertisers for broadcast purposes, add essential elements to advertising data, configure advertising settings, clear advertising data, + * start new advertising sessions, adjust advertising connectivity preferences, define LE scan modes, establish and remove scan filters, and register/unregister these filters. * * @section CAPI_NETWORK_BLUETOOTH_ADAPTER_LE_MODULE_FEATURE Related Features * This API is related with the following features:\n @@ -191,7 +192,9 @@ * \#include * * @section CAPI_NETWORK_BLUETOOTH_ADAPTER_LE_50_MODULE_OVERVIEW Overview - * Bluetooth LE API provides functions for bluetooth 5.0 functionality such as 2M Phy and Coded Phy + * The Bluetooth Adapter LE APIs extend their capabilities to include features related to LE 2M PHY and LE Coded PHY support checks. + * These APIs assist developers in verifying whether the LE 2M PHY and LE Coded PHY functionalities are available within the platform they're working on. + * This allows for improved understanding of the underlying hardware's compatibility with advanced LE technologies. * * @section CAPI_NETWORK_BLUETOOTH_ADAPTER_LE_50_MODULE_FEATURE Related Features * This API is related with the following features:\n @@ -217,7 +220,13 @@ * \#include * * @section CAPI_NETWORK_BLUETOOTH_ADAPTER_LE_ADV_EXT_MODULE_OVERVIEW Overview - * Bluetooth LE API provides functions for bluetooth extended advertising functionality such as setting Primary and Secondary Phy + * The Bluetooth Adapter LE APIs provide several functions to enhance the LE experience. + * These include starting a new LE scan session, adjusting the LE scan role, selecting the preferred LE scan physical layer, + * enabling or disabling LE advertising legacy mode, specifying the primary and secondary LE advertising physical layers, + * confirming LE Extended Advertising and Extended Scan support availability, obtaining the maximum allowed advertising data length, + * accessing primary and secondary LE physical layer data from extended scan results, retrieving advertising SID values, + * periodic advertising intervals, determining whether a scan result is considered "extended", and fetching legacy scan result information from extended scan results. + * These features cater to diverse needs while ensuring efficient utilization of LE resources. * * @section CAPI_NETWORK_BLUETOOTH_ADAPTER_LE_ADV_EXT_MODULE_FEATURE Related Features * This API is related with the following features:\n @@ -510,7 +519,14 @@ * \#include * * @section CAPI_NETWORK_BLUETOOTH_OPP_MODULE_OVERVIEW Overview - * OPP profile let users exchange objects between two devices. + * Bluetooth Object Push Profile (OPP) Client APIs supply a set of operations geared toward transferring files like images. Core elements comprise: + * - Initialization of Bluetooth OPP client modules + * - Deinitialization of Bluetooth OPP client modules + * - Addition of files intended for transmission + * - Clearing of queued files awaiting transfer + * - Asynchronous dispatch of file pushes to remote devices, coupled with event callbacks signaling response reception, progress updates, and task conclusion + * - Cancellation of active push requests, also implemented asynchronously + * Through this framework, developers can effortlessly orchestrate Bluetooth-based object transfers involving OPP clients. * */ @@ -523,7 +539,14 @@ * \#include * * @section CAPI_NETWORK_BLUETOOTH_OPP_SERVER_MODULE_OVERVIEW Overview - * This is OPP server APIs. + * Bluetooth Object Push Profile (OPP) Server APIs deliver a series of constructs focused on receiving files such as photographs. Fundamental building blocks consist of: + * - Initialization of Bluetooth OPP servers prompted by connection request callbacks + * - Deinitialization of Bluetooth OPP servers + * - Acceptance of push requests from remote devices, accompanied by progress update and completion notification callbacks, alongside optional name assignments and user data inputs, yielding unique transfer identifiers + * - Rejection of incoming push requests + * - Cancellation of ongoing file transfers, referencing assigned transfer IDs + * - Configuration of desired storage destinations for received files + * These streamlined tools enable straightforward implementation of Bluetooth-powered OPP server functionality. * * @section CAPI_NETWORK_BLUETOOTH_OPP_SERVER_MODULE_FEATURE Related Features * This API is related with the following features:\n @@ -651,6 +674,12 @@ * @section CAPI_NETWORK_BLUETOOTH_HID_MODULE_OVERVIEW Overview * In HID Profile, there are two roles - @a Host and @a Device. * The @a Host is a device that uses or requests the services of a HID. The @a Device is a device that provides the service of human data input and output to and from th + * Bluetooth Human Interface Device (HID) APIs furnish a collection of functionalities tailored towards linking with Bluetooth HID peripherals, such as keyboards and mouse. Primary offerings entail: + * - Initialization of Bluetooth HID Host, accompanied by optional callbacks for tracking connection state changes + * - Deinitialization of Bluetooth HID Host + * - Connection setup with remote devices featuring HID services, performed asynchronously + * - Disconnection of remote devices equipped with HID services, likewise conducted asynchronously + * By harnessing these capabilities, developers gain access to simplified pathways for interfacing with Bluetooth HID accessories. * * @section CAPI_NETWORK_BLUETOOTH_HID_MODULE_FEATURE Related Features * This API is related with the following features:\n @@ -876,8 +905,11 @@ * \#include * * @section CAPI_NETWORK_BLUETOOTH_HDP_MODULE_OVERVIEW Overview - * The @a Source is a transmitter of application data that is to be transferred to a @a Sink. The @a Sink is a receiver of application data delivered from a @a Source. - * This API supports the @a Sink role in HDP spec. + * Bluetooth Health Device Profile (HDP) APIs offer a suite of utilities designed for handling connections to medical equipment and facilitating data exchange. Highlights include: + * - Establishing links to remote devices operating as sources, utilizing remote addresses and app IDs, in an asynchronous manner + * - Disconnecting remote devices, employing remote addresses and channel numbers, again asynchronously + * - Transferring data packets via specified channels and defined payload sizes + * These streamlined tools promote smooth interoperability between Bluetooth-enabled healthcare devices. * * @section CAPI_NETWORK_BLUETOOTH_HDP_MODULE_FEATURE Related Features * This API is related with the following features:\n diff --git a/include/bluetooth.h b/include/bluetooth.h index aa74ad2..bf2edf1 100644 --- a/include/bluetooth.h +++ b/include/bluetooth.h @@ -119,6 +119,8 @@ int bt_adapter_get_state(bt_adapter_state_e *adapter_state); /** * @ingroup CAPI_NETWORK_BLUETOOTH_ADAPTER_MODULE * @brief Gets the address of local Bluetooth adapter. + * @details This function obtains the address of the local Bluetooth adapter and assigns it to the @a local_address output parameter. + * * @since_tizen 2.3 * * @remarks The @a local_address must be released with free() by you. @@ -326,6 +328,9 @@ int bt_device_get_service_mask_from_uuid_list(char **uuids, /** * @ingroup CAPI_NETWORK_BLUETOOTH_ADAPTER_MODULE * @brief Retrieves the device information of all bonded devices. + * @details This function iterates through each bonded device and calls the supplied @a callback function, + * passing along the device information for each iteration. + * The @a user_data argument allows for custom data to be passed from the caller to the callback function. * @since_tizen 2.3 * * @param[in] callback The callback function to invoke @@ -489,6 +494,8 @@ int bt_adapter_unset_name_changed_cb(void); /** * @ingroup CAPI_NETWORK_BLUETOOTH_ADAPTER_MODULE * @brief Registers a callback function to be invoked when the visibility mode changes. + * @details This function registers a callback function that gets called whenever the visibility mode of the local Bluetooth adapter changes. + * The registered callback function receives two arguments the new visibility mode and the user data passed from the @a bt_adapter_set_visibility_mode_changed_cb() function. * @since_tizen 2.3 * * @param[in] callback The callback function to register @@ -1342,6 +1349,8 @@ int bt_adapter_le_add_advertising_service_data(bt_advertiser_h advertiser, * @ingroup CAPI_NETWORK_BLUETOOTH_ADAPTER_LE_MODULE * @brief Sets the external appearance of this device to advertise or scan response data. * Please refer to the adopted Bluetooth specification for the the appearance. + * @details This function sets the external appearance of the device for purposes of advertising or responding to scans. + * The appearance value corresponds to the appropriate Bluetooth specification. * @since_tizen 2.3.1 * * @param[in] advertiser The handle of advertiser @@ -2137,6 +2146,8 @@ int bt_socket_listen_and_accept_rfcomm(int socket_fd, int max_pending_connection /** * @ingroup CAPI_NETWORK_BLUETOOTH_SOCKET_MODULE * @brief Connects to a specific RFCOMM based service on a remote Bluetooth device UUID, asynchronously. + * @details This function facilitates the creation of an asynchronous connection between the local host + * and a designated RFCOMM-based service hosted by a remote Bluetooth device, identified uniquely by its UUID. * @since_tizen 2.3 * @privlevel public * @privilege %http://tizen.org/privilege/bluetooth @@ -2620,6 +2631,7 @@ int bt_hid_host_deinitialize(void); /** * @ingroup CAPI_NETWORK_BLUETOOTH_HID_HOST_MODULE * @brief Connects the remote device with the HID (Human Interface Device) service, asynchronously. + * @details This function establishes an asynchronous connection to a remote device providing the Human Interface Device (HID) service. * @since_tizen 2.3 * @privlevel public * @privilege %http://tizen.org/privilege/bluetooth @@ -2858,6 +2870,8 @@ int bt_hid_device_unset_data_received_cb(void); /** * @ingroup CAPI_NETWORK_BLUETOOTH_HID_DEVICE_MODULE * @brief Responds to reports from the HID Host. + * @details This function facilitates responding to reports generated by the HID Host. + * Through this approach, the application can deliver personalized data back to the host. * @since_tizen 3.0 * @privlevel public * @privilege %http://tizen.org/privilege/bluetooth @@ -3069,6 +3083,8 @@ int bt_avrcp_target_notify_equalizer_state(bt_avrcp_equalizer_state_e state); /** * @ingroup CAPI_NETWORK_BLUETOOTH_AVRCP_TARGET_MODULE * @brief Notifies the repeat mode to the remote device. + * @details This function informs the remote device regarding the selected repeat mode. + * AVRCP Target uses this mechanism to communicate playback settings to the remote player. * @since_tizen 2.4 * @privlevel public * @privilege %http://tizen.org/privilege/bluetooth @@ -3092,6 +3108,8 @@ int bt_avrcp_target_notify_repeat_mode(bt_avrcp_repeat_mode_e mode); /** * @ingroup CAPI_NETWORK_BLUETOOTH_AVRCP_TARGET_MODULE * @brief Notifies the shuffle mode to the remote device. + * @details This function transmits the designated shuffle mode to the remote device. + * AVRCP Target leverages this functionality to convey shuffling preferences to the remote music player. * @since_tizen 2.4 * @privlevel public * @privilege %http://tizen.org/privilege/bluetooth @@ -3161,6 +3179,8 @@ int bt_avrcp_target_notify_player_state(bt_avrcp_player_state_e state); /** * @ingroup CAPI_NETWORK_BLUETOOTH_AVRCP_TARGET_MODULE * @brief Notifies the current position of song to the remote device. + * @details This function conveys the current playing position of the track to the remote device. + * AVRCP Target relies on this capability to update the playback progress on the remote music player. * @since_tizen 2.4 * @privlevel public * @privilege %http://tizen.org/privilege/bluetooth @@ -3184,6 +3204,8 @@ int bt_avrcp_target_notify_position(unsigned int position); /** * @ingroup CAPI_NETWORK_BLUETOOTH_AVRCP_TARGET_MODULE * @brief Notifies the track to the remote device. + * @details This function notifies the remote device about the currently playing track. + * AVRCP Target makes use of this feature to share metadata related to the active tune with the remote music player. * @since_tizen 2.4 * @privlevel public * @privilege %http://tizen.org/privilege/bluetooth