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) This method is deprecated. The local device ID is no longer exposed. This method will be removed in a future release.
abstract String | getLocalEndpointId(GoogleApiClient apiClient) This method is deprecated. The local endpoint ID is no longer exposed. This method will be removed in a future release.
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_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.

Constant Value: 4096 (0x00001000)

#### 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:

- `STATUS_OK` if the connection request was accepted.
- `STATUS_NETWORK_NOT_CONNECTED` if the device is not connected to a network.
- `STATUS_ALREADY_CONNECTED_TO_ENDPOINT` if the app already has a connection to the specified endpoint.

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)

This method is deprecated.
The local device ID is no longer exposed. This method will be removed in a future release.

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)

This method is deprecated.
The local endpoint ID is no longer exposed. This method will be removed in a future release.

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:

- `STATUS_OK` if the connection request was rejected.
- `STATUS_NETWORK_NOT_CONNECTED` if the device is not connected to a network.
- `STATUS_ALREADY_CONNECTED_TO_ENDPOINT` if the app already has a connection to the specified endpoint.

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:

- `STATUS_OK` if the connection request was sent.
- `STATUS_NETWORK_NOT_CONNECTED` if the device is not connected to a network.
- `STATUS_ALREADY_CONNECTED_TO_ENDPOINT` if the app already has a connection to the specified endpoint.

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

- `PendingResult` to access the data when available.

#### 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:

- `STATUS_OK` if discovery started successfully.
- `STATUS_NETWORK_NOT_CONNECTED` if the device is not connected to a network.
- `STATUS_ALREADY_DISCOVERING` if the app is already discovering the specified service.

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.