Merge "update addCall and CallControlScope docs" into androidx-main
diff --git a/core/core-telecom/src/main/java/androidx/core/telecom/CallControlScope.kt b/core/core-telecom/src/main/java/androidx/core/telecom/CallControlScope.kt
index 5e6f8f0..a7f1072 100644
--- a/core/core-telecom/src/main/java/androidx/core/telecom/CallControlScope.kt
+++ b/core/core-telecom/src/main/java/androidx/core/telecom/CallControlScope.kt
@@ -21,8 +21,13 @@
import kotlinx.coroutines.flow.Flow
/**
- * DSL interface to provide and receive updates about a single call session. The scope should be
- * used to provide updates to the call state and receive updates about a call state. Example usage:
+ * DSL interface to provide and receive updates about a call session. The CallControlScope should be
+ * used to provide updates (via the CallControlScope suspend functions) and receive updates
+ * (via the lambda functions) about the call. The CallControlScope will run for the duration of the
+ * call. To see an example implementation of the CallControlScope, please refer to the sample app on
+ * [github.](https://github.com/android/platform-samples/blob/3856087f7f0fa4901e521f1dc79a30ddfd108f4e/samples/connectivity/telecom/src/main/java/com/example/platform/connectivity/telecom/model/TelecomCallRepository.kt#L122)
+ *
+ * Example usage:
*
* // initiate a call and control via the CallControlScope
* mCallsManager.addCall(
@@ -31,12 +36,30 @@
* onDisconnectLambda,
* onSetActiveLambda,
* onSetInActiveLambda
- * ) { // This block represents the CallControlScope
+ * ) {
+ * // This block represents the CallControlScope. Once Telecom has added the call to the
+ * // system, your application can start changing the call state (via setActive(), etc.),
+ * // collect the flows.
*
- * // UI flow sends an update to a call state, relay the update to Telecom
- * disconnectCallButton.setOnClickListener {
- * val wasSuccessful = disconnect(reason) // waits for telecom async. response
- * // update UI
+ *
+ * // Your application should gate ALL CallControlScope suspend functions with UI logic or
+ * // logic that signals the call state is ready to be changed
+ * launch {
+ * when (val res = setActive() ) {
+ *
+ * is CallControlResult.Success -> {
+ * // Telecom can place the active
+ * // update your call state and handle UI
+ * }
+ *
+ * is CallControlResult.Error -> {
+ * // Telecom cannot set your VoIP call active. Maybe there is an ongoing
+ * // active call that cannot be held. Check the failure code to determine the
+ * // recommended next action
+ * handleErrorCode( res.errorCode )
+ * }
+ * }
+ * }
* }
*
* // Collect updates
@@ -54,7 +77,7 @@
* }
*
* **Note:** Each [Flow] must be wrapped in an individual launch block or the [Flow] will not be
- * collected.
+ * collected.
*/
interface CallControlScope : CoroutineScope {
/**
diff --git a/core/core-telecom/src/main/java/androidx/core/telecom/CallsManager.kt b/core/core-telecom/src/main/java/androidx/core/telecom/CallsManager.kt
index 058c217..d5224e3 100644
--- a/core/core-telecom/src/main/java/androidx/core/telecom/CallsManager.kt
+++ b/core/core-telecom/src/main/java/androidx/core/telecom/CallsManager.kt
@@ -250,6 +250,17 @@
* - For outgoing calls, your application should either immediately post a
* [android.app.Notification.CallStyle] notification or delay adding the call via this
* addCall method until the remote side is ready.
+ * - addCall will NOT complete until the call session has ended. Instead, the addCall block,
+ * which is called the [CallControlScope], will run once the call has been added. Do not
+ * put addCall in a function expecting it to return or add logic after the addCall request
+ * that is important for the call session.
+ * - Each lambda function (onAnswer, onDisconnect, onSetActive, onSetInactive) will be
+ * invoked by Telecom whenever the system needs your VoIP application to change the call
+ * state. For example, if there is an ongoing VoIP call in your application and the
+ * system receives a sim call, Telecom will invoke onSetInactive to place your call on
+ * hold/inactive if the user answers the incoming sim call. These events may not occur
+ * during most calls but should still be implemented in the event Telecom needs to
+ * manipulate your applications call state.
* - Each lambda function (onAnswer, onDisconnect, onSetActive, onSetInactive) has a
* timeout of 5000 milliseconds. Failing to complete the suspend fun before the timeout
* will result in a failed transaction.
@@ -257,10 +268,6 @@
* is handled successfully on the client side. If the callback cannot be completed,
* an Exception should be thrown. Telecom will rethrow the Exception and tear down
* the call session.
- * - Each lambda function (onAnswer, onDisconnect, onSetActive, onSetInactive) has a
- * timeout of 5000 milliseconds. Failing to complete the suspend fun before the
- * timeout will result in a failed transaction.
- *
* @param callAttributes attributes of the new call (incoming or outgoing, address, etc. )
*
* @param onAnswer where callType is the audio/video state the call should be
