public abstract class BlePeripheral
- Object
- BluetoothDevice
- BlePeripheral
A remote BLE peripheral: connection lifecycle, GATT client operations
and L2CAP channels. Obtained from scans
(ScanResult.getPeripheral()) or from
BluetoothLE.getPeripheral(String).
All operations return independent AsyncResource handles and may be
issued concurrently – an internal per-peripheral queue serializes them
toward the platform stack (which only allows one in-flight GATT request
per connection) and applies a safety timeout so a lost platform
callback can never wedge the queue. Operations on different
peripherals run fully concurrently.
Ports subclass this and implement the protected do* methods; they
report events through the fire* methods, which are safe to call from
any thread. All application-facing callbacks are delivered on the EDT.
Constructors
protected BlePeripheral() | Ports construct subclasses; application code receives instances from scans and BluetoothLE. |
Methods
Inherited methods
Constructor details
BlePeripheral
protected BlePeripheral()Ports construct subclasses; application code receives instances
from scans and
BluetoothLE.Method details
connect
public final AsyncResource<BlePeripheral> connect()Connects with default
ConnectionOptions.connect
public final AsyncResource<BlePeripheral> connect(ConnectionOptions options)Establishes a connection. Resolves with this peripheral once
connected or fails with a
BluetoothException. Calling connect
while already ConnectionState.CONNECTING returns the existing
attempt’s handle; while ConnectionState.CONNECTED it resolves
immediately.disconnect
public final void disconnect()Disconnects. A no-op while already disconnected; an in-flight
connect attempt is aborted with
BluetoothError.USER_CANCELED.getConnectionState
public final ConnectionState getConnectionState()The current connection state.
addConnectionListener
public final void addConnectionListener(ConnectionListener l)Registers a listener notified on the EDT of every connection state
transition.
removeConnectionListener
public final void removeConnectionListener(ConnectionListener l)Removes a listener added via
addConnectionListener(ConnectionListener).discoverServices
public final AsyncResource<List<GattService>> discoverServices()Discovers the peripheral’s services. Resolves with the service list
(also cached – see
getServices()) or fails with a
BluetoothException.getServices
public final List<GattService> getServices()The cached service list from the last
discoverServices() call;
empty before discovery.getService
public final GattService getService(BluetoothUuid uuid)The first cached service with the given UUID, or
null.getCharacteristic
public final GattCharacteristic getCharacteristic(BluetoothUuid service, BluetoothUuid characteristic)Convenience for
getService(service).getCharacteristic(characteristic)
that returns null instead of throwing when either is absent.readCharacteristic
public final AsyncResource<byte[]> readCharacteristic(GattCharacteristic c)Reads a characteristic value; prefer the convenience
GattCharacteristic.read().writeCharacteristic
public final AsyncResource<Boolean> writeCharacteristic(GattCharacteristic c, byte[] value, boolean withResponse)Writes a characteristic value; prefer the convenience
[GattCharacteristic#write(byte[])] /
[GattCharacteristic#writeWithoutResponse(byte[])].
readDescriptor
public final AsyncResource<byte[]> readDescriptor(GattDescriptor d)Reads a descriptor value; prefer the convenience
GattDescriptor.read().writeDescriptor
public final AsyncResource<Boolean> writeDescriptor(GattDescriptor d, byte[] value)Writes a descriptor value; prefer the convenience
[GattDescriptor#write(byte[])].
subscribe
public final AsyncResource<Boolean> subscribe(GattCharacteristic c, GattNotificationListener l)Subscribes a listener to a characteristic’s notifications; prefer
the convenience
GattCharacteristic.subscribe(GattNotificationListener). The CCCD
is written only on the transition from zero to one listener.unsubscribe
public final AsyncResource<Boolean> unsubscribe(GattCharacteristic c, GattNotificationListener l)Removes a notification listener; prefer the convenience
GattCharacteristic.unsubscribe(GattNotificationListener). The
CCCD is disarmed when the last listener is removed.isSubscribed
public final boolean isSubscribed(GattCharacteristic c)true while notifications are armed for the characteristic.readRssi
public final AsyncResource<Integer> readRssi()Reads the current RSSI of the connection.
requestMtu
public final AsyncResource<Integer> requestMtu(int mtu)Requests an MTU; resolves with the granted value (which may be
smaller). iOS negotiates the MTU itself – there the request
resolves immediately with the current value.
getMtu
public final int getMtu()The current MTU of the connection;
23 (the BLE default) until a
larger value was negotiated.requestConnectionPriority
public final AsyncResource<Boolean> requestConnectionPriority(ConnectionPriority priority)Requests a connection-interval preference; a successful no-op on
platforms that manage intervals themselves (iOS).
createBond
public final AsyncResource<Boolean> createBond()Initiates bonding/pairing. On iOS bonding is OS-managed (triggered
by encrypted characteristics), so the request resolves
true
without user interaction.openL2capChannel
public final AsyncResource<L2capChannel> openL2capChannel(int psm, boolean secure)Opens an L2CAP connection-oriented channel to the given PSM. Not
serialized with GATT operations. On Android this establishes its
own link and does not require
connect() first; on iOS the
peripheral must be connected.doConnect
protected abstract void doConnect(ConnectionOptions options, AsyncResource<BlePeripheral> out)Establishes the platform connection and completes/fails
out.doDisconnect
protected abstract void doDisconnect()Tears down the platform connection;
fireConnectionStateChanged(ConnectionState, BluetoothException)
reports the resulting DISCONNECTED transition.doDiscoverServices
protected abstract void doDiscoverServices(AsyncResource<List<GattService>> out)Performs service discovery and completes
out with the discovered
GattService list (constructed via the public gatt-package
constructors).doReadCharacteristic
protected abstract void doReadCharacteristic(GattCharacteristic c, AsyncResource<byte[]> out)Reads a characteristic and completes
out with its value.doWriteCharacteristic
protected abstract void doWriteCharacteristic(GattCharacteristic c, byte[] value, boolean withResponse, AsyncResource<Boolean> out)Writes a characteristic and completes
out once acknowledged
(withResponse) or queued to the controller.doReadDescriptor
protected abstract void doReadDescriptor(GattDescriptor d, AsyncResource<byte[]> out)Reads a descriptor and completes
out with its value.doWriteDescriptor
protected abstract void doWriteDescriptor(GattDescriptor d, byte[] value, AsyncResource<Boolean> out)Writes a descriptor and completes
out once acknowledged.doSetNotifications
protected abstract void doSetNotifications(GattCharacteristic c, boolean enable, boolean indication, AsyncResource<Boolean> out)Arms or disarms notifications/indications (including the CCCD
write) and completes
out once done.doReadRssi
protected abstract void doReadRssi(AsyncResource<Integer> out)Reads the connection RSSI and completes
out.doRequestMtu
protected abstract void doRequestMtu(int mtu, AsyncResource<Integer> out)Requests an MTU and completes
out with the granted value.doRequestConnectionPriority
protected abstract void doRequestConnectionPriority(ConnectionPriority priority, AsyncResource<Boolean> out)Requests a connection-interval preference and completes
out.doCreateBond
protected abstract void doCreateBond(AsyncResource<Boolean> out)Initiates bonding and completes
out when the bond state settles.doOpenL2cap
protected abstract void doOpenL2cap(int psm, boolean secure, AsyncResource<L2capChannel> out)Opens an L2CAP channel and completes
out with it. Called
directly (not through the operation queue).fireConnectionStateChanged
protected final void fireConnectionStateChanged(ConnectionState newState, BluetoothException reason)Reports an (unsolicited) connection state transition – link loss,
remote disconnect, or connection established outside a pending
connect call.
reason is null for app-requested transitions.fireNotification
protected final void fireNotification(GattCharacteristic c, byte[] value)Delivers a notification/indication value to the subscribed
listeners on the EDT. Ports must pass the canonical
GattCharacteristic instance from the discovered database.fireServicesInvalidated
protected final void fireServicesInvalidated()Invalidates the cached service database (iOS
didModifyServices); the app should re-run
discoverServices().setOperationTimeout
protected final void setOperationTimeout(int millis)Adjusts the safety timeout applied to each queued GATT operation
(default 30000ms;
0 disables).setMtu
protected final void setMtu(int mtu)Records the negotiated MTU – for ports whose platform reports MTU
changes outside a
requestMtu(int) call.