Create a Custom Connection Service

Last edit: 2024.04.30

The TomTom Digital Cockpit platform allows end-users to make phone calls using a Bluetooth-connected phone using the Bluetooth Hands Free Profile. TomTom Digital Cockpit can be extended to support other communications services such as VOIP (Voice Over Internet Protocol) calling or integrate an SDK of an online conference calling or messaging service and make and receive calls using the existing communications framework for these new services.

A ConnectionService is a service used by Android to implement calling functionality, like phone calling or any VOIP calling service like WhatsApp. Another communications service can be supported by implementing a custom ConnectionService.

How to create a custom connection service

The following sections describe how to create a custom connection service implementation.

Example code illustrating how to implement the concepts described in this document can be found in examples/telephony/customconnection.

Service module setup

To create a custom connection service, add an AndroidManifest.xml file to your module. This is necessary to let it interact with the Android Telecom Manager service. In the added manifest it is only necessary to configure the necessary permissions and intent filter, as the rest of the service configuration will be done by the IVI runtime deployment system:

Add a src/main/AndroidManifest.xml file:

1<manifest xmlns:android="http://schemas.android.com/apk/res/android">
2
3<!-- This is needed to place and receive calls using Android's TelecomManager. -->
4<uses-permission android:name="android.permission.MANAGE_OWN_CALLS" />
5<!-- This is needed to read available phone accounts using Android's TelecomManager. -->
6<uses-permission android:name="android.permission.READ_PHONE_STATE" />
7
8<application>
9    <!-- Declaration of the custom connection service which can be bound with the TelecomManager. -->
10    <service
11        android:name=".CustomConnectionService"
12        android:permission="android.permission.BIND_TELECOM_CONNECTION_SERVICE">
13        <intent-filter>
14            <action android:name="android.telecom.ConnectionService" />
15        </intent-filter>
16    </service>
17</application>
18</manifest>

Add a dependency to the TelecomService and LifecycleService in your build.gradle.kts file:

1dependencies {
2    implementation(libraries.iviPlatformTelecomApiServiceTelecom)
3    implementation("androidx.lifecycle:lifecycle-service:2.3.1")
4}

The dependency to the TelecomService is necessary in order to use CallState and toPhoneUri (package com.tomtom.ivi.platform.telecom.api.common.utils), both required for the phone call state management.

The dependency to the LifecycleService is necessary in order to create a dispatcher in your custom service class, as it is not possible to inherit from LifecycleService directly:

src/main/kotlin/com/example/ivi/example/telephony/customconnection/CustomConnectionService.kt

private val dispatcher = ServiceLifecycleDispatcher(this)

Service preparation

To use your custom implementation you need to create an internal object CustomConnectionServiceHolder.kt that will create and store an instance of CustomConnectionService.

src/main/kotlin/com/example/ivi/example/telephony/customconnection/CustomConnectionServiceHolder.kt

1internal object CustomConnectionServiceHolder {
  // The custom connection service used for communications.
  @Volatile
  private var customConnectionService: CustomConnectionService? = null
5
  // It should be called when we create the CustomConnectionService, so the instance of the
  // CustomConnectionService is initialized.
  @Synchronized
  fun setCustomConnectionService(customConnectionService: CustomConnectionService?) {
      this.customConnectionService = customConnectionService
  }
12
  // Checks if the connection service is ready.
  @Synchronized
  fun isCustomConnectionServiceReady() = (customConnectionService != null)
16
  //...
18}

CustomConnectionService will be set when the TelecomManager binds to the CustomConnectionService, which will happen when creating an incoming or outgoing call. If there is no more ongoing call, the TelecomManager unbinds the CustomConnectionService and this shall be null.

Service definition

In order to create a connection service implementation you need to create a class that inherits from the ConnectionService and LifecycleOwner classes. It should implement the required functions from ConnectionService like onCreateOutgoingConnection, onCreateOutgoingConnectionFailed, onCreateIncomingConnection and onCreateIncomingConnectionFailed. It should also implement getLifecycle from LifecycleService.

src/main/kotlin/com/example/ivi/example/telephony/customconnection/CustomConnectionService.kt

