no.nordicsemi.android.ble

Class BleServerManager

java.lang.Object

no.nordicsemi.android.ble.BleServerManager

All Implemented Interfaces:

ILogger

public abstract class BleServerManager
extends java.lang.Object
implements ILogger

The manager for local GATT server. To be used with one or more instances of BleManager

Since:

2.2

Constructor Summary

Constructors

Constructor and Description
BleServerManager(android.content.Context context)

Method Summary

Modifier and Type	Method and Description
protected android.bluetooth.BluetoothGattDescriptor	cccd() This helper method returns a new instance of Client Characteristic Configuration Descriptor (CCCD) that can be added to a server characteristic in initializeServer().
protected android.bluetooth.BluetoothGattCharacteristic	characteristic(java.util.UUID uuid, int properties, int permissions, android.bluetooth.BluetoothGattDescriptor... descriptors) A helper method that creates a characteristic with given UUID, properties and permissions.
protected android.bluetooth.BluetoothGattCharacteristic	characteristic(java.util.UUID uuid, int properties, int permissions, byte[] initialValue, android.bluetooth.BluetoothGattDescriptor... descriptors) A helper method that creates a characteristic with given UUID, properties and permissions.
protected android.bluetooth.BluetoothGattCharacteristic	characteristic(java.util.UUID uuid, int properties, int permissions, Data initialValue, android.bluetooth.BluetoothGattDescriptor... descriptors) A helper method that creates a characteristic with given UUID, properties and permissions.
void	close() Closes the GATT server.
protected android.bluetooth.BluetoothGattDescriptor	description(java.lang.String description, boolean writableAuxiliaries) This helper method returns a new instance of Client User Description Descriptor that can be added to a server characteristic in initializeServer().
protected android.bluetooth.BluetoothGattDescriptor	descriptor(java.util.UUID uuid, int permissions, byte[] initialValue) A helper method that creates a descriptor with given UUID and permissions.
protected android.bluetooth.BluetoothGattDescriptor	descriptor(java.util.UUID uuid, int permissions, Data initialValue) A helper method that creates a descriptor with given UUID and permissions.
protected abstract java.util.List<android.bluetooth.BluetoothGattService>	initializeServer() This method is called once, just after instantiating the BleServerManager.
void	log(int priority, int messageRes, java.lang.Object... params) Logs the given message with given log priority into the all managed devices' log session.
void	log(int priority, java.lang.String message) Logs the given message with given log priority into the all managed devices' log session.
boolean	open() Opens the GATT server and starts initializing services.
protected android.bluetooth.BluetoothGattDescriptor	reliableWrite() This helper method returns a new instance of Characteristic Extended Properties descriptor that can be added to a server characteristic.
protected android.bluetooth.BluetoothGattService	service(java.util.UUID uuid, android.bluetooth.BluetoothGattCharacteristic... characteristics) A helper method for creating a primary service with given UUID and list of characteristics.
void	setServerObserver(ServerObserver observer) Sets the server observer.
protected android.bluetooth.BluetoothGattDescriptor	sharedCccd() This helper method returns a new instance of Client Characteristic Configuration Descriptor (CCCD) that can be added to a server characteristic in initializeServer().
protected android.bluetooth.BluetoothGattCharacteristic	sharedCharacteristic(java.util.UUID uuid, int properties, int permissions, android.bluetooth.BluetoothGattDescriptor... descriptors) A helper method that creates a characteristic with given UUID, properties and permissions.
protected android.bluetooth.BluetoothGattCharacteristic	sharedCharacteristic(java.util.UUID uuid, int properties, int permissions, byte[] initialValue, android.bluetooth.BluetoothGattDescriptor... descriptors) A helper method that creates a characteristic with given UUID, properties and permissions.
protected android.bluetooth.BluetoothGattCharacteristic	sharedCharacteristic(java.util.UUID uuid, int properties, int permissions, Data initialValue, android.bluetooth.BluetoothGattDescriptor... descriptors) A helper method that creates a characteristic with given UUID, properties and permissions.
protected android.bluetooth.BluetoothGattDescriptor	sharedDescriptor(java.util.UUID uuid, int permissions, byte[] initialValue) A helper method that creates a descriptor with given UUID and permissions.
protected android.bluetooth.BluetoothGattDescriptor	sharedDescriptor(java.util.UUID uuid, int permissions, Data initialValue) A helper method that creates a descriptor with given UUID and permissions.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BleServerManager

