1 /* 2 * Copyright (C) 2016 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 com.android.dialer.enrichedcall; 18 19 import android.support.annotation.MainThread; 20 import android.support.annotation.NonNull; 21 import android.support.annotation.Nullable; 22 import com.android.dialer.calldetails.CallDetailsEntries; 23 import com.android.dialer.calldetails.CallDetailsEntries.CallDetailsEntry; 24 import com.android.dialer.enrichedcall.historyquery.proto.HistoryResult; 25 import com.android.dialer.enrichedcall.videoshare.VideoShareListener; 26 import com.android.dialer.multimedia.MultimediaData; 27 import java.util.List; 28 import java.util.Map; 29 30 /** Performs all enriched calling logic. */ 31 public interface EnrichedCallManager { 32 33 int POST_CALL_NOTE_MAX_CHAR = 60; 34 35 /** Receives updates when enriched call capabilities are ready. */ 36 interface CapabilitiesListener { 37 38 /** Callback fired when the capabilities are updated. */ 39 @MainThread 40 void onCapabilitiesUpdated(); 41 } 42 43 /** 44 * Registers the given {@link CapabilitiesListener}. 45 * 46 * <p>As a result of this method, the listener will receive a call to {@link 47 * CapabilitiesListener#onCapabilitiesUpdated()} after a call to {@link 48 * #requestCapabilities(String)}. 49 */ 50 @MainThread 51 void registerCapabilitiesListener(@NonNull CapabilitiesListener listener); 52 53 /** 54 * Starts an asynchronous process to get enriched call capabilities of the given number. 55 * 56 * <p>Registered listeners will receive a call to {@link 57 * CapabilitiesListener#onCapabilitiesUpdated()} on completion. 58 * 59 * @param number the remote number in any format 60 */ 61 @MainThread 62 void requestCapabilities(@NonNull String number); 63 64 /** 65 * Unregisters the given {@link CapabilitiesListener}. 66 * 67 * <p>As a result of this method, the listener will not receive capabilities of the given number. 68 */ 69 @MainThread 70 void unregisterCapabilitiesListener(@NonNull CapabilitiesListener listener); 71 72 /** Gets the cached capabilities for the given number, else null */ 73 @MainThread 74 @Nullable 75 EnrichedCallCapabilities getCapabilities(@NonNull String number); 76 77 /** Clears any cached data, such as capabilities. */ 78 @MainThread 79 void clearCachedData(); 80 81 /** 82 * Starts a call composer session with the given remote number. 83 * 84 * @param number the remote number in any format 85 * @return the id for the started session, or {@link Session#NO_SESSION_ID} if the session fails 86 */ 87 @MainThread 88 long startCallComposerSession(@NonNull String number); 89 90 /** 91 * Sends the given information through an open enriched call session. As per the enriched calling 92 * spec, up to two messages are sent: the first is an enriched call data message that optionally 93 * includes the subject and the second is the optional image data message. 94 * 95 * @param sessionId the id for the session. See {@link #startCallComposerSession(String)} 96 * @param data the {@link MultimediaData} 97 * @throws IllegalArgumentException if there's no open session with the given number 98 * @throws IllegalStateException if the session isn't in the {@link Session#STATE_STARTED} state 99 */ 100 @MainThread 101 void sendCallComposerData(long sessionId, @NonNull MultimediaData data); 102 103 /** 104 * Ends the given call composer session. Ending a session means that the call composer session 105 * will be closed. 106 * 107 * @param sessionId the id of the session to end 108 */ 109 @MainThread 110 void endCallComposerSession(long sessionId); 111 112 /** 113 * Sends a post call note to the given number. 114 * 115 * @throws IllegalArgumentException if message is longer than {@link #POST_CALL_NOTE_MAX_CHAR} 116 * characters 117 */ 118 @MainThread 119 void sendPostCallNote(@NonNull String number, @NonNull String message); 120 121 /** 122 * Called once the capabilities are available for a corresponding call to {@link 123 * #requestCapabilities(String)}. 124 * 125 * @param number the remote number in any format 126 * @param capabilities the supported capabilities 127 */ 128 @MainThread 129 void onCapabilitiesReceived( 130 @NonNull String number, @NonNull EnrichedCallCapabilities capabilities); 131 132 /** Receives updates when the state of an enriched call changes. */ 133 interface StateChangedListener { 134 135 /** 136 * Callback fired when state changes. Listeners should call {@link #getSession(long)} or {@link 137 * #getSession(String, String, Filter)} to retrieve the new state. 138 */ 139 void onEnrichedCallStateChanged(); 140 } 141 142 /** 143 * Registers the given {@link StateChangedListener}. 144 * 145 * <p>As a result of this method, the listener will receive updates when the state of any enriched 146 * call changes. 147 */ 148 @MainThread 149 void registerStateChangedListener(@NonNull StateChangedListener listener); 150 151 /** 152 * Returns the {@link Session} for the given unique call id, falling back to the number. If a 153 * filter is provided, it will be applied to both the uniqueCalId and number lookups. 154 */ 155 @MainThread 156 @Nullable 157 Session getSession(@NonNull String uniqueCallId, @NonNull String number, @Nullable Filter filter); 158 159 /** Returns the {@link Session} for the given sessionId, or {@code null} if no session exists. */ 160 @MainThread 161 @Nullable 162 Session getSession(long sessionId); 163 164 /** 165 * Returns a list containing viewable string representations of all existing sessions. 166 * 167 * <p>Intended for debug display purposes only. 168 */ 169 @MainThread 170 @NonNull 171 List<String> getAllSessionsForDisplay(); 172 173 @NonNull 174 Filter createIncomingCallComposerFilter(); 175 176 @NonNull 177 Filter createOutgoingCallComposerFilter(); 178 179 /** 180 * Starts an asynchronous process to get all historical data for the given number and set of 181 * {@link CallDetailsEntries}. 182 */ 183 @MainThread 184 void requestAllHistoricalData(@NonNull String number, @NonNull CallDetailsEntries entries); 185 186 /** 187 * Returns a mapping of enriched call data for all of the given {@link CallDetailsEntries}, which 188 * should not be modified. A {@code null} return indicates that clients should call {@link 189 * #requestAllHistoricalData(String, CallDetailsEntries)}. 190 * 191 * <p>The mapping is created by finding the HistoryResults whose timestamps occurred during or 192 * close after a CallDetailsEntry. A CallDetailsEntry can have multiple HistoryResults in the 193 * event that both a CallComposer message and PostCall message were sent for the same call. 194 */ 195 @Nullable 196 @MainThread 197 Map<CallDetailsEntry, List<HistoryResult>> getAllHistoricalData( 198 @NonNull String number, @NonNull CallDetailsEntries entries); 199 200 /** Returns true if any enriched calls have been made or received. */ 201 @MainThread 202 boolean hasStoredData(); 203 204 /** 205 * Unregisters the given {@link StateChangedListener}. 206 * 207 * <p>As a result of this method, the listener will not receive updates when the state of enriched 208 * calls changes. 209 */ 210 @MainThread 211 void unregisterStateChangedListener(@NonNull StateChangedListener listener); 212 213 /** 214 * Called when the status of an enriched call session changes. 215 * 216 * 217 * @throws IllegalArgumentException if the state is invalid 218 */ 219 @MainThread 220 void onSessionStatusUpdate(long sessionId, @NonNull String number, int state); 221 222 /** 223 * Called when the status of an enriched call message updates. 224 * 225 * 226 * @throws IllegalArgumentException if the state is invalid 227 * @throws IllegalStateException if there's no session for the given id 228 */ 229 @MainThread 230 void onMessageUpdate(long sessionId, @NonNull String messageId, int state); 231 232 /** 233 * Called when call composer data arrives for the given session. 234 * 235 * @throws IllegalStateException if there's no session for the given id 236 */ 237 @MainThread 238 void onIncomingCallComposerData(long sessionId, @NonNull MultimediaData multimediaData); 239 240 /** 241 * Called when post call data arrives for the given session. 242 * 243 * @throws IllegalStateException if there's no session for the given id 244 */ 245 @MainThread 246 void onIncomingPostCallData(long sessionId, @NonNull MultimediaData multimediaData); 247 248 /** 249 * Registers the given {@link VideoShareListener}. 250 * 251 * <p>As a result of this method, the listener will receive updates when any video share state 252 * changes. 253 */ 254 @MainThread 255 void registerVideoShareListener(@NonNull VideoShareListener listener); 256 257 /** 258 * Unregisters the given {@link VideoShareListener}. 259 * 260 * <p>As a result of this method, the listener will not receive updates when any video share state 261 * changes. 262 */ 263 @MainThread 264 void unregisterVideoShareListener(@NonNull VideoShareListener listener); 265 266 /** 267 * Called when an incoming video share invite is received. 268 * 269 * @return whether or not the invite was accepted by the manager (rejected when disabled) 270 */ 271 @MainThread 272 boolean onIncomingVideoShareInvite(long sessionId, @NonNull String number); 273 274 /** 275 * Starts a video share session with the given remote number. 276 * 277 * @param number the remote number in any format 278 * @return the id for the started session, or {@link Session#NO_SESSION_ID} if the session fails 279 */ 280 @MainThread 281 long startVideoShareSession(@NonNull String number); 282 283 /** 284 * Accepts a video share session invite. 285 * 286 * @param sessionId the session to accept 287 * @return whether or not accepting the session succeeded 288 */ 289 @MainThread 290 boolean acceptVideoShareSession(long sessionId); 291 292 /** 293 * Retrieve the session id for an incoming video share invite. 294 * 295 * @param number the remote number in any format 296 * @return the id for the session invite, or {@link Session#NO_SESSION_ID} if there is no invite 297 */ 298 @MainThread 299 long getVideoShareInviteSessionId(@NonNull String number); 300 301 /** 302 * Ends the given video share session. 303 * 304 * @param sessionId the id of the session to end 305 */ 306 @MainThread 307 void endVideoShareSession(long sessionId); 308 309 /** Interface for filtering sessions (compatible with Predicate from Java 8) */ 310 interface Filter { 311 boolean test(Session session); 312 } 313 } 314
