# Class NearbyTransport

java.lang.Object
com.codename1.nearby.transport.NearbyTransport

public final class NearbyTransport extends Object

Moving bytes and files to a device that is physically nearby, with no access point, no pairing and no internet.

The platform picks and combines the radios itself -- Bluetooth to find each other, then Wi-Fi to move the data -- so an app advertises a service id, discovers peers using the same id, connects, and sends payloads.

##### This transport does not cross ecosystems

Android talks to Android and Apple talks to Apple, and the two do not meet. Underneath are Google's Nearby Connections and Apple's MultipeerConnectivity, which share no wire protocol; nothing in this API papers over that, because a portable-looking API that silently never finds the peer is worse than an honest limitation.

For an iPhone that must talk to an Android phone, the framework already has two things that do work across the divide:

- `com.codename1.bluetooth.le.L2capChannel` -- a raw bidirectional byte stream over BLE, on every platform that has BLE.
- `com.codename1.io.bonjour` plus ordinary sockets, when both devices are on the same Wi-Fi network.

##### Quick start

    NearbyTransport.addTransportListener(new TransportAdapter() {
        public void endpointFound(Endpoint e) {
            NearbyTransport.requestConnection(e, "Shai's phone");
        }
        public void connectionRequested(IncomingConnection r) {
            // show r.getAuthenticationToken() on both screens before this
            r.accept();
        }
        public void connected(Endpoint e) {
            NearbyTransport.send(e, Payload.fromBytes(data));
        }
        public void payloadReceived(Endpoint e, Payload p) {
            process(p.getBytes());
        }
    });
    NearbyTransport.startAdvertising("com.example.chat", "Shai's phone",
            TransportStrategy.CLUSTER);
    NearbyTransport.startDiscovery("com.example.chat", TransportStrategy.CLUSTER);

##### Threading

