Tizen Native API
7.0
|
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
Enumerations of the Bluetooth HID handshake type.
- Since :
- 3.0
- Enumerator:
enum bt_hid_header_type_e |
Enumerations of the Bluetooth HID header type.
- Since :
- 3.0
- Enumerator:
enum bt_hid_param_type_e |
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().
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().
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.
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.
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.
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
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