Android APIs
public interface

Connections

com.google.android.gms.nearby.connection.Connections

Class Overview

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

Summary

Nested Classes
interface Connections.ConnectionRequestListener Listener invoked when a remote endpoint requests a connection to a local endpoint. 
interface Connections.ConnectionResponseCallback Callback for responses to connection requests. 
interface Connections.EndpointDiscoveryListener Listener invoked during endpoint discovery. 
interface Connections.MessageListener Listener for messages from a remote endpoint. 
interface Connections.StartAdvertisingResult Result delivered when a local endpoint starts being advertised. 
Constants
long DURATION_INDEFINITE Value for duration meaning advertising / discovery should continue indefinitely until the application asks it to stop.
int MAX_RELIABLE_MESSAGE_LEN This gives the maximum payload size supported via the sendReliableMessage(GoogleApiClient, String, byte[]), sendConnectionRequest(GoogleApiClient, String, String, byte[], Connections.ConnectionResponseCallback, Connections.MessageListener), and acceptConnectionRequest(GoogleApiClient, String, byte[], Connections.MessageListener) methods.
int MAX_UNRELIABLE_MESSAGE_LEN This gives the maximum payload size supported via the sendUnreliableMessage(GoogleApiClient, String, byte[]) methods.
Public Methods
abstract PendingResult<Status> acceptConnectionRequest(GoogleApiClient apiClient, String remoteEndpointId, byte[] payload, Connections.MessageListener messageListener)
Accepts a connection request from a remote endpoint.
abstract void disconnectFromEndpoint(GoogleApiClient apiClient, String remoteEndpointId)
Disconnects from a remote endpoint.
abstract String getLocalDeviceId(GoogleApiClient apiClient)
Returns the ID of the device, used when communicating with other devices.
abstract String getLocalEndpointId(GoogleApiClient apiClient)
Returns the ID of the local endpoint, used when communicating with other devices.
abstract PendingResult<Status> rejectConnectionRequest(GoogleApiClient apiClient, String remoteEndpointId)
Rejects a connection request from a remote endpoint.
abstract PendingResult<Status> sendConnectionRequest(GoogleApiClient apiClient, String name, String remoteEndpointId, byte[] payload, Connections.ConnectionResponseCallback connectionResponseCallback, Connections.MessageListener messageListener)
Sends a request to connect to a remote endpoint.
abstract void sendReliableMessage(GoogleApiClient apiClient, List<String> remoteEndpointIds, byte[] payload)
Sends a message to a list of remote endpoints using a reliable protocol.
abstract void sendReliableMessage(GoogleApiClient apiClient, String remoteEndpointId, byte[] payload)
Sends a message to a remote endpoint using a reliable protocol.
abstract void sendUnreliableMessage(GoogleApiClient apiClient, String remoteEndpointId, byte[] payload)
Sends a message to a remote endpoint using an unreliable protocol.
abstract void sendUnreliableMessage(GoogleApiClient apiClient, List<String> remoteEndpointIds, byte[] payload)
Sends a message to a list of remote endpoints using an unreliable protocol.
abstract PendingResult<Connections.StartAdvertisingResult> startAdvertising(GoogleApiClient apiClient, String name, AppMetadata appMetadata, long durationMillis, Connections.ConnectionRequestListener connectionRequestListener)
Starts advertising an endpoint for a local app.
abstract PendingResult<Status> startDiscovery(GoogleApiClient apiClient, String serviceId, long durationMillis, Connections.EndpointDiscoveryListener listener)
Starts discovery for remote endpoints with the specified service ID.
abstract void stopAdvertising(GoogleApiClient apiClient)
Stops advertising a local endpoint.
abstract void stopAllEndpoints(GoogleApiClient apiClient)
Stops advertising and discovery and disconnects from all endpoints.
abstract void stopDiscovery(GoogleApiClient apiClient, String serviceId)
Stops discovery for remote endpoints with the specified service ID.

Constants

public static final long DURATION_INDEFINITE

Value for duration meaning advertising / discovery should continue indefinitely until the application asks it to stop.

Constant Value: 0 (0x0000000000000000)

public static final int MAX_UNRELIABLE_MESSAGE_LEN

This gives the maximum payload size supported via the sendUnreliableMessage(GoogleApiClient, String, byte[]) methods.

Constant Value: 1168 (0x00000490)

Public Methods

public abstract PendingResult<Status> acceptConnectionRequest (GoogleApiClient apiClient, String remoteEndpointId, byte[] payload, Connections.MessageListener messageListener)

