1 /* 2 * Copyright 2024 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 androidx.core.telecom.util.ExperimentalAppActions 20 21 /** 22 * Interface used to allow the remote surface (automotive, watch, etc...) to know if the connected 23 * calling application supports the participant extension and optionally set up additional actions 24 * for the [Participant]s in the call. 25 * 26 * Actions allow the remote surface to display additional optional state regarding the 27 * [Participant]s in the call and send action requests to the calling application to modify the 28 * state of supported actions. 29 */ 30 @ExperimentalAppActions 31 public interface ParticipantExtensionRemote { 32 33 /** 34 * Whether or not the participants extension is supported by the calling application. 35 * 36 * If `true`, then updates about [Participant]s in the call will be notified. If `false`, then 37 * the remote doesn't support this extension and participants will not be notified to the caller 38 * nor will associated actions receive state updates. 39 * 40 * Note: Must not be queried until after [CallExtensionScope.onConnected] is called. 41 */ 42 public val isSupported: Boolean 43 44 /** 45 * Adds the "raise hand" action and provides the remote surface with the ability to display 46 * which [Participant]s have their hands raised and an action to request to raise and lower 47 * their own hand. 48 * 49 * ``` 50 * connectExtensions(call) { 51 * val participantExtension = addParticipantExtension( 52 * // consume participant changed events 53 * ) 54 * // Initialize the raise hand action 55 * val raiseHandAction = participantExtension.addRaiseHandAction { raisedHands -> 56 * // consume changes of participants with their hands raised 57 * } 58 * onConnected { 59 * // extensions have been negotiated and actions are ready to be used 60 * ... 61 * // notify the remote that this user has changed their hand raised state 62 * val raisedHandResult = raiseHandAction.setRaisedHandState(userHandRaisedState) 63 * } 64 * } 65 * ``` 66 * 67 * Note: Must be called during initialization before [CallExtensionScope.onConnected] is called. 68 * 69 * @param onRaisedHandsChanged Called when the List of [Participant]s with their hands raised 70 * has changed, ordered from oldest raised hand to newest raised hand. 71 * @return The action that is used to determine support of this action and send raise hand event 72 * requests to the calling application. 73 */ addRaiseHandActionnull74 public fun addRaiseHandAction( 75 onRaisedHandsChanged: suspend (List<Participant>) -> Unit 76 ): RaiseHandAction 77 78 /** 79 * Adds the ability for the user to request to kick [Participant]s in the call. 80 * 81 * ``` 82 * connectExtensions(call) { 83 * val participantExtension = addParticipantExtension( 84 * // consume participant changed events 85 * ) 86 * val kickParticipantAction = participantExtension.addKickParticipantAction() 87 * 88 * onConnected { 89 * // extensions have been negotiated and actions are ready to be used 90 * ... 91 * // kick a participant 92 * val kickResult = kickParticipantAction.kickParticipant(participant) 93 * } 94 * } 95 * ``` 96 * 97 * @return The action that is used to send kick Participant event requests to the remote Call. 98 */ 99 public fun addKickParticipantAction(): KickParticipantAction 100 } 101