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:

http://tizen.org/feature/network.bluetooth

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

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_NONE	Successful
BT_ERROR_NOT_INITIALIZED	Not initialized
BT_ERROR_OPERATION_FAILED	Operation failed
BT_ERROR_NOT_SUPPORTED	Not 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]	uuid	The UUID
[out]	name	The specification name defined at www.bluetooth.com

Returns:: 0 on success, otherwise a negative error value.

Return values:

BT_ERROR_NONE	Successful
BT_ERROR_INVALID_PARAMETER	Invalid parameter
BT_ERROR_NOT_SUPPORTED	Not 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]	callback	The callback called when the connection state is changed
[in]	user_data	The user data to be passed to the callback function

Returns:: 0 on success, otherwise a negative error value.

Return values:

BT_ERROR_NONE	Successful
BT_ERROR_NOT_INITIALIZED	Not initialized
BT_ERROR_INVALID_PARAMETER	Invalid parameter
BT_ERROR_NOT_ENABLED	Not enabled
BT_ERROR_NOW_IN_PROGRESS	Already activated
BT_ERROR_OPERATION_FAILED	Operation failed
BT_ERROR_PERMISSION_DENIED	Permission denied
BT_ERROR_NOT_SUPPORTED	Not 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_address The remote device's address.

Returns:: 0 on success, otherwise a negative error value.

Return values:

BT_ERROR_NONE	Successful
BT_ERROR_NOT_INITIALIZED	Not initialized
BT_ERROR_INVALID_PARAMETER	Invalid parameter
BT_ERROR_NOT_ENABLED	Not enabled
BT_ERROR_NOT_IN_PROGRESS	Not activated
BT_ERROR_OPERATION_FAILED	Operation failed
BT_ERROR_PERMISSION_DENIED	Permission denied
BT_ERROR_ALREADY_DONE	Already connected
BT_ERROR_NOT_SUPPORTED	Not 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_NONE	Successful
BT_ERROR_NOT_INITIALIZED	Not initialized
BT_ERROR_INVALID_PARAMETER	Invalid parameter
BT_ERROR_NOT_ENABLED	Not enabled
BT_ERROR_NOT_IN_PROGRESS	Not activated
BT_ERROR_OPERATION_FAILED	Operation failed
BT_ERROR_PERMISSION_DENIED	Permission denied
BT_ERROR_NOT_SUPPORTED	Not 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_address The remote device's address.

Returns:: 0 on success, otherwise a negative error value.

Return values:

BT_ERROR_NONE	Successful
BT_ERROR_NOT_INITIALIZED	Not initialized
BT_ERROR_NOT_ENABLED	Not enabled
BT_ERROR_REMOTE_DEVICE_NOT_CONNECTED	Remote device is not connected
BT_ERROR_OPERATION_FAILED	Operation failed
BT_ERROR_PERMISSION_DENIED	Permission denied
BT_ERROR_NOT_SUPPORTED	Not 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_address	The remote device's address.
[in]	header_type	The response header type
[in]	param_type	The response parameter type
[in]	data	The response data
[in]	data_len	The length of the response data

Return values:

BT_ERROR_NONE	Successful
BT_ERROR_NOT_INITIALIZED	Not initialized
BT_ERROR_NOT_ENABLED	Not enabled
BT_ERROR_OPERATION_FAILED	Operation failed
BT_ERROR_PERMISSION_DENIED	Permission denied
BT_ERROR_NOT_SUPPORTED	Not 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_address	The remote device's address.
[in]	key_data	The key data to be passed to the remote device

Returns:: 0 on success, otherwise a negative error value.

Return values:

BT_ERROR_NONE	Successful
BT_ERROR_NOT_INITIALIZED	Not initialized
BT_ERROR_INVALID_PARAMETER	Invalid parameter
BT_ERROR_OPERATION_FAILED	Operation failed
BT_ERROR_PERMISSION_DENIED	Permission denied
BT_ERROR_NOT_SUPPORTED	Not 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_address	The remote device's address.
[in]	mouse_data	The mouse data to be passed to the remote device.

Returns:: 0 on success, otherwise a negative error value.

Return values:

BT_ERROR_NONE	Successful
BT_ERROR_NOT_INITIALIZED	Not initialized
BT_ERROR_INVALID_PARAMETER	Invalid parameter
BT_ERROR_OPERATION_FAILED	Operation failed
BT_ERROR_PERMISSION_DENIED	Permission denied
BT_ERROR_NOT_SUPPORTED	Not 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]	callback	The callback function to be set when data is received.
[in]	user_data	The user data to be passed to the callback.

Return values:

BT_ERROR_NONE	Successful
BT_ERROR_NOT_INITIALIZED	Not initialized
BT_ERROR_INVALID_PARAMETER	Invalid parameter
BT_ERROR_NOT_SUPPORTED	Not supported

See also:: bt_hid_device_connection_state_changed_cb()

int bt_hid_device_unset_data_received_cb ( void )

Unsets the data received callback.

Since :

Return values:

BT_ERROR_NONE	Successful
BT_ERROR_NOT_INITIALIZED	Not initialized
BT_ERROR_NOT_SUPPORTED	Not 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_address The remote address

Returns:: 0 on success, otherwise a negative error value.

Return values:

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

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_NONE	Successful
BT_ERROR_NOT_INITIALIZED	Not initialized
BT_ERROR_OPERATION_FAILED	Operation failed
BT_ERROR_NOT_SUPPORTED	Not 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_address The remote address

Returns:: 0 on success, otherwise a negative error value.

Return values:

BT_ERROR_NONE	Successful
BT_ERROR_NOT_INITIALIZED	Not initialized
BT_ERROR_INVALID_PARAMETER	Invalid parameter
BT_ERROR_NOT_ENABLED	Not enabled
BT_ERROR_REMOTE_DEVICE_NOT_CONNECTED	Remote device is not connected
BT_ERROR_OPERATION_FAILED	Operation failed
BT_ERROR_PERMISSION_DENIED	Permission denied
BT_ERROR_NOT_SUPPORTED	Not 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_cb	The callback called when the connection state is changed
[in]	user_data	The user data to be passed to the callback function

Returns:: 0 on success, otherwise a negative error value.

Return values:

BT_ERROR_NONE	Successful
BT_ERROR_NOT_INITIALIZED	Not initialized
BT_ERROR_INVALID_PARAMETER	Invalid parameter
BT_ERROR_OPERATION_FAILED	Operation failed
BT_ERROR_NOT_SUPPORTED	Not 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_NONE	Successful
BT_ERROR_OPERATION_FAILED	Operation failed
BT_ERROR_NOT_SUPPORTED	Not supported

See also:: bt_deinitialize()

Required Header

Overview

Related Features

Functions

Enumeration Type Documentation

Function Documentation