Participant

@RequiresApi(value = 26) interface Participant

An opaque handle that represents a participant in a cross device experience. This participant is expected to be passed back to other Cross device SDK components to identify the desired participant.

Participants are not stable across experiences. If the user starts another experience by selecting the same receiving device, the resulting Participant instance will still be different.

This class is not thread safe.

Summary

Public fields
abstract @NonNull List<@NonNull RemoteConnection>

The list of connections connected to this participant.
abstract @NonNull CharSequence

A user-friendly name of the selected device.

Public methods
default @NonNull Result<@NonNull RemoteConnection>

Accepts an incoming connection from a remote device.
abstract @NonNull ListenableFuture<@NonNull RemoteConnection>

Java-compatible version of acceptConnection.
abstract void

Closes this participant and all the associated RemoteConnections.
abstract @NonNull ListenableFuture<Void>

Java-compatible version of close.
default @NonNull Result<@NonNull RemoteConnection>

Returns a remote channel to send and receive messages.
abstract @NonNull ListenableFuture<@NonNull RemoteConnection>

Java-compatible version of openConnection.

Public fields

connections

abstract @NonNull List<@NonNull RemoteConnection> connections

The list of connections connected to this participant. This list includes both connections opened and accepted.

displayName

abstract @NonNull CharSequence displayName

A user-friendly name of the selected device. This is the same name that the user saw in the device picker, for example, "Ryan's Pixel 6".

Public methods

acceptConnection

default @NonNull Result<@NonNull RemoteConnection> acceptConnection(@NonNull String channelName)

Accepts an incoming connection from a remote device.

This function completes as soon as the connection channel is created, even if there are no listeners registered for this connection on the receiving device yet. Messages can be sent as soon as the connection is created, but they may be queued until a listener is registered.

It is expected that this call will fail for a fraction of cases due to circumstances outside of the application and system's control, such as poor signal strength or wireless interference. Therefore, this method returns a Result and callers should always check and handle the failure cases.

If the connection is not created successfully within an implementation-defined timeout (typically on the order of tens of seconds), the result will fail with the code ConnectionsException.TIMEOUT.

Callers should close the connection after using it by calling either RemoteConnection.close or Participant.close.

Parameters
@NonNull String channelName

A string identifying the channel. This string must be the same on this device and the remote device indicated by participant for the messages to be received successfully. The tuple (callingApp, participant, channelName) must be unique - trying to create a channel with the same name, from the same application, to the same remote device will result in an IllegalArgumentException.

acceptConnectionFuture

abstract @NonNull ListenableFuture<@NonNull RemoteConnection> acceptConnectionFuture(@NonNull String channelName)

Java-compatible version of acceptConnection.

close

abstract void close()

Closes this participant and all the associated RemoteConnections. This participant should not be used after calling this method.

closeFuture

abstract @NonNull ListenableFuture<Void> closeFuture()

Java-compatible version of close.

openConnection

default @NonNull Result<@NonNull RemoteConnection> openConnection(@NonNull String channelName)

Returns a remote channel to send and receive messages.

This function completes as soon as the connection channel is created, even if there are no listeners registered for this connection on the receiving device yet. Messages can be sent as soon as the connection is created, but they may be queued until a listener is registered.

It is expected that this call will fail for a fraction of cases due to circumstances outside of the application and system's control, such as poor signal strength or wireless interference. Therefore, this method returns a Result and callers should always check and handle the failure cases.

If the connection is not created successfully within an implementation-defined timeout (typically on the order of tens of seconds), the result will fail with the code ConnectionsException.TIMEOUT.

Callers should close the connection after using it by calling either RemoteConnection.close or Participant.close.

Parameters
@NonNull String channelName

A string identifying the channel. This string must be the same on this device and the remote device from which this participant was provided for the messages to be received successfully. The tuple (callingApp, participant, channelName) must be unique - trying to create a channel with the same name, from the same application, to the same participant device will result in an IllegalArgumentException.

openConnectionFuture

abstract @NonNull ListenableFuture<@NonNull RemoteConnection> openConnectionFuture(@NonNull String channelName)

Java-compatible version of openConnection.