BluetoothHidDevice

public final class BluetoothHidDevice
extends Object implements BluetoothProfile

java.lang.Object
   ↳ android.bluetooth.BluetoothHidDevice

Provides the public APIs to control the Bluetooth HID Device profile.

BluetoothHidDevice is a proxy object for controlling the Bluetooth HID Device Service via IPC. Use BluetoothAdapter#getProfileProxy to get the BluetoothHidDevice proxy object.

Summary

Nested classes

class BluetoothHidDevice.Callback

The template class that applications use to call callback functions on events from the HID host. 

Constants

String ACTION_CONNECTION_STATE_CHANGED

Intent used to broadcast the change in connection state of the Input Host profile.

byte ERROR_RSP_INVALID_PARAM

Constant representing error response for Set Report due to "invalid parameter".

byte ERROR_RSP_INVALID_RPT_ID

Constant representing error response for Set Report due to "invalid report ID".

byte ERROR_RSP_NOT_READY

Constant representing error response for Set Report due to "not ready".

byte ERROR_RSP_SUCCESS

Constant representing success response for Set Report.

byte ERROR_RSP_UNKNOWN

Constant representing error response for Set Report with unknown reason.

byte ERROR_RSP_UNSUPPORTED_REQ

Constant representing error response for Set Report due to "unsupported request".

byte PROTOCOL_BOOT_MODE

Constant representing boot protocol mode used set by host.

byte PROTOCOL_REPORT_MODE

Constant representing report protocol mode used set by host.

byte REPORT_TYPE_FEATURE

Constant representing HID Feature Report type.

byte REPORT_TYPE_INPUT

Constant representing HID Input Report type.

byte REPORT_TYPE_OUTPUT

Constant representing HID Output Report type.

byte SUBCLASS1_COMBO

Constant representing combo keyboard and mouse subclass.

byte SUBCLASS1_KEYBOARD

Constant representing keyboard subclass.

byte SUBCLASS1_MOUSE

Constant representing mouse subclass.

byte SUBCLASS1_NONE

Constant representing unspecified HID device subclass.

byte SUBCLASS2_CARD_READER

Constant representing card reader subclass.

byte SUBCLASS2_DIGITIZER_TABLET

Constant representing digitizer tablet subclass.

byte SUBCLASS2_GAMEPAD

Constant representing gamepad subclass.

byte SUBCLASS2_JOYSTICK

Constant representing joystick subclass.

byte SUBCLASS2_REMOTE_CONTROL

Constant representing remote control subclass.

byte SUBCLASS2_SENSING_DEVICE

Constant representing sensing device subclass.

byte SUBCLASS2_UNCATEGORIZED

Constant representing uncategorized HID device subclass.

Inherited constants

Public methods

boolean connect(BluetoothDevice device)

Initiates connection to host which is currently paired with this device.

boolean disconnect(BluetoothDevice device)

Disconnects from currently connected host.

List<BluetoothDevice> getConnectedDevices()

Get connected devices for this specific profile.
For apps targeting Build.VERSION_CODES#S or or higher, this requires the Manifest.permission#BLUETOOTH_CONNECT permission which can be gained with Activity.requestPermissions(String[], int).

int getConnectionState(BluetoothDevice device)

Get the current connection state of the profile
For apps targeting Build.VERSION_CODES#S or or higher, this requires the Manifest.permission#BLUETOOTH_CONNECT permission which can be gained with Activity.requestPermissions(String[], int).

List<BluetoothDevice> getDevicesMatchingConnectionStates(int[] states)

Get a list of devices that match any of the given connection states.
For apps targeting Build.VERSION_CODES#S or or higher, this requires the Manifest.permission#BLUETOOTH_CONNECT permission which can be gained with Activity.requestPermissions(String[], int).

boolean registerApp(BluetoothHidDeviceAppSdpSettings sdp, BluetoothHidDeviceAppQosSettings inQos, BluetoothHidDeviceAppQosSettings outQos, Executor executor, BluetoothHidDevice.Callback callback)

Registers application to be used for HID device.

boolean replyReport(BluetoothDevice device, byte type, byte id, byte[] data)

Sends report to remote host as reply for GET_REPORT request from BluetoothHidDevice.Callback.onGetReport(android.bluetooth.BluetoothDevice, byte, byte, int).

boolean reportError(BluetoothDevice device, byte error)

Sends error handshake message as reply for invalid SET_REPORT request from BluetoothHidDevice.Callback.onSetReport(android.bluetooth.BluetoothDevice, byte, byte, byte[]).

boolean sendReport(BluetoothDevice device, int id, byte[] data)

Sends report to remote host using interrupt channel.

boolean unregisterApp()

Unregisters application.

Inherited methods

