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 Details

  • 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.