public interface NearbyBridge

Internal service-provider interface implemented by each platform port to carry the com.codename1.nearby API onto the native short-range stacks: Apple’s Nearby Interaction, MultipeerConnectivity and AccessorySetupKit, Android’s Jetpack UWB, Nearby Connections and CompanionDeviceManager.

Application code never touches this interface. It is obtained by the com.codename1.nearby packages from com.codename1.ui.Display#getNearbyBridge(), and the base implementation returns null – which is why the public API degrades to a well-behaved NOT_SUPPORTED on ports that implement nothing, and why application code needs no platform if statements.

Everything here is primitives, strings and byte arrays

A port may be Objective-C reached through ParparVM, where constructing a Java object is expensive and easy to get wrong. So no method on this interface takes or returns a framework type: enums cross as their ordinals, capability sets cross as bit masks, and structured records cross as tab-delimited strings built by com.codename1.impl.nearby.NearbyWire.

Asynchrony is by request id, and every operation must answer

Operations that can fail take a requestId allocated by the caller and answer exactly once by calling the matching deliver... entry point on the public class. An operation that never answers is worse than one that fails: the caller holds an AsyncResource that will never settle and has no way to find out. A port that cannot start something must still report the failure.

Unsolicited events – ranging updates, endpoint discoveries, presence changes – carry the handle or endpoint id they belong to instead of a request id. Every entry point may be called from any thread; they marshal to the EDT themselves.

Fields

`public static final int CAPABILITY_DISTANCE = 1`	`getRangingCapabilities()` bit: precise distance is measurable.
`public static final int CAPABILITY_DIRECTION = 2`	`getRangingCapabilities()` bit: horizontal direction is measurable.
`public static final int CAPABILITY_ELEVATION = 4`	`getRangingCapabilities()` bit: vertical direction is measurable.
`public static final int CAPABILITY_CAMERA_ASSISTANCE = 8`	`getRangingCapabilities()` bit: camera assistance is available.
`public static final int CAPABILITY_ACCESSORY = 16`	`getRangingCapabilities()` bit: third-party UWB accessories can be ranged.
`public static final int CAPABILITY_BACKGROUND = 32`	`getRangingCapabilities()` bit: ranging continues in the background.
`public static final int PERMISSION_RANGING = 1`	`requestPermissions` bit for `NearbyPermission.RANGING`.
`public static final int PERMISSION_DISCOVERY = 2`	`requestPermissions` bit for `NearbyPermission.DISCOVERY`.
`public static final int PERMISSION_ADVERTISE = 4`	`requestPermissions` bit for `NearbyPermission.ADVERTISE`.
`public static final int PERMISSION_CONNECT = 8`	`requestPermissions` bit for `NearbyPermission.CONNECT`.
`public static final int PAYLOAD_BYTES = 0`	`sendPayload` type: the payload is the `bytes` argument.
`public static final int PAYLOAD_FILE = 1`	`sendPayload` type: the payload is the file at `path`.

Methods

