1 /*
2  * Copyright 2025 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 package androidx.core.telecom.extensions
18 
19 import android.net.Uri
20 import androidx.core.telecom.util.ExperimentalAppActions
21 
22 /**
23  * Adds support for displaying a call icon on remote surfaces for a given call.
24  *
25  * This interface allows a VoIP app to provide a URI representing the call icon, which can then be
26  * displayed on remote surfaces (e.g., a connected car's display).
27  *
28  * **Important Manifest Declarations:**
29  * 1. **`InCallService` Intent Filter:** VoIP apps **must** declare the following `<queries>` intent
30  *    filter in their `AndroidManifest.xml` to allow remote surfaces to be discoverable when
31  *    granting URI permissions: ```xml <queries> <intent> <action
32  *    android:name="android.telecom.InCallService" /> </intent> </queries> ```
33  * 2. **`FileProvider` Definition:** To securely share call icon images with remote surfaces, it is
34  *    **strongly recommended** to use a `FileProvider`. A `FileProvider` generates `content://`
35  *    URIs, which allow temporary, secure access to specific files without requiring broad file
36  *    system permissions. Define a `FileProvider` in your `AndroidManifest.xml` similar to this: ```
37  *    <provider android:name="androidx.core.content.FileProvider"
38  *    android:authorities="androidx.core.telecom.test.fileprovider" android:exported="false"
39  *    android:grantUriPermissions="true"> <meta-data
40  *    android:name="android.support.FILE_PROVIDER_PATHS" android:resource="@xml/file_paths" />
41  *    </provider> ``` with your app's unique authority.
42  * 3. **`FileProvider` Configuration:** Create a `file_paths.xml` file in your `res/xml` directory
43  *    (as referenced in the `meta-data` of the `FileProvider` definition) to specify the directories
44  *    your app can share icons from: ``` <paths> <files-path name="my_images" path="images/" />
45  *    </paths> ```
46  *
47  *    This example allows sharing files from the `images` subdirectory of your app's internal
48  *    storage `files` directory. Adjust the `name` and `path` according to your needs.
49  *
50  * **Generating `content://` URIs:**
51  *
52  * In your app's code, use `FileProvider.getUriForFile()` to generate a secure `content://` URI for
53  * your call icon file:
54  * ```java
55  * // Assuming you have a file named 'call_icon.png' in your app's internal storage
56  * // directory, specifically within a subdirectory named 'images'
57  * File iconFile = new File(getFilesDir(), "images/call_icon.png");
58  *
59  * Uri iconUri = FileProvider.getUriForFile(
60  *         context,
61  *         "androidx.core.telecom.test.fileprovider", // Your FileProvider authority
62  *         iconFile
63  * );
64  * ```
65  *
66  * **Using the `content://` URI:**
67  *
68  * Pass the generated `content://` URI to the `addCallIconExtension` method when setting up your
69  * call. Remote surfaces will then be able to securely access and display the icon.
70  *
71  * Failure to properly declare the `InCallService` intent filter or to use a `FileProvider` for icon
72  * sharing will prevent remote surfaces from displaying the call icon.
73  *
74  * @see ExtensionInitializationScope.addCallIconExtension
75  * @see [androidx.core.content.FileProvider]
76  */
77 @ExperimentalAppActions
78 public interface CallIconExtension {
79 
80     /**
81      * Updates the call icon displayed on remote surfaces.
82      *
83      * Call this function whenever the call icon changes. The provided `iconUri` will be used to
84      * fetch and display the new icon.
85      *
86      * @param iconUri The `Uri` representing the new call icon. If the content of the URI has
87      *   changed, but the URI hasn't, there is no need to call this API.
88      */
updateCallIconUrinull89     public suspend fun updateCallIconUri(iconUri: Uri)
90 }
91