public BleServerManager(@NonNull
                        android.content.Context context)

Method Detail

open

public final boolean open()

Opens the GATT server and starts initializing services. This method only starts initializing services. The ServerObserver.onServerReady() will be called when all services are done.

Returns:

true, if the server has been started successfully. If GATT server could not be started, for example the Bluetooth is disabled, false is returned.

See Also:

close()

close

public final void close()

Closes the GATT server.

setServerObserver

public final void setServerObserver(@NonNull
                                    ServerObserver observer)

Sets the server observer.

Parameters:

observer - the observer.

log

public void log(int priority,
                @NonNull
                java.lang.String message)

Description copied from interface: ILogger

Logs the given message with given log priority into the all managed devices' log session.

Specified by:

log in interface ILogger

Parameters:

priority - the log priority.

message - the message to be logged.

log

public void log(int priority,
                @StringRes
                int messageRes,
                @Nullable
                java.lang.Object... params)

Description copied from interface: ILogger

Logs the given message with given log priority into the all managed devices' log session.

Specified by:

log in interface ILogger

Parameters:

priority - the log priority.

messageRes - string resource id.

params - additional (optional) parameters used to fill the message.

initializeServer

@NonNull
protected abstract java.util.List<android.bluetooth.BluetoothGattService> initializeServer()

This method is called once, just after instantiating the BleServerManager. It should return a list of server GATT services that will be available for the remote device to use. You may use service(UUID, BluetoothGattCharacteristic...) to easily instantiate a service.

Server services will be added to the local GATT configuration on the Android device. The library does not know what services are already set up by other apps or BleServerManager instances, so a UUID collision is possible. The remote device will discover all services set up by all apps.

In order to enable server callbacks (see BluetoothGattServerCallback), but without defining own services, return an empty list.

Returns:

The list of server GATT services, or null if no services should be created. An empty array to start the GATT server without any services.

Since:

2.2

service

@NonNull
protected final android.bluetooth.BluetoothGattService service(@NonNull
                                                                         java.util.UUID uuid,
                                                                         android.bluetooth.BluetoothGattCharacteristic... characteristics)

A helper method for creating a primary service with given UUID and list of characteristics. This method can be called from initializeServer().

Parameters:

uuid - The service UUID.

characteristics - The optional list of characteristics.

Returns:

The new service.

characteristic

@NonNull
protected final android.bluetooth.BluetoothGattCharacteristic characteristic(@NonNull
                                                                                       java.util.UUID uuid,
                                                                                       int properties,
                                                                                       int permissions,
                                                                                       @Nullable
                                                                                       byte[] initialValue,
                                                                                       android.bluetooth.BluetoothGattDescriptor... descriptors)

A helper method that creates a characteristic with given UUID, properties and permissions. Optionally, an initial value and a list of descriptors may be set.

The Client Characteristic Configuration Descriptor (CCCD) will be added automatically if BluetoothGattCharacteristic.PROPERTY_NOTIFY or BluetoothGattCharacteristic.PROPERTY_INDICATE was set, if not added explicitly in the descriptors list.

If reliableWrite() was added as one of the descriptors or the Characteristic User Description descriptor was created with any of write permissions (see description(String, boolean)) the BluetoothGattCharacteristic.PROPERTY_EXTENDED_PROPS property will be added automatically.

The value of the characteristic will NOT be shared between clients. Each client will write and read its own copy. To create a shared characteristic, use sharedCharacteristic(UUID, int, int, byte[], BluetoothGattDescriptor...) instead.

Parameters:

uuid - The characteristic UUID.

properties - The bit mask of characteristic properties. See BluetoothGattCharacteristic for details.

permissions - The bit mask or characteristic permissions. See BluetoothGattCharacteristic for details.