1internal class CustomConnectionService : ConnectionService(), LifecycleOwner {
  //...
3
  override fun onCreateOutgoingConnection(
          connectionManagerPhoneAccount: PhoneAccountHandle?,
          request: ConnectionRequest?
      ): Connection? {
      if (uriAlreadyHasAConnection(request?.address)) {
          tracer.uriAlreadyHasAConnection(request?.address)
          return null
      }
      return OutgoingCustomConnection(request).apply {
          setInitializing()
          setDialing()
          tracer.onCreateOutgoingConnection(this)
      }
  }
18
  override fun onCreateOutgoingConnectionFailed(
      connectionManagerPhoneAccount: PhoneAccountHandle?,
      request: ConnectionRequest?
  ) {
      super.onCreateOutgoingConnectionFailed(connectionManagerPhoneAccount, request)
      tracer.onCreateOutgoingConnectionFailed(connectionManagerPhoneAccount, request)
  }
26
  override fun onCreateIncomingConnection(
      connectionManagerPhoneAccount: PhoneAccountHandle?,
      request: ConnectionRequest?
30
  ): Connection? {
      if (uriAlreadyHasAConnection(request?.address)) {
          tracer.uriAlreadyHasAConnection(request?.address)
          return null
      }
      return IncomingCustomConnection(request).apply {
          setAddress(request?.address, TelecomManager.PRESENTATION_ALLOWED)
          setInitializing()
          setRinging()
          tracer.onCreateIncomingConnection(this)
      }
  }
43
  override fun onCreateIncomingConnectionFailed(
      connectionManagerPhoneAccount: PhoneAccountHandle?,
      request: ConnectionRequest?
  ) {
      super.onCreateIncomingConnectionFailed(connectionManagerPhoneAccount, request)
      tracer.onCreateIncomingConnectionFailed(connectionManagerPhoneAccount, request)
  }
51
  //...
53
  override fun getLifecycle() = dispatcher.lifecycle
55
  //...
57}

In this example we have created the CustomConnectionFacade class that simulates incoming and outgoing calls. This class is also able to change the current call's state. Simulated calls can be created after registering a custom phone account in the system.

src/main/kotlin/com/example/ivi/example/telephony/customconnection/CustomConnectionFacade.kt

1class CustomConnectionFacade(private val context: Context) {
  //...
3
  // Registers the custom phone account in the system. Needed before calling [createIncomingCall]
  // or [createOutgoingCall].
  private fun registerCustomPhoneAccount(): Boolean {
      //...
      telecomManager.registerPhoneAccount(customPhoneAccount)
      //...
  }
11
  // Unregisters the custom phone account from the system. The recent calls related to the custom
  // phone account will be deleted as well.
  private fun unregisterCustomPhoneAccount(): Boolean {
      //...
      CustomConnectionServiceHolder.withCustomConnectionService {
          // Clean and destroy all pending connections if there are any.
          it.clearAllConnections()
      }
      telecomManager.unregisterPhoneAccount(customPhoneAccount.accountHandle)
      //...
  }
23
  // Creates an incoming call using the [customPhoneAccount].
  private fun createIncomingCall(phoneNumber: String) {
      //...
      val extras = Bundle()
      val uri = phoneNumber.toPhoneUri()
      extras.putParcelable(TelecomManager.EXTRA_INCOMING_CALL_ADDRESS, uri)
      telecomManager.addNewIncomingCall(customPhoneAccount.accountHandle, extras)
      tracer.onCreatedIncomingCall(uri)
  }
33
  // Creates an outgoing call using the [customPhoneAccount].
  private fun createOutgoingCall(phoneNumber: String) {
      //...
      val extras = Bundle()
      val uri = phoneNumber.toPhoneUri()
      extras.putParcelable(
          TelecomManager.EXTRA_PHONE_ACCOUNT_HANDLE,
          customPhoneAccount.accountHandle
      )
      //...
      telecomManager.placeCall(uri, extras)
      tracer.onCreatedOutgoingCall(phoneNumber.toPhoneUri())
  }
47
  // Updates a call state.
  fun applyCallState(
      phoneNumber: String,
      callState: CallState,
      disconnectCause: DisconnectCause?
  ) {
      tracer.applyCallState(phoneNumber, callState, disconnectCause)
      CustomConnectionServiceHolder.withCustomConnectionService {
          // Change call's state.
          it.changeConnectionState(phoneNumber, callState, disconnectCause)
      }
      //...
  }
61
  //...
63}

Service lifecycle

To manage the initialization and destruction of the service, override the onCreate and onDestroy methods.

When the service is created:

src/main/kotlin/com/example/ivi/example/telephony/customconnection/CustomConnectionService.kt

1override fun onCreate() {
2    dispatcher.onServicePreSuperOnCreate()
3    CustomConnectionServiceHolder.setCustomConnectionService(this)
4    super.onCreate()
5}

The CustomConnectionServiceHolder creates and stores an instance of the CustomConnectionService.

When the service is destroyed:

src/main/kotlin/com/example/ivi/example/telephony/customconnection/CustomConnectionService.kt

1override fun onDestroy() {
2    dispatcher.onServicePreSuperOnDestroy()
3    super.onDestroy()
4    CustomConnectionServiceHolder.setCustomConnectionService(null)
5}

The instance of the CustomConnectionService is null.

External links

TomTom Digital Cockpit TelecomService.
Android ConnectionService.