Every callback here is delivered on the EDT.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static void`
  `addTransportListener(TransportListener l)`
  Registers a listener.
  `static void`
  `cancel(int payloadId)`
  Cancels an in-flight payload.
  `static void`
  `disconnect(Endpoint endpoint)`
  Disconnects one endpoint.
  `static NearbyAvailability`
  `getAvailability()`
  How usable the transport is right now.
  `static int`
  `getMaxPayloadSize()`
  The largest byte payload `send(Endpoint, Payload)` accepts in one call.
  `static boolean`
  `isSupported()`
  `true` when this port implements the nearby transport.
  `static void`
  `removeTransportListener(TransportListener l)`
  Removes a listener added by `addTransportListener(TransportListener)`.
  `static AsyncResource<Boolean>`
  `requestConnection(Endpoint endpoint, String localName)`
  Asks a discovered endpoint to connect.
  `static AsyncResource<Boolean>`
  `requestPermissions(NearbyPermission... permissions)`
  Asks for the runtime permissions the transport needs -- on Android that is the Bluetooth trio plus nearby Wi-Fi, which is a lot to ask for at once, so ask when the user reaches the feature rather than at startup.
  `static AsyncResource<Boolean>`
  `send(Endpoint[] endpoints, Payload payload)`
  Sends a payload to several connected endpoints at once, which both platforms do more efficiently than one call each.
  `static AsyncResource<Boolean>`
  `send(Endpoint endpoint, Payload payload)`
  Sends a payload to one connected endpoint.
  `static AsyncResource<Boolean>`
  `startAdvertising(String serviceId, String localName, TransportStrategy strategy)`
  Starts advertising this device so peers running the same service id can find it.
  `static AsyncResource<Boolean>`
  `startDiscovery(String serviceId, TransportStrategy strategy)`
  Starts looking for peers advertising the same service id.
  `static void`
  `stop()`
  Stops advertising and discovery and drops every connection.
  `static void`
  `stopAdvertising()`
  Stops advertising.
  `static void`
  `stopDiscovery()`
  Stops discovery.

  ### Methods inherited from class Object

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

- ## Method Details

  - ### isSupported

    public static boolean isSupported()
    `true` when this port implements the nearby transport.

  - ### getAvailability

    public static NearbyAvailability getAvailability()

    How usable the transport is right now.

    ###### Returns

    the current availability, never null

  - ### getMaxPayloadSize

    public static int getMaxPayloadSize()

    The largest byte payload `send(Endpoint, Payload)` accepts in one call. Anything bigger has to go as a file payload.

    ###### Returns

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

  - ### requestPermissions

    public static AsyncResource<Boolean> requestPermissions(NearbyPermission... permissions)

    Asks for the runtime permissions the transport needs -- on Android that is the Bluetooth trio plus nearby Wi-Fi, which is a lot to ask for at once, so ask when the user reaches the feature rather than at startup.

    ###### Parameters

    - `permissions`: what the app intends to do

    ###### Returns

    resolves `true` when every requested permission is granted

  - ### startAdvertising

    public static AsyncResource<Boolean> startAdvertising(String serviceId, String localName, TransportStrategy strategy)

    Starts advertising this device so peers running the same service id can find it.

    The service id must match exactly on both sides. On iOS it also becomes the Bonjour service type, which the platform restricts to fifteen characters of lowercase letters, digits and hyphens -- so a reverse-DNS string works on Android and is rejected on iOS. Pick a short one.

    ###### Parameters

    - `serviceId`: the service both ends agreed on
    - `localName`: the name to show peers
    - `strategy`: the topology to use; must match on both sides

    ###### Returns

    resolves `true` once the platform is advertising

  - ### stopAdvertising

    public static void stopAdvertising()
    Stops advertising. Idempotent; existing connections stay open.

  - ### startDiscovery

    public static AsyncResource<Boolean> startDiscovery(String serviceId, TransportStrategy strategy)

    Starts looking for peers advertising the same service id. Sightings arrive as `TransportListener.endpointFound(Endpoint)`.

    ###### Parameters

    - `serviceId`: the service both ends agreed on
    - `strategy`: the topology to use; must match on both sides

    ###### Returns

    resolves `true` once the platform is discovering

  - ### stopDiscovery

    public static void stopDiscovery()
    Stops discovery. Idempotent; existing connections stay open.

  - ### requestConnection

    public static AsyncResource<Boolean> requestConnection(Endpoint endpoint, String localName)

    Asks a discovered endpoint to connect.

    The resource here resolves once the request has been sent, which is not the same as being connected: the far side still has to accept, and that answer arrives as `TransportListener.connected(Endpoint)` or `TransportListener.connectionFailed(Endpoint, NearbyException)`.

    ###### Parameters

    - `endpoint`: the peer to ask
    - `localName`: the name to show them

    ###### Returns

    resolves `true` once the request has been sent

  - ### send

    public static AsyncResource<Boolean> send(Endpoint endpoint, Payload payload)

    Sends a payload to one connected endpoint.

    ###### Parameters

    - `endpoint`: the recipient
    - `payload`: what to send

    ###### Returns

    resolves `true` once the payload is handed to the platform. Delivery is reported by `TransportListener.payloadProgress(Endpoint, PayloadTransferUpdate)`.

  - ### send

    public static AsyncResource<Boolean> send(Endpoint[] endpoints, Payload payload)

    Sends a payload to several connected endpoints at once, which both platforms do more efficiently than one call each.

    ###### Parameters

    - `endpoints`: the recipients
    - `payload`: what to send

    ###### Returns

    resolves `true` once the payload is handed to the platform

  - ### cancel

    public static void cancel(int payloadId)

    Cancels an in-flight payload. Idempotent.

    The send reaches `PayloadStatus.CANCELED` on this side, and a transfer the platform can still recall is recalled -- which for a file is every byte not yet sent, on all three implementations.

    A BYTE payload is a different matter, and the same on every one of them: it is handed to the platform whole, and no platform offers a handle to take it back. Cancelling one that has already been accepted stops this side reporting it as delivered, but the peer may receive it anyway. Cancel a byte payload to stop waiting on it, not to prevent its arrival.

    ###### Parameters

    - `payloadId`: the id from `Payload.getId()`

  - ### disconnect

    public static void disconnect(Endpoint endpoint)

    Disconnects one endpoint. Idempotent.

    ###### Parameters

    - `endpoint`: the peer to drop

  - ### stop

    public static void stop()
    Stops advertising and discovery and drops every connection. Call it when the feature's UI closes: both platforms keep the radios busy until something says stop.

  - ### addTransportListener

    public static void addTransportListener(TransportListener l)

    Registers a listener. Callbacks arrive on the EDT.

    ###### Parameters

    - `l`: the listener to add

  - ### removeTransportListener

    public static void removeTransportListener(TransportListener l)

    Removes a listener added by `addTransportListener(TransportListener)`.

    ###### Parameters

    - `l`: the listener to remove