Added in API level 18

Summary: Inherited Constants | Methods | Inherited Methods

BluetoothGattServer

---

Kotlin |Java

public final class BluetoothGattServer
extends Object implements BluetoothProfile

java.lang.Object
↳	android.bluetooth.BluetoothGattServer

---

Public API for the Bluetooth GATT Profile server role.

This class provides Bluetooth GATT server role functionality, allowing applications to create Bluetooth Smart services and characteristics.

BluetoothGattServer is a proxy object for controlling the Bluetooth Service via IPC. Use BluetoothManager.openGattServer to get an instance of this class.

Summary

Inherited constants

From interface android.bluetooth.BluetoothProfile int A2DP A2DP profile. int CSIP_SET_COORDINATOR Coordinated Set Identification Profile set coordinator String EXTRA_PREVIOUS_STATE Extra for the connection state intents of the individual profiles. String EXTRA_STATE Extra for the connection state intents of the individual profiles. int GATT GATT int GATT_SERVER GATT_SERVER int HAP_CLIENT int HEADSET Headset and Handsfree profile int HEALTH This constant was deprecated in API level 29. Health Device Profile (HDP) and MCAP protocol are no longer used. New apps should use Bluetooth Low Energy based solutions such as BluetoothGatt, BluetoothAdapter.listenUsingL2capChannel(), or BluetoothDevice.createL2capChannel(int) int HEARING_AID Hearing Aid Device int HID_DEVICE HID Device int LE_AUDIO LE Audio Device int SAP SAP Profile int STATE_CONNECTED The profile is in connected state int STATE_CONNECTING The profile is in connecting state int STATE_DISCONNECTED The profile is in disconnected state int STATE_DISCONNECTING The profile is in disconnecting state

Public methods
boolean	addService(BluetoothGattService service) Add a service to the list of services to be hosted.
void	cancelConnection(BluetoothDevice device) Disconnects an established connection, or cancels a connection attempt currently in progress.
void	clearServices() Remove all services from the list of provided services.
void	close() Close this GATT server instance.
boolean	connect(BluetoothDevice device, boolean autoConnect) Initiate a connection to a Bluetooth GATT capable device.
List<BluetoothDevice>	getConnectedDevices() Not supported - please use BluetoothManager.getConnectedDevices(int) with BluetoothProfile.GATT as argument
int	getConnectionState(BluetoothDevice device) Not supported - please use BluetoothManager.getConnectedDevices(int) with BluetoothProfile.GATT as argument
List<BluetoothDevice>	getDevicesMatchingConnectionStates(int[] states) Not supported - please use BluetoothManager.getDevicesMatchingConnectionStates(int, int[]) with BluetoothProfile.GATT as first argument
BluetoothGattService	getService(UUID uuid) Returns a BluetoothGattService from the list of services offered by this device.
List<BluetoothGattService>	getServices() Returns a list of GATT services offered by this device.
int	notifyCharacteristicChanged(BluetoothDevice device, BluetoothGattCharacteristic characteristic, boolean confirm, byte[] value) Send a notification or indication that a local characteristic has been updated.
boolean	notifyCharacteristicChanged(BluetoothDevice device, BluetoothGattCharacteristic characteristic, boolean confirm) This method was deprecated in API level 33. Use BluetoothGattServer.notifyCharacteristicChanged(BluetoothDevice, BluetoothGattCharacteristic, boolean, byte[]) as this is not memory safe.
void	readPhy(BluetoothDevice device) Read the current transmitter PHY and receiver PHY of the connection.
boolean	removeService(BluetoothGattService service) Removes a service from the list of services to be provided.
boolean	sendResponse(BluetoothDevice device, int requestId, int status, int offset, byte[] value) Send a response to a read or write request to a remote device.
void	setPreferredPhy(BluetoothDevice device, int txPhy, int rxPhy, int phyOptions) Set the preferred connection PHY for this app.

Inherited methods
From class java.lang.Object Object clone() Creates and returns a copy of this object. boolean equals(Object obj) Indicates whether some other object is "equal to" this one. void finalize() Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. final Class<?> getClass() Returns the runtime class of this Object. int hashCode() Returns a hash code value for the object. final void notify() Wakes up a single thread that is waiting on this object's monitor. final void notifyAll() Wakes up all threads that are waiting on this object's monitor. String toString() Returns a string representation of the object. final void wait(long timeoutMillis, int nanos) Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed. final void wait(long timeoutMillis) Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed. final void wait() Causes the current thread to wait until it is awakened, typically by being notified or interrupted.
From interface android.bluetooth.BluetoothProfile abstract List<BluetoothDevice> getConnectedDevices() Get connected devices for this specific profile. abstract int getConnectionState(BluetoothDevice device) Get the current connection state of the profile abstract List<BluetoothDevice> getDevicesMatchingConnectionStates(int[] states) Get a list of devices that match any of the given connection states.