initialValue - The optional initial value of the characteristic.

descriptors - The optional list of descriptors.

Returns:

The characteristic.

characteristic

@NonNull
protected final android.bluetooth.BluetoothGattCharacteristic characteristic(@NonNull
                                                                                       java.util.UUID uuid,
                                                                                       int properties,
                                                                                       int permissions,
                                                                                       @Nullable
                                                                                       Data initialValue,
                                                                                       android.bluetooth.BluetoothGattDescriptor... descriptors)

A helper method that creates a characteristic with given UUID, properties and permissions. Optionally, an initial value and a list of descriptors may be set.

The Client Characteristic Configuration Descriptor (CCCD) will be added automatically if BluetoothGattCharacteristic.PROPERTY_NOTIFY or BluetoothGattCharacteristic.PROPERTY_INDICATE was set, if not added explicitly in the descriptors list.

If reliableWrite() was added as one of the descriptors or the Characteristic User Description descriptor was created with any of write permissions (see description(String, boolean)) the BluetoothGattCharacteristic.PROPERTY_EXTENDED_PROPS property will be added automatically.

The value of the characteristic will NOT be shared between clients. Each client will write and read its own copy. To create a shared characteristic, use sharedCharacteristic(UUID, int, int, byte[], BluetoothGattDescriptor...) instead.

Parameters:

uuid - The characteristic UUID.

properties - The bit mask of characteristic properties. See BluetoothGattCharacteristic for details.

permissions - The bit mask or characteristic permissions. See BluetoothGattCharacteristic for details.

initialValue - The optional initial value of the characteristic.

descriptors - The optional list of descriptors.

Returns:

The characteristic.

characteristic

@NonNull
protected final android.bluetooth.BluetoothGattCharacteristic characteristic(@NonNull
                                                                                       java.util.UUID uuid,
                                                                                       int properties,
                                                                                       int permissions,
                                                                                       android.bluetooth.BluetoothGattDescriptor... descriptors)

A helper method that creates a characteristic with given UUID, properties and permissions. Optionally, a list of descriptors may be set.

The Client Characteristic Configuration Descriptor (CCCD) will be added automatically if BluetoothGattCharacteristic.PROPERTY_NOTIFY or BluetoothGattCharacteristic.PROPERTY_INDICATE was set, if not added explicitly in the descriptors list.

If reliableWrite() was added as one of the descriptors or the Characteristic User Description descriptor was created with any of write permissions (see description(String, boolean)) the BluetoothGattCharacteristic.PROPERTY_EXTENDED_PROPS property will be added automatically.

The value of the characteristic will NOT be shared between clients. Each client will write and read its own copy. To create a shared characteristic, use sharedCharacteristic(UUID, int, int, byte[], BluetoothGattDescriptor...) instead.

Parameters:

uuid - The characteristic UUID.

properties - The bit mask of characteristic properties. See BluetoothGattCharacteristic for details.

permissions - The bit mask or characteristic permissions. See BluetoothGattCharacteristic for details.

descriptors - The optional list of descriptors.

Returns:

The characteristic.

sharedCharacteristic

@NonNull
protected final android.bluetooth.BluetoothGattCharacteristic sharedCharacteristic(@NonNull
                                                                                             java.util.UUID uuid,
                                                                                             int properties,
                                                                                             int permissions,
                                                                                             @Nullable
                                                                                             byte[] initialValue,
                                                                                             android.bluetooth.BluetoothGattDescriptor... descriptors)

A helper method that creates a characteristic with given UUID, properties and permissions. Optionally, an initial value and a list of descriptors may be set.

The Client Characteristic Configuration Descriptor (CCCD) will be added automatically if BluetoothGattCharacteristic.PROPERTY_NOTIFY or BluetoothGattCharacteristic.PROPERTY_INDICATE was set, if not added explicitly in the descriptors list.

If reliableWrite() was added as one of the descriptors or the Characteristic User Description descriptor was created with any of write permissions (see description(String, boolean)) the BluetoothGattCharacteristic.PROPERTY_EXTENDED_PROPS property will be added automatically.

