FileDocCategorySizeDatePackage
BluetoothGattServer.javaAPI DocAndroid 5.1 API28824Thu Mar 12 22:22:10 GMT 2015android.bluetooth

BluetoothGattServer

public final class BluetoothGattServer extends Object implements android.bluetooth.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 {@link BluetoothManager#openGattServer} to get an instance of this class.

Fields Summary
private static final String
TAG
private static final boolean
DBG
private static final boolean
VDBG
private final android.content.Context
mContext
private android.bluetooth.BluetoothAdapter
mAdapter
private IBluetoothGatt
mService
private BluetoothGattServerCallback
mCallback
private Object
mServerIfLock
private int
mServerIf
private int
mTransport
private List
mServices
private static final int
CALLBACK_REG_TIMEOUT
private final IBluetoothGattServerCallback
mBluetoothGattServerCallback
Bluetooth GATT interface callbacks
Constructors Summary
BluetoothGattServer(android.content.Context context, IBluetoothGatt iGatt, int transport)
Create a BluetoothGattServer proxy object.


              
    /*package*/       
        mContext = context;
        mService = iGatt;
        mAdapter = BluetoothAdapter.getDefaultAdapter();
        mCallback = null;
        mServerIf = 0;
        mTransport = transport;
        mServices = new ArrayList<BluetoothGattService>();
Methods Summary
public booleanaddService(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.

Requires {@link android.Manifest.permission#BLUETOOTH} permission.

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

        if (DBG) Log.d(TAG, "addService() - service: " + service.getUuid());
        if (mService == null || mServerIf == 0) return false;

        mServices.add(service);

        try {
            mService.beginServiceDeclaration(mServerIf, service.getType(),
                service.getInstanceId(), service.getHandles(),
                new ParcelUuid(service.getUuid()), service.isAdvertisePreferred());

            List<BluetoothGattService> includedServices = service.getIncludedServices();
            for (BluetoothGattService includedService : includedServices) {
                mService.addIncludedService(mServerIf,
                    includedService.getType(),
                    includedService.getInstanceId(),
                    new ParcelUuid(includedService.getUuid()));
            }

            List<BluetoothGattCharacteristic> characteristics = service.getCharacteristics();
            for (BluetoothGattCharacteristic characteristic : characteristics) {
                int permission = ((characteristic.getKeySize() - 7) << 12)
                                    + characteristic.getPermissions();
                mService.addCharacteristic(mServerIf,
                    new ParcelUuid(characteristic.getUuid()),
                    characteristic.getProperties(), permission);

                List<BluetoothGattDescriptor> descriptors = characteristic.getDescriptors();
                for (BluetoothGattDescriptor descriptor: descriptors) {
                    permission = ((characteristic.getKeySize() - 7) << 12)
                                        + descriptor.getPermissions();
                    mService.addDescriptor(mServerIf,
                        new ParcelUuid(descriptor.getUuid()), permission);
                }
            }

            mService.endServiceDeclaration(mServerIf);
        } catch (RemoteException e) {
            Log.e(TAG,"",e);
            return false;
        }

        return true;
public voidcancelConnection(android.bluetooth.BluetoothDevice device)
Disconnects an established connection, or cancels a connection attempt currently in progress.

Requires {@link android.Manifest.permission#BLUETOOTH} permission.

param
device Remote device

        if (DBG) Log.d(TAG, "cancelConnection() - device: " + device.getAddress());
        if (mService == null || mServerIf == 0) return;

        try {
            mService.serverDisconnect(mServerIf, device.getAddress());
        } catch (RemoteException e) {
            Log.e(TAG,"",e);
        }
public voidclearServices()
Remove all services from the list of provided services.

Requires {@link android.Manifest.permission#BLUETOOTH} permission.

        if (DBG) Log.d(TAG, "clearServices()");
        if (mService == null || mServerIf == 0) return;

        try {
            mService.clearServices(mServerIf);
            mServices.clear();
        } catch (RemoteException e) {
            Log.e(TAG,"",e);
        }
public voidclose()
Close this GATT server instance. Application should call this method as early as possible after it is done with this GATT server.

        if (DBG) Log.d(TAG, "close()");
        unregisterCallback();
public booleanconnect(android.bluetooth.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 {@link BluetoothGattServerCallback#onConnectionStateChange} 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 {@link android.Manifest.permission#BLUETOOTH} permission.

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

        if (DBG) Log.d(TAG, "connect() - device: " + device.getAddress() + ", auto: " + autoConnect);
        if (mService == null || mServerIf == 0) return false;

        try {
            mService.serverConnect(mServerIf, device.getAddress(),
                               autoConnect ? false : true,mTransport); // autoConnect is inverse of "isDirect"
        } catch (RemoteException e) {
            Log.e(TAG,"",e);
            return false;
        }

        return true;
public java.util.ListgetConnectedDevices()
Not supported - please use {@link BluetoothManager#getConnectedDevices(int)} with {@link BluetoothProfile#GATT} as argument

throws
UnsupportedOperationException

        throw new UnsupportedOperationException
            ("Use BluetoothManager#getConnectedDevices instead.");
public intgetConnectionState(android.bluetooth.BluetoothDevice device)
Not supported - please use {@link BluetoothManager#getConnectedDevices(int)} with {@link BluetoothProfile#GATT} as argument

throws
UnsupportedOperationException

        throw new UnsupportedOperationException("Use BluetoothManager#getConnectionState instead.");
public java.util.ListgetDevicesMatchingConnectionStates(int[] states)
Not supported - please use {@link BluetoothManager#getDevicesMatchingConnectionStates(int, int[])} with {@link BluetoothProfile#GATT} as first argument

throws
UnsupportedOperationException

        throw new UnsupportedOperationException
            ("Use BluetoothManager#getDevicesMatchingConnectionStates instead.");
public BluetoothGattServicegetService(java.util.UUID uuid)
Returns a {@link 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 {@link android.Manifest.permission#BLUETOOTH} permission.

param
uuid UUID of the requested service
return
BluetoothGattService if supported, or null if the requested service is not offered by this device.

        for (BluetoothGattService service : mServices) {
            if (service.getUuid().equals(uuid)) {
                return service;
            }
        }

        return null;
BluetoothGattServicegetService(java.util.UUID uuid, int instanceId, int type)
Returns a service by UUID, instance and type.

hide

        for(BluetoothGattService svc : mServices) {
            if (svc.getType() == type &&
                svc.getInstanceId() == instanceId &&
                svc.getUuid().equals(uuid)) {
                return svc;
            }
        }
        return null;
public java.util.ListgetServices()
Returns a list of GATT services offered by this device.

An application must call {@link #addService} to add a serice to the list of services offered by this device.

Requires {@link android.Manifest.permission#BLUETOOTH} permission.

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

        return mServices;
public booleannotifyCharacteristicChanged(android.bluetooth.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 {@link android.Manifest.permission#BLUETOOTH} permission.

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

        if (VDBG) Log.d(TAG, "notifyCharacteristicChanged() - device: " + device.getAddress());
        if (mService == null || mServerIf == 0) return false;

        BluetoothGattService service = characteristic.getService();
        if (service == null) return false;

        if (characteristic.getValue() == null) {
            throw new IllegalArgumentException("Chracteristic value is empty. Use "
                    + "BluetoothGattCharacteristic#setvalue to update");
        }

        try {
            mService.sendNotification(mServerIf, device.getAddress(),
                    service.getType(), service.getInstanceId(),
                    new ParcelUuid(service.getUuid()), characteristic.getInstanceId(),
                    new ParcelUuid(characteristic.getUuid()), confirm,
                    characteristic.getValue());
        } catch (RemoteException e) {
            Log.e(TAG,"",e);
            return false;
        }

        return true;
booleanregisterCallback(BluetoothGattServerCallback callback)
Register an application callback to start using GattServer.

This is an asynchronous call. The callback is used to notify success or failure if the function returns true.

Requires {@link android.Manifest.permission#BLUETOOTH} permission.

param
callback GATT callback handler that will receive asynchronous callbacks.
return
true, the callback will be called to notify success or failure, false on immediate error

        if (DBG) Log.d(TAG, "registerCallback()");
        if (mService == null) {
            Log.e(TAG, "GATT service not available");
            return false;
        }
        UUID uuid = UUID.randomUUID();
        if (DBG) Log.d(TAG, "registerCallback() - UUID=" + uuid);

        synchronized(mServerIfLock) {
            if (mCallback != null) {
                Log.e(TAG, "App can register callback only once");
                return false;
            }

            mCallback = callback;
            try {
                mService.registerServer(new ParcelUuid(uuid), mBluetoothGattServerCallback);
            } catch (RemoteException e) {
                Log.e(TAG,"",e);
                mCallback = null;
                return false;
            }

            try {
                mServerIfLock.wait(CALLBACK_REG_TIMEOUT);
            } catch (InterruptedException e) {
                Log.e(TAG, "" + e);
                mCallback = null;
            }

            if (mServerIf == 0) {
                mCallback = null;
                return false;
            } else {
                return true;
            }
        }
public booleanremoveService(BluetoothGattService service)
Removes a service from the list of services to be provided.

Requires {@link android.Manifest.permission#BLUETOOTH} permission.

param
service Service to be removed.
return
true, if the service has been removed

        if (DBG) Log.d(TAG, "removeService() - service: " + service.getUuid());
        if (mService == null || mServerIf == 0) return false;

        BluetoothGattService intService = getService(service.getUuid(),
                                service.getInstanceId(), service.getType());
        if (intService == null) return false;

        try {
            mService.removeService(mServerIf, service.getType(),
                service.getInstanceId(), new ParcelUuid(service.getUuid()));
            mServices.remove(intService);
        } catch (RemoteException e) {
            Log.e(TAG,"",e);
            return false;
        }

        return true;
public booleansendResponse(android.bluetooth.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:

  • {@link BluetoothGattServerCallback#onCharacteristicReadRequest}
  • {@link BluetoothGattServerCallback#onCharacteristicWriteRequest}
  • {@link BluetoothGattServerCallback#onDescriptorReadRequest}
  • {@link BluetoothGattServerCallback#onDescriptorWriteRequest}

Requires {@link android.Manifest.permission#BLUETOOTH} permission.

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

        if (VDBG) Log.d(TAG, "sendResponse() - device: " + device.getAddress());
        if (mService == null || mServerIf == 0) return false;

        try {
            mService.sendResponse(mServerIf, device.getAddress(), requestId,
                                  status, offset, value);
        } catch (RemoteException e) {
            Log.e(TAG,"",e);
            return false;
        }
        return true;
private voidunregisterCallback()
Unregister the current application and callbacks.

        if (DBG) Log.d(TAG, "unregisterCallback() - mServerIf=" + mServerIf);
        if (mService == null || mServerIf == 0) return;

        try {
            mCallback = null;
            mService.unregisterServer(mServerIf);
            mServerIf = 0;
        } catch (RemoteException e) {
            Log.e(TAG,"",e);
        }