Tizen Native API  5.0
Bluetooth

Bluetooth Service provides API to manage Bluetooth device.

Required Header

#include <bluetooth.h>

Overview

Bluetooth Service consists of Bluetooth Adapter, Bluetooth Device and Bluetooth Socket.


In order to use the above APIs, you must call bt_initialize() in advance. In addition, bt_deinitialize() should be called when Bluetooth Service is no longer needed. Please refer Bluetooth Tutorial if you want to get more detailed usages and information of this api.

Note on callbacks: All callbacks in this module are called in the main loop context.

Related Features

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.

Functions

int bt_initialize (void)
 Initializes the Bluetooth API.
int bt_deinitialize (void)
 Releases all resources of the Bluetooth API.
int bt_get_uuid_name (const char *uuid, char **name)
 Gets the specification name for the given UUID.
int bt_hid_host_initialize (bt_hid_host_connection_state_changed_cb connection_cb, void *user_data)
 Initializes the Bluetooth HID (Human Interface Device) Host.
int bt_hid_host_deinitialize (void)
 Deinitializes the Bluetooth HID (Human Interface Device) Host.
int bt_hid_host_connect (const char *remote_address)
 Connects the remote device with the HID (Human Interface Device) service, asynchronously.
int bt_hid_host_disconnect (const char *remote_address)
 Disconnects the remote device with the HID (Human Interface Device) service, asynchronously.
int bt_hid_device_activate (bt_hid_device_connection_state_changed_cb callback, void *user_data)
 Activates the Bluetooth HID Device role.
int bt_hid_device_deactivate (void)
 Deactivates the Bluetooth HID Device role.
int bt_hid_device_connect (const char *remote_address)
 Initiates the HID device connection with the Device role, asynchronously.
int bt_hid_device_disconnect (const char *remote_address)
 Disconnects from the HID Host device, asynchronously.
int bt_hid_device_send_mouse_event (const char *remote_address, const bt_hid_mouse_data_s *mouse_data)
 Sends the mouse event data to the remote device.
int bt_hid_device_send_key_event (const char *remote_address, const bt_hid_key_data_s *key_data)
 Sends the keyboard event data to the remote device.
int bt_hid_device_set_data_received_cb (bt_hid_device_data_received_cb callback, void *user_data)
 Sets the callback called when the device receives data from the HID Host.
int bt_hid_device_unset_data_received_cb (void)
 Unsets the data received callback.
int bt_hid_device_reply_to_report (const char *remote_address, bt_hid_header_type_e header_type, bt_hid_param_type_e param_type, const char *data, unsigned int data_len)
 Responds to reports from the HID Host.

Enumeration Type Documentation

enum bt_error_e

Enumerations of Bluetooth error codes.

Since :
2.3
Enumerator:
BT_ERROR_NONE 

Successful

BT_ERROR_CANCELLED 

Operation cancelled

BT_ERROR_INVALID_PARAMETER 

Invalid parameter

BT_ERROR_OUT_OF_MEMORY 

Out of memory

BT_ERROR_RESOURCE_BUSY 

Device or resource busy

BT_ERROR_TIMED_OUT 

Timeout error

BT_ERROR_NOW_IN_PROGRESS 

Operation now in progress

BT_ERROR_NOT_SUPPORTED 

BT is Not Supported

BT_ERROR_PERMISSION_DENIED 

Permission denied

BT_ERROR_QUOTA_EXCEEDED 

Quota exceeded

BT_ERROR_NO_DATA 

No data available

BT_ERROR_DEVICE_POLICY_RESTRICTION 

Device policy restriction (Since 3.0)

BT_ERROR_NOT_INITIALIZED 

Local adapter not initialized

BT_ERROR_NOT_ENABLED 

Local adapter not enabled

BT_ERROR_ALREADY_DONE 

Operation already done

BT_ERROR_OPERATION_FAILED 

Operation failed

BT_ERROR_NOT_IN_PROGRESS 

Operation not in progress

BT_ERROR_REMOTE_DEVICE_NOT_BONDED 

Remote device not bonded

BT_ERROR_AUTH_REJECTED 

Authentication rejected

BT_ERROR_AUTH_FAILED 

Authentication failed

BT_ERROR_REMOTE_DEVICE_NOT_FOUND 

Remote device not found

BT_ERROR_SERVICE_SEARCH_FAILED 

Service search failed

BT_ERROR_REMOTE_DEVICE_NOT_CONNECTED 

Remote device is not connected

BT_ERROR_AGAIN 

Resource temporarily unavailable