Accepts a connection request from a remote endpoint. This method must be called before messages can be received from the remote endpoint.

Possible result status codes include:

Required API: CONNECTIONS_API
Required Scopes: None

Parameters
apiClient The GoogleApiClient to service the call.
remoteEndpointId The identifier for the remote endpoint that sent the connection request. Should match the value provided in a call to onConnectionRequest(String, String, String, byte[]).
payload Bytes of a custom message to send with the connection response. This message must not exceed MAX_RELIABLE_MESSAGE_LEN bytes in length.
messageListener A listener notified when a message is received from the remote endpoint, or it disconnects.
Returns
  • PendingResult to access the status of the operation when available.

public abstract void disconnectFromEndpoint (GoogleApiClient apiClient, String remoteEndpointId)

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

Required API: CONNECTIONS_API
Required Scopes: None

Parameters
apiClient The GoogleApiClient to service the call.
remoteEndpointId The identifier for the remote endpoint to disconnect from.

public abstract String getLocalDeviceId (GoogleApiClient apiClient)

Returns the ID of the device, used when communicating with other devices. This identifier will be the same for all clients on this device, and will be stable across reboots of the device.

Returns
  • The local device id.

public abstract String getLocalEndpointId (GoogleApiClient apiClient)

Returns the ID of the local endpoint, used when communicating with other devices. This identifier will be different for each GoogleApiClient.

Returns
  • The local endpoint id.

public abstract PendingResult<Status> rejectConnectionRequest (GoogleApiClient apiClient, String remoteEndpointId)

Rejects a connection request from a remote endpoint.

Possible result status codes include:

Required API: CONNECTIONS_API
Required Scopes: None

Parameters
apiClient The GoogleApiClient to service the call.
remoteEndpointId The identifier for the remote endpoint that sent the connection request. Should match the value provided in a call to onConnectionRequest(String, String, String, byte[]).
Returns
  • PendingResult to access the status of the operation when available.

public abstract PendingResult<Status> sendConnectionRequest (GoogleApiClient apiClient, String name, String remoteEndpointId, byte[] payload, Connections.ConnectionResponseCallback connectionResponseCallback, Connections.MessageListener messageListener)

Sends a request to connect to a remote endpoint.

Possible result status codes include:

Required API: CONNECTIONS_API
Required Scopes: None

Parameters
apiClient The GoogleApiClient to service the call.
name A human readable name for the local endpoint, to appear on the remote endpoint. If null or empty, a name will be generated based on the device name or model.
remoteEndpointId The identifier for the remote endpoint to which a connection request will be sent. Should match the value provided in a call to onEndpointFound(String, String, String, String)
payload Bytes of a custom message to send with the connection request. This message must not exceed MAX_RELIABLE_MESSAGE_LEN bytes in length.
connectionResponseCallback A callback notified when the remote endpoint sends a response to the connection request.
messageListener A listener notified when a message is received from the remote endpoint, or it disconnects.
Returns
  • PendingResult to access the status of the operation when available.

public abstract void sendReliableMessage (GoogleApiClient apiClient, List<String> remoteEndpointIds, byte[] payload)

Sends a message to a list of remote endpoints using a reliable protocol. Reliable messages will be retried until delivered, and are delivered in the order they were sent to a given endpoint. Messages can only be sent to remote endpoints once a connection request was first sent and accepted (in either direction).

Required API: CONNECTIONS_API
Required Scopes: None

Parameters
apiClient The GoogleApiClient to service the call.
remoteEndpointIds The identifiers for the remote endpoints to which the message should be sent.
payload The bytes of the message to send to the remote endpoint. This message must not exceed MAX_RELIABLE_MESSAGE_LEN bytes in length.

public abstract void sendReliableMessage (GoogleApiClient apiClient, String remoteEndpointId, byte[] payload)

Sends a message to a remote endpoint using a reliable protocol. Reliable messages will be retried until delivered, and are delivered in the order they were sent to a given endpoint. Messages can only be sent to remote endpoints once a connection request was first sent and accepted (in either direction).

Required API: CONNECTIONS_API
Required Scopes: None

Parameters
apiClient The GoogleApiClient to service the call.
remoteEndpointId The identifier for the remote endpoint to which the message should be sent.
payload The bytes of the message to send to the remote endpoint. This message must not exceed MAX_RELIABLE_MESSAGE_LEN bytes in length.

public abstract void sendUnreliableMessage (GoogleApiClient apiClient, String remoteEndpointId, byte[] payload)