Constants

ACTION_CONNECTION_STATE_CHANGED

Added in API level 28 
public static final String ACTION_CONNECTION_STATE_CHANGED

Intent used to broadcast the change in connection state of the Input Host profile.

This intent will have 3 extras:

BluetoothProfile.EXTRA_STATE or BluetoothProfile.EXTRA_PREVIOUS_STATE can be any of BluetoothProfile.STATE_DISCONNECTED, BluetoothProfile.STATE_CONNECTING, BluetoothProfile.STATE_CONNECTED, BluetoothProfile.STATE_DISCONNECTING.
For apps targeting Build.VERSION_CODES#R or lower, this requires the Manifest.permission#BLUETOOTH permission which can be gained with a simple <uses-permission> manifest tag.
For apps targeting Build.VERSION_CODES#S or or higher, this requires the Manifest.permission#BLUETOOTH_CONNECT permission which can be gained with Activity.requestPermissions(String[], int).
Requires Manifest.permission.BLUETOOTH_CONNECT

Constant Value: "android.bluetooth.hiddevice.profile.action.CONNECTION_STATE_CHANGED"

ERROR_RSP_INVALID_PARAM

Added in API level 28 
public static final byte ERROR_RSP_INVALID_PARAM

Constant representing error response for Set Report due to "invalid parameter".

Constant Value: 4 (0x00000004)

ERROR_RSP_INVALID_RPT_ID

Added in API level 28 
public static final byte ERROR_RSP_INVALID_RPT_ID

Constant representing error response for Set Report due to "invalid report ID".

Constant Value: 2 (0x00000002)

ERROR_RSP_NOT_READY

Added in API level 28 
public static final byte ERROR_RSP_NOT_READY

Constant representing error response for Set Report due to "not ready".

Constant Value: 1 (0x00000001)

ERROR_RSP_SUCCESS

Added in API level 28 
public static final byte ERROR_RSP_SUCCESS

Constant representing success response for Set Report.

Constant Value: 0 (0x00000000)

ERROR_RSP_UNKNOWN

Added in API level 28 
public static final byte ERROR_RSP_UNKNOWN

Constant representing error response for Set Report with unknown reason.

Constant Value: 14 (0x0000000e)

ERROR_RSP_UNSUPPORTED_REQ

Added in API level 28 
public static final byte ERROR_RSP_UNSUPPORTED_REQ

Constant representing error response for Set Report due to "unsupported request".

Constant Value: 3 (0x00000003)

PROTOCOL_BOOT_MODE

Added in API level 28 
public static final byte PROTOCOL_BOOT_MODE

Constant representing boot protocol mode used set by host. Default is always PROTOCOL_REPORT_MODE unless notified otherwise.

Constant Value: 0 (0x00000000)

PROTOCOL_REPORT_MODE

Added in API level 28 
public static final byte PROTOCOL_REPORT_MODE

Constant representing report protocol mode used set by host. Default is always PROTOCOL_REPORT_MODE unless notified otherwise.

Constant Value: 1 (0x00000001)

REPORT_TYPE_FEATURE

Added in API level 28 
public static final byte REPORT_TYPE_FEATURE

Constant representing HID Feature Report type.

Constant Value: 3 (0x00000003)

REPORT_TYPE_INPUT

Added in API level 28 
public static final byte REPORT_TYPE_INPUT

Constant representing HID Input Report type.

Constant Value: 1 (0x00000001)

REPORT_TYPE_OUTPUT

Added in API level 28 
public static final byte REPORT_TYPE_OUTPUT

Constant representing HID Output Report type.

Constant Value: 2 (0x00000002)

SUBCLASS1_COMBO

Added in API level 28 
public static final byte SUBCLASS1_COMBO

Constant representing combo keyboard and mouse subclass.

Constant Value: -64 (0xffffffc0)

SUBCLASS1_KEYBOARD

Added in API level 28 
public static final byte SUBCLASS1_KEYBOARD

Constant representing keyboard subclass.

Constant Value: 64 (0x00000040)

SUBCLASS1_MOUSE

Added in API level 28 
public static final byte SUBCLASS1_MOUSE

Constant representing mouse subclass.

Constant Value: -128 (0xffffff80)

SUBCLASS1_NONE

Added in API level 28 
public static final byte SUBCLASS1_NONE

Constant representing unspecified HID device subclass.

Constant Value: 0 (0x00000000)

SUBCLASS2_CARD_READER

Added in API level 28 
public static final byte SUBCLASS2_CARD_READER

Constant representing card reader subclass.

Constant Value: 6 (0x00000006)

SUBCLASS2_DIGITIZER_TABLET

Added in API level 28 
public static final byte SUBCLASS2_DIGITIZER_TABLET

