# Interface NearbyBridge

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.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `CAPABILITY_ACCESSORY`
  `getRangingCapabilities()` bit: third-party UWB accessories can be ranged.
  `static final int`
  `CAPABILITY_BACKGROUND`
  `getRangingCapabilities()` bit: ranging continues in the background.
  `static final int`
  `CAPABILITY_CAMERA_ASSISTANCE`
  `getRangingCapabilities()` bit: camera assistance is available.
  `static final int`
  `CAPABILITY_DIRECTION`
  `getRangingCapabilities()` bit: horizontal direction is measurable.
  `static final int`
  `CAPABILITY_DISTANCE`
  `getRangingCapabilities()` bit: precise distance is measurable.
  `static final int`
  `CAPABILITY_ELEVATION`
  `getRangingCapabilities()` bit: vertical direction is measurable.
  `static final int`
  `PAYLOAD_BYTES`
  `sendPayload(int, String[], int, int, byte[], String)` type: the payload is the `bytes` argument.
  `static final int`
  `PAYLOAD_FILE`
  `sendPayload(int, String[], int, int, byte[], String)` type: the payload is the file at `path`.
  `static final int`
  `PERMISSION_ADVERTISE`
  `requestPermissions(int, int)` bit for `NearbyPermission.ADVERTISE`.
  `static final int`
  `PERMISSION_CONNECT`
  `requestPermissions(int, int)` bit for `NearbyPermission.CONNECT`.
  `static final int`
  `PERMISSION_DISCOVERY`
  `requestPermissions(int, int)` bit for `NearbyPermission.DISCOVERY`.
  `static final int`
  `PERMISSION_RANGING`
  `requestPermissions(int, int)` bit for `NearbyPermission.RANGING`.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `acceptConnection(int requestId, String endpointId)`
  Accepts an incoming connection request.
  `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`.
  `void`
  `cancelPayload(int payloadId)`
  Cancels an in-flight payload.
  `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.
  `void`
  `disconnect(String endpointId)`
  Disconnects one endpoint.
  `String[]`
  `getAssociations()`
  Every association this app currently holds, each encoded by `com.codename1.impl.nearby.NearbyWire`.
  `int`
  `getCompanionAvailability()`
  How usable companion association is right now, as a `NearbyAvailability` ordinal.
  `int`
  `getMaxPayloadSize()`
  The largest byte payload `sendPayload(int, String[], int, int, byte[], String)` accepts in one call.
  `int`
  `getRangingAvailability()`
  How usable ranging is right now, as a `NearbyAvailability` ordinal.
  `int`
  `getRangingCapabilities()`
  What the device can measure, as an OR of the `CAPABILITY_` constants.
  `int`
  `getTransportAvailability()`
  How usable the transport is right now, as a `NearbyAvailability` ordinal.
  `boolean`
  `isCompanionSupported()`
  Whether this port implements companion-device association.
  `boolean`
  `isRangingSupported()`
  Whether this port implements precision ranging at all.
  `boolean`
  `isTransportSupported()`
  Whether this port implements the nearby transport.
  `void`
  `prepareRangingSession(int requestId, int sessionHandle, boolean controller)`
  Allocates a platform ranging session and publishes its local token.
  `void`
  `rejectConnection(String endpointId)`
  Rejects an incoming connection request.
  `void`
  `requestConnection(int requestId, String endpointId, String localName)`
  Asks a discovered endpoint to connect.
  `void`
  `requestPermissions(int requestId, int permissionBits)`
  Requests the platform permissions behind the given `NearbyPermission` bits, answering with `com.codename1.nearby.ranging.Ranging#deliverPermissionResult`.
  `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`.
  `void`
  `startAccessoryRanging(int requestId, int sessionHandle, byte[] accessoryData)`
  Starts ranging a third-party UWB accessory.
  `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`.
  `void`
  `startDiscovery(int requestId, String serviceId, int strategy)`
  Starts looking for peers advertising the same service id, answering with `NearbyTransport#deliverRequestOk`.
  `boolean`
  `startObservingPresence(String associationId)`
  Asks the platform to wake this app when the associated device comes and goes.
  `void`
  `startRanging(int requestId, int sessionHandle, byte[] peerToken)`
  Starts ranging a peer whose token arrived out of band.
  `void`
  `stopAdvertising()`
  Stops advertising.
  `void`
  `stopAllTransport()`
  Stops advertising and discovery and drops every connection.
  `void`
  `stopDiscovery()`
  Stops discovery.
  `void`
  `stopObservingPresence(String associationId)`
  Stops watching an association.
  `void`
  `stopRangingSession(int sessionHandle)`
  Tears a ranging session down and releases the radio.

