Create a Custom Contacts Service

Last edit: 2024.04.30

The IVI platform comes with a ContactsService interface for getting access to address book contacts. A product may provide its own implementation of the ContactsService interface or use an existing implementation. In order for the UI to be able to display contacts from this service, a custom contacts service needs to be written. This document describes how to do this.

How to create a custom contacts service

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

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

Service module setup

To create a custom contacts service, add a dependency to the ContactsService in the Gradle file of your module.

Your build.gradle.kts file should contain:

1dependencies {
2    implementation(libraries.iviPlatformContactsApiServiceContacts)
3}

Service configuration

To configure a contacts service to use your custom implementation, define a service host configuration class that inherits from the IviServiceHostConfig class. This class should be placed in the application Gradle build file.

examples/telephony/app/build.gradle.kts

1val customContactsServiceHost by extra {
  IviServiceHostConfig(
      serviceHostBuilderName = "CustomContactsServiceHostBuilder",
      implementationModule = ExampleModuleReference("examples_telephony_customcontacts"),
      interfaces = listOf(
          IviServiceInterfaceConfig(
              serviceName = "ContactsService",
              serviceApiModule = IviPlatformModuleReference("platform_contacts_api_service_contacts")
          )
      )
  )
12}

In this configuration, the services_customcontacts module defines the implementation for the platform_contacts_api_service_contacts interface.

In order to create the service host configuration named CustomContactsServiceHost, the IVI platform needs a service host builder class with the specific name CustomContactsServiceHostBuilder.

src/main/kotlin/com/example/ivi/example/telephony/customcontacts/CustomContactsServiceHostBuilder.kt

1class CustomContactsServiceHostBuilder : SimpleIviServiceHostBuilder() {
2
3    override fun createIviServices(
4        iviServiceHostContext: IviServiceHostContext
5    ): Collection<AnyIviServiceBase> =
6        listOf(CustomContactsService(iviServiceHostContext))
7
8    companion object
9}

Note: Every service host configuration needs to be registered in your application. This is necessary to know which service should be started with which implementation when a client requires the access to a service api.

To register this configuration, add the service host to your application build.gradle.kts file:

1ivi {
  optInToExperimentalApis = true
3
  application {
      enabled = true
      services {
          // Replace the default contact service with the custom contacts service.
          removeHost(contactsServiceHost)
          addHost(customContactsServiceHost)
      }
  }
12}

Service definition

In order to create a custom contacts service implementation you need to create a class that inherits from the ContactsServiceBase class.

src/main/kotlin/com/example/ivi/example/telephony/customcontacts/CustomContactsService.kt

1internal class CustomContactsService(iviServiceHostContext: IviServiceHostContext) :
2    ContactsServiceBase(iviServiceHostContext) {
3
4    private val mutableContacts = MutableContactsDataSource(context)
5}

Note: The contacts service implementation can define any kind of source for the list of contacts, for example the Android Contacts provider.

In this example the contacts service contains two contacts. The list of contacts contains those two contacts after initialization. The mutable list contactsSource is the source of contacts:

src/main/kotlin/com/example/ivi/example/telephony/customcontacts/CustomContactsService.kt

1// The source of contacts.
2private val contactsSource = mutableListOf(
  Contact(
      displayName = "John Smith",
      initials = "JS",
      givenName = "John",
      familyName = "Smith",
      companyName = "Company Name",
      phoneNumbers = listOf(PhoneNumber("+281111111", PhoneNumberType.Main)),
      defaultPhoneNumberIndex = 0,
      addresses = listOf(Address("45 Some Street, SomeCity, SC 10000", AddressType.Home)),
      defaultAddressIndex = 0,
      favorite = true,
      primarySortKey = "John Smith",
      alternativeSortKey = "Smith John"
  ),
  Contact(
      displayName = "Kelly Goodwin",
      initials = "KG",
      givenName = "Kelly",
      familyName = "Goodwin",
      companyName = "Another Company Name",
      phoneNumbers = listOf(PhoneNumber("+2822222222", PhoneNumberType.Mobile)),
      defaultPhoneNumberIndex = 0,
      addresses = listOf(
          Address(
              "45 Some Other Street, SomeOtherCity, SC 12000",
              AddressType.Work
          )
      ),
      defaultAddressIndex = 0,
      favorite = false,
      primarySortKey = "Kelly Goodwin",
      alternativeSortKey = "Goodwin Kelly"
  ),
36)

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/customcontacts/CustomContactsService.kt

1override fun onCreate() {
  super.onCreate()
  // Initialize the synchronization status.
  phoneBookSynchronizationStatus = PhoneBookSynchronizationStatus.NO_CONNECTED_DEVICES
  // Bind the contacts property to an empty mutable map.
  contacts = mutableContacts
  // Set the service ready and clients can call any Api of the service.
  serviceReady = true
9
  // The source of contacts is ready and synchronization starts.
  phoneBookSynchronizationStatus = PhoneBookSynchronizationStatus.SYNCHRONIZATION_IN_PROGRESS
  // Updating the contacts property with some contacts from the source
  mutableContacts.addContacts(contactsSource)
14}

The ContactsService.contacts and ContactsService.phoneBookSynchronizationStatus properties have been initialized.

When the service is destroyed:

src/main/kotlin/com/example/ivi/example/telephony/customcontacts/CustomContactsService.kt

1override fun onDestroy() {
2    // Put here cleaning code if necessary.
3    super.onDestroy()
4}

External links

TomTom Digital Cockpit ContactsService.
Android Contacts provider.