BT_ERROR_SERVICE_NOT_FOUND 

Service Not Found

BT_ERROR_AUTHORIZATION_REJECTED 

Authorization rejected (Since 5.0)


Function Documentation

int bt_deinitialize ( void  )

Releases all resources of the Bluetooth API.

Since :
2.3
Remarks:
This function must be called if Bluetooth API is no longer needed.
Returns:
0 on success, otherwise a negative error value.
Return values:
BT_ERROR_NONESuccessful
BT_ERROR_NOT_INITIALIZEDNot initialized
BT_ERROR_OPERATION_FAILEDOperation failed
BT_ERROR_NOT_SUPPORTEDNot supported
Precondition:
Bluetooth API must be initialized with bt_initialize().
See also:
bt_initialize()
int bt_get_uuid_name ( const char *  uuid,
char **  name 
)

Gets the specification name for the given UUID.

Since :
3.0
Remarks:
The name must be released using free().
Parameters:
[in]uuidThe UUID
[out]nameThe specification name defined at www.bluetooth.com
Returns:
0 on success, otherwise a negative error value.
Return values:
BT_ERROR_NONESuccessful
BT_ERROR_INVALID_PARAMETERInvalid parameter
BT_ERROR_NOT_SUPPORTEDNot supported
See also:
bt_gatt_get_uuid()
int bt_hid_device_activate ( bt_hid_device_connection_state_changed_cb  callback,
void *  user_data 
)

Activates the Bluetooth HID Device role.

Since :
Privilege Level:
public
Privilege:
http://tizen.org/privilege/bluetooth
Remarks:
This function must be called to register HID UUID.
Only then a remote device is able to identify this one as a HID device.
Parameters:
[in]callbackThe callback called when the connection state is changed
[in]user_dataThe user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value.
Return values:
BT_ERROR_NONESuccessful
BT_ERROR_NOT_INITIALIZEDNot initialized
BT_ERROR_INVALID_PARAMETERInvalid parameter
BT_ERROR_NOT_ENABLEDNot enabled
BT_ERROR_NOW_IN_PROGRESSAlready activated
BT_ERROR_OPERATION_FAILEDOperation failed
BT_ERROR_PERMISSION_DENIEDPermission denied
BT_ERROR_NOT_SUPPORTEDNot supported
Precondition:
The Bluetooth service must be initialized with bt_initialize().
See also:
bt_initialize()
bt_hid_device_deactivate()
int bt_hid_device_connect ( const char *  remote_address)

Initiates the HID device connection with the Device role, asynchronously.

Since :
Privilege Level:
public
Privilege:
http://tizen.org/privilege/bluetooth
Remarks:
This function must be called to Initiate the HID device role connection.
Parameters:
[in]remote_addressThe remote device's address.
Returns:
0 on success, otherwise a negative error value.
Return values:
BT_ERROR_NONESuccessful
BT_ERROR_NOT_INITIALIZEDNot initialized
BT_ERROR_INVALID_PARAMETERInvalid parameter
BT_ERROR_NOT_ENABLEDNot enabled
BT_ERROR_NOT_IN_PROGRESSNot activated
BT_ERROR_OPERATION_FAILEDOperation failed
BT_ERROR_PERMISSION_DENIEDPermission denied
BT_ERROR_ALREADY_DONEAlready connected
BT_ERROR_NOT_SUPPORTEDNot supported
Precondition:
The Bluetooth service must be initialized with bt_initialize().
The local device must be bonded with the remote device by bt_device_create_bond().
See also:
bt_initialize()
bt_hid_device_activate()
int bt_hid_device_deactivate ( void  )

Deactivates the Bluetooth HID Device role.

Since :
Privilege Level:
public
Privilege:
http://tizen.org/privilege/bluetooth
Remarks:
This function must be called to deregister the HID UUID.
Returns:
0 on success, otherwise a negative error value.
Return values:
BT_ERROR_NONESuccessful
BT_ERROR_NOT_INITIALIZEDNot initialized
BT_ERROR_NOT_ENABLEDNot enabled
BT_ERROR_NOT_IN_PROGRESSNot activated
BT_ERROR_OPERATION_FAILEDOperation failed
BT_ERROR_PERMISSION_DENIEDPermission denied
BT_ERROR_NOT_SUPPORTEDNot supported
Precondition:
The Bluetooth service must be initialized with bt_initialize().
See also:
bt_initialize()
bt_hid_device_activate()
int bt_hid_device_disconnect ( const char *  remote_address)

Disconnects from the HID Host device, asynchronously.

