Tizen Native API
5.0
|
Bluetooth Adapter API provides functions for setting up Bluetooth and discovering other devices.
#include <bluetooth.h>
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
This API is related with the following features:
It is recommended to design feature related codes in your application for reliability.
You can check if a device supports the related features for this API by using System Information,thereby controlling the procedure of your application.
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.
More details on featuring your application can be found from Feature Element.
FUNCTION | CALLBACK | DESCRIPTION |
---|---|---|
bt_adapter_set_name() | bt_adapter_name_changed_cb() | Used to set adapter name. |
bt_adapter_visibility_mode_changed_cb() | Used to set visibility mode (bt_adapter_visibility_mode_e). | |
bt_adapter_start_device_discovery() bt_adapter_stop_device_discovery() | bt_adapter_device_discovery_state_changed_cb() | Used to start or cancel device discovery. |
REGISTER | UNREGISTER | CALLBACK | DESCRIPTION |
---|---|---|---|
bt_adapter_set_state_changed_cb() | bt_adapter_unset_state_changed_cb() | bt_adapter_state_changed_cb() | Used to be notified of state change (enable or disable). |
bt_adapter_set_name_changed_cb() | bt_adapter_unset_name_changed_cb() | bt_adapter_name_changed_cb() | Used to be notified of name change. |
bt_adapter_set_visibility_mode_changed_cb() | bt_adapter_unset_visibility_mode_changed_cb() | bt_adapter_visibility_mode_changed_cb() | Used to be notified of change of visibility mode (bt_adapter_visibility_mode_e). |
bt_adapter_set_device_discovery_state_changed_cb() | bt_adapter_unset_device_discovery_state_changed_cb() | bt_adapter_device_discovery_state_changed_cb() | Used to be notified of change of device discovery state (bt_adapter_device_discovery_state_e). |
FOREACH | CALLBACK | DESCRIPTION |
---|---|---|
bt_adapter_foreach_bonded_device() | bt_adapter_bonded_device_cb() | Used to get bonded devices. |
Please refer Bluetooth Tutorial if you want to get more detailed usages and information of this api.
Functions | |
int | bt_adapter_get_state (bt_adapter_state_e *adapter_state) |
Gets the current state of local Bluetooth adapter. | |
int | bt_adapter_get_address (char **local_address) |
Gets the address of local Bluetooth adapter. | |
int | bt_adapter_get_name (char **local_name) |
Gets the name of local Bluetooth adapter. | |
int | bt_adapter_set_name (const char *local_name) |
Sets the name of local Bluetooth adapter. | |
int | bt_adapter_get_visibility (bt_adapter_visibility_mode_e *mode, int *duration) |
Gets the visibility mode of local Bluetooth adapter. | |
int | bt_adapter_start_device_discovery (void) |
Starts the device discovery, asynchronously. | |
int | bt_adapter_stop_device_discovery (void) |
Stops the device discovery, asynchronously. | |
int | bt_adapter_is_discovering (bool *is_discovering) |
Checks for the device discovery is in progress or not. | |
int | bt_adapter_foreach_bonded_device (bt_adapter_bonded_device_cb callback, void *user_data) |
Retrieves the device information of all bonded devices. | |
int | bt_adapter_get_bonded_device_info (const char *remote_address, bt_device_info_s **device_info) |
Gets the device information of a bonded device. | |
int | bt_adapter_free_device_info (bt_device_info_s *device_info) |
Frees device info. | |
int | bt_adapter_is_service_used (const char *service_uuid, bool *used) |
Checks whether the UUID of service is used or not. | |
int | bt_adapter_set_state_changed_cb (bt_adapter_state_changed_cb callback, void *user_data) |
Registers a callback function to be invoked when the Bluetooth adapter state changes. | |
int | bt_adapter_unset_state_changed_cb (void) |
Unregisters the callback function. | |
int | bt_adapter_set_name_changed_cb (bt_adapter_name_changed_cb callback, void *user_data) |
Registers a callback function to be invoked when the name of Bluetooth adapter changes. | |
int | bt_adapter_unset_name_changed_cb (void) |
Unregisters the callback function. | |
int | bt_adapter_set_visibility_mode_changed_cb (bt_adapter_visibility_mode_changed_cb callback, void *user_data) |
Registers a callback function to be invoked when the visibility mode changes. | |
int | bt_adapter_unset_visibility_mode_changed_cb (void) |
Unregisters the callback function. | |
int | bt_adapter_set_visibility_duration_changed_cb (bt_adapter_visibility_duration_changed_cb callback, void *user_data) |
Registers a callback function to be invoked every second. | |
int | bt_adapter_unset_visibility_duration_changed_cb (void) |
Unregisters the callback function. | |
int | bt_adapter_set_device_discovery_state_changed_cb (bt_adapter_device_discovery_state_changed_cb callback, void *user_data) |
Registers a callback function to be invoked when the device discovery state changes. | |
int | bt_adapter_unset_device_discovery_state_changed_cb (void) |
Unregisters the callback function. | |
Typedefs | |
typedef void(* | bt_adapter_state_changed_cb )(int result, bt_adapter_state_e adapter_state, void *user_data) |
Called when the Bluetooth adapter state changes. | |
typedef void(* | bt_adapter_name_changed_cb )(char *device_name, void *user_data) |
Called when adapter name changes. | |
typedef void(* | bt_adapter_visibility_mode_changed_cb )(int result, bt_adapter_visibility_mode_e visibility_mode, void *user_data) |
Called when the visibility mode changes. | |
typedef void(* | bt_adapter_visibility_duration_changed_cb )(int duration, void *user_data) |
Called every second until the visibility mode is changed to BT_ADAPTER_VISIBILITY_MODE_NON_DISCOVERABLE. | |
typedef void(* | bt_adapter_device_discovery_state_changed_cb )(int result, bt_adapter_device_discovery_state_e discovery_state, bt_adapter_device_discovery_info_s *discovery_info, void *user_data) |
Called when the state of device discovery changes. | |
typedef bool(* | bt_adapter_bonded_device_cb )(bt_device_info_s *device_info, void *user_data) |
Called when you get bonded devices repeatedly. |
typedef bool(* bt_adapter_bonded_device_cb)(bt_device_info_s *device_info, void *user_data) |
Called when you get bonded devices repeatedly.
[in] | device_info | The bonded device information |
[in] | user_data | The user data passed from the foreach function |
true
to continue with the next iteration of the loop, false
to break out of the loop. typedef void(* bt_adapter_device_discovery_state_changed_cb)(int result, bt_adapter_device_discovery_state_e discovery_state, bt_adapter_device_discovery_info_s *discovery_info, void *user_data) |
Called when the state of device discovery changes.
[in] | result | The result of the device discovery |
[in] | discovery_state | The discovery state to be changed |
[in] | discovery_info | The information of the discovered device If discovery_state is BT_ADAPTER_DEVICE_DISCOVERY_STARTED or BT_ADAPTER_DEVICE_DISCOVERY_FINISHED, then discovery_info is NULL. |
[in] | user_data | The user data passed from the callback registration function |
typedef void(* bt_adapter_name_changed_cb)(char *device_name, void *user_data) |
Called when adapter name changes.
[in] | device_name | The name of the Bluetooth device to be changed |
[in] | user_data | The user data passed from the callback registration function |
typedef void(* bt_adapter_state_changed_cb)(int result, bt_adapter_state_e adapter_state, void *user_data) |
Called when the Bluetooth adapter state changes.
[in] | result | The result of the adapter state changing |
[in] | adapter_state | The adapter state to be changed |
[in] | user_data | The user data passed from the callback registration function |
typedef void(* bt_adapter_visibility_duration_changed_cb)(int duration, void *user_data) |
Called every second until the visibility mode is changed to BT_ADAPTER_VISIBILITY_MODE_NON_DISCOVERABLE.
[in] | duration | The duration until the visibility mode is changed to BT_ADAPTER_VISIBILITY_MODE_NON_DISCOVERABLE (in seconds) |
[in] | user_data | The user data passed from the callback registration function |
typedef void(* bt_adapter_visibility_mode_changed_cb)(int result, bt_adapter_visibility_mode_e visibility_mode, void *user_data) |
Called when the visibility mode changes.
[in] | result | The result of the visibility mode changing |
[in] | visibility_mode | The visibility mode to be changed |
[in] | user_data | The user data passed from the callback registration function |
enum bt_adapter_state_e |
Enumerations of the Bluetooth visibility mode.
BT_ADAPTER_VISIBILITY_MODE_NON_DISCOVERABLE |
Other devices cannot find your device via discovery |
BT_ADAPTER_VISIBILITY_MODE_GENERAL_DISCOVERABLE |
Discoverable mode |
BT_ADAPTER_VISIBILITY_MODE_LIMITED_DISCOVERABLE |
Discoverable mode with time limit. After specific period, it is changed to BT_ADAPTER_VISIBILITY_MODE_NON_DISCOVERABLE. |
int bt_adapter_foreach_bonded_device | ( | bt_adapter_bonded_device_cb | callback, |
void * | user_data | ||
) |
Retrieves the device information of all bonded devices.
[in] | callback | The callback function to invoke |
[in] | user_data | The user data passed from the foreach function |
BT_ERROR_NONE | Successful |
BT_ERROR_NOT_INITIALIZED | Not initialized |
BT_ERROR_INVALID_PARAMETER | Invalid parameter |
BT_ERROR_OUT_OF_MEMORY | Out of memory |
BT_ERROR_NOT_ENABLED | Not enabled |
BT_ERROR_OPERATION_FAILED | Operation failed |
BT_ERROR_NOT_SUPPORTED | Not supported |
int bt_adapter_free_device_info | ( | bt_device_info_s * | device_info | ) |
Frees device info.
[in] | device_info | The bonded device information |
BT_ERROR_NONE | Successful |
BT_ERROR_INVALID_PARAMETER | Invalid parameter |
BT_ERROR_NOT_SUPPORTED | Not supported |
int bt_adapter_get_address | ( | char ** | local_address | ) |
Gets the address of local Bluetooth adapter.
[out] | local_address | The device address of local Bluetooth adapter |
BT_ERROR_NONE | Successful |
BT_ERROR_NOT_INITIALIZED | Not initialized |
BT_ERROR_INVALID_PARAMETER | Invalid parameter |
BT_ERROR_NOT_ENABLED | Not enabled |
BT_ERROR_OUT_OF_MEMORY | Out of memory |
BT_ERROR_OPERATION_FAILED | Operation failed |
BT_ERROR_NOT_SUPPORTED | Not supported |
int bt_adapter_get_bonded_device_info | ( | const char * | remote_address, |
bt_device_info_s ** | device_info | ||
) |
Gets the device information of a bonded device.
[in] | remote_address | The address of remote device |
[out] | device_info | The bonded device information |
BT_ERROR_NONE | Successful |
BT_ERROR_NOT_INITIALIZED | Not initialized |
BT_ERROR_INVALID_PARAMETER | Invalid parameter |
BT_ERROR_OUT_OF_MEMORY | Out of memory |
BT_ERROR_NOT_ENABLED | Not enabled |
BT_ERROR_OPERATION_FAILED | Operation failed |
BT_ERROR_REMOTE_DEVICE_NOT_BONDED | Remote device not bonded |
BT_ERROR_NOT_SUPPORTED | Not supported |
int bt_adapter_get_name | ( | char ** | local_name | ) |
Gets the name of local Bluetooth adapter.
Use this function to get the friendly name associated with Bluetooth
device, retrieved by the remote Bluetooth devices.
[out] | local_name | The local device name |
BT_ERROR_NONE | Successful |
BT_ERROR_NOT_INITIALIZED | Not initialized |
BT_ERROR_INVALID_PARAMETER | Invalid parameter |
BT_ERROR_NOT_ENABLED | Not enabled |
BT_ERROR_OUT_OF_MEMORY | Out of memory |
BT_ERROR_OPERATION_FAILED | Operation failed |
BT_ERROR_NOT_SUPPORTED | Not supported |
int bt_adapter_get_state | ( | bt_adapter_state_e * | adapter_state | ) |
Gets the current state of local Bluetooth adapter.
[out] | adapter_state | The current adapter state |
BT_ERROR_NONE | Successful |
BT_ERROR_NOT_INITIALIZED | Not initialized |
BT_ERROR_INVALID_PARAMETER | Invalid parameter |
BT_ERROR_NOT_SUPPORTED | Not supported |
int bt_adapter_get_visibility | ( | bt_adapter_visibility_mode_e * | mode, |
int * | duration | ||
) |
Gets the visibility mode of local Bluetooth adapter.
[out] | mode | The visibility mode of the Bluetooth device |
[out] | duration | The duration until the visibility mode is changed to BT_ADAPTER_VISIBILITY_MODE_NON_DISCOVERABLE (in seconds). duration is valid only if mode is BT_ADAPTER_VISIBILITY_MODE_LIMITED_DISCOVERABLE. This value can be NULL. |
BT_ERROR_NONE | Successful |
BT_ERROR_NOT_INITIALIZED | Not initialized |
BT_ERROR_INVALID_PARAMETER | Invalid parameter |
BT_ERROR_NOT_ENABLED | Not enabled |
BT_ERROR_OPERATION_FAILED | Operation failed |
BT_ERROR_NOT_SUPPORTED | Not supported |
int bt_adapter_is_discovering | ( | bool * | is_discovering | ) |
Checks for the device discovery is in progress or not.
[out] | is_discovering | The discovering status: (true = in progress , false = not in progress ) |
BT_ERROR_NONE | Successful |
BT_ERROR_NOT_INITIALIZED | Not initialized |
BT_ERROR_INVALID_PARAMETER | Invalid parameter |
BT_ERROR_NOT_ENABLED | Not enabled |
BT_ERROR_OPERATION_FAILED | Operation failed |
BT_ERROR_NOT_SUPPORTED | Not supported |
int bt_adapter_is_service_used | ( | const char * | service_uuid, |
bool * | used | ||
) |
Checks whether the UUID of service is used or not.
[in] | service_uuid | The UUID of service |
[out] | used | Indicates whether the service is used or not |
BT_ERROR_NONE | Successful |
BT_ERROR_NOT_INITIALIZED | Not initialized |
BT_ERROR_INVALID_PARAMETER | Invalid parameter |
BT_ERROR_NOT_ENABLED | Not enabled |
BT_ERROR_OPERATION_FAILED | Operation failed |
BT_ERROR_NOT_SUPPORTED | Not supported |
int bt_adapter_set_device_discovery_state_changed_cb | ( | bt_adapter_device_discovery_state_changed_cb | callback, |
void * | user_data | ||
) |
Registers a callback function to be invoked when the device discovery state changes.
[in] | callback | The callback function to register |
[in] | user_data | The user data to be passed to the callback function |
BT_ERROR_NONE | Successful |
BT_ERROR_NOT_INITIALIZED | Not initialized |
BT_ERROR_INVALID_PARAMETER | Invalid parameter |
BT_ERROR_NOT_SUPPORTED | Not supported |
int bt_adapter_set_name | ( | const char * | local_name | ) |
Sets the name of local Bluetooth adapter.
[in] | local_name | The name of the Bluetooth device. The maximum length is 248 characters. |
BT_ERROR_NONE | Successful |
BT_ERROR_NOT_INITIALIZED | Not initialized |
BT_ERROR_INVALID_PARAMETER | Invalid parameter |
BT_ERROR_NOT_ENABLED | Not enabled |
BT_ERROR_OPERATION_FAILED | Operation failed |
BT_ERROR_PERMISSION_DENIED | Permission denied |
BT_ERROR_NOT_SUPPORTED | Not supported |
int bt_adapter_set_name_changed_cb | ( | bt_adapter_name_changed_cb | callback, |
void * | user_data | ||
) |
Registers a callback function to be invoked when the name of Bluetooth adapter changes.
[in] | callback | The callback function to invoke |
[in] | user_data | The user data to be passed to the callback function |
BT_ERROR_NONE | Successful |
BT_ERROR_NOT_INITIALIZED | Not initialized |
BT_ERROR_INVALID_PARAMETER | Invalid parameter |
BT_ERROR_NOT_SUPPORTED | Not supported |
int bt_adapter_set_state_changed_cb | ( | bt_adapter_state_changed_cb | callback, |
void * | user_data | ||
) |
Registers a callback function to be invoked when the Bluetooth adapter state changes.
[in] | callback | The callback function to invoke |
[in] | user_data | The user data to be passed to the callback function |
BT_ERROR_NONE | Successful |
BT_ERROR_NOT_INITIALIZED | Not initialized |
BT_ERROR_INVALID_PARAMETER | Invalid parameter |
BT_ERROR_NOT_SUPPORTED | Not supported |
int bt_adapter_set_visibility_duration_changed_cb | ( | bt_adapter_visibility_duration_changed_cb | callback, |
void * | user_data | ||
) |
Registers a callback function to be invoked every second.
When you set visibility mode as BT_ADAPTER_VISIBILITY_MODE_LIMITED_DISCOVERABLE,
callback will be called every second until visibility mode is changed to BT_ADAPTER_VISIBILITY_MODE_NON_DISCOVERABLE.
[in] | callback | The callback function to register |
[in] | user_data | The user data to be passed to the callback function |
BT_ERROR_NONE | Successful |
BT_ERROR_NOT_INITIALIZED | Not initialized |
BT_ERROR_INVALID_PARAMETER | Invalid parameter |
BT_ERROR_NOT_SUPPORTED | Not supported |
int bt_adapter_set_visibility_mode_changed_cb | ( | bt_adapter_visibility_mode_changed_cb | callback, |
void * | user_data | ||
) |
Registers a callback function to be invoked when the visibility mode changes.
[in] | callback | The callback function to register |
[in] | user_data | The user data to be passed to the callback function |
BT_ERROR_NONE | Successful |
BT_ERROR_NOT_INITIALIZED | Not initialized |
BT_ERROR_INVALID_PARAMETER | Invalid parameter |
BT_ERROR_NOT_SUPPORTED | Not supported |
int bt_adapter_start_device_discovery | ( | void | ) |
Starts the device discovery, asynchronously.
If a device is discovered, bt_adapter_device_discovery_state_changed_cb() will be invoked
with BT_ADAPTER_DEVICE_DISCOVERY_FOUND, and then bt_adapter_device_discovery_state_changed_cb()
will be called with BT_ADAPTER_DEVICE_DISCOVERY_FINISHED in case of the completion or cancellation of the discovery.
BT_ERROR_NONE | Successful |
BT_ERROR_NOT_INITIALIZED | Not initialized |
BT_ERROR_NOT_ENABLED | Not enabled |
BT_ERROR_NOW_IN_PROGRESS | Operation is now in progress |
BT_ERROR_OPERATION_FAILED | Operation failed |
BT_ERROR_PERMISSION_DENIED | Permission denied |
BT_ERROR_NOT_SUPPORTED | Not supported |
int bt_adapter_stop_device_discovery | ( | void | ) |
Stops the device discovery, asynchronously.
BT_ERROR_NONE | Successful |
BT_ERROR_NOT_INITIALIZED | Not initialized |
BT_ERROR_NOT_ENABLED | Not enabled |
BT_ERROR_NOT_IN_PROGRESS | Operation is not in progress |
BT_ERROR_OPERATION_FAILED | Operation failed |
BT_ERROR_PERMISSION_DENIED | Permission denied |
BT_ERROR_NOT_SUPPORTED | Not supported |
int bt_adapter_unset_device_discovery_state_changed_cb | ( | void | ) |
Unregisters the callback function.
BT_ERROR_NONE | Successful |
BT_ERROR_NOT_INITIALIZED | Not initialized |
BT_ERROR_NOT_SUPPORTED | Not supported |
int bt_adapter_unset_name_changed_cb | ( | void | ) |
Unregisters the callback function.
BT_ERROR_NONE | Successful |
BT_ERROR_NOT_INITIALIZED | Not initialized |
BT_ERROR_NOT_SUPPORTED | Not supported |
int bt_adapter_unset_state_changed_cb | ( | void | ) |
Unregisters the callback function.
BT_ERROR_NONE | Successful |
BT_ERROR_NOT_INITIALIZED | Not initialized |
BT_ERROR_NOT_SUPPORTED | Not supported |
int bt_adapter_unset_visibility_duration_changed_cb | ( | void | ) |
Unregisters the callback function.
BT_ERROR_NONE | Successful |
BT_ERROR_NOT_INITIALIZED | Not initialized |
BT_ERROR_NOT_SUPPORTED | Not supported |
int bt_adapter_unset_visibility_mode_changed_cb | ( | void | ) |
Unregisters the callback function.
BT_ERROR_NONE | Successful |
BT_ERROR_NOT_INITIALIZED | Not initialized |
BT_ERROR_NOT_SUPPORTED | Not supported |