- ## Field Details

  - ### CAPABILITY_DISTANCE

    static final int CAPABILITY_DISTANCE
    `getRangingCapabilities()` bit: precise distance is measurable.
    See Also:
      - Constant Field Values

  - ### CAPABILITY_DIRECTION

    static final int CAPABILITY_DIRECTION
    `getRangingCapabilities()` bit: horizontal direction is measurable.
    See Also:
      - Constant Field Values

  - ### CAPABILITY_ELEVATION

    static final int CAPABILITY_ELEVATION
    `getRangingCapabilities()` bit: vertical direction is measurable.
    See Also:
      - Constant Field Values

  - ### CAPABILITY_CAMERA_ASSISTANCE

    static final int CAPABILITY_CAMERA_ASSISTANCE
    `getRangingCapabilities()` bit: camera assistance is available.
    See Also:
      - Constant Field Values

  - ### CAPABILITY_ACCESSORY

    static final int CAPABILITY_ACCESSORY
    `getRangingCapabilities()` bit: third-party UWB accessories can be ranged.
    See Also:
      - Constant Field Values

  - ### CAPABILITY_BACKGROUND

    static final int CAPABILITY_BACKGROUND
    `getRangingCapabilities()` bit: ranging continues in the background.
    See Also:
      - Constant Field Values

  - ### PERMISSION_RANGING

    static final int PERMISSION_RANGING
    `requestPermissions(int, int)` bit for `NearbyPermission.RANGING`.
    See Also:
      - Constant Field Values

  - ### PERMISSION_DISCOVERY

    static final int PERMISSION_DISCOVERY
    `requestPermissions(int, int)` bit for `NearbyPermission.DISCOVERY`.
    See Also:
      - Constant Field Values

  - ### PERMISSION_ADVERTISE

    static final int PERMISSION_ADVERTISE
    `requestPermissions(int, int)` bit for `NearbyPermission.ADVERTISE`.
    See Also:
      - Constant Field Values

  - ### PERMISSION_CONNECT

    static final int PERMISSION_CONNECT
    `requestPermissions(int, int)` bit for `NearbyPermission.CONNECT`.
    See Also:
      - Constant Field Values

  - ### PAYLOAD_BYTES

    static final int PAYLOAD_BYTES
    `sendPayload(int, String[], int, int, byte[], String)` type: the payload is the `bytes` argument.
    See Also:
      - Constant Field Values

  - ### PAYLOAD_FILE

    static final int PAYLOAD_FILE
    `sendPayload(int, String[], int, int, byte[], String)` type: the payload is the file at `path`.
    See Also:
      - Constant Field Values

- ## Method Details

  - ### isRangingSupported

    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

    boolean isCompanionSupported()

    Whether this port implements companion-device association.

    ###### Returns

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

  - ### isTransportSupported

    boolean isTransportSupported()

    Whether this port implements the nearby transport.

    ###### Returns

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

  - ### getRangingAvailability

    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

    int getCompanionAvailability()

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

    ###### Returns

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

  - ### getTransportAvailability

    int getTransportAvailability()

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

    ###### Returns

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

  - ### requestPermissions

    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`: the id to answer with
    - `permissionBits`: an OR of the `PERMISSION_` constants

  - ### getRangingCapabilities

    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

    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(int, int, byte[])` or `startAccessoryRanging(int, int, byte[])` does that.

    ###### Parameters

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

  - ### startRanging

    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`: the id to answer with, via `Ranging#deliverSessionStarted`
    - `sessionHandle`: the prepared session
    - `peerToken`: the peer's encoded token

  - ### startAccessoryRanging

    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`: the id to answer with
    - `sessionHandle`: the prepared session
    - `accessoryData`: the configuration data the accessory published

  - ### stopRangingSession

    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`: the session to stop

  - ### associate

    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`: the id to answer with
    - `profile`: the ordinal of a `com.codename1.nearby.companion.CompanionProfile` constant
    - `singleDevice`: whether to associate without showing a list when exactly one device matches
    - `filters`: the encoded filters from `com.codename1.impl.nearby.NearbyWire`, never null and possibly empty

  - ### getAssociations

    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

    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`: the id to answer with
    - `associationId`: the association to drop

  - ### startObservingPresence

    boolean startObservingPresence(String associationId)

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

    ###### Parameters

    - `associationId`: the association to watch

    ###### Returns

    true when the platform accepted the request

  - ### stopObservingPresence

    void stopObservingPresence(String associationId)

    Stops watching an association. Idempotent.

    ###### Parameters

    - `associationId`: the association to stop watching

  - ### getMaxPayloadSize

    int getMaxPayloadSize()

    The largest byte payload `sendPayload(int, String[], int, int, byte[], String)` accepts in one call.

    ###### Returns

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

  - ### startAdvertising

    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`: the id to answer with
    - `serviceId`: the service both ends agreed on
    - `localName`: the name to show peers
    - `strategy`: the ordinal of a `com.codename1.nearby.transport.TransportStrategy` constant

  - ### stopAdvertising

    void stopAdvertising()
    Stops advertising. Idempotent.

  - ### startDiscovery

    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`: the id to answer with
    - `serviceId`: the service both ends agreed on
    - `strategy`: the ordinal of a `com.codename1.nearby.transport.TransportStrategy` constant

  - ### stopDiscovery

    void stopDiscovery()
    Stops discovery. Idempotent.

  - ### requestConnection

    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`: the id to answer with
    - `endpointId`: the endpoint to ask
    - `localName`: the name to show them

  - ### acceptConnection

    void acceptConnection(int requestId, String endpointId)

    Accepts an incoming connection request.

    ###### Parameters

    - `requestId`: the id to answer with
    - `endpointId`: the endpoint that asked

  - ### rejectConnection

    void rejectConnection(String endpointId)

    Rejects an incoming connection request.

    ###### Parameters

    - `endpointId`: the endpoint that asked

  - ### sendPayload

    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`: the id to answer with once the payload is handed to the platform
    - `endpointIds`: the recipients
    - `payloadId`: the id progress and cancellation use
    - `payloadType`: `PAYLOAD_BYTES` or `PAYLOAD_FILE`
    - `bytes`: the payload for `PAYLOAD_BYTES`, otherwise null
    - `path`: the file for `PAYLOAD_FILE`, otherwise null

  - ### cancelPayload

    void cancelPayload(int payloadId)

    Cancels an in-flight payload. Idempotent.

    ###### Parameters

    - `payloadId`: the payload to cancel

  - ### disconnect

    void disconnect(String endpointId)

    Disconnects one endpoint. Idempotent.

    ###### Parameters

    - `endpointId`: the endpoint to drop

  - ### stopAllTransport

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