Connections | Google APIs for Android

Connections

public interface Connections

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

Nested Class Summary

class	Connections.ConnectionRequestListener	This class was deprecated. Use `ConnectionLifecycleCallback` instead.
interface	Connections.ConnectionResponseCallback	This interface was deprecated. Use `ConnectionLifecycleCallback` instead.
class	Connections.EndpointDiscoveryListener	This class was deprecated. Use `EndpointDiscoveryCallback` instead.
interface	Connections.MessageListener	This interface was deprecated. Use `PayloadCallback` instead.
interface	Connections.StartAdvertisingResult	Result delivered when a local endpoint starts being advertised.

Constant Summary

long	DURATION_INDEFINITE	This constant was deprecated. Durations are no longer supported.
int	MAX_BYTES_DATA_SIZE	This specifies the maximum allowed size of `BYTES` `Payload`s sent via the `sendPayload(GoogleApiClient, String, Payload)` method.
int	MAX_RELIABLE_MESSAGE_LEN	This constant was deprecated. Use `MAX_BYTES_DATA_SIZE`.
int	MAX_UNRELIABLE_MESSAGE_LEN	This constant was deprecated. Use `MAX_BYTES_DATA_SIZE`.

Public Method Summary

abstract PendingResult<Status>	acceptConnection(GoogleApiClient apiClient, String endpointId, PayloadCallback payloadCallback) Accepts a connection to a remote endpoint.
abstract PendingResult<Status>	acceptConnectionRequest(GoogleApiClient apiClient, String endpointId, byte[] handshakeData, Connections.MessageListener messageListener) This method was deprecated. Use `acceptConnection(GoogleApiClient, String, PayloadCallback)` instead.
abstract void	disconnectFromEndpoint(GoogleApiClient apiClient, String endpointId) Disconnects from a remote endpoint.
abstract PendingResult<Status>	rejectConnection(GoogleApiClient apiClient, String endpointId) Rejects a connection to a remote endpoint.
abstract PendingResult<Status>	rejectConnectionRequest(GoogleApiClient apiClient, String remoteEndpointId) This method was deprecated. Use `rejectConnection(GoogleApiClient, String)` instead.
abstract PendingResult<Status>	requestConnection(GoogleApiClient apiClient, String name, String endpointId, ConnectionLifecycleCallback connectionLifecycleCallback) Sends a request to connect to a remote endpoint.
abstract PendingResult<Status>	sendConnectionRequest(GoogleApiClient apiClient, String name, String remoteEndpointId, byte[] handshakeData, Connections.ConnectionResponseCallback connectionResponseCallback, Connections.MessageListener messageListener) This method was deprecated. Use `requestConnection(GoogleApiClient, String, String, ConnectionLifecycleCallback)` instead.
abstract PendingResult<Status>	sendPayload(GoogleApiClient apiClient, String endpointId, Payload payload) Sends a `Payload` to a remote endpoint.
abstract PendingResult<Status>	sendPayload(GoogleApiClient apiClient, List<String> endpointIds, Payload payload) Variant of `sendPayload(GoogleApiClient, String, Payload)` that takes a list of remote endpoint IDs.
abstract void	sendReliableMessage(GoogleApiClient apiClient, List<String> remoteEndpointIds, byte[] payload) This method was deprecated. Use `sendPayload(GoogleApiClient, List, Payload)` with `BYTES` instead.
abstract void	sendReliableMessage(GoogleApiClient apiClient, String remoteEndpointId, byte[] payload) This method was deprecated. Use `sendPayload(GoogleApiClient, String, Payload)` with `BYTES` instead.
abstract void	sendUnreliableMessage(GoogleApiClient apiClient, String remoteEndpointId, byte[] payload) This method was deprecated. Use `sendPayload(GoogleApiClient, String, Payload)` with `BYTES` instead.
abstract void	sendUnreliableMessage(GoogleApiClient apiClient, List<String> remoteEndpointIds, byte[] payload) This method was deprecated. Use `sendPayload(GoogleApiClient, List, Payload)` with `BYTES` instead.
abstract PendingResult<Connections.StartAdvertisingResult>	startAdvertising(GoogleApiClient apiClient, String name, String serviceId, ConnectionLifecycleCallback connectionLifecycleCallback, AdvertisingOptions options) Starts advertising an endpoint for a local app.
abstract PendingResult<Connections.StartAdvertisingResult>	startAdvertising(GoogleApiClient apiClient, String name, AppMetadata appMetadata, long durationMillis, Connections.ConnectionRequestListener connectionRequestListener) This method was deprecated. Use `startAdvertising(GoogleApiClient, String, String, ConnectionLifecycleCallback, AdvertisingOptions)` instead.
abstract PendingResult<Status>	startDiscovery(GoogleApiClient apiClient, String serviceId, long durationMillis, Connections.EndpointDiscoveryListener listener) This method was deprecated. Use `startDiscovery(GoogleApiClient, String, EndpointDiscoveryCallback, DiscoveryOptions)` instead.
abstract PendingResult<Status>	startDiscovery(GoogleApiClient apiClient, String serviceId, EndpointDiscoveryCallback endpointDiscoveryCallback, DiscoveryOptions options) 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) Disconnects from, and removes all traces of, all connected and/or discovered endpoints.
abstract void	stopDiscovery(GoogleApiClient apiClient) Stops discovery for remote endpoints, after a previous call to `startDiscovery(GoogleApiClient, String, com.google.android.gms.nearby.connection.EndpointDiscoveryCallback, DiscoveryOptions)`, when the client no longer needs to discover endpoints or goes inactive.
abstract void	stopDiscovery(GoogleApiClient apiClient, String serviceId) This method was deprecated. Use `stopDiscovery(GoogleApiClient)` instead. You can only discover for a single serviceId at a time, so no need to pass in the serviceId.

