core/core-telecom/src/main/java/androidx/core/telecom/internal/CallCompat.kt - platform/frameworks/support - Git at Google

 /*
  * Copyright 2023 The Android Open Source Project
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
  *
  *      http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */

 package androidx.core.telecom.internal

 import android.os.Build
 import android.os.Bundle
 import android.telecom.Call
 import android.util.Log
 import androidx.annotation.RequiresApi
 import androidx.annotation.VisibleForTesting
 import androidx.core.telecom.CallsManager
 import androidx.core.telecom.extensions.Capability
 import androidx.core.telecom.extensions.CapabilityExchange
 import androidx.core.telecom.extensions.ParticipantClientActions
 import androidx.core.telecom.extensions.ParticipantClientActionsImpl
 import androidx.core.telecom.internal.utils.CapabilityExchangeUtils
 import androidx.core.telecom.util.ExperimentalAppActions
 import java.util.concurrent.CancellationException
 import java.util.concurrent.TimeUnit
 import kotlin.math.min
 import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.async
 import kotlinx.coroutines.withTimeout

 @ExperimentalAppActions
 @RequiresApi(Build.VERSION_CODES.O)
 internal class CallCompat(
     private val call: Call,
     val scope: CoroutineScope,
 ) {
     internal val icsCapabilities = mutableListOf<Capability>()

     @VisibleForTesting
     internal var capExchangeSetupComplete = false

     internal lateinit var onParticipantInitializationComplete: (ParticipantClientActions) -> Unit
     internal lateinit var participantStateListener: ParticipantClientActionsImpl

     companion object {
         /**
          * Current capability exchange version
          */
         internal const val CAPABILITY_EXCHANGE_VERSION = 1

         private val TAG = CallCompat::class.simpleName

         fun toCallCompat(call: Call, scope: CoroutineScope, init: CallCompat.() -> Unit):
             CallCompat {
             Log.i(TAG, "toCallCompat; call = $call")
             val callCompat = CallCompat(call, scope)
             callCompat.init()
             return callCompat
         }
     }

     fun toCall(): Call {
         return call
     }

     internal fun getParticipantClientActions(): Result<ParticipantClientActions> {
         Log.i(TAG, "getParticipantClientActions")
         return if (this::participantStateListener.isInitialized) {
             if (participantStateListener.mIsInitializationComplete) {
                 Result.success(participantStateListener)
             } else {
                 Result.failure(IllegalAccessException("ParticipantClientActions not setup yet."))
             }
         } else {
             Result.failure(IllegalAccessException("The participantStateListener field in " +
                 "CallCompat was not initialized."))
         }
     }

     internal fun addCapability(capability: Capability) {
         Log.i(TAG, "addCapability capability = $capability")
         // This is called by extensions to include their capabilities to the call.
         icsCapabilities.add(capability)
     }

     internal fun addExtension(onInitializationComplete: (pca: ParticipantClientActions) -> Unit) {
         Log.i(TAG, "addExtension")
         onParticipantInitializationComplete = onInitializationComplete
     }

     /**
      * Initiate capability exchange negotiation between ICS and VOIP app. The acknowledgement begins
      * when the ICS sends a call event with [CallsManager.EVENT_JETPACK_CAPABILITY_EXCHANGE] to
      * notify the VOIP app to begin capability exchange negotiation. At that point, 3 stages of
      * acknowledgement are required between the two parties in order for negotiation to succeed.
      *
      * This entails the ICS side waiting for the VOIP app to communicate its supported capabilities,
      * the VOIP side waiting for the ICS side to communicate its supported capabilities, and the
      * VOIP side signaling the ICS side that feature setup (negotiation) is complete. If any one of
      * the aforementioned stages of ACK fails (i.e. timeout), the negotiation will fail.
      *
      * Note: Negotiation is only supported by InCallServices that support capability exchange
      * ([InCallServiceCompat.CAPABILITY_EXCHANGE]).
      *
      * @return the capability negotiation status.
      * between the ICS and VOIP app.
      */
     internal suspend fun startCapabilityExchange() {
         Log.i(TAG, "startCapabilityExchange: Starting capability negotiation with VOIP app...")

         // Initialize binder for facilitating IPC (capability exchange) between ICS and VOIP app
         // and notify VOIP app via a call event.
         val capExchange = CapabilityExchange()
         val extras = Bundle()
         extras.putBinder(CallsManager.EXTRA_CAPABILITY_EXCHANGE_BINDER, capExchange)
         extras.putInt(
             CallsManager.EXTRA_CAPABILITY_EXCHANGE_VERSION,
             CAPABILITY_EXCHANGE_VERSION
         )
         call.sendCallEvent(CallsManager.EVENT_JETPACK_CAPABILITY_EXCHANGE, extras)

         // Launch a new coroutine from the context of the current coroutine and wait for task to
         // complete.
         scope.async {
             beginCapabilityNegotiationAck(capExchange)
         }.await()
     }

     /**
      * Helper to start acknowledgement process for capability negotiation between the ICS and VOIP
      * app.
      */
     private suspend fun beginCapabilityNegotiationAck(capExchange: CapabilityExchange) {
         Log.i(TAG, "beginCapabilityNegotiationAck")

         try {
             withTimeout(CapabilityExchangeUtils.CAPABILITY_NEGOTIATION_COROUTINE_TIMEOUT) {
                 // Wait for VOIP app to return its supported capabilities.
                 if (capExchange.beginExchangeLatch.await(
                         CapabilityExchangeUtils.CAPABILITY_EXCHANGE_TIMEOUT,
                         TimeUnit.MILLISECONDS)) {
                     Log.i(TAG, "beginCapabilityNegotiationAck beginExchange returned from " +
                         "the VOIP side.")

                     setupSupportedCapabilities(capExchange)

                     Log.i(TAG, "beginCapabilityNegotiationAck: " +
                         "Completed capability exchange feature set up.")
                     capExchangeSetupComplete = true
                 }
             }
         } catch (e: Exception) {
             when (e) {
                 is CancellationException -> {
                     Log.i(
                         TAG, "beginCapabilityNegotiationAck: Capability negotiation job " +
                             "timed out in ICS side."
                     )
                     completeParticipantCapExchangeUnsupported()
                     // Todo: complete other extensions exceptionally
                 }
                 else -> {
                     // Handle the case where the VOIP app dies:
                     Log.i(
                         TAG, "beginCapabilityNegotiationAck: Remote party threw exception = $e"
                     )
                     completeParticipantCapExchangeUnsupported()
                     // Todo: complete other extensions exceptionally
                 }
             }
         }
     }

     /***********************************************************************************************
      *                           Helpers
      *********************************************************************************************/

     internal fun setupSupportedCapabilities(capExchange: CapabilityExchange) {
         val voipCaps: Set<Capability> = capExchange.voipCapabilities.toSet()
         for (icsCap in icsCapabilities) {
             // Check if the VoIP app supports this capability:
             val voipCap: Capability? = voipCaps.find {
                 it.featureId == icsCap.featureId
             }

             // If so, then initialize the listener and send the relevant callback:
             if (voipCap != null) {
                 val negotiatedActions = icsCap.supportedActions
                     .intersect(voipCap.supportedActions.toSet())
                 val minExtVersion = min(icsCap.featureVersion,
                     voipCap.featureVersion)

                 when (icsCap.featureId) {
                     CallsManager.PARTICIPANT -> initializeParticipantListenerAndInformVoipApp(
                         negotiatedActions, minExtVersion, capExchange)
                     CallsManager.CALL_ICON -> initializeCallIconListenerAndInformVoipApp(
                         negotiatedActions, minExtVersion, capExchange)
                 }
             } else {
                 when (icsCap.featureId) {
                     CallsManager.PARTICIPANT -> completeParticipantCapExchangeUnsupported()
                     CallsManager.CALL_ICON -> completeCallIconCapExchangeUnsupported()
                 }
             }
         }
     }

     private fun initializeParticipantListenerAndInformVoipApp(
         negotiatedParticipantActions: Set<Int>,
         minVersion: Int,
         capExchange: CapabilityExchange
     ) {
         participantStateListener = ParticipantClientActionsImpl(scope, negotiatedParticipantActions,
             onParticipantInitializationComplete)
         capExchange.capabilityExchangeListener.onCreateParticipantExtension(
             minVersion,
             negotiatedParticipantActions.toIntArray(),
             participantStateListener)
     }

     private fun initializeCallIconListenerAndInformVoipApp(
         negotiatedCallIconActions: Set<Int>,
         minVersion: Int,
         capExchange: CapabilityExchange
     ) {
         Log.i(TAG, "initializeCallIconListenerAndInformVoipApp: size of negotiatedActions" +
             " = ${negotiatedCallIconActions.size}, version = $minVersion, " +
             "capExchange = $capExchange")
         // Todo: initialize ICallDetailsListener and send onCreateCallDetailsExtension.
     }

     private fun completeParticipantCapExchangeUnsupported() {
         // complete the call cap exchange exceptionally and let Telecom take care of the cleanup:
         participantStateListener = ParticipantClientActionsImpl(scope, emptySet()) {}
         participantStateListener.mIsParticipantExtensionSupported = false
         onParticipantInitializationComplete(participantStateListener)
     }

     private fun completeCallIconCapExchangeUnsupported() {
         Log.i(TAG, "completeCallIconCapExchangeUnsupported")
         // Todo: inform the ICS app that voip doesn't support CallDetails extension
     }
 }
	/*
	* Copyright 2023 The Android Open Source Project
	*
	* Licensed under the Apache License, Version 2.0 (the "License");
	* you may not use this file except in compliance with the License.
	* You may obtain a copy of the License at
	*
	* http://www.apache.org/licenses/LICENSE-2.0
	*
	* Unless required by applicable law or agreed to in writing, software
	* distributed under the License is distributed on an "AS IS" BASIS,
	* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	* See the License for the specific language governing permissions and
	* limitations under the License.
	*/

	package androidx.core.telecom.internal

	import android.os.Build
	import android.os.Bundle
	import android.telecom.Call
	import android.util.Log
	import androidx.annotation.RequiresApi
	import androidx.annotation.VisibleForTesting
	import androidx.core.telecom.CallsManager
	import androidx.core.telecom.extensions.Capability
	import androidx.core.telecom.extensions.CapabilityExchange
	import androidx.core.telecom.extensions.ParticipantClientActions
	import androidx.core.telecom.extensions.ParticipantClientActionsImpl
	import androidx.core.telecom.internal.utils.CapabilityExchangeUtils
	import androidx.core.telecom.util.ExperimentalAppActions
	import java.util.concurrent.CancellationException
	import java.util.concurrent.TimeUnit
	import kotlin.math.min
	import kotlinx.coroutines.CoroutineScope
	import kotlinx.coroutines.async
	import kotlinx.coroutines.withTimeout

	@ExperimentalAppActions
	@RequiresApi(Build.VERSION_CODES.O)
	internal class CallCompat(
	private val call: Call,
	val scope: CoroutineScope,
	) {
	internal val icsCapabilities = mutableListOf<Capability>()

	@VisibleForTesting
	internal var capExchangeSetupComplete = false

	internal lateinit var onParticipantInitializationComplete: (ParticipantClientActions) -> Unit
	internal lateinit var participantStateListener: ParticipantClientActionsImpl

	companion object {
	/**
	* Current capability exchange version
	*/
	internal const val CAPABILITY_EXCHANGE_VERSION = 1

	private val TAG = CallCompat::class.simpleName

	fun toCallCompat(call: Call, scope: CoroutineScope, init: CallCompat.() -> Unit):
	CallCompat {
	Log.i(TAG, "toCallCompat; call = $call")
	val callCompat = CallCompat(call, scope)
	callCompat.init()
	return callCompat
	}
	}

	fun toCall(): Call {
	return call
	}

	internal fun getParticipantClientActions(): Result<ParticipantClientActions> {
	Log.i(TAG, "getParticipantClientActions")
	return if (this::participantStateListener.isInitialized) {
	if (participantStateListener.mIsInitializationComplete) {
	Result.success(participantStateListener)
	} else {
	Result.failure(IllegalAccessException("ParticipantClientActions not setup yet."))
	}
	} else {
	Result.failure(IllegalAccessException("The participantStateListener field in " +
	"CallCompat was not initialized."))
	}
	}

	internal fun addCapability(capability: Capability) {
	Log.i(TAG, "addCapability capability = $capability")
	// This is called by extensions to include their capabilities to the call.
	icsCapabilities.add(capability)
	}

	internal fun addExtension(onInitializationComplete: (pca: ParticipantClientActions) -> Unit) {
	Log.i(TAG, "addExtension")
	onParticipantInitializationComplete = onInitializationComplete
	}

	/**
	* Initiate capability exchange negotiation between ICS and VOIP app. The acknowledgement begins
	* when the ICS sends a call event with [CallsManager.EVENT_JETPACK_CAPABILITY_EXCHANGE] to
	* notify the VOIP app to begin capability exchange negotiation. At that point, 3 stages of
	* acknowledgement are required between the two parties in order for negotiation to succeed.
	*
	* This entails the ICS side waiting for the VOIP app to communicate its supported capabilities,
	* the VOIP side waiting for the ICS side to communicate its supported capabilities, and the
	* VOIP side signaling the ICS side that feature setup (negotiation) is complete. If any one of
	* the aforementioned stages of ACK fails (i.e. timeout), the negotiation will fail.
	*
	* Note: Negotiation is only supported by InCallServices that support capability exchange
	* ([InCallServiceCompat.CAPABILITY_EXCHANGE]).
	*
	* @return the capability negotiation status.
	* between the ICS and VOIP app.
	*/
	internal suspend fun startCapabilityExchange() {
	Log.i(TAG, "startCapabilityExchange: Starting capability negotiation with VOIP app...")

	// Initialize binder for facilitating IPC (capability exchange) between ICS and VOIP app
	// and notify VOIP app via a call event.
	val capExchange = CapabilityExchange()
	val extras = Bundle()
	extras.putBinder(CallsManager.EXTRA_CAPABILITY_EXCHANGE_BINDER, capExchange)
	extras.putInt(
	CallsManager.EXTRA_CAPABILITY_EXCHANGE_VERSION,
	CAPABILITY_EXCHANGE_VERSION
	)
	call.sendCallEvent(CallsManager.EVENT_JETPACK_CAPABILITY_EXCHANGE, extras)

	// Launch a new coroutine from the context of the current coroutine and wait for task to
	// complete.
	scope.async {
	beginCapabilityNegotiationAck(capExchange)
	}.await()
	}

	/**
	* Helper to start acknowledgement process for capability negotiation between the ICS and VOIP
	* app.
	*/
	private suspend fun beginCapabilityNegotiationAck(capExchange: CapabilityExchange) {
	Log.i(TAG, "beginCapabilityNegotiationAck")

	try {
	withTimeout(CapabilityExchangeUtils.CAPABILITY_NEGOTIATION_COROUTINE_TIMEOUT) {
	// Wait for VOIP app to return its supported capabilities.
	if (capExchange.beginExchangeLatch.await(
	CapabilityExchangeUtils.CAPABILITY_EXCHANGE_TIMEOUT,
	TimeUnit.MILLISECONDS)) {
	Log.i(TAG, "beginCapabilityNegotiationAck beginExchange returned from " +
	"the VOIP side.")

	setupSupportedCapabilities(capExchange)

	Log.i(TAG, "beginCapabilityNegotiationAck: " +
	"Completed capability exchange feature set up.")
	capExchangeSetupComplete = true
	}
	}
	} catch (e: Exception) {
	when (e) {
	is CancellationException -> {
	Log.i(
	TAG, "beginCapabilityNegotiationAck: Capability negotiation job " +
	"timed out in ICS side."
	)
	completeParticipantCapExchangeUnsupported()
	// Todo: complete other extensions exceptionally
	}
	else -> {
	// Handle the case where the VOIP app dies:
	Log.i(
	TAG, "beginCapabilityNegotiationAck: Remote party threw exception = $e"
	)
	completeParticipantCapExchangeUnsupported()
	// Todo: complete other extensions exceptionally
	}
	}
	}
	}

	/***********************************************************************************************
	* Helpers
	*********************************************************************************************/

	internal fun setupSupportedCapabilities(capExchange: CapabilityExchange) {
	val voipCaps: Set<Capability> = capExchange.voipCapabilities.toSet()
	for (icsCap in icsCapabilities) {
	// Check if the VoIP app supports this capability:
	val voipCap: Capability? = voipCaps.find {
	it.featureId == icsCap.featureId
	}

	// If so, then initialize the listener and send the relevant callback:
	if (voipCap != null) {
	val negotiatedActions = icsCap.supportedActions
	.intersect(voipCap.supportedActions.toSet())
	val minExtVersion = min(icsCap.featureVersion,
	voipCap.featureVersion)

	when (icsCap.featureId) {
	CallsManager.PARTICIPANT -> initializeParticipantListenerAndInformVoipApp(
	negotiatedActions, minExtVersion, capExchange)
	CallsManager.CALL_ICON -> initializeCallIconListenerAndInformVoipApp(
	negotiatedActions, minExtVersion, capExchange)
	}
	} else {
	when (icsCap.featureId) {
	CallsManager.PARTICIPANT -> completeParticipantCapExchangeUnsupported()
	CallsManager.CALL_ICON -> completeCallIconCapExchangeUnsupported()
	}
	}
	}
	}

	private fun initializeParticipantListenerAndInformVoipApp(
	negotiatedParticipantActions: Set<Int>,
	minVersion: Int,
	capExchange: CapabilityExchange
	) {
	participantStateListener = ParticipantClientActionsImpl(scope, negotiatedParticipantActions,
	onParticipantInitializationComplete)
	capExchange.capabilityExchangeListener.onCreateParticipantExtension(
	minVersion,
	negotiatedParticipantActions.toIntArray(),
	participantStateListener)
	}

	private fun initializeCallIconListenerAndInformVoipApp(
	negotiatedCallIconActions: Set<Int>,
	minVersion: Int,
	capExchange: CapabilityExchange
	) {
	Log.i(TAG, "initializeCallIconListenerAndInformVoipApp: size of negotiatedActions" +
	" = ${negotiatedCallIconActions.size}, version = $minVersion, " +
	"capExchange = $capExchange")
	// Todo: initialize ICallDetailsListener and send onCreateCallDetailsExtension.
	}

	private fun completeParticipantCapExchangeUnsupported() {
	// complete the call cap exchange exceptionally and let Telecom take care of the cleanup:
	participantStateListener = ParticipantClientActionsImpl(scope, emptySet()) {}
	participantStateListener.mIsParticipantExtensionSupported = false
	onParticipantInitializationComplete(participantStateListener)
	}

	private fun completeCallIconCapExchangeUnsupported() {
	Log.i(TAG, "completeCallIconCapExchangeUnsupported")
	// Todo: inform the ICS app that voip doesn't support CallDetails extension
	}
	}