`public abstract boolean isRangingSupported()`	Whether this port implements precision ranging at all.
`public abstract boolean isCompanionSupported()`	Whether this port implements companion-device association.
`public abstract boolean isTransportSupported()`	Whether this port implements the nearby transport.
`public abstract int getRangingAvailability()`	How usable ranging is right now, as a `NearbyAvailability` ordinal.
`public abstract int getCompanionAvailability()`	How usable companion association is right now, as a `NearbyAvailability` ordinal.
`public abstract int getTransportAvailability()`	How usable the transport is right now, as a `NearbyAvailability` ordinal.
`public abstract void requestPermissions(int requestId, int permissionBits)`	Requests the platform permissions behind the given `NearbyPermission` bits, answering with `com.codename1.nearby.ranging.Ranging#deliverPermissionResult`.
`public abstract int getRangingCapabilities()`	What the device can measure, as an OR of the `CAPABILITY_` constants.
`public abstract void prepareRangingSession(int requestId, int sessionHandle, boolean controller)`	Allocates a platform ranging session and publishes its local token.
`public abstract void startRanging(int requestId, int sessionHandle, byte[] peerToken)`	Starts ranging a peer whose token arrived out of band.
`public abstract void startAccessoryRanging(int requestId, int sessionHandle, byte[] accessoryData)`	Starts ranging a third-party UWB accessory.
`public abstract void stopRangingSession(int sessionHandle)`	Tears a ranging session down and releases the radio.
`public abstract void associate(int requestId, int profile, boolean singleDevice,` `String[] filters)`	Runs the platform’s device chooser and associates whatever the user picks, answering with `com.codename1.nearby.companion.CompanionDevices#deliverAssociated`.
`public abstract` `String[] getAssociations()`	Every association this app currently holds, each encoded by `com.codename1.impl.nearby.NearbyWire`.
`public abstract void disassociate(int requestId,` `String associationId)`	Drops an association, answering with `com.codename1.nearby.companion.CompanionDevices#deliverRequestFailed` only on failure and `CompanionDevices#deliverDisassociated` on success.
`public abstract boolean startObservingPresence(String associationId)`	Asks the platform to wake this app when the associated device comes and goes.
`public abstract void stopObservingPresence(String associationId)`	Stops watching an association.
`public abstract int getMaxPayloadSize()`	The largest byte payload `sendPayload` accepts in one call.
`public abstract void startAdvertising(int requestId,` `String serviceId, String localName, int strategy)`	Starts advertising this device under a service id, answering with `com.codename1.nearby.transport.NearbyTransport#deliverRequestOk`.
`public abstract void stopAdvertising()`	Stops advertising.
`public abstract void startDiscovery(int requestId,` `String serviceId, int strategy)`	Starts looking for peers advertising the same service id, answering with `NearbyTransport#deliverRequestOk`.
`public abstract void stopDiscovery()`	Stops discovery.
`public abstract void requestConnection(int requestId,` `String endpointId, String localName)`	Asks a discovered endpoint to connect.
`public abstract void acceptConnection(int requestId,` `String endpointId)`	Accepts an incoming connection request.
`public abstract void rejectConnection(String endpointId)`	Rejects an incoming connection request.
`public abstract void sendPayload(int requestId,` `String[] endpointIds, int payloadId, int payloadType, byte[] bytes, String path)`	Sends a payload to one or more connected endpoints, reporting progress through `NearbyTransport#deliverPayloadProgress`.
`public abstract void cancelPayload(int payloadId)`	Cancels an in-flight payload.
`public abstract void disconnect(String endpointId)`	Disconnects one endpoint.
`public abstract void stopAllTransport()`	Stops advertising and discovery and drops every connection.

Field details

CAPABILITY_DISTANCE

public static final int CAPABILITY_DISTANCE = 1

getRangingCapabilities() bit: precise distance is measurable.

CAPABILITY_DIRECTION

public static final int CAPABILITY_DIRECTION = 2

getRangingCapabilities() bit: horizontal direction is measurable.

CAPABILITY_ELEVATION

public static final int CAPABILITY_ELEVATION = 4

getRangingCapabilities() bit: vertical direction is measurable.

CAPABILITY_CAMERA_ASSISTANCE

public static final int CAPABILITY_CAMERA_ASSISTANCE = 8

getRangingCapabilities() bit: camera assistance is available.

CAPABILITY_ACCESSORY

public static final int CAPABILITY_ACCESSORY = 16

getRangingCapabilities() bit: third-party UWB accessories can be ranged.

CAPABILITY_BACKGROUND

public static final int CAPABILITY_BACKGROUND = 32

getRangingCapabilities() bit: ranging continues in the background.

PERMISSION_RANGING

public static final int PERMISSION_RANGING = 1

requestPermissions bit for NearbyPermission.RANGING.

PERMISSION_DISCOVERY

public static final int PERMISSION_DISCOVERY = 2

requestPermissions bit for NearbyPermission.DISCOVERY.

PERMISSION_ADVERTISE

public static final int PERMISSION_ADVERTISE = 4

requestPermissions bit for NearbyPermission.ADVERTISE.

PERMISSION_CONNECT

public static final int PERMISSION_CONNECT = 8

requestPermissions bit for NearbyPermission.CONNECT.

PAYLOAD_BYTES

public static final int PAYLOAD_BYTES = 0

