Tizen Native API  5.5
Bluetooth HID Device

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]resultThe result of changing the connection state.
[in]connectedThe requested state. true means the connection is enabled, false means the connection is disabled.
[in]remote_addressThe remote device's address
[in]user_dataThe 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]dataThe data received from the HID Host.
[in]user_dataThe user data passed from the callback registration function
See also:
bt_hid_device_set_data_received_cb()

Enumeration Type Documentation

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

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

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

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]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 :
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_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 :
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_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 :
3.0
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 :
3.0
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 :
3.0
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 :
3.0
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 :
3.0
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 :
3.0
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()