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 functions
open suspend Result<RemoteConnection>
acceptConnection(channelName: String)

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

Java-compatible version of acceptConnection.
suspend Unit

Closes this participant and all the associated RemoteConnections.
ListenableFuture<Void?>

Java-compatible version of close.
open suspend Result<RemoteConnection>
openConnection(channelName: String)

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

Java-compatible version of openConnection.

Public properties
List<RemoteConnection>

The list of connections connected to this participant.
CharSequence

A user-friendly name of the selected device.

Public functions

acceptConnection

open suspend fun acceptConnection(channelName: String): Result<RemoteConnection>

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
channelName: String

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

fun acceptConnectionFuture(channelName: String): ListenableFuture<RemoteConnection>

Java-compatible version of acceptConnection.

close

suspend fun close(): Unit

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

closeFuture

fun closeFuture(): ListenableFuture<Void?>

Java-compatible version of close.

openConnection

open suspend fun openConnection(channelName: String): Result<RemoteConnection>

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
channelName: String

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

fun openConnectionFuture(channelName: String): ListenableFuture<RemoteConnection>

Java-compatible version of openConnection.

Public properties

connections

val connections: List<RemoteConnection>

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

displayName

val displayName: CharSequence

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