CapabilityExchangeUtils.kt
/*
* 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.utils
import android.os.Build
import android.os.Bundle
import android.util.Log
import androidx.annotation.RequiresApi
import androidx.core.telecom.CallsManager
import androidx.core.telecom.extensions.Capability
import androidx.core.telecom.extensions.CapabilityExchange
import androidx.core.telecom.extensions.CapabilityExchangeListener
import androidx.core.telecom.util.ExperimentalAppActions
import java.util.concurrent.TimeUnit
import kotlinx.coroutines.TimeoutCancellationException
import kotlinx.coroutines.withTimeout
@ExperimentalAppActions
@RequiresApi(Build.VERSION_CODES.O)
internal class CapabilityExchangeUtils {
companion object {
private val TAG = Companion::class.java.simpleName
/**
* Timeouts to help facilitate capability exchange negotiation between ICS and VOIP app.
*/
internal const val CAPABILITY_EXCHANGE_TIMEOUT = 1000L
internal const val CAPABILITY_NEGOTIATION_COROUTINE_TIMEOUT = 3000L
/**
* Internal helper to help facilitate acknowledgement for capability negotiation between
* the VOIP app and ICS. This helper is invoked on the VOIP side where negotiation begins
* when we are notified via a call event (containing
* [CallsManager.EVENT_JETPACK_CAPABILITY_EXCHANGE]). The VOIP side is responsible for
* informing the ICS of its supported capabilities, receiving the ICS's supported
* capabilities (ACK), and informing the ICS that negotiation has completed. If the VOIP
* side is unable to receive the ICS supported capabilities, feature setup will fail and
* the ICS will report the status for negotiation as failed.
*
* @param extras received from call event.
* @param supportedCapabilities for the VOIP app.
* @param logTag to help identify if legacy or v2 APIs are being used.
*/
internal suspend fun initiateVoipAppCapabilityExchange(
extras: Bundle,
supportedCapabilities: MutableList<Capability>,
logTag: String? = TAG
) {
try {
withTimeout(CAPABILITY_NEGOTIATION_COROUTINE_TIMEOUT) {
Log.i(logTag, "Starting capability negotiation with ICS...")
var isFeatureSetupComplete = false
// Retrieve binder from ICS.
val capabilityExchange: CapabilityExchange? = extras.getBinder(
CallsManager.EXTRA_CAPABILITY_EXCHANGE_BINDER) as CapabilityExchange?
// Initialize capability exchange listener and set it on binder
val capabilityExchangeListener = CapabilityExchangeListener()
capabilityExchange?.let {
capabilityExchange.setListener(capabilityExchangeListener)
// Negotiate the supported VOIP app capabilities to the ICS (stub with empty
// capabilities until the implementation is supported).
capabilityExchange.negotiateCapabilities(supportedCapabilities)
// Wait for the ICS to return its supported capabilities and notify that the
// setup is complete.
if (capabilityExchangeListener.onCapabilitiesNegotiatedLatch
.await(CAPABILITY_EXCHANGE_TIMEOUT, TimeUnit.MILLISECONDS)) {
capabilityExchange.featureSetupComplete()
isFeatureSetupComplete = true
Log.i(logTag, "Capability negotiation with ICS has completed.")
}
}
if (!isFeatureSetupComplete) {
Log.i(logTag, "Unable to receive supported capabilities from (ICS) client.")
}
}
} catch (e: TimeoutCancellationException) {
Log.i(logTag, "Capability negotiation job timed out in VOIP app side.")
}
}
}
}