Since :
Privilege Level:
public
Privilege:
http://tizen.org/privilege/bluetooth
Parameters:
[in]remote_addressThe remote device's address.
Returns:
0 on success, otherwise a negative error value.
Return values:
BT_ERROR_NONESuccessful
BT_ERROR_NOT_INITIALIZEDNot initialized
BT_ERROR_INVALID_PARAMETERInvalid parameter
BT_ERROR_NOT_ENABLEDNot enabled
BT_ERROR_REMOTE_DEVICE_NOT_CONNECTEDRemote device is not connected
BT_ERROR_OPERATION_FAILEDOperation failed
BT_ERROR_PERMISSION_DENIEDPermission denied
BT_ERROR_NOT_SUPPORTEDNot supported
Precondition:
The Bluetooth service must be initialized with bt_initialize().
See also:
bt_initialize()
bt_hid_device_connection_state_changed_cb()
int bt_hid_device_reply_to_report ( const char *  remote_address,
bt_hid_header_type_e  header_type,
bt_hid_param_type_e  param_type,
const char *  data,
unsigned int  data_len 
)

Responds to reports from the HID Host.

Since :
Privilege Level:
public
Privilege:
http://tizen.org/privilege/bluetooth
Parameters:
[in]remote_addressThe remote device's address.
[in]header_typeThe response header type
[in]param_typeThe response parameter type
[in]dataThe response data
[in]data_lenThe length of the response data
Returns:
0 on success, otherwise a negative error value.
Return values:
BT_ERROR_NONESuccessful
BT_ERROR_NOT_INITIALIZEDNot initialized
BT_ERROR_INVALID_PARAMETERInvalid parameter
BT_ERROR_NOT_ENABLEDNot enabled
BT_ERROR_OPERATION_FAILEDOperation failed
BT_ERROR_PERMISSION_DENIEDPermission denied
BT_ERROR_NOT_SUPPORTEDNot supported
Precondition:
The HID connection must be established.
See also:
bt_hid_device_connection_state_changed_cb()
int bt_hid_device_send_key_event ( const char *  remote_address,
const bt_hid_key_data_s key_data 
)

Sends the keyboard event data to the remote device.

Since :
Privilege Level:
public
Privilege:
http://tizen.org/privilege/bluetooth
Parameters:
[in]remote_addressThe remote device's address.
[in]key_dataThe key data to be passed to the remote device
Returns:
0 on success, otherwise a negative error value.
Return values:
BT_ERROR_NONESuccessful
BT_ERROR_NOT_INITIALIZEDNot initialized
BT_ERROR_INVALID_PARAMETERInvalid parameter
BT_ERROR_OPERATION_FAILEDOperation failed
BT_ERROR_PERMISSION_DENIEDPermission denied
BT_ERROR_NOT_SUPPORTEDNot supported
Precondition:
The HID connection must be established.
See also:
bt_hid_device_connection_state_changed_cb()
int bt_hid_device_send_mouse_event ( const char *  remote_address,
const bt_hid_mouse_data_s mouse_data 
)

Sends the mouse event data to the remote device.

Since :
Privilege Level:
public
Privilege:
http://tizen.org/privilege/bluetooth
Parameters:
[in]remote_addressThe remote device's address.
[in]mouse_dataThe mouse data to be passed to the remote device.
Returns:
0 on success, otherwise a negative error value.
Return values:
BT_ERROR_NONESuccessful
BT_ERROR_NOT_INITIALIZEDNot initialized
BT_ERROR_INVALID_PARAMETERInvalid parameter
BT_ERROR_OPERATION_FAILEDOperation failed
BT_ERROR_PERMISSION_DENIEDPermission denied
BT_ERROR_NOT_SUPPORTEDNot supported
Precondition:
The HID connection must be established.
See also:
bt_hid_device_connection_state_changed_cb()
int bt_hid_device_set_data_received_cb ( bt_hid_device_data_received_cb  callback,
void *  user_data 
)

Sets the callback called when the device receives data from the HID Host.

Since :
Parameters:
[in]callbackThe callback function to be set when data is received.
[in]user_dataThe user data to be passed to the callback.
Returns:
0 on success, otherwise a negative error value.
Return values:
BT_ERROR_NONESuccessful
BT_ERROR_NOT_INITIALIZEDNot initialized
BT_ERROR_INVALID_PARAMETERInvalid parameter
BT_ERROR_NOT_SUPPORTEDNot supported
See also:
bt_hid_device_connection_state_changed_cb()

Unsets the data received callback.