Sends a message to a remote endpoint using an unreliable protocol. Unreliable messages may be dropped or delivered out of order. Messages can only be sent to remote endpoints once a connection request was first sent and accepted (in either direction).

Required API: CONNECTIONS_API
Required Scopes: None

Parameters
apiClient The GoogleApiClient to service the call.
remoteEndpointId The identifier for the remote endpoint to which the message should be sent.
payload The bytes of the message to send to the remote endpoint. This message must not exceed MAX_UNRELIABLE_MESSAGE_LEN bytes in length.

public abstract void sendUnreliableMessage (GoogleApiClient apiClient, List<String> remoteEndpointIds, byte[] payload)

Sends a message to a list of remote endpoints using an unreliable protocol. Unreliable messages may be dropped or delivered out of order. Messages can only be sent to remote endpoints once a connection request was first sent and accepted (in either direction).

Required API: CONNECTIONS_API
Required Scopes: None

Parameters
apiClient The GoogleApiClient to service the call.
remoteEndpointIds The identifiers for the remote endpoints to which the message should be sent.
payload The bytes of the message to send to the remote endpoint. This message must not exceed MAX_UNRELIABLE_MESSAGE_LEN bytes in length.

public abstract PendingResult<Connections.StartAdvertisingResult> startAdvertising (GoogleApiClient apiClient, String name, AppMetadata appMetadata, long durationMillis, Connections.ConnectionRequestListener connectionRequestListener)

Starts advertising an endpoint for a local app.

To advertise an endpoint you must specify a service ID in a meta-data tag with the name com.google.android.gms.nearby.connection.SERVICE_ID inside your application tag, like so:

Required API: CONNECTIONS_API
Required Scopes: None

Parameters
apiClient The GoogleApiClient to service the call.
name A human readable name for this endpoint, to appear on other devices. If null or empty, a name will be generated based on the device name or model.
appMetadata Metadata used to describe this application which can be used to prompt the user to launch or install the application. If null, only applications looking for the specified service ID will be able to discover this endpoint.
durationMillis The duration of the advertisement in milliseconds, unless stopAdvertising(com.google.android.gms.common.api.GoogleApiClient) is called first. If DURATION_INDEFINITE is passed in, the advertisement will continue indefinitely until stopAdvertising(com.google.android.gms.common.api.GoogleApiClient) is called.
connectionRequestListener A listener notified when remote endpoints request a connection to this endpoint.
Returns

public abstract PendingResult<Status> startDiscovery (GoogleApiClient apiClient, String serviceId, long durationMillis, Connections.EndpointDiscoveryListener listener)

Starts discovery for remote endpoints with the specified service ID.

Possible result status codes include:

Required API: CONNECTIONS_API
Required Scopes: None

Parameters
apiClient The GoogleApiClient to service the call.
serviceId The ID for the service to be discovered, as specified in its manifest.
durationMillis The duration of discovery in milliseconds, unless stopDiscovery(com.google.android.gms.common.api.GoogleApiClient, String) is called first. If DURATION_INDEFINITE is passed in, discovery will continue indefinitely until stopDiscovery(com.google.android.gms.common.api.GoogleApiClient, String) is called.
listener A listener notified when a remote endpoint is discovered.
Returns
  • PendingResult to access the status of the operation when available.

public abstract void stopAdvertising (GoogleApiClient apiClient)

Stops advertising a local endpoint. Should be called after calling startAdvertising(com.google.android.gms.common.api.GoogleApiClient, String, AppMetadata, long, ConnectionRequestListener), as soon as the application no longer needs to advertise itself or goes inactive. Messages can still be sent to remote endpoints after advertising ends.

Required API: CONNECTIONS_API
Required Scopes: None

Parameters
apiClient The GoogleApiClient to service the call.

public abstract void stopAllEndpoints (GoogleApiClient apiClient)

Stops advertising and discovery and disconnects from all endpoints.

Required API: CONNECTIONS_API
Required Scopes: None

Parameters
apiClient The GoogleApiClient to service the call.

public abstract void stopDiscovery (GoogleApiClient apiClient, String serviceId)

Stops discovery for remote endpoints with the specified service ID. Should be called after calling startDiscovery(com.google.android.gms.common.api.GoogleApiClient, String, long, EndpointDiscoveryListener), with the same service ID value, as soon as the client no longer needs to discover endpoints or goes inactive. Messages can still be sent to remote endpoints after discovery ends.

Required API: CONNECTIONS_API
Required Scopes: None

Parameters
apiClient The GoogleApiClient to service the call.
serviceId The ID for the service to stop being discovered.