Constant representing digitizer tablet subclass.

Constant Value: 5 (0x00000005)

SUBCLASS2_GAMEPAD

Added in API level 28 
public static final byte SUBCLASS2_GAMEPAD

Constant representing gamepad subclass.

Constant Value: 2 (0x00000002)

SUBCLASS2_JOYSTICK

Added in API level 28 
public static final byte SUBCLASS2_JOYSTICK

Constant representing joystick subclass.

Constant Value: 1 (0x00000001)

SUBCLASS2_REMOTE_CONTROL

Added in API level 28 
public static final byte SUBCLASS2_REMOTE_CONTROL

Constant representing remote control subclass.

Constant Value: 3 (0x00000003)

SUBCLASS2_SENSING_DEVICE

Added in API level 28 
public static final byte SUBCLASS2_SENSING_DEVICE

Constant representing sensing device subclass.

Constant Value: 4 (0x00000004)

SUBCLASS2_UNCATEGORIZED

Added in API level 28 
public static final byte SUBCLASS2_UNCATEGORIZED

Constant representing uncategorized HID device subclass.

Constant Value: 0 (0x00000000)

Public methods

connect

Added in API level 28 
public boolean connect (BluetoothDevice device)

Initiates connection to host which is currently paired with this device. If the application is not registered, #connect(BluetoothDevice) will fail. The connection state should be tracked by the application by handling callback from Callback#onConnectionStateChanged. The connection state is not related to the return value of this method.
For apps targeting Build.VERSION_CODES#S or or higher, this requires the Manifest.permission#BLUETOOTH_CONNECT permission which can be gained with Activity.requestPermissions(String[], int).
Requires Manifest.permission.BLUETOOTH_CONNECT

Parameters
device BluetoothDevice

Returns
boolean true if the command is successfully sent; otherwise false.

disconnect

Added in API level 28 
public boolean disconnect (BluetoothDevice device)

Disconnects from currently connected host. The connection state should be tracked by the application by handling callback from Callback#onConnectionStateChanged. The connection state is not related to the return value of this method.
For apps targeting Build.VERSION_CODES#S or or higher, this requires the Manifest.permission#BLUETOOTH_CONNECT permission which can be gained with Activity.requestPermissions(String[], int).
Requires Manifest.permission.BLUETOOTH_CONNECT

Parameters
device BluetoothDevice

Returns
boolean true if the command is successfully sent; otherwise false.

getConnectedDevices

Added in API level 28 
public List<BluetoothDevice> getConnectedDevices ()

Get connected devices for this specific profile.

Return the set of devices which are in state STATE_CONNECTED
For apps targeting Build.VERSION_CODES#S or or higher, this requires the Manifest.permission#BLUETOOTH_CONNECT permission which can be gained with Activity.requestPermissions(String[], int).
Requires Manifest.permission.BLUETOOTH_CONNECT

Returns
List<BluetoothDevice> List of devices. The list will be empty on error.

getConnectionState

Added in API level 28 
public int getConnectionState (BluetoothDevice device)

Get the current connection state of the profile
For apps targeting Build.VERSION_CODES#S or or higher, this requires the Manifest.permission#BLUETOOTH_CONNECT permission which can be gained with Activity.requestPermissions(String[], int).
Requires Manifest.permission.BLUETOOTH_CONNECT

Parameters
device BluetoothDevice: Remote bluetooth device.
Returns
int State of the profile connection. One of STATE_CONNECTED, STATE_CONNECTING, STATE_DISCONNECTED, STATE_DISCONNECTING Value is STATE_DISCONNECTED, STATE_CONNECTING, STATE_CONNECTED, or STATE_DISCONNECTING

getDevicesMatchingConnectionStates

Added in API level 28 
public List<BluetoothDevice> getDevicesMatchingConnectionStates (int[] states)

Get a list of devices that match any of the given connection states.

If none of the devices match any of the given states, an empty list will be returned.
For apps targeting Build.VERSION_CODES#S or or higher, this requires the Manifest.permission#BLUETOOTH_CONNECT permission which can be gained with Activity.requestPermissions(String[], int).
Requires Manifest.permission.BLUETOOTH_CONNECT

Parameters
states int: Array of states. States can be one of BluetoothProfile.STATE_CONNECTED, BluetoothProfile.STATE_CONNECTING, BluetoothProfile.STATE_DISCONNECTED, BluetoothProfile.STATE_DISCONNECTING,
Returns
List<BluetoothDevice> List of devices. The list will be empty on error.

registerApp

Added in API level 28 
public boolean registerApp (BluetoothHidDeviceAppSdpSettings sdp, 
                BluetoothHidDeviceAppQosSettings inQos, 
                BluetoothHidDeviceAppQosSettings outQos, 
                Executor executor, 
                BluetoothHidDevice.Callback callback)

