Telecom 框架概览

Android Telecom 框架(也简称为“Telecom”)管理 Android 设备上的音频和视频通话。这包括基于 SIM 卡的通话(例如使用电话框架的通话)以及实现 Core-Telecom Jetpack 库的 VoIP 通话。

Telecom 管理的主要组件是 ConnectionService 和 InCallService。

ConnectionService 实现基于 PSTN 等技术,可将通话连接到其他方。手机上最常见的 ConnectionService 实现是电话 ConnectionService。它可连接运营商通话。

InCallService 实现为 Telecom 管理的通话提供界面,并允许用户控制这些通话以及与之互动。InCallService 最常见的实现是设备自带的电话应用。

Telecom 充当总机。它会将 ConnectionService 实现提供的通话路由到 InCallService 实现提供的通话界面。

您可能需要实现 Telecom API,原因如下:

创建替代电话应用

如需为 Android 设备上的默认电话应用创建替代应用,请实现 InCallService API。您的实现必须满足以下要求:

  • 它不得具有任何通话功能,并且必须仅包含通话界面。
  • 它必须处理 Telecom 框架知道的所有通话,并且不得对通话的性质做出假设。例如,它不得假定通话是基于 SIM 卡的电话通话,也不得实现基于任何一个 ConnectionService 的通话限制,例如对视频通话强制执行电话限制。

如需了解详情,请参阅 InCallService。

集成通话解决方案

如需将通话解决方案集成到 Android 中,您有以下几种选择:

  • 实现自行管理的 Core-Telecom Jetpack 库:此选项非常适合独立通话应用的开发者,他们不希望在默认电话应用中显示其通话,也不希望在其界面中显示其他通话。

    集成 Core-Telecom Jetpack 库后,您的应用不仅可以与设备上的系统电话通话功能互操作,还可以与集成了 Telecom 的其他独立通话应用互操作。Core-Telecom 库还管理音频路由和焦点。如需了解详情,请参阅构建通话应用。

  • 实现受管理的 ConnectionService API:此选项有助于开发依赖于现有设备电话应用来提供通话界面的通话解决方案。例如,SIP 通话和 VoIP 通话服务的第三方实现。如需了解详情,请参阅 getDefaultDialerPackage()。

    ConnectionService 本身仅提供连接通话的方式。它没有关联的界面。

  • 同时实现 InCallService 和 ConnectionService API:如果您想创建自己的基于 ConnectionService 的通话解决方案(具有自己的界面),并且还想在同一界面中显示所有其他 Android 通话,则此选项是理想之选。使用此方法时,InCallService 的实现不得对所显示通话的来源做出任何假设。此外,即使未将默认电话应用设置为自定义 InCallService,您的 ConnectionService 实现也必须继续正常运行。

过滤来电

搭载 Android 10(API 级别 29)或更高版本的设备允许您的应用将来自不在用户通讯簿中的号码的来电识别为潜在骚扰电话。用户可以选择静默拒接骚扰电话。为了让用户更清楚地了解自己错过的来电,系统会在通话记录中记录这些被屏蔽的来电的相关信息。使用 Android 10 API 后,您无需从用户处获取 READ_CALL_LOG 权限即可提供来电过滤和来电显示功能。

您可以使用 CallScreeningService 实现来过滤来电。当号码不在用户的联系人列表中时,针对任何新的来电或去电调用 onScreenCall() 函数。您可以查看 Call.Details 对象,了解有关调用的信息。具体而言,getCallerNumberVerificationStatus() 函数包含来自网络提供商的关于另一个号码的信息。如果验证状态为失败,则表明来电可能来自无效号码或可能是骚扰电话。

class ScreeningService : CallScreeningService() {
    // This function is called when an ingoing or outgoing call
    // is from a number not in the user's contacts list
    override fun onScreenCall(callDetails: Call.Details) {
        // Can check the direction of the call
        val isIncoming = callDetails.callDirection == Call.Details.DIRECTION_INCOMING

        if (isIncoming) {
            // the handle (e.g. phone number) that the Call is currently connected to
            val handle: Uri = callDetails.handle

            // determine if you want to allow or reject the call
            when (callDetails.callerNumberVerificationStatus) {
                Connection.VERIFICATION_STATUS_FAILED -> {
                    // Network verification failed, likely an invalid/spam call.
                }
                Connection.VERIFICATION_STATUS_PASSED -> {
                    // Network verification passed, likely a valid call.
                }
                else -> {
                    // Network could not perform verification.
                    // This branch matches Connection.VERIFICATION_STATUS_NOT_VERIFIED.
                }
            }
        }
    }
}