sendPayload type: the payload is the bytes argument.

PAYLOAD_FILE

public static final int PAYLOAD_FILE = 1

sendPayload type: the payload is the file at path.

Method details

isRangingSupported

public abstract boolean isRangingSupported()

Whether this port implements precision ranging at all. Answer for the port and the hardware, not for whether a peer is around.

Returns

true when com.codename1.nearby.ranging has a real implementation

isCompanionSupported

public abstract boolean isCompanionSupported()

Whether this port implements companion-device association.

Returns

true when com.codename1.nearby.companion has a real implementation

isTransportSupported

public abstract boolean isTransportSupported()

Whether this port implements the nearby transport.

Returns

true when com.codename1.nearby.transport has a real implementation

getRangingAvailability

public abstract int getRangingAvailability()

How usable ranging is right now, as a NearbyAvailability ordinal. A port backed by a simulation must answer LOCAL_ONLY rather than AVAILABLE, so an app can tell the developer their peers are not real.

Returns

the ordinal of a com.codename1.nearby.NearbyAvailability constant

getCompanionAvailability

public abstract int getCompanionAvailability()

How usable companion association is right now, as a NearbyAvailability ordinal.

Returns

the ordinal of a com.codename1.nearby.NearbyAvailability constant

getTransportAvailability

public abstract int getTransportAvailability()

How usable the transport is right now, as a NearbyAvailability ordinal.

Returns

the ordinal of a com.codename1.nearby.NearbyAvailability constant

requestPermissions

public abstract void requestPermissions(int requestId, int permissionBits)

Requests the platform permissions behind the given NearbyPermission bits, answering with com.codename1.nearby.ranging.Ranging#deliverPermissionResult.

A port that needs no permission for the bits it was given must still answer, reporting them granted.

Parameters

requestId int: the id to answer with
permissionBits int: an OR of the PERMISSION_ constants

getRangingCapabilities

public abstract int getRangingCapabilities()

What the device can measure, as an OR of the CAPABILITY_ constants.

Returns

the capability bits, or zero when ranging is unsupported

prepareRangingSession

public abstract void prepareRangingSession(int requestId, int sessionHandle, boolean controller)

Allocates a platform ranging session and publishes its local token.

The port answers with com.codename1.nearby.ranging.Ranging#deliverSessionPrepared on success, passing back the same sessionHandle it was given, or with Ranging#deliverRequestFailed on failure. The session is not ranging yet – startRanging or startAccessoryRanging does that.

Parameters

requestId int: the id to answer with
sessionHandle int: the handle every later call and event uses to name this session
controller boolean: true for RangingRole.CONTROLLER. Ports whose platform negotiates roles by itself ignore this.

startRanging

public abstract void startRanging(int requestId, int sessionHandle, byte[] peerToken)

Starts ranging a peer whose token arrived out of band.

The token is the full encoded form from com.codename1.nearby.ranging.RangingToken#toByteArray(); the port validates that it was minted by this platform and fails the request with NearbyError.INVALID_TOKEN when it was not.

Parameters

requestId int: the id to answer with, via Ranging#deliverSessionStarted
sessionHandle int: the prepared session
peerToken byte[]: the peer’s encoded token

startAccessoryRanging

public abstract void startAccessoryRanging(int requestId, int sessionHandle, byte[] accessoryData)

Starts ranging a third-party UWB accessory.

The port answers with com.codename1.nearby.ranging.Ranging#deliverAccessoryConfiguration, passing the bytes the app must send back to the accessory to make it start ranging (Apple’s Nearby Interaction Accessory Protocol requires this handshake). A platform with no such handshake answers with an empty array rather than failing.

Parameters

requestId int: the id to answer with
sessionHandle int: the prepared session
accessoryData byte[]: the configuration data the accessory published

stopRangingSession

public abstract void stopRangingSession(int sessionHandle)

Tears a ranging session down and releases the radio. Idempotent, and must not deliver any further event for this handle.

Parameters

sessionHandle int: the session to stop

associate

public abstract void associate(int requestId, int profile, boolean singleDevice, String[] filters)

Runs the platform’s device chooser and associates whatever the user picks, answering with com.codename1.nearby.companion.CompanionDevices#deliverAssociated.