Registers application to be used for HID device. Connections to HID Device are only possible when application is registered. Only one application can be registered at one time. When an application is registered, the HID Host service will be disabled until it is unregistered. When no longer used, application should be unregistered using unregisterApp(). The app will be automatically unregistered if it is not foreground. The registration status should be tracked by the application by handling callback from Callback#onAppStatusChanged. The app registration status is not related to the return value of this method.
For apps targeting Build.VERSION_CODES#S or or higher, this requires the Manifest.permission#BLUETOOTH_CONNECT permission which can be gained with Activity.requestPermissions(String[], int).
Requires Manifest.permission.BLUETOOTH_CONNECT

Parameters
sdp BluetoothHidDeviceAppSdpSettings: BluetoothHidDeviceAppSdpSettings object of HID Device SDP record. The HID Device SDP record is required.
inQos BluetoothHidDeviceAppQosSettings: BluetoothHidDeviceAppQosSettings object of Incoming QoS Settings. The Incoming QoS Settings is not required. Use null or default BluetoothHidDeviceAppQosSettings.Builder for default values.
outQos BluetoothHidDeviceAppQosSettings: BluetoothHidDeviceAppQosSettings object of Outgoing QoS Settings. The Outgoing QoS Settings is not required. Use null or default BluetoothHidDeviceAppQosSettings.Builder for default values.
executor Executor: Executor object on which callback will be executed. The Executor object is required.
callback BluetoothHidDevice.Callback: Callback object to which callback messages will be sent. The Callback object is required.
Returns
boolean true if the command is successfully sent; otherwise false.

replyReport

Added in API level 28 
public boolean replyReport (BluetoothDevice device, 
                byte type, 
                byte id, 
                byte[] data)

Sends report to remote host as reply for GET_REPORT request from BluetoothHidDevice.Callback.onGetReport(android.bluetooth.BluetoothDevice, byte, byte, int).
For apps targeting Build.VERSION_CODES#S or or higher, this requires the Manifest.permission#BLUETOOTH_CONNECT permission which can be gained with Activity.requestPermissions(String[], int).
Requires Manifest.permission.BLUETOOTH_CONNECT

Parameters
device BluetoothDevice

type byte: Report Type, as in request.
id byte: Report Id, as in request.
data byte: Report data, not including Report Id.
Returns
boolean true if the command is successfully sent; otherwise false.

reportError

Added in API level 28 
public boolean reportError (BluetoothDevice device, 
                byte error)

Sends error handshake message as reply for invalid SET_REPORT request from BluetoothHidDevice.Callback.onSetReport(android.bluetooth.BluetoothDevice, byte, byte, byte[]).
For apps targeting Build.VERSION_CODES#S or or higher, this requires the Manifest.permission#BLUETOOTH_CONNECT permission which can be gained with Activity.requestPermissions(String[], int).
Requires Manifest.permission.BLUETOOTH_CONNECT

Parameters
device BluetoothDevice

error byte: Error to be sent for SET_REPORT via HANDSHAKE.
Returns
boolean true if the command is successfully sent; otherwise false.

sendReport

Added in API level 28 
public boolean sendReport (BluetoothDevice device, 
                int id, 
                byte[] data)

Sends report to remote host using interrupt channel.
For apps targeting Build.VERSION_CODES#S or or higher, this requires the Manifest.permission#BLUETOOTH_CONNECT permission which can be gained with Activity.requestPermissions(String[], int).
Requires Manifest.permission.BLUETOOTH_CONNECT

Parameters
device BluetoothDevice

id int: Report Id, as defined in descriptor. Can be 0 in case Report Id are not defined in descriptor.
data byte: Report data, not including Report Id.
Returns
boolean true if the command is successfully sent; otherwise false.

unregisterApp

Added in API level 28 
public boolean unregisterApp ()

Unregisters application. Active connection will be disconnected and no new connections will be allowed until registered again using (android.bluetooth.BluetoothHidDeviceAppQosSettings,android.bluetooth.BluetoothHidDeviceAppQosSettings,android.bluetooth.BluetoothHidDeviceAppQosSettings,java.util.concurrent.Executor,android.bluetooth.BluetoothHidDevice.Callback). The registration status should be tracked by the application by handling callback from Callback#onAppStatusChanged. The app registration status is not related to the return value of this method.
For apps targeting Build.VERSION_CODES#S or or higher, this requires the Manifest.permission#BLUETOOTH_CONNECT permission which can be gained with Activity.requestPermissions(String[], int).
Requires Manifest.permission.BLUETOOTH_CONNECT

Returns
boolean true if the command is successfully sent; otherwise false.