Sessions

@RequiresApi(value = 26) interface Sessions

Entry-point for creating and interacting with Sessions. Create a client by calling Sessions.create.

Summary

Nested types
Sessions.Companion

Public functions
SessionId
createSession(applicationSessionTag: ApplicationSessionTag?)

Creates a Session which can be be transferred to or shared with another device.
suspend ReceivingSession
getReceivingSession(
    intent: Intent,
    callback: ReceivingSessionStateCallback
)

Receives a ReceivingSession to transfer a Session to this device.
ListenableFuture<ReceivingSession>

Java-compatible version of getReceivingSession.
suspend SecondarySession
getSecondarySession(
    intent: Intent,
    callback: SecondarySessionStateCallback
)

Receives a SecondarySession to join a Session from this device.
ListenableFuture<SecondarySession>

Java-compatible version of getSecondarySession.
Unit
registerActivityResultCaller(
    activityResultCaller: ActivityResultCaller
)

Registers an ActivityResultCaller to enable Sessions to show available devices via Discovery's device launcher.
suspend Unit

Removes a Session so that it can no longer be discovered by other devices requesting transfer or share.
ListenableFuture<Void?>

Java-compatible version of removeSession.
suspend PrimarySession
shareSession(
    sessionId: SessionId,
    startComponentRequest: StartComponentRequest,
    deviceFilters: List<DeviceFilter>,
    callback: PrimarySessionStateCallback
)

Invites another device to join a Session currently running on the device this function is called on.
ListenableFuture<PrimarySession>
shareSessionFuture(
    sessionId: SessionId,
    startComponentRequest: StartComponentRequest,
    deviceFilters: List<DeviceFilter>,
    callback: PrimarySessionStateCallback
)

Java-compatible version of shareSession.
suspend OriginatingSession
transferSession(
    sessionId: SessionId,
    startComponentRequest: StartComponentRequest,
    deviceFilters: List<DeviceFilter>,
    callback: OriginatingSessionStateCallback
)

Transfers a Session from the device this function is called on to another.
ListenableFuture<OriginatingSession>
transferSessionFuture(
    sessionId: SessionId,
    startComponentRequest: StartComponentRequest,
    deviceFilters: List<DeviceFilter>,
    callback: OriginatingSessionStateCallback
)

Java-compatible version of transferSession.

Public functions

createSession

fun createSession(applicationSessionTag: ApplicationSessionTag? = null): SessionId

Creates a Session which can be be transferred to or shared with another device. Returns the SessionId associated with that Session.

Parameters
applicationSessionTag: ApplicationSessionTag? = null

A client-defined concept that optionally describes the high level type of experience for a Session within an app.

getReceivingSession

suspend fun getReceivingSession(
    intent: Intent,
    callback: ReceivingSessionStateCallback
): ReceivingSession

Receives a ReceivingSession to transfer a Session to this device. Should be called from receiving device after app is launched by D2DI with an intent specified by the originating device.

App should pass the intent it was launched with as a parameter.

Throws
com.google.ambient.crossdevice.sessions.SessionException: com.google.ambient.crossdevice.sessions.SessionException

if unable to return a ReceivingSession.

getReceivingSessionFuture

fun getReceivingSessionFuture(
    intent: Intent,
    callback: ReceivingSessionStateCallback
): ListenableFuture<ReceivingSession>

Java-compatible version of getReceivingSession.

getSecondarySession

suspend fun getSecondarySession(
    intent: Intent,
    callback: SecondarySessionStateCallback
): SecondarySession

Receives a SecondarySession to join a Session from this device. Should be called from receiving device after app is launched by D2DI with an intent specified by the originating device.

App should pass the intent it was launched with as a parameter.

Throws
com.google.ambient.crossdevice.sessions.SessionException: com.google.ambient.crossdevice.sessions.SessionException

if unable to return a SecondarySession.

getSecondarySessionFuture

fun getSecondarySessionFuture(
    intent: Intent,
    callback: SecondarySessionStateCallback
): ListenableFuture<SecondarySession>

Java-compatible version of getSecondarySession.

registerActivityResultCaller

fun registerActivityResultCaller(
    activityResultCaller: ActivityResultCaller
): Unit

Registers an ActivityResultCaller to enable Sessions to show available devices via Discovery's device launcher.

removeSession

suspend fun removeSession(sessionId: SessionId): Unit

Removes a Session so that it can no longer be discovered by other devices requesting transfer or share. If remove fails, a SessionException will be thrown.

This will cancel any ongoing requests for transfer/share ( SessionStateCallback.onTransferFailure, SessionStateCallback.onShareFailure). This will terminate any active shared sessions (Primary and Secondaries will be cleaned up - PrimarySessionStateCallback.onPrimarySessionCleanup, SecondarySessionStateCallback.onSecondarySessionCleanup).

removeSessionFuture

fun removeSessionFuture(sessionId: SessionId): ListenableFuture<Void?>

Java-compatible version of removeSession.

shareSession

suspend fun shareSession(
    sessionId: SessionId,
    startComponentRequest: StartComponentRequest,
    deviceFilters: List<DeviceFilter>,
    callback: PrimarySessionStateCallback
): PrimarySession

Invites another device to join a Session currently running on the device this function is called on.

Opens a dialog that searches for compatible, trusted devices. When the user selects a specific device, the receiving app on that device will receive the request to join the session via StartComponentRequest and can begin initialization (see SecondarySession). StartComponentRequest must contain an action and a user-visible reason for the request, and can optionally contain extras.

If the share cannot be initiated, a SessionException will be thrown.

If the receiving app is ready to accept the share request, PrimarySessionStateCallback.onParticipantJoined is triggered. Otherwise, PrimarySessionStateCallback.onShareFailureWithParticipant is triggered.

Once devices are selected, PrimarySessionStateCallback.onShareInitiated will be called to inform the application of the number of potential participants.

shareSessionFuture

fun shareSessionFuture(
    sessionId: SessionId,
    startComponentRequest: StartComponentRequest,
    deviceFilters: List<DeviceFilter>,
    callback: PrimarySessionStateCallback
): ListenableFuture<PrimarySession>

Java-compatible version of shareSession.

transferSession

suspend fun transferSession(
    sessionId: SessionId,
    startComponentRequest: StartComponentRequest,
    deviceFilters: List<DeviceFilter>,
    callback: OriginatingSessionStateCallback
): OriginatingSession

Transfers a Session from the device this function is called on to another.

Opens a window that searches for compatible, trusted devices. When the user selects a specific device, the receiving app on that device will receive the request to transfer via StartComponentRequest and can begin initialization (see ReceivingSession). StartComponentRequest must contain an action and a user-visible reason for the request, and can optionally contain extras.

If transfer cannot be initiated, a SessionException will be thrown.

If receiving app is ready to accept the transfer, OriginatingSessionStateCallback.onConnected is triggered. Otherwise, OriginatingSessionStateCallback.onTransferFailure is triggered.

transferSessionFuture

fun transferSessionFuture(
    sessionId: SessionId,
    startComponentRequest: StartComponentRequest,
    deviceFilters: List<DeviceFilter>,
    callback: OriginatingSessionStateCallback
): ListenableFuture<OriginatingSession>

Java-compatible version of transferSession.