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:
#using-contacts-service-api.
#contacts-synchronization-status.
#contacts-list-update.
#getting-a-contact-image.
Using contacts service api
To use the contacts service, add a dependency to the ContactsService to your gradle file:
dependencies {
implementation("com.tomtom.ivi.platform:platform_contacts_api_service_contacts")
}
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 = contactsService.contacts.map {
// Retrieve for each available contact the displayName.
it.values.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
Types
Represents contacts data source element, that can be either a ContactItem or a ContactGroup depending on the provided query. See ContactsDataSourceQuery.
Represents a query that can be applied to the contacts data set.
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.