Package com.tomtom.ivi.platform.recentcalls.api.service.recentcalls

The recent calls service API package.

Recent calls service

The recent calls service is an IVI service and is the service used for accessing recent call information. A single recent call includes:

• Type of the call (RecentCallsService.CallType).

• Displayed name.

• Phone number.

• Duration.

• Timestamp.

Clients (frontends) can use that information to populate the UI of a communications application on the IVI system to show the user's missed calls, recently dialed outgoing calls or incoming calls and allow the user to call the caller back. All the information about a recent call can be retrieved with the recent calls service API. The recent calls service also provides the synchronization status of the sources providing recent call information.

Overview of the recent calls service

The recent calls service is responsible for providing clients with a list of phone calls that the device or connected devices have received or made recently. They can include, amongst other types:

• Missed calls.

• Recently dialed calls.

• Outgoing calls.

• Incoming calls.

The recent calls service is a layer on top of the sources of recent calls.

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

The RecentCallsService updates the RecentCallsService.phoneBookSynchronizationStatus with the current synchronization status of the recent calls in the system ( see #recent-calls-synchronization-status).

The recent calls can have multiple sources, such as multiple connected mobile phones.

The recent calls service API documentation

The recent calls service provides the following functionality:

1. #using-recent-calls-service-api.

2. #recent-calls-synchronization-status.

3. #recent-calls-list-update.

Using recent calls service API

To use the recent calls service, add a dependency to the RecentCallsService to your gradle file:

dependencies {
    implementation("com.tomtom.ivi.platform:platform_recentcalls_api_service_recentcalls")
}

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

val recentCallsService = RecentCallsService.createApi(lifecycleOwner, iviServiceProvider)

Once you have a RecentCallsServiceApi 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:

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

Recent calls synchronization status

Synchronization states

The recent calls list RecentCallsService.phoneBookSynchronizationStatus can have different states:

State description:

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

Getting the synchronization status

A client can observe the synchronization status of the list of recent calls by observing the RecentCallsService.phoneBookSynchronizationStatus property.

recentCallsService.phoneBookSynchronizationStatus.observe(lifecycleOwner) {
    if (it == PhoneBookSynchronizationStatus.SYNCHRONIZATION_IN_PROGRESS) {
        // Recent calls are being synchronized.
    } else {
        // Recent calls are not being synchronized.
    }
}

Recent calls list update

It is possible to get an up to date list of recent calls by observing the RecentCallsService.recentCalls property. In the following example, the list of recent calls is transformed into a list of today's recent calls.

val recentCallsFromToday = recentCallsService.recentCalls.map {
    // Filter the list of recent calls to get the calls from today in the form of a List<ListItemViewModel>.
}

The list recentCallsFromToday is updated continuously with today's recent calls available in the system.

Note: If the RecentCallsService.phoneBookSynchronizationStatus is in the PhoneBookSynchronizationStatus.NO_CONNECTED_DEVICES or PhoneBookSynchronizationStatus.SYNCHRONIZATION_NOT_ENABLED state, the list of recent calls is cleared, so the RecentCallsService.recentCalls property will be empty.

External links

• RecentCallsService.