Parameters

requestId int: the id to answer with
profile int: the ordinal of a com.codename1.nearby.companion.CompanionProfile constant
singleDevice boolean: whether to associate without showing a list when exactly one device matches
filters String[]: the encoded filters from com.codename1.impl.nearby.NearbyWire, never null and possibly empty

getAssociations

public abstract String[] getAssociations()

Every association this app currently holds, each encoded by com.codename1.impl.nearby.NearbyWire.

Returns

the associations, never null and possibly empty

disassociate

public abstract void disassociate(int requestId, String associationId)

Drops an association, answering with com.codename1.nearby.companion.CompanionDevices#deliverRequestFailed only on failure and CompanionDevices#deliverDisassociated on success.

Parameters

requestId int: the id to answer with
associationId String: the association to drop

startObservingPresence

public abstract boolean startObservingPresence(String associationId)

Asks the platform to wake this app when the associated device comes and goes.

Parameters

associationId String: the association to watch

Returns

true when the platform accepted the request

stopObservingPresence

public abstract void stopObservingPresence(String associationId)

Stops watching an association. Idempotent.

Parameters

associationId String: the association to stop watching

getMaxPayloadSize

public abstract int getMaxPayloadSize()

The largest byte payload sendPayload accepts in one call.

Returns

the limit in bytes, or zero when the transport is unsupported

startAdvertising

public abstract void startAdvertising(int requestId, String serviceId, String localName, int strategy)

Starts advertising this device under a service id, answering with com.codename1.nearby.transport.NearbyTransport#deliverRequestOk.

Parameters

requestId int: the id to answer with
serviceId String: the service both ends agreed on
localName String: the name to show peers
strategy int: the ordinal of a com.codename1.nearby.transport.TransportStrategy constant

stopAdvertising

public abstract void stopAdvertising()

Stops advertising. Idempotent.

startDiscovery

public abstract void startDiscovery(int requestId, String serviceId, int strategy)

Starts looking for peers advertising the same service id, answering with NearbyTransport#deliverRequestOk. Sightings arrive unsolicited through NearbyTransport#deliverEndpointFound.

Parameters

requestId int: the id to answer with
serviceId String: the service both ends agreed on
strategy int: the ordinal of a com.codename1.nearby.transport.TransportStrategy constant

stopDiscovery

public abstract void stopDiscovery()

Stops discovery. Idempotent.

requestConnection

public abstract void requestConnection(int requestId, String endpointId, String localName)

Asks a discovered endpoint to connect. The endpoint answers by accepting or rejecting, which arrives through NearbyTransport#deliverConnectionResult.

Parameters

requestId int: the id to answer with
endpointId String: the endpoint to ask
localName String: the name to show them

acceptConnection

public abstract void acceptConnection(int requestId, String endpointId)

Accepts an incoming connection request.

Parameters

requestId int: the id to answer with
endpointId String: the endpoint that asked

rejectConnection

public abstract void rejectConnection(String endpointId)

Rejects an incoming connection request.

Parameters

endpointId String: the endpoint that asked

sendPayload

public abstract void sendPayload(int requestId, String[] endpointIds, int payloadId, int payloadType, byte[] bytes, String path)

Sends a payload to one or more connected endpoints, reporting progress through NearbyTransport#deliverPayloadProgress.

Parameters

requestId int: the id to answer with once the payload is handed to the platform
endpointIds String[]: the recipients
payloadId int: the id progress and cancellation use
payloadType int: PAYLOAD_BYTES or PAYLOAD_FILE
bytes byte[]: the payload for PAYLOAD_BYTES, otherwise null
path String: the file for PAYLOAD_FILE, otherwise null

cancelPayload

public abstract void cancelPayload(int payloadId)

Cancels an in-flight payload. Idempotent.

Parameters

payloadId int: the payload to cancel

disconnect

public abstract void disconnect(String endpointId)

Disconnects one endpoint. Idempotent.

Parameters

endpointId String: the endpoint to drop

stopAllTransport

public abstract void stopAllTransport()

Stops advertising and discovery and drops every connection. Called when the app is shutting the transport down.