The value of the characteristic is shared between clients. A value written by one of the connected clients will be available for all other clients. To create a sandboxed characteristic, use characteristic(UUID, int, int, byte[], BluetoothGattDescriptor...) instead.

Parameters:

uuid - The characteristic UUID.

properties - The bit mask of characteristic properties. See BluetoothGattCharacteristic for details.

permissions - The bit mask or characteristic permissions. See BluetoothGattCharacteristic for details.

initialValue - The optional initial value of the characteristic.

descriptors - The optional list of descriptors.

Returns:

The characteristic.

sharedCharacteristic

@NonNull
protected final android.bluetooth.BluetoothGattCharacteristic sharedCharacteristic(@NonNull
                                                                                             java.util.UUID uuid,
                                                                                             int properties,
                                                                                             int permissions,
                                                                                             @Nullable
                                                                                             Data initialValue,
                                                                                             android.bluetooth.BluetoothGattDescriptor... descriptors)

A helper method that creates a characteristic with given UUID, properties and permissions. Optionally, an initial value and a list of descriptors may be set.

The Client Characteristic Configuration Descriptor (CCCD) will be added automatically if BluetoothGattCharacteristic.PROPERTY_NOTIFY or BluetoothGattCharacteristic.PROPERTY_INDICATE was set, if not added explicitly in the descriptors list.

If reliableWrite() was added as one of the descriptors or the Characteristic User Description descriptor was created with any of write permissions (see description(String, boolean)) the BluetoothGattCharacteristic.PROPERTY_EXTENDED_PROPS property will be added automatically.

The value of the characteristic is shared between clients. A value written by one of the connected clients will be available for all other clients. To create a sandboxed characteristic, use characteristic(UUID, int, int, byte[], BluetoothGattDescriptor...) instead.

Parameters:

uuid - The characteristic UUID.

properties - The bit mask of characteristic properties. See BluetoothGattCharacteristic for details.

permissions - The bit mask or characteristic permissions. See BluetoothGattCharacteristic for details.

initialValue - The optional initial value of the characteristic.

descriptors - The optional list of descriptors.

Returns:

The characteristic.

sharedCharacteristic

@NonNull
protected final android.bluetooth.BluetoothGattCharacteristic sharedCharacteristic(@NonNull
                                                                                             java.util.UUID uuid,
                                                                                             int properties,
                                                                                             int permissions,
                                                                                             android.bluetooth.BluetoothGattDescriptor... descriptors)

A helper method that creates a characteristic with given UUID, properties and permissions. Optionally, a list of descriptors may be set.

The Client Characteristic Configuration Descriptor (CCCD) will be added automatically if BluetoothGattCharacteristic.PROPERTY_NOTIFY or BluetoothGattCharacteristic.PROPERTY_INDICATE was set, if not added explicitly in the descriptors list.

If reliableWrite() was added as one of the descriptors or the Characteristic User Description descriptor was created with any of write permissions (see description(String, boolean)) the BluetoothGattCharacteristic.PROPERTY_EXTENDED_PROPS property will be added automatically.

The value of the characteristic is shared between clients. A value written by one of the connected clients will be available for all other clients. To create a sandboxed characteristic, use characteristic(UUID, int, int, byte[], BluetoothGattDescriptor...) instead.

Parameters:

uuid - The characteristic UUID.

properties - The bit mask of characteristic properties. See BluetoothGattCharacteristic for details.

permissions - The bit mask or characteristic permissions. See BluetoothGattCharacteristic for details.

descriptors - The optional list of descriptors.

Returns:

The characteristic.

descriptor

@NonNull
protected final android.bluetooth.BluetoothGattDescriptor descriptor(@NonNull
                                                                               java.util.UUID uuid,
                                                                               int permissions,
                                                                               @Nullable
                                                                               byte[] initialValue)

A helper method that creates a descriptor with given UUID and permissions. Optionally, an initial value may be set.

The value of the descriptor will NOT be shared between clients. Each client will write and read its own copy. To create a shared descriptor, use sharedDescriptor(UUID, int, byte[]) instead.

Parameters:

uuid - The characteristic UUID.

