# CallIconExtension

Artifact: [androidx.core:core-telecom](https://developer.android.com/jetpack/androidx/releases/core) [View Source](https://cs.android.com/search?q=file:androidx/core/telecom/extensions/CallIconExtension.kt+class:androidx.core.telecom.extensions.CallIconExtension) Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/core#1.0.0)

*** ** * ** ***

<br />

```
@ExperimentalAppActions
interface CallIconExtension
```

<br />

*** ** * ** ***

Adds support for displaying a call icon on remote surfaces for a given call.

This interface allows a VoIP app to provide a URI representing the call icon, which can then be displayed on remote surfaces (e.g., a connected car's display).

**Important Manifest Declarations:**

1. **`InCallService` Intent Filter:** VoIP apps **must** declare the following `<queries>` intent filter in their `AndroidManifest.xml` to allow remote surfaces to be discoverable when granting URI permissions: ``` ``xml <queries> <intent> <action android:name="android.telecom.InCallService" /> </intent> </queries> `` ```

2. **`FileProvider` Definition:** To securely share call icon images with remote surfaces, it is **strongly recommended** to use a `FileProvider`. A `FileProvider` generates `content://` URIs, which allow temporary, secure access to specific files without requiring broad file system permissions. Define a `FileProvider` in your `AndroidManifest.xml` similar to this: ``` `` <provider android:name="androidx.core.content.FileProvider" android:authorities="androidx.core.telecom.test.fileprovider" android:exported="false" android:grantUriPermissions="true"> <meta-data android:name="android.support.FILE_PROVIDER_PATHS" android:resource="@xml/file_paths" /> </provider> `` ``` with your app's unique authority.

3. **`FileProvider` Configuration:** Create a `file_paths.xml` file in your `res/xml` directory (as referenced in the `meta-data` of the `FileProvider` definition) to specify the directories your app can share icons from: ``` `` <paths> <files-path name="my_images" path="images/" /> </paths> `` ```

   This example allows sharing files from the `images` subdirectory of your app's internal storage `files` directory. Adjust the `name` and `path` according to your needs.

**Generating `content://` URIs:**

In your app's code, use `FileProvider.getUriForFile()` to generate a secure `content://` URI for your call icon file:

```kotlin
// Assuming you have a file named 'call_icon.png' in your app's internal storage
// directory, specifically within a subdirectory named 'images'
File iconFile = new File(getFilesDir(), "images/call_icon.png");

Uri iconUri = FileProvider.getUriForFile(
        context,
        "androidx.core.telecom.test.fileprovider", // Your FileProvider authority
        iconFile
);
```

**Using the `content://` URI:**

Pass the generated `content://` URI to the `addCallIconExtension` method when setting up your call. Remote surfaces will then be able to securely access and display the icon.

Failure to properly declare the `InCallService` intent filter or to use a `FileProvider` for icon sharing will prevent remote surfaces from displaying the call icon.

| See also |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/core/telecom/extensions/ExtensionInitializationScope#addCallIconExtension(android.net.Uri)` |   |
| `https://developer.android.com/reference/kotlin/androidx/core/content/FileProvider` |   |

## Summary

| ### Public functions |
|---|---|
| `suspend https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/core/telecom/extensions/CallIconExtension#updateCallIconUri(android.net.Uri)(iconUri: https://developer.android.com/reference/android/net/Uri.html)` Updates the call icon displayed on remote surfaces. |

## Public functions

### updateCallIconUri

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/core#1.0.0)

```
suspend fun updateCallIconUri(iconUri: Uri): Unit
```

Updates the call icon displayed on remote surfaces.

Call this function whenever the call icon changes. The provided `iconUri` will be used to fetch and display the new icon.

| Parameters |
|---|---|
| `iconUri: https://developer.android.com/reference/android/net/Uri.html` | The `Uri` representing the new call icon. If the content of the URI has changed, but the URI hasn't, there is no need to call this API. |