Constants

public static final long DURATION_INDEFINITE

This constant was deprecated.
Durations are no longer supported.

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

Constant Value: 0

public static final int MAX_BYTES_DATA_SIZE

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

Constant Value: 32768

public static final int MAX_RELIABLE_MESSAGE_LEN

This constant was deprecated.
Use MAX_BYTES_DATA_SIZE.

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

public static final int MAX_UNRELIABLE_MESSAGE_LEN

This constant was deprecated.
Use MAX_BYTES_DATA_SIZE.

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

Constant Value: 1168

Public Methods

public abstract PendingResult<Status> acceptConnection (GoogleApiClient apiClient, 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:

STATUS_OK if the connection request was accepted.
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.
endpointId	The identifier for the remote endpoint. Should match the value provided in a call to `onConnectionInitiated(String, ConnectionInfo)`.
payloadCallback	A callback for payloads exchanged with the remote endpoint.

Returns

PendingResult to access the status of the operation when available.

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

This method was deprecated.
Use acceptConnection(GoogleApiClient, String, PayloadCallback) instead.

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_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.
endpointId	The identifier for the remote endpoint that sent the connection request. Should match the value provided in a call to `onConnectionRequest(String, String, byte[])`.
handshakeData	Bytes of a custom message to send with the connection response. This message must not exceed `MAX_BYTES_DATA_SIZE` 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 endpointId)

Disconnects from a remote endpoint. Payloads 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.
endpointId	The identifier for the remote endpoint to disconnect from.

public abstract PendingResult<Status> rejectConnection (GoogleApiClient apiClient, String endpointId)

Rejects a connection to a remote endpoint.

Possible result status codes include:

STATUS_OK if the connection request was rejected.
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.
endpointId	The identifier for the remote endpoint. Should match the value provided in a call to `onConnectionInitiated(String, ConnectionInfo)`.

Returns

PendingResult to access the status of the operation when available.

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

This method was deprecated.
Use rejectConnection(GoogleApiClient, String) instead.

Rejects a connection request from a remote endpoint.

Possible result status codes include:

STATUS_OK if the connection request was rejected.
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, byte[])`.

Returns

PendingResult to access the status of the operation when available.

public abstract PendingResult<Status> requestConnection (GoogleApiClient apiClient, String name, String endpointId, ConnectionLifecycleCallback connectionLifecycleCallback)

Sends a request to connect to a remote endpoint.

Possible result status codes include:

STATUS_OK if the connection request was sent.
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.
endpointId	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, DiscoveredEndpointInfo)`
connectionLifecycleCallback	A callback notified when the remote endpoint sends a response to the connection request.

Returns

PendingResult to access the status of the operation when available.

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

This method was deprecated.
Use requestConnection(GoogleApiClient, String, String, ConnectionLifecycleCallback) instead.

Sends a request to connect to a remote endpoint.

Possible result status codes include:

STATUS_OK if the connection request was sent.
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)`
handshakeData	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 PendingResult<Status> sendPayload (GoogleApiClient apiClient, 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 onConnectionResult(String, ConnectionResolution)

Possible result status codes include:

STATUS_OUT_OF_ORDER_API_CALL if the device has not first performed advertisement or discovery (to set the Strategy).
STATUS_ENDPOINT_UNKNOWN if there's no active (or pending) connection to the remote endpoint.
STATUS_OK if none of the above errors occurred. Note that this indicates that Nearby Connections will attempt to send the Payload, but not that the send has successfully completed yet. Errors might still occur during transmission (and at different times for different endpoints), and will be delivered via onPayloadTransferUpdate(String, PayloadTransferUpdate).

Required API: CONNECTIONS_API
Required Scopes: None

Parameters

apiClient	The `GoogleApiClient` to service the call.
endpointId	The identifier for the remote endpoint to which the payload should be sent.
payload	The `Payload` to be sent.

Returns

PendingResult to access the status of the operation when available.

public abstract PendingResult<Status> sendPayload (GoogleApiClient apiClient, List<String> endpointIds, Payload payload)

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

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

This method was deprecated.
Use sendPayload(GoogleApiClient, List, Payload) with BYTES instead.

Variant of sendReliableMessage(GoogleApiClient, String, byte[]) that takes a list of remote endpoint IDs.

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

This method was deprecated.
Use sendPayload(GoogleApiClient, String, Payload) with BYTES instead.

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)

This method was deprecated.
Use sendPayload(GoogleApiClient, String, Payload) with BYTES instead.

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)

This method was deprecated.
Use sendPayload(GoogleApiClient, List, Payload) with BYTES instead.

Variant of sendUnreliableMessage(GoogleApiClient, String, byte[]) that takes a list of remote endpoint IDs.

public abstract PendingResult<Connections.StartAdvertisingResult> startAdvertising (GoogleApiClient apiClient, String name, String serviceId, ConnectionLifecycleCallback connectionLifecycleCallback, AdvertisingOptions options)

Starts advertising an endpoint for a local app.

Possible result status codes include:

STATUS_OK if advertising started successfully.
STATUS_ALREADY_ADVERTISING if the app is already advertising.
STATUS_OUT_OF_ORDER_API_CALL if the app is currently connected to remote endpoints; call stopAllEndpoints(GoogleApiClient) first.

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

PendingResult to access the data when available.

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

This method was deprecated.
Use startAdvertising(GoogleApiClient, String, String, ConnectionLifecycleCallback, AdvertisingOptions) instead.

Starts advertising an endpoint for a local app.

Possible result status codes include:

STATUS_OK if advertising started successfully.
STATUS_ALREADY_DISCOVERING if the app is currently discovering.
STATUS_ALREADY_ADVERTISING if the app is already advertising.
STATUS_OUT_OF_ORDER_API_CALL if the app is currently connected to remote endpoints; call stopAllEndpoints(GoogleApiClient) first.

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)

This method was deprecated.
Use startDiscovery(GoogleApiClient, String, EndpointDiscoveryCallback, DiscoveryOptions) instead.

Starts discovery for remote endpoints with the specified service ID.

Possible result status codes include:

STATUS_OK if discovery started successfully.
STATUS_ALREADY_DISCOVERING if the app is already discovering the specified service.
STATUS_ALREADY_ADVERTISING if the app is currently advertising.
STATUS_OUT_OF_ORDER_API_CALL if the app is currently connected to remote endpoints; call stopAllEndpoints(GoogleApiClient) first.

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 PendingResult<Status> startDiscovery (GoogleApiClient apiClient, String serviceId, EndpointDiscoveryCallback endpointDiscoveryCallback, DiscoveryOptions options)

Starts discovery for remote endpoints with the specified service ID.

Possible result status codes include:

STATUS_OK if discovery started successfully.
STATUS_ALREADY_DISCOVERING if the app is already discovering the specified service.
STATUS_OUT_OF_ORDER_API_CALL if the app is currently connected to remote endpoints; call stopAllEndpoints(GoogleApiClient) first.

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 the corresponding call to `startAdvertising(GoogleApiClient, String, String, ConnectionLifecycleCallback, AdvertisingOptions)`.
endpointDiscoveryCallback	A callback notified when a remote endpoint is discovered.
options	The options for discovery.

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(GoogleApiClient, 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.

Required API: CONNECTIONS_API
Required Scopes: None

Parameters

apiClient	The `GoogleApiClient` to service the call.

public abstract void stopAllEndpoints (GoogleApiClient apiClient)

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(GoogleApiClient) or startDiscovery(GoogleApiClient, String, EndpointDiscoveryCallback, DiscoveryOptions) as needed. After calling stopAllEndpoints(GoogleApiClient), no further operations with remote endpoints will be possible until a new call to one of startAdvertising(GoogleApiClient, String, String, ConnectionLifecycleCallback, AdvertisingOptions) or startDiscovery(GoogleApiClient, String, EndpointDiscoveryCallback, DiscoveryOptions).

Required API: CONNECTIONS_API
Required Scopes: None

Parameters

apiClient	The `GoogleApiClient` to service the call.

public abstract void stopDiscovery (GoogleApiClient apiClient)

Stops discovery for remote endpoints, after a previous call to startDiscovery(GoogleApiClient, String, com.google.android.gms.nearby.connection.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.

Required API: CONNECTIONS_API
Required Scopes: None

Parameters

apiClient	The `GoogleApiClient` to service the call.

public abstract void stopDiscovery (GoogleApiClient apiClient, String serviceId)

This method was deprecated.
Use stopDiscovery(GoogleApiClient) instead. You can only discover for a single serviceId at a time, so no need to pass in the 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.

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License, and code samples are licensed under the Apache 2.0 License. For details, see our Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

上次更新日期：六月 7, 2017