The Bluetooth HID (Human Interface Device) API provides functions for connecting Bluetooth HID such as keyboards and mice.

Required Header

#include <bluetooth.h>

Overview

In HID Profile, there are two roles - Host and Device. The Host is a device that uses or requests the services of a HID. The Device is a device that provides the service of human data input and output to and from the Host. This API supports the Device role.

Related Features

This API is related to the following features:

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

It is recommended to use features in your application for reliability.

You can check if a device supports the related features for this API by using System Information, thereby controlling your application's actions.

To ensure your application runs only on devices with the required features, please declare 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_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.
Typedefs
typedef void(*	bt_hid_device_connection_state_changed_cb )(int result, bool connected, const char remote_address, void user_data)
	Called when the Bluetooth HID Device connection state changes.
typedef void(*	bt_hid_device_data_received_cb )(const bt_hid_device_received_data_s data, void user_data)
	Called when the HID Device receives data from the HID Host.

Typedef Documentation

typedef void(* bt_hid_device_connection_state_changed_cb)(int result, bool connected, const char *remote_address, void *user_data)

Called when the Bluetooth HID Device connection state changes.

The following error codes can be delivered:
BT_ERROR_NONE
BT_ERROR_OPERATION_FAILED

Since :: 3.0

Parameters:

[in]	result	The result of changing the connection state.
[in]	connected	The requested state. true means the connection is enabled, false means the connection is disabled.
[in]	remote_address	The remote device's address
[in]	user_data	The user data passed from the callback registration function

See also:: bt_hid_device_activate()

typedef void(* bt_hid_device_data_received_cb)(const bt_hid_device_received_data_s *data, void *user_data)

Called when the HID Device receives data from the HID Host.

The following error codes can be delivered:
BT_ERROR_NONE
BT_ERROR_OPERATION_FAILED

Since :: 3.0

Parameters:

[in]	data	The data received from the HID Host.
[in]	user_data	The user data passed from the callback registration function

See also:: bt_hid_device_set_data_received_cb()

Enumeration Type Documentation

enum bt_hid_handshake_type_e

Enumerations of the Bluetooth HID handshake type.

Since :: 3.0

Enumerator:

BT_HID_HANDSHAKE_SUCCESSFUL	Handshake error code none
BT_HID_HANDSHAKE_NOT_READY	Handshake error code Not Ready
BT_HID_HANDSHAKE_ERR_INVALID_REPORT_ID	Handshake error code send invalid report id
BT_HID_HANDSHAKE_ERR_UNSUPPORTED_REQUEST	Handshake error code request unsupported request
BT_HID_HANDSHAKE_ERR_INVALID_PARAMETER	Handshake error code received invalid parameter
BT_HID_HANDSHAKE_ERR_UNKNOWN	unknown error
BT_HID_HANDSHAKE_ERR_FATAL	Fatal error

enum bt_hid_header_type_e

Enumerations of the Bluetooth HID header type.

Since :: 3.0

Enumerator:

BT_HID_HEADER_HANDSHAKE	The Bluetooth HID header type: Handshake
BT_HID_HEADER_HID_CONTROL	The Bluetooth HID header type: HID control
BT_HID_HEADER_GET_REPORT	The Bluetooth HID header type: Get report
BT_HID_HEADER_SET_REPORT	The Bluetooth HID header type: Set report
BT_HID_HEADER_GET_PROTOCOL	The Bluetooth HID header type: Get protocol
BT_HID_HEADER_SET_PROTOCOL	The Bluetooth HID header type: Set protocol
BT_HID_HEADER_DATA	The Bluetooth HID header type: Data
BT_HID_HEADER_UNKNOWN	The Bluetooth HID header type: Unknown

enum bt_hid_mouse_button_e

Enumerations of the Bluetooth HID mouse's button.

Since :: 3.0

Enumerator:

BT_HID_MOUSE_BUTTON_NONE	The mouse's none value
BT_HID_MOUSE_BUTTON_LEFT	The mouse's left button value
BT_HID_MOUSE_BUTTON_RIGHT	The mouse's right button value
BT_HID_MOUSE_BUTTON_MIDDLE	The mouse's middle button value

enum bt_hid_param_type_e

Enumerations of the Bluetooth HID parameter type.

Since :: 3.0

Enumerator:

BT_HID_PARAM_DATA_RTYPE_INPUT	Parameter type: Input
BT_HID_PARAM_DATA_RTYPE_OUTPUT	Parameter type: Output

Function Documentation

int bt_hid_device_activate	(	bt_hid_device_connection_state_changed_cb	callback,
		void *	user_data
	)

Activates the Bluetooth HID Device role.

Since :: 3.0

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 :: 3.0

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 :: 3.0

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_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 :: 3.0

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_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 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 :: 3.0

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

Returns:: the number of bytes written (zero indicates nothing was written).

Return values:

On	error, -1 is returned, and errno is set appropriately. See write 2 man page.
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 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 :: 3.0

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:: the number of bytes written (zero indicates nothing was written).

Return values:

On	error, -1 is returned, and errno is set appropriately. See write 2 man page.
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 :: 3.0

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:: the number of bytes written (zero indicates nothing was written).

Return values:

On	error, -1 is returned, and errno is set appropriately. See write 2 man page.
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 :: 3.0

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.

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_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 :: 3.0

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

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()

Required Header

Overview

Related Features

Functions

Typedefs

Typedef Documentation

Enumeration Type Documentation

Function Documentation