Android APIs
public final class

BluetoothGattServer

extends Object
implements BluetoothProfile
java.lang.Object
   ↳ android.bluetooth.BluetoothGattServer

Class Overview

Public API for the Bluetooth GATT Profile server role.

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

BluetoothGattServer is a proxy object for controlling the Bluetooth Service via IPC. Use getProfileProxy(Context, BluetoothProfile.ServiceListener, int) to get the BluetoothGatt proxy object.

Summary

[Expand]
Inherited Constants
From interface android.bluetooth.BluetoothProfile
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 getConnectedDevices(int) with GATT as argument
int getConnectionState(BluetoothDevice device)
Not supported - please use getConnectedDevices(int) with GATT as argument
List<BluetoothDevice> getDevicesMatchingConnectionStates(int[] states)
Not supported - please use getDevicesMatchingConnectionStates(int, int[]) with 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.
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.
[Expand]
Inherited Methods
From class java.lang.Object
From interface android.bluetooth.BluetoothProfile

Public Methods

public boolean addService (BluetoothGattService service)

Added in API level 18

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

Once a service has been addded to the the list, the service and it's 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.

Requires BLUETOOTH permission.

Parameters
service Service to be added to the list of services provided by this device.
Returns
  • true, if the service has been added successfully

public void cancelConnection (BluetoothDevice device)

Added in API level 18

Disconnects an established connection, or cancels a connection attempt currently in progress.

Requires BLUETOOTH permission.

Parameters
device Remote device

public void clearServices ()

Added in API level 18

Remove all services from the list of provided services.

Requires BLUETOOTH permission.

public void close ()

Added in API level 18

Close this GATT server instance. Application should call this method as early as possible after it is done with this GATT server.

public boolean connect (BluetoothDevice device, boolean autoConnect)

Added in API level 18

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 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 BLUETOOTH permission.

Parameters
autoConnect Whether to directly connect to the remote device (false) or to automatically connect as soon as the remote device becomes available (true).
Returns
  • true, if the connection attempt was initiated successfully

public List<BluetoothDevice> getConnectedDevices ()

Added in API level 18

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

Returns
  • List of devices. The list will be empty on error.
Throws
UnsupportedOperationException

public int getConnectionState (BluetoothDevice device)

Added in API level 18

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

Parameters
device Remote bluetooth device.
Returns
Throws
UnsupportedOperationException

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

Added in API level 18

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

Parameters
states Array of states. States can be one of STATE_CONNECTED, STATE_CONNECTING, STATE_DISCONNECTED, STATE_DISCONNECTING,
Returns
  • List of devices. The list will be empty on error.
Throws
UnsupportedOperationException

public BluetoothGattService getService (UUID uuid)

Added in API level 18

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 BLUETOOTH permission.

Parameters
uuid UUID of the requested service
Returns
  • BluetoothGattService if supported, or null if the requested service is not offered by this device.

public List<BluetoothGattService> getServices ()

Added in API level 18

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 BLUETOOTH permission.

Returns
  • List of services. Returns an empty list if no services have been added yet.

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

Added in API level 18

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 BLUETOOTH permission.

Parameters
device The remote device to receive the notification/indication
characteristic The local characteristic that has been updated
confirm true to request confirmation from the client (indication), false to send a notification
Returns
  • true, if the notification has been triggered successfully

public boolean removeService (BluetoothGattService service)

Added in API level 18

Removes a service from the list of services to be provided.

Requires BLUETOOTH permission.

Parameters
service Service to be removed.
Returns
  • true, if the service has been removed

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

Added in API level 18

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 BLUETOOTH permission.

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