Home Original page

BluetoothGattServer  |  API reference  |  Android Developers

public final class BluetoothGattServer
extends Object implements BluetoothProfile


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

Advanced Audio Distribution Profile (A2DP)

int CSIP_SET_COORDINATOR

Coordinated Set Identification Profile (CSIP) set coordinator

String EXTRA_PREVIOUS_STATE

Extra for the connection state intents of the individual profiles.

String EXTRA_PROFILE

Extra for the BluetoothProfile that the intent applies to.

String EXTRA_STATE

Extra for the connection state intents of the individual profiles.

int GATT

Generic Attribute Profile (GATT)

int GATT_SERVER

Generic Attribute Profile (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

Human Interface Device (HID) Device

int LE_AUDIO

LE Audio Device

int SAP

SIM Access Profile (SAP)

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

connect

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 android.app.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

getService

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.

notifyCharacteristicChanged

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 android.app.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 one of the following:
Throws
IllegalArgumentException if the device, characteristic, value, or the characteristic's service is null, or if the value length exceeds the maximum attribute length of 512 bytes (As defined in GATT max attribute length (Bluetooth Core Specification 6.1 Volume 3, Part F, section 3.2.9).

notifyCharacteristicChanged

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 android.app.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