Since :
Returns:
0 on success, otherwise a negative error value.
Return values:
BT_ERROR_NONESuccessful
BT_ERROR_NOT_INITIALIZEDNot initialized
BT_ERROR_NOT_SUPPORTEDNot supported
See also:
bt_hid_device_connection_state_changed_cb()
int bt_hid_host_connect ( const char *  remote_address)

Connects the remote device with the HID (Human Interface Device) service, asynchronously.

@ @ @

Since :
2.3
Privilege Level:
public
Privilege:
http://tizen.org/privilege/bluetooth
Parameters:
[in]remote_addressThe remote address
Returns:
0 on success, otherwise a negative error value.
Return values:
BT_ERROR_NONESuccessful
BT_ERROR_NOT_INITIALIZEDNot initialized
BT_ERROR_INVALID_PARAMETERInvalid parameter
BT_ERROR_NOT_ENABLEDNot enabled
BT_ERROR_OPERATION_FAILEDOperation failed
BT_ERROR_PERMISSION_DENIEDPermission denied
BT_ERROR_NOT_SUPPORTEDNot supported
Precondition:
The local device must be bonded with the remote device by bt_device_create_bond().
The Bluetooth HID service must be initialized with bt_hid_host_initialize().
Postcondition:
bt_hid_host_connection_state_changed_cb() will be invoked.
See also:
bt_hid_host_disconnect()
bt_hid_host_connection_state_changed_cb()
int bt_hid_host_deinitialize ( void  )

Deinitializes the Bluetooth HID (Human Interface Device) Host.

@ @ @

Since :
2.3
Returns:
0 on success, otherwise a negative error value.
Return values:
BT_ERROR_NONESuccessful
BT_ERROR_NOT_INITIALIZEDNot initialized
BT_ERROR_OPERATION_FAILEDOperation failed
BT_ERROR_NOT_SUPPORTEDNot supported
Precondition:
The Bluetooth HID service must be initialized with bt_hid_host_initialize().
See also:
bt_hid_host_initialize()
int bt_hid_host_disconnect ( const char *  remote_address)

Disconnects the remote device with the HID (Human Interface Device) service, asynchronously.

@ @ @

Since :
2.3
Privilege Level:
public
Privilege:
http://tizen.org/privilege/bluetooth
Parameters:
[in]remote_addressThe remote address
Returns:
0 on success, otherwise a negative error value.
Return values:
BT_ERROR_NONESuccessful
BT_ERROR_NOT_INITIALIZEDNot initialized
BT_ERROR_INVALID_PARAMETERInvalid parameter
BT_ERROR_NOT_ENABLEDNot enabled
BT_ERROR_REMOTE_DEVICE_NOT_CONNECTEDRemote device is not connected
BT_ERROR_OPERATION_FAILEDOperation failed
BT_ERROR_PERMISSION_DENIEDPermission denied
BT_ERROR_NOT_SUPPORTEDNot supported
Precondition:
The remote device must be connected by bt_hid_host_connect().
Postcondition:
bt_hid_host_connection_state_changed_cb() will be invoked.
See also:
bt_hid_host_connect()
bt_hid_host_connection_state_changed_cb()
int bt_hid_host_initialize ( bt_hid_host_connection_state_changed_cb  connection_cb,
void *  user_data 
)

Initializes the Bluetooth HID (Human Interface Device) Host.

@ @ @

Since :
2.3
Remarks:
This function must be called before Bluetooth HID Host starts.
You must free all resources of the Bluetooth service by calling bt_hid_host_deinitialize()
if Bluetooth HID Host service is no longer needed.
Parameters:
[in]connection_cbThe callback called when the connection state is changed
[in]user_dataThe user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value.
Return values:
BT_ERROR_NONESuccessful
BT_ERROR_NOT_INITIALIZEDNot initialized
BT_ERROR_INVALID_PARAMETERInvalid parameter
BT_ERROR_OPERATION_FAILEDOperation failed
BT_ERROR_NOT_SUPPORTEDNot supported
Precondition:
The Bluetooth service must be initialized with bt_initialize().
See also:
bt_initialize()
bt_hid_host_deinitialize()
int bt_initialize ( void  )

Initializes the Bluetooth API.

Since :
2.3
Remarks:
This function must be called before Bluetooth API starts.
You must free all resources of the Bluetooth service by calling bt_deinitialize() if Bluetooth service is no longer needed.
Returns:
0 on success, otherwise a negative error value.
Return values:
BT_ERROR_NONESuccessful
BT_ERROR_OPERATION_FAILEDOperation failed
BT_ERROR_NOT_SUPPORTEDNot supported
See also:
bt_deinitialize()