Save the date! Android Dev Summit is coming to Mountain View, CA on November 7-8, 2018.

BluetoothGattServer

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(Context, BluetoothGattServerCallback) to get an instance of this class.

Summary

Inherited constants

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.

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

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

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

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 addded to the 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(int, BluetoothGattService) callback will indicate whether this service has been added successfully. Do not add another service before this callback.

Requires Manifest.permission.BLUETOOTH permission.

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.

Requires Manifest.permission.BLUETOOTH permission.

Parameters
device BluetoothDevice: Remote device

clearServices

added in API level 18
public void clearServices ()

Remove all services from the list of provided services.

Requires Manifest.permission.BLUETOOTH permission.

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.

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(BluetoothDevice, int, int) callback will be invoked when the connection state changes as a result of this function.

The autoConnect paramter 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.

Requires Manifest.permission.BLUETOOTH permission.

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

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

Throws
UnsupportedOperationException

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

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.

Requires Manifest.permission.BLUETOOTH permission.

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 serice to the list of services offered by this device.

Requires Manifest.permission.BLUETOOTH permission.

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

notifyCharacteristicChanged

added in API level 18
public boolean notifyCharacteristicChanged (BluetoothDevice device, 
                BluetoothGattCharacteristic characteristic, 
                boolean confirm)

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.

Requires Manifest.permission.BLUETOOTH permission.

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

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(BluetoothDevice, int, int, int)

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.

Requires Manifest.permission.BLUETOOTH permission.

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:

Requires Manifest.permission.BLUETOOTH permission.

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 peferences, local and remote controller capabilities. Controller can override these settings.

BluetoothGattServerCallback.onPhyUpdate(BluetoothDevice, int, int, int) 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.

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