Public methods

addService

Added in API level 18

public boolean addService (BluetoothGattService service)

Add a service to the list of services to be hosted.

Once a service has been added to the list, the service and its included characteristics will be provided by the local device.

If the local device has already exposed services when this function is called, a service update notification will be sent to all clients.

The BluetoothGattServerCallback.onServiceAdded callback will indicate whether this service has been added successfully. Do not add another service before this callback.
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

Parameters
service	BluetoothGattService: Service to be added to the list of services provided by this device.

Returns
boolean	true, if the request to add service has been initiated

cancelConnection

Added in API level 18

public void cancelConnection (BluetoothDevice device)

Disconnects an established connection, or cancels a connection attempt currently in progress.
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

Parameters
device	BluetoothDevice: Remote device

clearServices

Added in API level 18

public void clearServices ()

Remove all services from the list of provided services.
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

close

Added in API level 18

public void close ()

Close this GATT server instance.

Application should call this method as early as possible after it is done with this GATT server.
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

connect

Added in API level 18

public boolean connect (BluetoothDevice device, 
                boolean autoConnect)

Initiate a connection to a Bluetooth GATT capable device.

The connection may not be established right away, but will be completed when the remote device is available. A BluetoothGattServerCallback.onConnectionStateChange callback will be invoked when the connection state changes as a result of this function.

The autoConnect parameter determines whether to actively connect to the remote device, or rather passively scan and finalize the connection when the remote device is in range/available. Generally, the first ever connection to a device should be direct (autoConnect set to false) and subsequent connections to known devices should be invoked with the autoConnect parameter set to true.
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

Parameters
device	BluetoothDevice
autoConnect	boolean: Whether to directly connect to the remote device (false) or to automatically connect as soon as the remote device becomes available (true).

Returns
boolean	true, if the connection attempt was initiated successfully

getConnectedDevices

Added in API level 18

public List<BluetoothDevice> getConnectedDevices ()

Not supported - please use BluetoothManager.getConnectedDevices(int) with BluetoothProfile.GATT as argument

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

Throws
UnsupportedOperationException	on every call

getConnectionState

Added in API level 18

public int getConnectionState (BluetoothDevice device)

Not supported - please use BluetoothManager.getConnectedDevices(int) with BluetoothProfile.GATT as argument

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

Throws
UnsupportedOperationException	on every call

getDevicesMatchingConnectionStates

Added in API level 18

public List<BluetoothDevice> getDevicesMatchingConnectionStates (int[] states)

Not supported - please use BluetoothManager.getDevicesMatchingConnectionStates(int, int[]) with BluetoothProfile.GATT as first argument

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.

Throws
UnsupportedOperationException	on every call

getService

Added in API level 18

public BluetoothGattService getService (UUID uuid)

Returns a BluetoothGattService from the list of services offered by this device.

If multiple instances of the same service (as identified by UUID) exist, the first instance of the service is returned.
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.

Parameters
uuid	UUID: UUID of the requested service

Returns
BluetoothGattService	BluetoothGattService if supported, or null if the requested service is not offered by this device.

getServices

Added in API level 18

public List<BluetoothGattService> getServices ()

Returns a list of GATT services offered by this device.

An application must call addService(BluetoothGattService) to add a service to the list of services offered by this device.
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.

Returns
List<BluetoothGattService>	List of services. Returns an empty list if no services have been added yet.

notifyCharacteristicChanged

Added in API level 33

public int notifyCharacteristicChanged (BluetoothDevice device, 
                BluetoothGattCharacteristic characteristic, 
                boolean confirm, 
                byte[] value)

Send a notification or indication that a local characteristic has been updated.

A notification or indication is sent to the remote device to signal that the characteristic has been updated. This function should be invoked for every client that requests notifications/indications by writing to the "Client Configuration" descriptor for the given characteristic.
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