permissions - The bit mask or descriptor permissions. See BluetoothGattCharacteristic for details.

initialValue - The optional initial value of the descriptor.

Returns:

The characteristic.

descriptor

@NonNull
protected final android.bluetooth.BluetoothGattDescriptor descriptor(@NonNull
                                                                               java.util.UUID uuid,
                                                                               int permissions,
                                                                               @Nullable
                                                                               Data initialValue)

A helper method that creates a descriptor with given UUID and permissions. Optionally, an initial value may be set.

The value of the descriptor will NOT be shared between clients. Each client will write and read its own copy. To create a shared descriptor, use sharedDescriptor(UUID, int, byte[]) instead.

Parameters:

uuid - The characteristic UUID.

permissions - The bit mask or descriptor permissions. See BluetoothGattCharacteristic for details.

initialValue - The optional initial value of the descriptor.

Returns:

The characteristic.

sharedDescriptor

@NonNull
protected final android.bluetooth.BluetoothGattDescriptor sharedDescriptor(@NonNull
                                                                                     java.util.UUID uuid,
                                                                                     int permissions,
                                                                                     @Nullable
                                                                                     byte[] initialValue)

A helper method that creates a descriptor with given UUID and permissions. Optionally, an initial value may be set.

The value of the characteristic is shared between clients. A value written by one of the connected clients will be available for all other clients. To create a sandboxed characteristic, use characteristic(UUID, int, int, byte[], BluetoothGattDescriptor...) instead.

Parameters:

uuid - The characteristic UUID.

permissions - The bit mask or characteristic permissions. See BluetoothGattCharacteristic for details.

initialValue - The optional initial value of the characteristic.

Returns:

The characteristic.

sharedDescriptor

@NonNull
protected final android.bluetooth.BluetoothGattDescriptor sharedDescriptor(@NonNull
                                                                                     java.util.UUID uuid,
                                                                                     int permissions,
                                                                                     @Nullable
                                                                                     Data initialValue)

A helper method that creates a descriptor with given UUID and permissions. Optionally, an initial value may be set.

The value of the characteristic is shared between clients. A value written by one of the connected clients will be available for all other clients. To create a sandboxed characteristic, use characteristic(UUID, int, int, byte[], BluetoothGattDescriptor...) instead.

Parameters:

uuid - The characteristic UUID.

permissions - The bit mask or characteristic permissions. See BluetoothGattCharacteristic for details.

initialValue - The optional initial value of the characteristic.

Returns:

The characteristic.

cccd

@NonNull
protected final android.bluetooth.BluetoothGattDescriptor cccd()

This helper method returns a new instance of Client Characteristic Configuration Descriptor (CCCD) that can be added to a server characteristic in initializeServer().

Returns:

The CCC descriptor used to enable and disable notifications or indications.

sharedCccd

@NonNull
protected final android.bluetooth.BluetoothGattDescriptor sharedCccd()

This helper method returns a new instance of Client Characteristic Configuration Descriptor (CCCD) that can be added to a server characteristic in initializeServer().

Returns:

The CCC descriptor used to enable and disable notifications or indications.

reliableWrite

@NonNull
protected final android.bluetooth.BluetoothGattDescriptor reliableWrite()

This helper method returns a new instance of Characteristic Extended Properties descriptor that can be added to a server characteristic. This descriptor should be added it BluetoothGattCharacteristic.PROPERTY_EXTENDED_PROPS property is set.

Returns:

The CEP descriptor with Reliable Write bit set.

description

@NonNull
protected final android.bluetooth.BluetoothGattDescriptor description(@Nullable
                                                                                java.lang.String description,
                                                                                boolean writableAuxiliaries)

This helper method returns a new instance of Client User Description Descriptor that can be added to a server characteristic in initializeServer().

Parameters:

description - the UTF-8 string that is a user textual description of the characteristic.

writableAuxiliaries - if true, the descriptor will be writable and the Writable Auxiliaries bit in Characteristic Extended Properties descriptor will be set. See Vol. 3, Part F, Section 3.3.3.2 in Bluetooth Core specification 5.1.

Returns:

The User Description descriptor.