ConnectionsClient

public interface ConnectionsClient implements HasApiKey<ConnectionsOptions>

Entry point for advertising and discovering nearby apps and services, and communicating with them over established connections.

Constant Summary

int MAX_BYTES_DATA_SIZE This specifies the maximum allowed size of Payload.Type.BYTES Payloads sent via the sendPayload(String, Payload) method.

Public Method Summary

abstract Task<Void>
acceptConnection(String endpointId, PayloadCallback payloadCallback)
Accepts a connection to a remote endpoint.
abstract Task<Void>
cancelPayload(long payloadId)
Cancels a Payload currently in-flight to or from remote endpoint(s).
abstract void
disconnectFromEndpoint(String endpointId)
Disconnects from a remote endpoint.
abstract Task<Void>
rejectConnection(String endpointId)
Rejects a connection to a remote endpoint.
abstract Task<Void>
requestConnection(byte[] endpointInfo, String endpointId, ConnectionLifecycleCallback connectionLifecycleCallback, ConnectionOptions options)
Sends a request to connect to a remote endpoint.
abstract Task<Void>
requestConnection(byte[] endpointInfo, String endpointId, ConnectionLifecycleCallback connectionLifecycleCallback)
Sends a request to connect to a remote endpoint.
abstract Task<Void>
requestConnection(String name, String endpointId, ConnectionLifecycleCallback connectionLifecycleCallback)
Sends a request to connect to a remote endpoint.
abstract Task<Void>
requestConnection(String name, String endpointId, ConnectionLifecycleCallback connectionLifecycleCallback, ConnectionOptions options)
Sends a request to connect to a remote endpoint.
abstract Task<Void>
sendPayload(String endpointId, Payload payload)
Sends a Payload to a remote endpoint.
abstract Task<Void>
sendPayload(List<String> endpointIds, Payload payload)
Variant of sendPayload(String, Payload) that takes a list of remote endpoint IDs.
abstract Task<Void>
startAdvertising(byte[] endpointInfo, String serviceId, ConnectionLifecycleCallback connectionLifecycleCallback, AdvertisingOptions options)
Starts advertising an endpoint for a local app.
abstract Task<Void>
startAdvertising(String name, String serviceId, ConnectionLifecycleCallback connectionLifecycleCallback, AdvertisingOptions options)
Starts advertising an endpoint for a local app.
abstract Task<Void>
startDiscovery(String serviceId, EndpointDiscoveryCallback endpointDiscoveryCallback, DiscoveryOptions options)
Starts discovery for remote endpoints with the specified service ID.
abstract void
stopAdvertising()
Stops advertising a local endpoint.
abstract void
stopAllEndpoints()
Disconnects from, and removes all traces of, all connected and/or discovered endpoints.
abstract void
stopDiscovery()
Stops discovery for remote endpoints, after a previous call to startDiscovery(String, EndpointDiscoveryCallback, DiscoveryOptions), when the client no longer needs to discover endpoints or goes inactive.

Constants

public static final int MAX_BYTES_DATA_SIZE

This specifies the maximum allowed size of Payload.Type.BYTES Payloads sent via the sendPayload(String, Payload) method.

Constant Value: 1047552

Public Methods

public abstract Task<Void> acceptConnection (String endpointId, PayloadCallback payloadCallback)

Accepts a connection to a remote endpoint. This method must be called before Payloads can be exchanged with the remote endpoint.

Possible result status codes include:

Parameters
endpointId The identifier for the remote endpoint. Should match the value provided in a call to ConnectionLifecycleCallback.onConnectionInitiated(String, ConnectionInfo).
payloadCallback A callback for payloads exchanged with the remote endpoint.
Returns
  • Task to access the status of the operation when available.

public abstract Task<Void> cancelPayload (long payloadId)

Cancels a Payload currently in-flight to or from remote endpoint(s).

Parameters
payloadId The identifier for the Payload to be canceled.
Returns
  • Task to access the status of the operation when available.

public abstract void disconnectFromEndpoint (String endpointId)

Disconnects from a remote endpoint. Payloads can no longer be sent to or received from the endpoint after this method is called.

Parameters
endpointId The identifier for the remote endpoint to disconnect from.

public abstract Task<Void> rejectConnection (String endpointId)

Rejects a connection to a remote endpoint.

Possible result status codes include:

Parameters
endpointId The identifier for the remote endpoint. Should match the value provided in a call to ConnectionLifecycleCallback.onConnectionInitiated(String, ConnectionInfo).
Returns
  • Task to access the status of the operation when available.

public abstract Task<Void> requestConnection (byte[] endpointInfo, String endpointId, ConnectionLifecycleCallback connectionLifecycleCallback, ConnectionOptions options)

Sends a request to connect to a remote endpoint.

Possible result status codes include:

Parameters
endpointInfo Identifing information about this endpoint (eg. name, device type), to appear on the remote device. Defined by client/application.
endpointId The identifier for the remote endpoint to which a connection request will be sent. Should match the value provided in a call to EndpointDiscoveryCallback.onEndpointFound(String, DiscoveredEndpointInfo)
connectionLifecycleCallback A callback notified when the remote endpoint sends a response to the connection request.
options The options to set up a connection.
Returns
  • Task to access the status of the operation when available.

public abstract Task<Void> requestConnection (byte[] endpointInfo, String endpointId, ConnectionLifecycleCallback connectionLifecycleCallback)

Sends a request to connect to a remote endpoint.

Possible result status codes include:

Parameters
endpointInfo Identifing information about this endpoint (eg. name, device type), to appear on the remote device. Defined by client/application.
endpointId The identifier for the remote endpoint to which a connection request will be sent. Should match the value provided in a call to EndpointDiscoveryCallback.onEndpointFound(String, DiscoveredEndpointInfo)
connectionLifecycleCallback A callback notified when the remote endpoint sends a response to the connection request.
Returns
  • Task to access the status of the operation when available.

public abstract Task<Void> requestConnection (String name, String endpointId, ConnectionLifecycleCallback connectionLifecycleCallback)

Sends a request to connect to a remote endpoint.

Possible result status codes include:

Parameters
name A human readable name for the local endpoint, to appear on the remote device. Defined by client/application.
endpointId The identifier for the remote endpoint to which a connection request will be sent. Should match the value provided in a call to EndpointDiscoveryCallback.onEndpointFound(String, DiscoveredEndpointInfo)
connectionLifecycleCallback A callback notified when the remote endpoint sends a response to the connection request.
Returns
  • Task to access the status of the operation when available.

public abstract Task<Void> requestConnection (String name, String endpointId, ConnectionLifecycleCallback connectionLifecycleCallback, ConnectionOptions options)

Sends a request to connect to a remote endpoint.

Possible result status codes include:

Parameters
name A human readable name for this endpoint, to appear on the remote device. Defined by client/application.
endpointId The identifier for the remote endpoint to which a connection request will be sent. Should match the value provided in a call to EndpointDiscoveryCallback.onEndpointFound(String, DiscoveredEndpointInfo)
connectionLifecycleCallback A callback notified when the remote endpoint sends a response to the connection request.
options The options to set up a connection.
Returns
  • Task to access the status of the operation when available.

public abstract Task<Void> sendPayload (String endpointId, Payload payload)

Sends a Payload to a remote endpoint. Payloads can only be sent to remote endpoints once a notice of connection acceptance has been delivered via ConnectionLifecycleCallback.onConnectionResult(String, ConnectionResolution)

Possible result status codes include:

Parameters
endpointId The identifier for the remote endpoint to which the payload should be sent.
payload The Payload to be sent.
Returns
  • Task to access the status of the operation when available.

public abstract Task<Void> sendPayload (List<String> endpointIds, Payload payload)

Variant of sendPayload(String, Payload) that takes a list of remote endpoint IDs. If none of the requested endpoints are connected, ConnectionsStatusCodes.STATUS_ENDPOINT_UNKNOWN will be returned.

public abstract Task<Void> startAdvertising (byte[] endpointInfo, String serviceId, ConnectionLifecycleCallback connectionLifecycleCallback, AdvertisingOptions options)

Starts advertising an endpoint for a local app.

Possible result status codes include:

Parameters
endpointInfo Identifing information about this endpoint (eg. name, device type), to appear on the remote device. Defined by client/application.
serviceId An identifier to advertise your app to other endpoints. This can be an arbitrary string, so long as it uniquely identifies your service. A good default is to use your app's package name.
connectionLifecycleCallback A callback notified when remote endpoints request a connection to this endpoint.
options The options for advertising.
Returns
  • Task to access the status of the operation when available.

public abstract Task<Void> startAdvertising (String name, String serviceId, ConnectionLifecycleCallback connectionLifecycleCallback, AdvertisingOptions options)

Starts advertising an endpoint for a local app.

Possible result status codes include:

Parameters
name A human readable name for this endpoint, to appear on the remote device. Defined by client/application.
serviceId An identifier to advertise your app to other endpoints. This can be an arbitrary string, so long as it uniquely identifies your service. A good default is to use your app's package name.
connectionLifecycleCallback A callback notified when remote endpoints request a connection to this endpoint.
options The options for advertising.
Returns
  • Task to access the status of the operation when available.

public abstract Task<Void> startDiscovery (String serviceId, EndpointDiscoveryCallback endpointDiscoveryCallback, DiscoveryOptions options)

Starts discovery for remote endpoints with the specified service ID.

Possible result status codes include:

Parameters
serviceId The ID for the service to be discovered, as specified in the corresponding call to startAdvertising(String, String, ConnectionLifecycleCallback, AdvertisingOptions).
endpointDiscoveryCallback A callback notified when a remote endpoint is discovered.
options The options for discovery.
Returns
  • Task to access the status of the operation when available.

public abstract void stopAdvertising ()

Stops advertising a local endpoint. Should be called after calling startAdvertising(String, String, ConnectionLifecycleCallback, AdvertisingOptions), as soon as the application no longer needs to advertise itself or goes inactive. Payloads can still be sent to connected endpoints after advertising ends.

public abstract void stopAllEndpoints ()

Disconnects from, and removes all traces of, all connected and/or discovered endpoints. This call is expected to be preceded by a call to stopAdvertising() or startDiscovery(String, EndpointDiscoveryCallback, DiscoveryOptions) as needed. After calling stopAllEndpoints(), no further operations with remote endpoints will be possible until a new call to one of startAdvertising(String, String, ConnectionLifecycleCallback, AdvertisingOptions) or startDiscovery(String, EndpointDiscoveryCallback, DiscoveryOptions).

public abstract void stopDiscovery ()

Stops discovery for remote endpoints, after a previous call to startDiscovery(String, EndpointDiscoveryCallback, DiscoveryOptions), when the client no longer needs to discover endpoints or goes inactive. Payloads can still be sent to connected endpoints after discovery ends.