Parameters
device	BluetoothDevice: the remote device to receive the notification/indication This value cannot be null.
characteristic	BluetoothGattCharacteristic: the local characteristic that has been updated This value cannot be null.
confirm	boolean: true to request confirmation from the client (indication) or false to send a notification
value	byte: the characteristic value This value cannot be null.

Returns
int	whether the notification has been triggered successfully Value is BluetoothStatusCodes.SUCCESS, BluetoothStatusCodes.ERROR_MISSING_BLUETOOTH_CONNECT_PERMISSION, android.bluetooth.BluetoothStatusCodes.ERROR_DEVICE_NOT_CONNECTED, BluetoothStatusCodes.ERROR_PROFILE_SERVICE_NOT_BOUND, or BluetoothStatusCodes.ERROR_UNKNOWN

Throws
IllegalArgumentException	if the characteristic value or service is null

notifyCharacteristicChanged

Added in API level 18
Deprecated in API level 33

public boolean notifyCharacteristicChanged (BluetoothDevice device, 
                BluetoothGattCharacteristic characteristic, 
                boolean confirm)

This method was deprecated in API level 33.
Use BluetoothGattServer.notifyCharacteristicChanged(BluetoothDevice, BluetoothGattCharacteristic, boolean, byte[]) as this is not memory safe.

Send a notification or indication that a local characteristic has been updated.

A notification or indication is sent to the remote device to signal that the characteristic has been updated. This function should be invoked for every client that requests notifications/indications by writing to the "Client Configuration" descriptor for the given characteristic.
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

Parameters
device	BluetoothDevice: The remote device to receive the notification/indication
characteristic	BluetoothGattCharacteristic: The local characteristic that has been updated
confirm	boolean: true to request confirmation from the client (indication), false to send a notification

Returns
boolean	true, if the notification has been triggered successfully

Throws
IllegalArgumentException	if the characteristic value or service is null

readPhy

Added in API level 26

public void readPhy (BluetoothDevice device)

Read the current transmitter PHY and receiver PHY of the connection. The values are returned in BluetoothGattServerCallback.onPhyRead
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: The remote device to send this response to

removeService

Added in API level 18

public boolean removeService (BluetoothGattService service)

Removes a service from the list of services to be provided.
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

Parameters
service	BluetoothGattService: Service to be removed.

Returns
boolean	true, if the service has been removed

sendResponse

Added in API level 18

public boolean sendResponse (BluetoothDevice device, 
                int requestId, 
                int status, 
                int offset, 
                byte[] value)

Send a response to a read or write request to a remote device.

This function must be invoked in when a remote read/write request is received by one of these callback methods:

• BluetoothGattServerCallback.onCharacteristicReadRequest
• BluetoothGattServerCallback.onCharacteristicWriteRequest
• BluetoothGattServerCallback.onDescriptorReadRequest
• BluetoothGattServerCallback.onDescriptorWriteRequest

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

Parameters
device	BluetoothDevice: The remote device to send this response to
requestId	int: The ID of the request that was received with the callback
status	int: The status of the request to be sent to the remote devices
offset	int: Value offset for partial read/write response
value	byte: The value of the attribute that was read/written (optional)

Returns
boolean

setPreferredPhy

Added in API level 26

public void setPreferredPhy (BluetoothDevice device, 
                int txPhy, 
                int rxPhy, 
                int phyOptions)

Set the preferred connection PHY for this app. Please note that this is just a recommendation, whether the PHY change will happen depends on other applications preferences, local and remote controller capabilities. Controller can override these settings.

BluetoothGattServerCallback.onPhyUpdate will be triggered as a result of this call, even if no PHY change happens. It is also triggered when remote device updates the PHY.
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: The remote device to send this response to
txPhy	int: preferred transmitter PHY. Bitwise OR of any of BluetoothDevice.PHY_LE_1M_MASK, BluetoothDevice.PHY_LE_2M_MASK, and BluetoothDevice.PHY_LE_CODED_MASK.
rxPhy	int: preferred receiver PHY. Bitwise OR of any of BluetoothDevice.PHY_LE_1M_MASK, BluetoothDevice.PHY_LE_2M_MASK, and BluetoothDevice.PHY_LE_CODED_MASK.
phyOptions	int: preferred coding to use when transmitting on the LE Coded PHY. Can be one of BluetoothDevice.PHY_OPTION_NO_PREFERRED, BluetoothDevice.PHY_OPTION_S2 or BluetoothDevice.PHY_OPTION_S8