Package-level declarations

The contacts service API package.

Contacts service

The contacts service is an IVI service and is the entry point for all data related to contacts in the IVI system. Clients (frontends) can use it to get all the contacts currently available in the IVI system. All the information about a specific contact can be retrieved with the contacts service API. The contacts service also provides a synchronization status with the sources providing contacts.

Overview of the contacts service

The contacts service is responsible for providing clients with address book contacts and can contain data transferred from, amongst other sources, Bluetooth-connected devices such as paired mobile phones.

The contacts service is a layer on top of the sources of contacts.

When contacts are updated in the sources the ContactsService is updated and provides a list of currently available contacts in the system, via the ContactsService.contacts property ( see #contacts-list-update).

The ContactsService updates the ContactsService.phoneBookSynchronizationStatus with the current synchronization status of the contacts in the system ( see #contacts-synchronization-status).

The source of contacts can actually be multiple sources, such as multiple mobile phones.

The ContactsService also provide an API to retrieve a specific contact image ( see #getting-a-contact-image).

The contacts service API documentation

The contacts service provides the following functionality:

  1. #using-contacts-service-api.

  2. #contacts-synchronization-status.

  3. #contacts-list-update.

  4. #getting-a-contact-image.

Using contacts service api

To use the contacts service, add a dependency to the ContactsService to your gradle file:

dependencies {

To get access to the ContactsService API, you need to first get a ContactsServiceApi instance by calling the companion function ContactsService.createApi(...).

val contactsService = ContactsService.createApi(lifecycleOwner, iviServiceProvider)

Once you have the ContactsServiceApi instance, you can use it to call any API, and observe any property provided by the service.

Note: The service may not be ready when a client calls the service API and could return a SERVICE_UNAVAILABLE result. It is possible to check the service availability by observing the serviceAvailable property:

contactsService.serviceAvailable.observe(lifecycleOwner) {
if (it) {
// Service is available
} else {
// Service is not available

Contacts synchronization status

Synchronization states

The contacts list ContactsService.phoneBookSynchronizationStatus can have different states:


State description:

| State                       | Value                         | Description                                                                                                                     |
| --------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| Disconnected | `NO_CONNECTED_DEVICES` | Bluetooth device is not connected. Empty list of contacts. |
| Synchronizing | `SYNCHRONIZATION_IN_PROGRESS` | The list of contacts is synchronizing. The list of contacts is updated continuously. |
| Synchronization not enabled | `SYNCHRONIZATION_NOT_ENABLED` | The device is connected but contacts synchronization with PBAP (Phone Book Access Profile) is disabled. Empty list of contacts. |

Getting the synchronization status

A client can observe the synchronization status of the list of contacts by observing the phoneBookSynchronizationStatus property.

contactsService.phoneBookSynchronizationStatus.observe(lifecycleOwner) {
if (it == PhoneBookSynchronizationStatus.SYNCHRONIZATION_IN_PROGRESS) {
// Contacts are being synchronized.
} else {
// Contacts are not being synchronized.

Contacts list update

It is possible to get an updated list of contacts by observing the contacts property. In the following example, the list of contacts is transformed into a list of contact names.

val contactNames = {
// Retrieve for each available contact the displayName.

The list contactNames is updated continuously with the name of the contacts available in the system.

Note: If phoneBookSynchronizationStatus is in PhoneBookSynchronizationStatus.NO_CONNECTED_DEVICES or PhoneBookSynchronizationStatus.SYNCHRONIZATION_NOT_ENABLED state, the list of contacts is cleared.

External links


Link copied to clipboard

Represents contacts data source element, that can be either a ContactItem or a ContactGroup depending on the provided query. See ContactsDataSourceQuery.

Link copied to clipboard

Represents a query that can be applied to the contacts data set.

Link copied to clipboard
interface ContactsService

Service responsible for providing clients with address book contacts and contains data transferred from amongst other sources, Bluetooth-connected devices such as paired mobile phones. This can be used by a TomTom Digital Cockpit frontend for use with hands-free calling.