将 onScreenCall() 函数设置为调用 respondToCall(),以告知系统如何响应新通话。此函数接受 CallResponse 参数,您可以使用该参数告知系统屏蔽来电、像用户一样拒接来电或将通话静音。您还可以指示系统完全跳过将此通话添加到设备通话记录的操作。

// Tell the system how to respond to the incoming call
// and if it should notify the user of the call.
val response = CallResponse.Builder()
    // Sets whether the incoming call should be blocked.
    .setDisallowCall(false)
    // Sets whether the incoming call should be rejected as if the user did so manually.
    .setRejectCall(false)
    // Sets whether ringing should be silenced for the incoming call.
    .setSilenceCall(false)
    // Sets whether the incoming call should not be displayed in the call log.
    .setSkipCallLog(false)
    // Sets whether a missed call notification should not be shown for the incoming call.
    .setSkipNotification(false)
    .build()

// Call this function to provide your screening response.
respondToCall(callDetails, response)

您必须在清单文件中注册 CallScreeningService 实现,并指定适当的 intent 过滤器和权限,以便系统能够正确触发它。

<service
    android:name=".ScreeningService"
    android:permission="android.permission.BIND_SCREENING_SERVICE">
    <intent-filter>
        <action android:name="android.telecom.CallScreeningService" />
    </intent-filter>
</service>

重定向通话

搭载 Android 10 或更高版本的设备与搭载 Android 9 或更低版本的设备管理通话 intent 的方式不同。在 Android 10 及更高版本中,ACTION_NEW_OUTGOING_CALL 广播已弃用,取而代之的是 CallRedirectionService API。CallRedirectionService 提供了可供您修改 Android 平台发出的去电的接口。例如,第三方应用可能会取消通话,并通过 VoIP 重新路由。

class RedirectionService : CallRedirectionService() {
    override fun onPlaceCall(
        handle: Uri,
        initialPhoneAccount: PhoneAccountHandle,
        allowInteractiveResponse: Boolean
    ) {
        // Determine if the call should proceed, be redirected, or cancelled.
        val callShouldProceed = true
        val callShouldRedirect = false
        when {
            callShouldProceed -> {
                placeCallUnmodified()
            }
            callShouldRedirect -> {
                // Update the URI to point to a different phone number or modify the
                // PhoneAccountHandle and redirect.
                redirectCall(handle, initialPhoneAccount, true)
            }
            else -> {
                cancelCall()
            }
        }
    }
}

您必须在清单中注册此服务,以便系统可以正确启动它。

<service
    android:name=".RedirectionService"
    android:permission="android.permission.BIND_CALL_REDIRECTION_SERVICE">
    <intent-filter>
        <action android:name="android.telecom.CallRedirectionService"/>
    </intent-filter>
</service>

如需使用重定向服务,您的应用必须向 RoleManager 请求通话重定向角色。系统会询问用户是否允许您的应用处理通话重定向。如果您的应用未被授予此角色,则系统不会使用您的重定向服务。

您应在用户启动应用时检查应用是否具有此角色,以便根据需要请求此角色。您启动由 RoleManager 创建的 intent,因此请务必替换 onActivityResult() 函数来处理用户的选择。

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        // Tell the system that you want your app to handle call redirects. This
        // is done by using the RoleManager to register your app to handle redirects.
        if (android.os.Build.VERSION.SDK_INT >= android.os.Build.VERSION_CODES.Q) {
            val roleManager = getSystemService(Context.ROLE_SERVICE) as RoleManager
            // Check if the app needs to register call redirection role.
            val shouldRequestRole = roleManager.isRoleAvailable(RoleManager.ROLE_CALL_REDIRECTION) &&
                !roleManager.isRoleHeld(RoleManager.ROLE_CALL_REDIRECTION)
            if (shouldRequestRole) {
                val intent = roleManager.createRequestRoleIntent(RoleManager.ROLE_CALL_REDIRECTION)
                startActivityForResult(intent, REDIRECT_ROLE_REQUEST_CODE)
            }
        }
    }

    companion object {
        private const val REDIRECT_ROLE_REQUEST_CODE = 1
    }
}